Bridge a device from your local MQTT broker

Updated

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

  1. Open Devices → Add device, choose Local MQTT bridge (under Software gateway) and pick the gateway.
  2. 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
  1. 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

Reachability

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.