API Reference: Signals

django_devicehub.signals

All signals are standard Django Signal instances. Connect handlers with @receiver or .connect().

from django_devicehub.signals import device_data_received

device_data_received

Sent when a device sends data readings. Fired by the MessageRouter after the reading record is stored in the database.

Arguments sent with this signal:

Argument	Type	Description
sender	type	The DeviceType class (e.g., WeatherStation)
device	BaseDevice subclass	The device model instance
readings	dict[str, Any]	Field name to value mapping of the parsed readings
message	BaseMessage subclass	The raw Message model instance (audit record)

Example:

from django.dispatch import receiver
from django_devicehub.signals import device_data_received

@receiver(device_data_received)
def on_data(sender, device, readings, message, **kwargs):
    print(f"Device {device.device_id} sent: {readings}")

Filter by device type:

from myapp.devices import WeatherStation

@receiver(device_data_received, sender=WeatherStation)
def on_weather_data(sender, device, readings, **kwargs):
    temp = readings.get("temperature")
    if temp and temp > 50:
        send_alert(device, temp)

---

device_status_changed

Sent when a device's status changes. Fired by the MessageRouter when a status update message contains a new status value.

Arguments sent with this signal:

Argument	Type	Description
sender	type	The DeviceType class
device	BaseDevice subclass	The device model instance
old_status	str	Previous status value (e.g., "offline")
new_status	str	Current status value (e.g., "online")

Example:

from django_devicehub.signals import device_status_changed

@receiver(device_status_changed)
def on_status(sender, device, old_status, new_status, **kwargs):
    if new_status == "error":
        create_incident_ticket(device)
    elif new_status == "online" and old_status == "offline":
        log_reconnection(device)

---

device_connected

Sent when a device connects. Fired by the broker auth view (BrokerAuthView) after successful authentication.

Arguments sent with this signal:

Argument	Type	Description
sender	type	The DeviceType class
device	BaseDevice subclass	The device model instance

Example:

from django_devicehub.signals import device_connected

@receiver(device_connected)
def on_connect(sender, device, **kwargs):
    log_event(device, "connected")

---

device_disconnected

Sent when a device disconnects or its heartbeat times out.

Arguments sent with this signal:

Argument	Type	Description
sender	type	The DeviceType class
device	BaseDevice subclass	The device model instance

Example:

from django_devicehub.signals import device_disconnected

@receiver(device_disconnected)
def on_disconnect(sender, device, **kwargs):
    log_event(device, "disconnected")
    check_fleet_health()

---

device_command_sent

Sent after a command is published to a device via MQTT. Fired by BaseDevice.send_command() and the REST API provision action.

Arguments sent with this signal:

Argument	Type	Description
sender	type	The DeviceType class
device	BaseDevice subclass	The device model instance
command	str	Command name (e.g., "reboot", "set_interval")
payload	dict	Command payload (empty dict if no payload)

Example:

from django_devicehub.signals import device_command_sent

@receiver(device_command_sent)
def on_command(sender, device, command, payload, **kwargs):
    audit_log.create(
        device=device,
        action=f"command:{command}",
        data=payload,
    )

---

device_provisioned

Sent after a device is provisioned with credentials. Fired by the iot_provision management command and the REST API /provision/ action.

Arguments sent with this signal:

Argument	Type	Description
sender	type	The DeviceType class
device	BaseDevice subclass	The device model instance
credentials	dict	Plaintext credentials with keys: mqtt_username, mqtt_password, api_key

Example:

from django_devicehub.signals import device_provisioned

@receiver(device_provisioned)
def on_provisioned(sender, device, credentials, **kwargs):
    # Store in a secrets vault
    vault.store(device.device_id, credentials)

    # Send to a provisioning service
    provision_service.enqueue(device.device_id, credentials)

---

Signal Summary

Signal	When it fires	Key arguments
device_data_received	Data message processed	device, readings, message
device_status_changed	Status value changes	device, old_status, new_status
device_connected	Broker auth succeeds	device
device_disconnected	Disconnect / heartbeat timeout	device
device_command_sent	Command published via MQTT	device, command, payload
device_provisioned	Credentials generated	device, credentials

All signals send sender as the DeviceType class, which allows filtering with @receiver(signal, sender=MyDeviceType).