API Reference: Fields¶

`django_devicehub.fields` ¶

`Command` ¶

Declares a command that can be sent to a device.

Usage

class WeatherStation(DeviceType): reboot = Command() set_interval = Command(payload={"interval": int})

`validate_payload(data)` ¶

Validate command payload against declared types.

`Reading` ¶

Declares a sensor reading field on a DeviceType.

Each Reading becomes a nullable column on the generated Reading model, forming a wide time-series table (one row = one data point, multiple readings).

Usage

class WeatherStation(DeviceType): temperature = Reading(type=reading_types.FLOAT, unit="C", range=(-40, 80)) humidity = Reading(type=reading_types.FLOAT, unit="%", range=(0, 100))

`to_django_field()` ¶

Convert this Reading to a concrete Django model field.

`ReadingType` ¶

Supported data types for Reading fields.

`StateField` ¶

Declares a persistent state field on a device (beyond base fields).

State fields become columns on the generated Device model.

Usage

class SmartCamera(DeviceType): recording_mode = StateField( type="string", default="continuous", choices=["continuous", "motion", "scheduled"], )

`to_django_field()` ¶

Convert this StateField to a concrete Django model field.

Reading¶

from django_devicehub import Reading, reading_types

Declares a sensor reading field on a DeviceType. Each Reading becomes a nullable column on the generated Reading model, forming a wide time-series table.

Constructor¶

Reading(
    type=reading_types.FLOAT,
    unit="",
    range=None,
    required=False,
    verbose_name=None,
)

Parameters:

Parameter	Type	Default	Description
`type`	`str`	`reading_types.FLOAT`	Data type. One of the `reading_types` constants.
`unit`	`str`	`""`	Unit label. Stored as the Django field's `help_text`.
`range`	`tuple[float\|None, float\|None] \| None`	`(min, max)` validation bounds. Either bound can be `None`.
`required`	`bool`	`False`	Whether the reading is required (reserved for future use).
`verbose_name`	`str \| None`	`None`	Human-readable field label.

Attributes¶

Attribute	Type	Description
`type`	`str`	The reading type constant
`unit`	`str`	Unit label
`range`	`tuple \| None`	Validation range
`required`	`bool`	Required flag
`verbose_name`	`str \| None`	Human label
`name`	`str \| None`	Attribute name on the DeviceType (set by `DeviceTypeMeta`)

Methods¶

to_django_field()¶

Convert this Reading to a concrete Django model field.

Returns: A Django model field instance (e.g., FloatField, IntegerField).

The field is always null=True, blank=True. If unit is set, it becomes help_text. If range is set, MinValueValidator and/or MaxValueValidator are added.

Type mapping¶

`reading_types` constant	Value	Django field	Extra kwargs
`FLOAT`	`"float"`	`FloatField`	--
`INTEGER`	`"integer"`	`IntegerField`	--
`BOOLEAN`	`"boolean"`	`BooleanField`	--
`STRING`	`"string"`	`CharField`	`max_length=255`
`JSON`	`"json"`	`JSONField`	--
`BINARY`	`"binary"`	`BinaryField`	--

Examples¶

temperature = Reading(type=reading_types.FLOAT, unit="C", range=(-40, 80))
humidity = Reading(type=reading_types.FLOAT, unit="%", range=(0, 100))
motion = Reading(type=reading_types.BOOLEAN)
label = Reading(type=reading_types.STRING, verbose_name="Status Label")
payload = Reading(type=reading_types.JSON)
raw_data = Reading(type=reading_types.BINARY)

reading_types¶

from django_devicehub import reading_types

Singleton instance of ReadingType that provides constants for the type parameter of Reading.

Constants¶

Constant	Value	Description
`reading_types.FLOAT`	`"float"`	Floating-point number
`reading_types.INTEGER`	`"integer"`	Integer
`reading_types.BOOLEAN`	`"boolean"`	Boolean (True/False)
`reading_types.STRING`	`"string"`	String (max 255 chars)
`reading_types.JSON`	`"json"`	JSON object (dict or list)
`reading_types.BINARY`	`"binary"`	Binary data (bytes)

Command¶

from django_devicehub import Command

