MQTT (self-hosted)

Self-hosted Lattice ships an MQTT broker for fleets that already speak it. On the hosted platform, use the HTTPS device API today — hosted MQTT is coming.

Hosted MQTT endpoints are not yet available. If you're on the hosted platform, follow the device HTTP API — same data, no broker required.

Topic namespace

t/{org_slug}/d/{device_id}/telemetry   device → cloud   QoS 1, not retained, JSON
t/{org_slug}/d/{device_id}/state       device → cloud   QoS 1, RETAINED, reported-state JSON
t/{org_slug}/d/{device_id}/status      device → cloud   QoS 1, RETAINED, {"online": bool} (LWT)
t/{org_slug}/d/{device_id}/cmd         cloud → device   QoS 1, not retained, {"name": str, "params": {}}

Devices may publish only to their own telemetry/state/status topics and subscribe only to their own cmd topic. Everything else is denied and the client is disconnected. The org slug in the topic must match the device's real org.

Authentication

username = the device id (UUID), password = the device token shown once at provisioning.
Rotating a token immediately invalidates the old credential — the next CONNECT is refused.

Payload rules

Topic	Rules
`telemetry`	Flat JSON, metric → value. 16 KB max, 64 metrics/message, 256 chars per text value, 5 msg/s per device (burst 20).
`state`	Arbitrary JSON, shallow-merged into reported state. Publish retained. Keys `lat`/`lng` power the map widget.
`status`	Set an LWT of `{"online": false}` retained; publish `{"online": true}` retained on connect.
`cmd`	`{"name": "set_lamp", "params": {"on": true}}` — names and params come from the device type's command definitions.

Connection example

# publish one telemetry reading
mosquitto_pub -h YOUR-BROKER-HOST -p 1883 \
  -u 'DEVICE-UUID' -P 'DEVICE-TOKEN' \
  -t 't/ORG-SLUG/d/DEVICE-UUID/telemetry' \
  -m '{"temp_c": 23.4, "humidity": 61}'

# listen for commands
mosquitto_sub -h YOUR-BROKER-HOST -p 1883 \
  -u 'DEVICE-UUID' -P 'DEVICE-TOKEN' \
  -t 't/ORG-SLUG/d/DEVICE-UUID/cmd'

Existing ecosystems

Tasmota / ESPHome: point their MQTT config at your broker with the device credentials and template topics onto the namespace above.
Zigbee2MQTT: a small bridge script can republish its topic tree onto per-device topics.