Connect a direct MQTT device

Updated 19 Oct 2026

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

Connection details

Add a device with protocol mqtt-direct and define its tags — each with the JSON key it is published under (see JSON keys below).
Right after you save, a window shows the device's connection details. Copy the username and password now. They are shown once and can't be read back later.

Setting	Value
Host	`mqtt.synacl.com`
Port	`8883`, with TLS on — `mqtts://mqtt.synacl.com:8883`
WebSocket (alternative)	`wss://mqtt.synacl.com/mqtt`, for clients that can only use WebSockets
Username / password	Issued when you create the device. The broker only lets them use this device's topics.
Client ID	Any ID that no other connection uses. The device ID is a good choice. Two connections with the same client ID keep disconnecting each other.
Base topic	`tenants/{tenantId}/devices/{deviceId}`, the prefix of every topic below

Plain MQTT on port 1883 can't be reached from the internet, so use TLS on port 8883 or the WebSocket address. The broker has a standard public (Let's Encrypt) certificate, so you don't upload a certificate file.

Lost the password?

Open the device and click Reset MQTT password. A new password appears in the same window, and it's shown once. The old password stops working right away and the device's current connection is closed, so update the device with the new password. The username doesn't change. You need the Edit devices permission to reset it.

Using the API? The mqtt object in the 201 Created response holds the same details (host, port, tls, url, wsUrl, username, password, clientId, topics). POST /devices/{id}/mqtt-credentials resets the password and returns the same object.

Topics and payloads

Topic	Direction	Payload
`{baseTopic}/data`	publish	`{"ts": 1758780000000, "values": {"temperature": 23.4, "door": true}}` — `ts` is required, in epoch milliseconds; a reading without it is discarded. `values` is keyed by each tag's JSON key. 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.

JSON keys

Each tag has a JSON key — the exact key your device puts in values for that reading. Type it when you add the tag; the measurement pick is optional.

No measurement picked: the tag is named after the key. Key temperature → tag temperature.
Measurement picked (say Temperature → Ambient): the tag is named after the measurement (temperature_ambient) and keeps the key you typed. A device that publishes {"values": {"temp": 23.4}} for key temp is filed under temperature_ambient — on the dashboard, in history, in rules and in alarms.

A key must match exactly, case included, and each key can belong to one tag only. It is a top-level key of values — values must be numbers, booleans or strings, so there are no nested paths. A key that matches no tag is still stored under that key, but nothing is bound to it, so the dashboard stays empty. Publishing under the tag's own name (temperature_ambient) also works.

To change a tag's key, edit the device, remove the tag and add it again with the same measurement and the new key: it keeps its name, so its widgets and history stay attached. (A tag named after its key gets a new name when the key changes.)

Presence and rate

The device is marked online whenever a reading arrives, and by a retained status with reachable: true. Publish status on connect and let the Last Will publish reachable: false.
Publish no faster than the device's minimum interval — half the plan's advertised cadence. Faster arrivals count as violations, and more than 20 in 24 h suspend the device. See publish-rate limits and device suspension.