Declares a command that can be sent to a device. Commands are published to the device's cmd MQTT topic.

Constructor¶

Command(
    payload=None,
    description="",
    qos=1,
)

Parameters:

Parameter	Type	Default	Description
`payload`	`dict[str, type] \| None`	`None`	Expected payload schema. Keys are field names, values are Python types.
`description`	`str`	`""`	Human-readable description of the command.
`qos`	`int`	`1`	MQTT QoS level (0, 1, or 2).

Attributes¶

Attribute	Type	Description
`payload`	`dict`	Payload schema (empty dict if none)
`description`	`str`	Description
`qos`	`int`	QoS level
`name`	`str \| None`	Attribute name on the DeviceType (set by `DeviceTypeMeta`)

Methods¶

validate_payload(data)¶

Validate a command payload against the declared types.

Parameters:

data (dict): The payload to validate.

Returns: True if valid.

Raises:

ValueError if a required key is missing.
TypeError if a value has the wrong type.

cmd = Command(payload={"interval": int, "mode": str})

cmd.validate_payload({"interval": 60, "mode": "fast"})    # True
cmd.validate_payload({"interval": 60})                      # ValueError
cmd.validate_payload({"interval": "60", "mode": "fast"})    # TypeError

Examples¶

reboot = Command()                                           # no payload
set_interval = Command(payload={"interval": int}, qos=1)
configure = Command(
    payload={"mode": str, "threshold": float},
    description="Configure device operating parameters",
    qos=2,
)

StateField¶

from django_devicehub import StateField

Declares a persistent state field on a device model. State fields become columns on the generated Device model, beyond the base fields provided by BaseDevice.

Constructor¶

StateField(
    type="string",
    default=None,
    choices=None,
    verbose_name=None,
)

Parameters:

Parameter	Type	Default	Description
`type`	`str`	`"string"`	Data type. See type mapping below.
`default`	`any \| None`	`None`	Default value. If set, the field is `NOT NULL`.
`choices`	`list[str] \| None`	`None`	Allowed values. Converted to Django `choices` format.
`verbose_name`	`str \| None`	`None`	Human-readable field label.

Attributes¶

Attribute	Type	Description
`type`	`str`	The field type string
`default`	`any \| None`	Default value
`choices`	`list \| None`	Allowed values
`verbose_name`	`str \| None`	Human label
`name`	`str \| None`	Attribute name on the DeviceType (set by `DeviceTypeMeta`)

Methods¶

to_django_field()¶

Convert this StateField to a concrete Django model field.

Returns: A Django model field instance.

Behavior:

If default is not None: field is NOT NULL with the given default.
If default is None: field is null=True, blank=True.
If choices is provided: converted to [(c, c) for c in choices].

Type mapping¶

Type string	Django field	Extra kwargs
`"string"`	`CharField`	`max_length=255`
`"float"`	`FloatField`	--
`"integer"`	`IntegerField`	--
`"boolean"`	`BooleanField`	--
`"json"`	`JSONField`	--
`"datetime"`	`DateTimeField`	--

Examples¶

recording_mode = StateField(
    type="string",
    default="continuous",
    choices=["continuous", "motion", "scheduled"],
    verbose_name="Recording Mode",
)
night_vision = StateField(type="boolean", default=False)
sensitivity = StateField(type="integer", default=50)
config = StateField(type="json")
last_calibrated = StateField(type="datetime")

API Reference: Fields¶

django_devicehub.fields ¶

Command ¶

validate_payload(data) ¶

Reading ¶

to_django_field() ¶

ReadingType ¶

StateField ¶

to_django_field() ¶

Reading¶

Constructor¶

Attributes¶

Methods¶

to_django_field()¶

Type mapping¶

Examples¶

reading_types¶

Constants¶

Command¶

Constructor¶

Attributes¶

Methods¶

validate_payload(data)¶

Examples¶

StateField¶

Constructor¶

Attributes¶

Methods¶

to_django_field()¶

Type mapping¶

Examples¶

`django_devicehub.fields` ¶

`Command` ¶

`validate_payload(data)` ¶

`Reading` ¶

`to_django_field()` ¶

`ReadingType` ¶

`StateField` ¶

`to_django_field()` ¶