Bridge a device from your local MQTT broker
Many buildings already have an MQTT broker with devices publishing to it — Tasmota and Shelly plugs, zigbee2mqtt, Home Assistant, a PLC, a home-grown script. The synacl-gateway reference gateway's Local MQTT bridge driver subscribes to topics on that broker, picks a value out of each message, and publishes it to Synacl as a device tag. Nothing changes on the local side, and your broker is never exposed to the internet: the gateway connects out to it and out to Synacl.
Requires a software gateway running synacl-gateway with network access to your broker, already online — the protocol is only offered once the gateway has reported that it supports it.
Add the device
- Open Devices → Add device, choose Local MQTT bridge (under Software gateway) and pick the gateway.
- Fill in the connection to your local broker:
| Field | Meaning |
|---|---|
| Local broker URL | mqtt://host:1883, mqtts://host:8883, ws://… or wss://… — the address the gateway can reach on its own network, not the Synacl broker. Do not put a username and password in the URL |
| Username / password | Optional, if your broker needs them. The password is write-only once saved — the field reads Saved — type to replace. Leave it as it is when you edit the device to keep it; type a new one to replace it, or select Remove to delete it |
| Sample interval | How often the gateway publishes what it has received (your plan's minimum interval applies) |
| Stale after (ms) | Optional. How long with no message on any of the device's topics before it is reported unreachable. Leave it empty for the default (3 × the sample interval, never less than 300 000 ms = 5 min); 0 = never. A whole number of milliseconds |
| Client ID | Optional. The MQTT client id the gateway uses on your broker. Leave it empty for the default, synacl-<gateway id>-<last 6 characters of a device id>. Set it only if your broker requires a particular client id (an ACL keyed on it, for example) — see Connections and client ids below |
- Add one tag per value. Each tag has its own Topic — a subscription filter on your broker (
+and#are allowed) — and an optional JSON Path that picks a field out of a JSON payload. Tags of one device may listen on different topics.
JSON paths
A path is dot notation; a numeric segment indexes an array. Leave it empty when the payload is a bare value (23.5, ON).
| Source | Topic | JSON path | Payload it matches |
|---|---|---|---|
| Tasmota plug — power | tele/<device>/SENSOR |
ENERGY.Power |
{"Time":"…","ENERGY":{"Power":41,"Voltage":231,…}}, sent every TelePeriod (300 s by default) |
| Tasmota plug — relay state | stat/<device>/POWER |
(empty) | ON / OFF → 1 / 0 |
| zigbee2mqtt sensor | zigbee2mqtt/<friendly name> |
temperature |
{"temperature":22.4,"humidity":48,"battery":93} |
| Home Assistant MQTT Statestream | homeassistant/sensor/<entity>/state |
(empty) | one bare value per topic |
| An element of an array | plc/line1 |
sensors.0.temp |
{"sensors":[{"temp":61.5},…]} |
<device> is the Tasmota Topic from its MQTT settings (tasmota_XXXXXX by default) and <friendly name> is the device's name in zigbee2mqtt. Statestream's base topic and layout follow your Home Assistant configuration.
How values are handled
- Numbers are kept as they are.
true/false/ON/OFF(any case) become1/0, so a switch charts and compares like a relay on an ESP32. Numeric strings such as"23.5"become numbers. Other strings are kept, up to 256 characters. Objects, arrays andnullare skipped — if a path lands on an object, add a deeper path. - The gateway keeps the latest value received per tag and publishes it at the sample interval. A device that publishes faster than the interval is neither throttled nor suspended; only its most recent value goes up. If nothing arrived for a tag since the last publish, nothing is sent for it.
- Values are sent raw. Use the tag's scale and offset in Synacl for unit conversion. Alert thresholds are evaluated in the cloud by default, as for any device behind a software gateway; set the device to On the gateway if you want it alarming while the uplink is down (see Normal, Watch and Alert).
- A tag whose topic filter is invalid, or whose path is not in the payload, is skipped with a warning in the gateway log — once per tag, not once per message.
Reachability
- The device is reachable while messages keep arriving on any of its topics.
- After nothing has arrived for the stale time it is reported unreachable with the reason
bridge/no_message. The default is 3 × the sample interval, but never less than 300 s (Tasmota's default telemetry period, so a plug on factory settings never flaps). For a device that publishes rarely — a door sensor that only reports when it opens — raise Stale after, or set it to0so silence never counts against it. - If the local broker is unreachable for more than 10 s, every device on it is reported unreachable with
bridge/disconnected; the gateway keeps reconnecting with back-off and resubscribes when the broker is back.
Connections and client ids
Devices that point at the same broker with the same login — and the same Client ID, or none — share one connection, so a fleet of plugs on one broker costs one local connection. With Client ID empty, that connection is named after the first device that opened it, which is always safe. If you set one, no other client on the broker may use it — including a Synacl device on the same broker with a different login: MQTT allows one connection per client id, so the broker disconnects the two in turn and both flap.
Limits in 0.1
The bridge is one-way: it reads from your broker. Publishing to a local device from Synacl is not supported in this release — to command a local device, use an MQTT-direct actuator or a rule with an MQTT action.