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}
| Page | What it is for | Started by |
|---|---|---|
| Data ingestion | Send metrics, states and events (also HACCP data) | device |
| Realtime monitoring | Know when a user is watching the device live | Things5 |
| Parameters | Read and write configuration parameters, report local changes | both |
| Perform action | Run an action defined on the device model | Things5 |
| Firmware update | Install a firmware sent from Things5 | Things5 |
| Firmware version and list | Report the installed version, list available firmware | device |
| Recipes | Read, write and delete recipes on the device | Things5 |
| Cookbook sync | Load a cookbook of recipe templates on the device | Things5 |
| Logs | Send log lines | device |
| Token exchange | Log a user in on the device with a QR code | device |
| Device tokens | Show a QR code that gives users access to the device | device |
| Model change | Change the device model | device |
| VPN | Start and stop a VPN (things5OS) | Things5 |
Conventions
- Messages come in pairs: a
..._reqmessage and its..._resanswer, linked by the samerequest_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_idis a string; Things5 uses UUIDs, the device can use any unique string for its own requests. errorsis 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.
