Actuator MQTT command contract
You can control an actuator without a gateway by running an MQTT client on the device itself. Add it as an MQTT-direct actuator (Devices → Add device → Actuator → MQTT Direct) and pick the control kind. On save you receive the device's MQTT username/password (shown once) and its topics.
Your device subscribes to its command topic and publishes an acknowledgement so the platform can confirm state.
Topics
Command (subscribe): tenants/{tenantId}/devices/{deviceId}/cmd
Ack (publish): tenants/{tenantId}/devices/{deviceId}/cmd/ack
Command payloads
The platform publishes one of these to the command topic (the op depends on the control kind you chose):
| Control kind | Payload |
|---|---|
| On / Off | { "correlationId": "…", "value": 0 | 1 } |
| Level % | { "correlationId": "…", "value": 0..255 } (duty) |
| Position ° | { "correlationId": "…", "value": <microseconds> } |
| Move (stepper) | { "correlationId": "…", "command": "move", "steps": <int>, "dir": 0 | 1 } |
| Speed % | { "correlationId": "…", "dir": 0 | 1, "value": 0..255 } |
(The platform converts your friendly command — percent, degrees, units — into these raw values using the actuator's calibration, exactly as it does for gateway-driven actuators.)
Acknowledgement
After applying a command, publish to the ack topic:
{ "correlationId": "<echo the command's id>", "status": "ok", "value": <applied value>, "error": null, "ts": 1719446400000 }
Use "status": "error" with an "error" string if the command could not be applied. The platform reflects the confirmed state on the device page, dashboards, and the mobile app once it receives the ack.
The same contract applies to gateway-wired actuators — the gateway firmware implements it for you. This page is only needed when you bring your own MQTT device.