Introduction

Topics, message pairs and conventions of the device MQTT API.

The MQTT API is how a device exchanges data and commands with Things5. Before using it, connect the device as described in Connecting a device.

Every topic of a device has the form

things5-production/v1/devices/{device_id}/{suffix}
PageWhat it is forStarted by
Data ingestionSend metrics, states and events (also HACCP data)device
Realtime monitoringKnow when a user is watching the device liveThings5
ParametersRead and write configuration parameters, report local changesboth
Perform actionRun an action defined on the device modelThings5
Firmware updateInstall a firmware sent from Things5Things5
Firmware version and listReport the installed version, list available firmwaredevice
RecipesRead, write and delete recipes on the deviceThings5
Cookbook syncLoad a cookbook of recipe templates on the deviceThings5
LogsSend log linesdevice
Token exchangeLog a user in on the device with a QR codedevice
Device tokensShow a QR code that gives users access to the devicedevice
Model changeChange the device modeldevice
VPNStart and stop a VPN (things5OS)Things5

Conventions

  • Messages come in pairs: a ..._req message and its ..._res answer, linked by the same request_id. cmd/ topics are requests from Things5, req/ topics are requests from the device, event/ topics are notifications from the device.
  • Each page shows for every topic who publishes it: Things5 → device (the device subscribes) or Device → Things5 (the device publishes).
  • Payloads are JSON. request_id is a string; Things5 uses UUIDs, the device can use any unique string for its own requests.
  • errors is a list of human-readable messages: an empty list means success.
  • Values of metrics, parameters and recipes are always JSON strings ("value": "21.5"). Timestamps are Unix time in milliseconds.
  • Things5 waits 30 seconds for the device's answer to parameters, actions and firmware update requests, and up to 60 seconds for recipes. When the device sends a request and gets no answer within a few seconds, it should send it again.
  • A message published by the device can be at most 128 KB. Ignore topics and fields you do not know: new ones can be added.