API Reference: Settings¶

`django_devicehub.conf` ¶

All configuration lives under the DJANGO_DEVICEHUB dict in your Django settings module. Every key has a default, so the minimum configuration is an empty dict (though you will typically want to set at least TOPIC_PREFIX and broker HOST/PORT).

Accessing Settings¶

from django_devicehub.conf import devicehub_settings

prefix = devicehub_settings.TOPIC_PREFIX
brokers = devicehub_settings.BROKERS

Settings are cached on first access. To force a reload (useful in tests):

devicehub_settings.invalidate_cache()

Full Default Configuration¶

DJANGO_DEVICEHUB = {
    "BROKERS": {
        "default": {
            "ENGINE": "django_devicehub.brokers.mqtt.MQTTBroker",
            "HOST": "localhost",
            "PORT": 1883,
            "USERNAME": "",
            "PASSWORD": "",
            "CLIENT_ID": "",
            "KEEPALIVE": 60,
            "USE_TLS": False,
            "CA_CERTS": "",
            "CERTFILE": "",
            "KEYFILE": "",
            "USE_SHARED_SUBSCRIPTIONS": True,
            "SHARE_GROUP": "django-devicehub",
            "AUTH_BACKEND": False,
        }
    },
    "STORAGE": {
        "ENGINE": "django_devicehub.storage.django_orm.DjangoORMStorage",
    },
    "TOPIC_PREFIX": "things",
    "AUTO_API": True,
    "AUTO_ADMIN": True,
    "DEVICE_ID_MAX_LENGTH": 128,
    "API_KEY_LENGTH": 64,
    "HEARTBEAT_TIMEOUT_MULTIPLIER": 2.5,
}

Top-Level Settings¶

BROKERS¶

Type: dict[str, dict] Default: See above

A dict of named broker configurations. Each key is a broker name (referenced by DeviceType.Meta.broker), and each value is a dict of connection parameters.

See Broker Configuration Keys below for the full list of per-broker options.

You can define multiple brokers:

DJANGO_DEVICEHUB = {
    "BROKERS": {
        "default": {"HOST": "localhost", "PORT": 1883},
        "lorawan": {"HOST": "lora.example.com", "PORT": 8883, "USE_TLS": True},
    },
}

STORAGE¶

Type: dict Default: {"ENGINE": "django_devicehub.storage.django_orm.DjangoORMStorage"}

Storage backend configuration. The ENGINE key specifies the backend class.

Django ORM (default -- no extra config):

"STORAGE": {
    "ENGINE": "django_devicehub.storage.django_orm.DjangoORMStorage",
}

TimescaleDB:

"STORAGE": {
    "ENGINE": "django_devicehub.storage.timescale.TimescaleDBStorage",
}

InfluxDB 2.x:

"STORAGE": {
    "ENGINE": "django_devicehub.storage.influxdb.InfluxDBStorage",
    "INFLUXDB_URL": "http://localhost:8086",
    "INFLUXDB_TOKEN": "my-token",
    "INFLUXDB_ORG": "my-org",
    "INFLUXDB_BUCKET": "iot_readings",
}

TOPIC_PREFIX¶

Type: str Default: "things"

The prefix for all MQTT topics. Used in the topic template: {prefix}/{type_name}/{device_id}/{message_type}.

"TOPIC_PREFIX": "myproject",
# Topics become: myproject/weatherstation/STATION-001/data

AUTO_API¶

Type: bool Default: True

When True and Django REST Framework is installed, REST API endpoints are available via get_iot_urlpatterns(). Set to False to disable auto-generated API endpoints.

AUTO_ADMIN¶

Type: bool Default: True

When True, Django admin classes are auto-registered for all device types with models during app startup (AppConfig.ready()). Set to False to register your own admin classes.

DEVICE_ID_MAX_LENGTH¶

Type: int Default: 128

Maximum length for the device_id field on generated Device models.

API_KEY_LENGTH¶

Type: int Default: 64

Length of generated API keys (in hex characters). The actual entropy is half this value in bytes (64 hex chars = 32 bytes).

HEARTBEAT_TIMEOUT_MULTIPLIER¶

Type: float Default: 2.5

Multiplier applied to heartbeat_interval to determine when a device is considered overdue. Used by BaseDevice.is_heartbeat_overdue().

For example, with a heartbeat interval of 300 seconds and a multiplier of 2.5, a device is overdue if it has not been seen for 750 seconds.

Broker Configuration Keys¶

Each broker in the BROKERS dict supports these keys:

ENGINE¶

Type: str Default: "django_devicehub.brokers.mqtt.MQTTBroker"

Dotted path to the broker backend class. Must be a subclass of BaseBroker.

HOST¶

Type: str Default: "localhost"

Broker hostname or IP address.

PORT¶

Type: int Default: 1883

Broker port. Use 1883 for plain MQTT, 8883 for MQTT over TLS.

USERNAME¶

