Skip to content

Quick Start

This guide walks you through creating your first device type, generating models, and simulating data.

1. Define a device type

Create devices.py in your Django app:

# myapp/devices.py
from django_devicehub import DeviceType, Reading, Command, reading_types

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

    # Sensor readings (become columns on the Reading model)
    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")

    # Commands (can be sent to device via MQTT)
    reboot = Command()
    set_interval = Command(payload={"interval": int})

    # Hook: runs on every data message
    def on_data(self, device, readings):
        if readings.get("temperature", 0) > 50:
            print(f"ALERT: {device.device_id} high temperature!")

2. Generate models

In your app's models.py:

# myapp/models.py
from .devices import WeatherStation

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

This generates three concrete Django models:

  • WeatherStationDevice -- device identity, status, credentials
  • WeatherStationReading -- time-series data (temperature, humidity, rainfall columns)
  • WeatherStationMessage -- raw MQTT message audit trail

3. Create and run migrations

python manage.py makemigrations myapp
python manage.py migrate

4. Create a device

from myapp.models import WeatherStationDevice

device = WeatherStationDevice.objects.create(
    device_id="STATION-001",
    name="Field Station Alpha",
)

# Generate MQTT credentials
credentials = device.generate_credentials()
device.save()
print(credentials)
# {'mqtt_username': 'myapp-weatherstationdevice-STATION-001',
#  'mqtt_password': 'abc123...',  (plaintext, shown once)
#  'api_key': 'def456...'}

5. Simulate data (no hardware needed)

python manage.py iot_simulate weatherstation --count 3 --interval 5 --realistic

This creates 3 simulated devices and publishes realistic sensor data every 5 seconds.

6. Start the listener

In a separate terminal:

python manage.py iot_listen

Output:

django-devicehub listener starting on broker 'default'
  WeatherStation: test/weatherstation/+/data, test/weatherstation/+/status
Listening for messages...

7. Query the data

from myapp.models import WeatherStationDevice, WeatherStationReading

device = WeatherStationDevice.objects.get(device_id="sim-weatherstation-001")

# Last 10 readings
readings = device.readings.order_by("-timestamp")[:10]
for r in readings:
    print(f"{r.timestamp}: {r.temperature}C, {r.humidity}%")

# Aggregate
from django.db.models import Avg
avg_temp = WeatherStationReading.objects.filter(
    device=device
).aggregate(Avg("temperature"))

8. Bulk provisioning

python manage.py iot_provision weatherstation --count 10 --output credentials.json

This creates 10 devices and exports their credentials to a JSON file for flashing onto real hardware.

Next steps