Explained¶

The service connects to configured MQTT brokers automatically and continuously. Once a client is configured, no manual intervention is needed — the service will publish messages from all connected devices to every configured client.

Clients¶

MQTT clients can be added and removed at runtime using the REST API. See Add MQTT Clients and Remove MQTT Client in the API reference.

When a client is added, it is automatically saved to the MQTT clients config file and will be restored on the next service restart. Similarly, when a client is removed, it is removed from the config file and will not be restored.

Configuration Files¶

MQTT client configurations are stored on disk and updated automatically when using the API. Configuration files are created automatically at startup if they do not exist.

Windows Ubuntu macOS

MQTT clients config: %PROGRAMDATA%\Dracal\dracal-mqtt-clients-config.json

Service config (defaults): %PROGRAMDATA%\Dracal\dracal-device-service-config.json

MQTT clients config: /etc/dracal/dracal-mqtt-clients-config.json

Service config (defaults): /etc/dracal/dracal-device-server-config.json

MQTT clients config: /Library/Application Support/Dracal/dracal-mqtt-clients-config.json

Service config (defaults): /Library/Application Support/Dracal/dracal-device-service-config.json

MQTT clients config¶

Holds the active MQTT client configurations. Updated automatically when clients are added or removed via the API.

{
    "mqtt": {
        "clients": {
            "local": {
                "clean_session": true,
                "host": "127.0.0.1",
                "keep_alive": 60,
                "name": "local",
                "password": "",
                "port": 1883,
                "protocol_version": 4,
                "reconnect": {
                    "enable": true,
                    "max_delay": 60000,
                    "min_delay": 1000
                },
                "ssl": false,
                "username": ""
            }
        }
    }
}

Field	Description
`clean_session`	Start a clean MQTT session on connect (discard previous session state)
`host`	Broker hostname or IP address
`keep_alive`	Keep-alive interval in seconds
`name`	Client name, used as the topic prefix
`password`	Broker password (empty if not required)
`port`	Broker port (default: `1883`, TLS: `8883`)
`protocol_version`	MQTT protocol version (`4` = MQTT 3.1.1, `5` = MQTT 5.0)
`reconnect.enable`	Automatically reconnect on disconnect
`reconnect.min_delay`	Minimum reconnect delay in milliseconds
`reconnect.max_delay`	Maximum reconnect delay in milliseconds (exponential backoff cap)
`ssl`	Enable TLS/SSL encryption
`username`	Broker username (empty if not required)

Service config (defaults)¶

Contains the default values used when fields are omitted from an add-client request.

{
    "mqtt": {
        "clients": {
            "defaults": {
                "clean_session": true,
                "host": "localhost",
                "keep_alive": 60,
                "password": "",
                "port": 1883,
                "protocol_version": 4,
                "reconnect_enable": true,
                "reconnect_max_delay": 60000,
                "reconnect_min_delay": 1000,
                "ssl": false,
                "username": ""
            }
        }
    }
}

Field	Description
`defaults`	Default field values applied when creating a new client via the API

Topics and Payloads¶

Once an MQTT client is configured and connected, the service publishes device data to the broker. Topics follow this pattern:

{client_name}/{type}/{serial}

Where {client_name} is the name field from the client configuration.

Topic types¶

Topic	Description	Published
`{name}/events/{serial}`	Device connection and disconnection events	On connect/disconnect
`{name}/meta/{serial}`	Channel metadata (units)	Once on device connect
`{name}/values/{serial}`	Sensor readings	At `update_interval` (default 100 ms)

`events` payload¶

Published when a device connects or disconnects.

{
    "event": "device connected",
    "product": "USB-TRH200",
    "serial": "E24537",
    "timestamp": "2026-02-12T18:45:36.333Z"
}

{
    "event": "device disconnected",
    "product": "USB-TRH200",
    "serial": "E24537",
    "timestamp": "2026-02-12T18:45:38.755Z"
}

`meta` payload¶

Published once when a device connects. Describes the available channels and their units.

{
    "dew_point": { "unit": "°C" },
    "heat_index": { "unit": "°C" },
    "humidex": { "unit": "°C" },
    "relative_humidity": { "unit": "%rh" },
    "temperature": { "unit": "°C" }
}

`values` payload¶

Published continuously at the configured update_interval. Contains the current sensor readings.

{
    "dew_point": { "value": 9.95 },
    "heat_index": { "value": -4.71 },
    "humidex": { "value": 24.78 },
    "relative_humidity": { "value": 42.24 },
    "temperature": { "value": 23.53 },
    "timestamp": "2026-02-12T18:45:37.855Z"
}