Type: str Default: ""

MQTT username for the Django listener to authenticate with the broker. This is the server-side credential, not the per-device credential.

PASSWORD¶

Type: str Default: ""

MQTT password for the Django listener.

CLIENT_ID¶

Type: str Default: "" (auto-generated)

MQTT client ID. If empty, a unique ID is generated as django-devicehub-{random_hex}.

KEEPALIVE¶

Type: int Default: 60

MQTT keepalive interval in seconds. The broker disconnects the client if no ping is received within 1.5x this value.

USE_TLS¶

Type: bool Default: False

Enable TLS encryption for the broker connection.

CA_CERTS¶

Type: str Default: ""

Path to the CA certificate file for TLS verification. Required when USE_TLS is True unless the system CA bundle is sufficient.

CERTFILE¶

Type: str Default: ""

Path to the client certificate file for mutual TLS (mTLS) authentication.

KEYFILE¶

Type: str Default: ""

Path to the client private key file for mutual TLS.

USE_SHARED_SUBSCRIPTIONS¶

Type: bool Default: True

Enable MQTT 5.0 shared subscriptions. When True, subscription topics are prefixed with $share/{SHARE_GROUP}/, distributing messages across multiple listener instances.

Requires an MQTT 5.0-compatible broker (EMQX, HiveMQ, etc.). Disable for MQTT 3.1.1 brokers.

SHARE_GROUP¶

Type: str Default: "django-devicehub"

The shared subscription group name. All listeners with the same group name share the message load.

AUTH_BACKEND¶

Type: bool Default: False

When True, enables the HTTP authentication endpoints (/broker/auth/ and /broker/acl/) for this broker. Configure your MQTT broker to call these endpoints for device authentication and authorization.

Realtime Settings¶

Realtime configuration is nested under the REALTIME key:

DJANGO_DEVICEHUB = {
    "REALTIME": {
        "BACKEND": "channels",
        "SSE_KEEPALIVE_INTERVAL": 30,
    },
}

REALTIME.BACKEND¶

Type: str Default: "channels"

Realtime delivery backend. Options: "channels" (WebSocket via Django Channels) or "sse" (Server-Sent Events).

REALTIME.SSE_KEEPALIVE_INTERVAL¶

Type: int Default: 30

Seconds between SSE keepalive comments. Only used when BACKEND is "sse". Prevents proxies and browsers from closing the connection due to inactivity.

InfluxDB Storage Settings¶

When using the InfluxDB backend, these keys go inside the STORAGE dict:

INFLUXDB_URL¶

Type: str Default: "http://localhost:8086"

InfluxDB server URL.

INFLUXDB_TOKEN¶

Type: str Default: ""

InfluxDB authentication token.

INFLUXDB_ORG¶

Type: str Default: ""

InfluxDB organization name.

INFLUXDB_BUCKET¶

Type: str Default: "iot_readings"

InfluxDB bucket name for storing readings.

Merging Behavior¶

User settings are deep-merged with defaults. This means you only need to specify the keys you want to override:

# This is sufficient -- all other keys use defaults
DJANGO_DEVICEHUB = {
    "BROKERS": {
        "default": {
            "HOST": "mqtt.example.com",
            "PORT": 8883,
            "USE_TLS": True,
        }
    },
    "TOPIC_PREFIX": "myproject",
}

Keys in user settings that are not in defaults are preserved (pass-through). This allows broker-specific custom keys.

Minimal Configuration¶

The absolute minimum to get started:

DJANGO_DEVICEHUB = {
    "TOPIC_PREFIX": "myproject",
}

This uses localhost:1883 for MQTT, Django ORM for storage, and enables auto-admin and auto-API.

API Reference: Settings¶

django_devicehub.conf ¶

Accessing Settings¶

Full Default Configuration¶

Top-Level Settings¶

BROKERS¶

STORAGE¶

TOPIC_PREFIX¶

AUTO_API¶

AUTO_ADMIN¶

DEVICE_ID_MAX_LENGTH¶

API_KEY_LENGTH¶

HEARTBEAT_TIMEOUT_MULTIPLIER¶

Broker Configuration Keys¶

ENGINE¶

HOST¶

PORT¶

USERNAME¶

PASSWORD¶

CLIENT_ID¶

KEEPALIVE¶

USE_TLS¶

CA_CERTS¶

CERTFILE¶

KEYFILE¶

USE_SHARED_SUBSCRIPTIONS¶

SHARE_GROUP¶

AUTH_BACKEND¶

Realtime Settings¶

REALTIME.BACKEND¶

REALTIME.SSE_KEEPALIVE_INTERVAL¶

InfluxDB Storage Settings¶

INFLUXDB_URL¶

INFLUXDB_TOKEN¶

INFLUXDB_ORG¶

INFLUXDB_BUCKET¶

Merging Behavior¶

Minimal Configuration¶

`django_devicehub.conf` ¶