Getting Started¶

The MQTT interface lets the Dracal Device Service push sensor readings directly to any MQTT broker as soon as they arrive. There is no polling — data flows continuously the moment a client is configured.

This walkthrough uses curl to configure the client and mosquitto_sub to verify data is flowing. Any MQTT client will work the same way.

Step 1 — Install Dracal Utilities¶

Download and install the Dracal Utilities installer from the download page. This installs the Dracal Device Service, which exposes both the REST JSON API and the MQTT publisher on your machine.

Step 2 — Start an MQTT broker¶

You need a running MQTT broker for the service to connect to. If you already have one, skip to the next step. Otherwise, Mosquitto is a lightweight broker that works on all platforms:

mosquitto

sudo apt install mosquitto mosquitto-clients
sudo systemctl start mosquitto

brew install mosquitto
/opt/homebrew/opt/mosquitto/sbin/mosquitto -c /opt/homebrew/etc/mosquitto/mosquitto.conf

By default, Mosquitto listens on port 1883 on localhost.

Step 3 — Add an MQTT client¶

Tell the service to connect to your broker using the REST API:

curl -s -X POST http://localhost:11395/expert/3.6.0/add_mqtt_clients ^
  -H "Content-Type: application/json" ^
  -d "{\"mqtt\":{\"clients\":{\"my-client\":{\"host\":\"127.0.0.1\",\"name\":\"local\",\"port\":1883}}}}"

curl -s -X POST http://localhost:11395/expert/3.6.0/add_mqtt_clients \
  -H "Content-Type: application/json" \
  -d '{"mqtt":{"clients":{"my-client":{"host":"127.0.0.1","name":"local","port":1883}}}}'

curl -s -X POST http://localhost:11395/expert/3.6.0/add_mqtt_clients \
  -H "Content-Type: application/json" \
  -d '{"mqtt":{"clients":{"my-client":{"host":"127.0.0.1","name":"local","port":1883}}}}'

Response:

{
  "success": true
}

The service connects to the broker immediately and starts publishing. The configuration is saved to disk and will be restored automatically on the next service restart.

Step 4 — Subscribe and see data¶

Open a second terminal and subscribe to all topics published by this client. The name field you set above (local) is the topic prefix:

mosquitto_sub -h 127.0.0.1 -t "local/#" -v

mosquitto_sub -h 127.0.0.1 -t 'local/#' -v

mosquitto_sub -h 127.0.0.1 -t 'local/#' -v

Step 5 — Plug in a device¶

Connect a Dracal device via USB — the service detects it automatically.

Step 6 — Data starts flowing¶

Three topic types will appear immediately in your mosquitto_sub terminal. First, a device connection event and a one-time metadata message:

local/events/E24537 {"event":"device connected","product":"USB-TRH200","serial":"E24537","timestamp":"2026-02-12T18:45:36.333Z"}
local/meta/E24537 {"dew_point":{"unit":"°C"},"heat_index":{"unit":"°C"},"humidex":{"unit":"°C"},"relative_humidity":{"unit":"%rh"},"temperature":{"unit":"°C"}}

Then a continuous stream of readings (default: every 100 ms):

local/values/E24537 {"dew_point":{"value":9.95},"heat_index":{"value":23.1},"humidex":{"value":26.5},"relative_humidity":{"value":42.24},"temperature":{"value":23.53},"timestamp":"2026-02-12T18:45:37.855Z"}
local/values/E24537 {"dew_point":{"value":9.96},"heat_index":{"value":23.11},"humidex":{"value":26.51},"relative_humidity":{"value":42.25},"temperature":{"value":23.54},"timestamp":"2026-02-12T18:45:37.955Z"}

If you unplug or replug a device, you will see disconnect and reconnect events:

local/events/E24537 {"event":"device disconnected","product":"USB-TRH200","serial":"E24537","timestamp":"2026-02-12T18:45:40.333Z"}
local/events/E24537 {"event":"device connected","product":"USB-TRH200","serial":"E24537","timestamp":"2026-02-12T18:45:45.333Z"}

Step 7 — Looking at the data¶

Each message topic follows the pattern <client-name>/<type>/<serial>:

• local/events/E24537 — device connect and disconnect notifications
• local/meta/E24537 — published once when a device connects; lists each channel and its unit
• local/values/E24537 — published continuously; contains the latest reading for every channel

Each entry in the values payload is a channel name mapped to its current value. The timestamp field is UTC and reflects when the service captured the reading.

Next steps¶

You now have a working MQTT data stream from your Dracal device. The Explained section covers the full topic structure and all payload fields. The API reference documents all available options for adding and removing clients, including TLS and authentication settings.