# 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).
