Connect a direct MQTT device
A mqtt-direct device connects to our broker itself — no gateway needed. It speaks the same messages as a gateway-attached device, on shorter topics.
Protocol: mqtt-direct
Credentials
- Add a device with protocol mqtt-direct and define its tags. A tag's name is the key you will publish under.
- On the 201 Created response (or the confirmation screen in the app), copy the username and password shown once — they are not retrievable later.
| Field | Meaning |
|---|---|
mqttUsername |
The device's broker username (issued on creation). The broker confines it to this device's topics. |
baseTopic |
tenants/{tenantId}/devices/{deviceId} — the prefix of every topic below |
Broker: mqtt.synacl.com, port 8883, TLS.
Topics and payloads
| Topic | Direction | Payload |
|---|---|---|
{baseTopic}/data |
publish | {"ts": 1758780000000, "values": {"temperature": 23.4, "door": true}} — ts in epoch milliseconds, values keyed by tag name. Values are raw; the tag's scale and offset are applied by the platform. |
{baseTopic}/status |
publish, retained | {"ts": 1758780000000, "reachable": true} on connect. Set the connection's Last Will to {"ts": …, "reachable": false, "reason": "lwt"} on this topic, retained — ts is required there too. |
{baseTopic}/alert |
publish, optional | A threshold the device evaluated itself — see the alert schema. Platform rules do not need it, and neither do alarm limits: a direct MQTT device's limits are evaluated in the cloud on every reading it publishes. |
{baseTopic}/cmd |
subscribe, actuators only | Commands from the platform — see the actuator command contract. |
{baseTopic}/cmd/ack |
publish, actuators only | {"correlationId": "…", "status": "ok", "value": …, "ts": …} after applying a command. |
A message that does not match its schema is discarded with nothing sent back, and keys the schema does not list are dropped. Validate against the published schemas before you ship: synacl.com/protocol has one per message, with a valid example.
Presence and rate
- The device is marked online whenever a reading arrives, and by a retained
statuswithreachable: true. Publishstatuson connect and let the Last Will publishreachable: false. - Publish no faster than the device's minimum interval — half the plan's advertised cadence. Faster arrivals count as violations, and 20 in 24 h suspend the device. See publish-rate limits and device suspension.