Metadata-Version: 2.4
Name: django-devicehub
Version: 0.2.1
Summary: Declarative IoT device management for Django
Author: Altius Academy SNC
Author-email: Paul Guindo <paulguindo@altius-group.ch>
License-Expression: MIT
Project-URL: Homepage, https://github.com/Altius-Academy-SNC/django-devicehub
Project-URL: Documentation, https://altius-academy-snc.github.io/django-devicehub
Project-URL: Repository, https://github.com/Altius-Academy-SNC/django-devicehub
Project-URL: Issues, https://github.com/Altius-Academy-SNC/django-devicehub/issues
Keywords: django,iot,mqtt,devices,sensors,telemetry
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Home Automation
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django>=4.2
Provides-Extra: mqtt
Requires-Dist: paho-mqtt>=2.0; extra == "mqtt"
Provides-Extra: drf
Requires-Dist: djangorestframework>=3.14; extra == "drf"
Provides-Extra: timescale
Requires-Dist: psycopg2-binary>=2.9; extra == "timescale"
Provides-Extra: influxdb
Requires-Dist: influxdb-client>=1.30; extra == "influxdb"
Provides-Extra: channels
Requires-Dist: channels>=4.0; extra == "channels"
Requires-Dist: channels-redis>=4.0; extra == "channels"
Provides-Extra: all
Requires-Dist: paho-mqtt>=2.0; extra == "all"
Requires-Dist: djangorestframework>=3.14; extra == "all"
Requires-Dist: psycopg2-binary>=2.9; extra == "all"
Requires-Dist: influxdb-client>=1.30; extra == "all"
Requires-Dist: channels>=4.0; extra == "all"
Requires-Dist: channels-redis>=4.0; extra == "all"
Provides-Extra: dev
Requires-Dist: paho-mqtt>=2.0; extra == "dev"
Requires-Dist: djangorestframework>=3.14; extra == "dev"
Requires-Dist: psycopg2-binary>=2.9; extra == "dev"
Requires-Dist: influxdb-client>=1.30; extra == "dev"
Requires-Dist: channels>=4.0; extra == "dev"
Requires-Dist: channels-redis>=4.0; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-django; extra == "dev"
Dynamic: license-file

# Django DeviceHub

Declarative IoT device management for Django. Define device types with Python classes, get auto-generated models, REST API, admin, MQTT integration, and realtime updates.

[![PyPI version](https://img.shields.io/pypi/v/django-devicehub.svg)](https://pypi.org/project/django-devicehub/)
[![Python versions](https://img.shields.io/pypi/pyversions/django-devicehub.svg)](https://pypi.org/project/django-devicehub/)
[![Django versions](https://img.shields.io/badge/django-4.2%20%7C%205.0%20%7C%205.1%20%7C%206.0-0C4B33.svg)](https://www.djangoproject.com/)
[![Tests](https://img.shields.io/github/actions/workflow/status/Altius-Academy-SNC/django-devicehub/tests.yml?branch=main&label=tests)](https://github.com/Altius-Academy-SNC/django-devicehub/actions/workflows/tests.yml)
[![License](https://img.shields.io/pypi/l/django-devicehub.svg)](https://github.com/Altius-Academy-SNC/django-devicehub/blob/main/LICENSE)

**[Documentation](https://altius-academy-snc.github.io/django-devicehub)** | **[PyPI](https://pypi.org/project/django-devicehub/)** | **[Source](https://github.com/Altius-Academy-SNC/django-devicehub)**

## Quick Example

```python
# devices.py - declare your device types
from django_devicehub import DeviceType, Reading, Command, reading_types

class WeatherStation(DeviceType):
    class Meta:
        protocol = "mqtt"
        heartbeat_interval = 300

    temperature = Reading(type=reading_types.FLOAT, unit="C", range=(-40, 80))
    humidity = Reading(type=reading_types.FLOAT, unit="%", range=(0, 100))
    rainfall = Reading(type=reading_types.FLOAT, unit="mm")

    reboot = Command()
    set_interval = Command(payload={"interval": int})
```

```python
# models.py - one line generates 3 concrete Django models
from .devices import WeatherStation

WeatherStationDevice, WeatherStationReading, WeatherStationMessage = (
    WeatherStation.create_models()
)
```

```bash
python manage.py makemigrations    # generates migrations
python manage.py migrate           # creates tables
python manage.py iot_listen        # starts MQTT listener
python manage.py iot_simulate weatherstation --realistic  # simulate devices
```

## Features

- **Declarative device types** -- define readings, commands, and state fields as Python classes
- **Concrete model generation** -- `create_models()` produces real Django models with `makemigrations`
- **MQTT 5.0 broker** -- paho-mqtt with shared subscriptions, TLS, EMQX/Mosquitto compatible
- **Auto-generated REST API** -- DRF viewsets with device CRUD, readings, and provisioning
- **Auto-generated admin** -- Django admin registered automatically
- **Broker authentication** -- HTTP auth/ACL endpoints for EMQX and Mosquitto
- **Device provisioning** -- credential generation, bulk provisioning, API key management
- **Realtime updates** -- Django Channels WebSocket + SSE fallback + `iot.js` frontend library
- **Pluggable storage** -- Django ORM (default), TimescaleDB, InfluxDB 2.x
- **Django signals** -- `device_data_received`, `device_status_changed`, `device_provisioned`, etc.
- **Management commands** -- `iot_listen`, `iot_simulate`, `iot_provision`

## Installation

```bash
pip install django-devicehub              # core
pip install django-devicehub[mqtt]        # + MQTT support
pip install django-devicehub[drf]         # + REST API
pip install django-devicehub[channels]    # + WebSocket realtime
pip install django-devicehub[all]         # everything
```

Add to `INSTALLED_APPS`:

```python
INSTALLED_APPS = [
    ...
    "django_devicehub",
    "myapp",
]
```

Configure the broker:

```python
DJANGO_DEVICEHUB = {
    "BROKERS": {
        "default": {
            "ENGINE": "django_devicehub.brokers.mqtt.MQTTBroker",
            "HOST": "localhost",
            "PORT": 1883,
        }
    },
    "TOPIC_PREFIX": "myproject",
}
```

## Documentation

Full documentation at **[altius-academy-snc.github.io/django-devicehub](https://altius-academy-snc.github.io/django-devicehub)**.

- [Installation](https://altius-academy-snc.github.io/django-devicehub/getting-started/install/)
- [Quick Start](https://altius-academy-snc.github.io/django-devicehub/getting-started/quickstart/)
- [Device Types Guide](https://altius-academy-snc.github.io/django-devicehub/guides/device-types/)
- [MQTT & Brokers](https://altius-academy-snc.github.io/django-devicehub/guides/brokers/)
- [API Reference](https://altius-academy-snc.github.io/django-devicehub/api/device-type/)

## License

MIT -- see [LICENSE](LICENSE).
