MQTT connections
Configure the broker
Use Brokers to configure the MQTT broker used by your devices. Verify its connection details and credentials, then associate the device with that broker.
Both sides of the path have to work: the platform must be able to reach the broker, and the device must be able to reach it too. A broker that the device publishes to successfully is not necessarily one the platform can subscribe to.
Match the topics
The device publish topic carries telemetry from the device. Its subscribe topic is used for incoming commands. Check both against the device firmware configuration.
Topic spelling, capitalisation and separators matter. A topic such as
devices/sensor-01/telemetry is an example, not a required platform topic —
use the actual topic configured for your device.
Match payload keys to inputs
Telemetry payloads must be valid JSON, and their keys are matched against your device input names.
For a device with inputs named temperature and humidity:
{
"temperature": 23.4,
"humidity": 58
}Connect these inputs to an entity to make the readings useful in dashboards and history.
A message arriving at the broker does not establish that the input mapping is correct. In the MQTT path, telemetry whose keys match no connected input can be processed without creating a history record — the message is visible, but the chart stays empty.
Check the connection
Confirm the broker is reachable
From the platform and from the device.
Verify the device’s broker and telemetry topic
The selected broker on the device must be the one it actually publishes to.
Check that the payload is valid JSON
Malformed JSON is discarded before any mapping happens.
Match payload keys to input names
Exactly — see Devices and I/O.
Check entity mappings and the Messages tab
If the Messages tab shows data, the connection is fine and the problem is in entity mappings.
Commands over MQTT
Commands are published to the device’s subscribe topic. A successful publish means the broker accepted the message — it is not an acknowledgement that the device acted on it. Verify the resulting device state separately, usually by waiting for the device’s next state report.
See Send a downlink for the full command workflow.