Connect your own gateway (software gateway)
A gateway does not have to be an ESP32 running our firmware. Anything that can open an MQTT connection and publish JSON — a Raspberry Pi, a Linux box next to your SCADA, a PLC with an MQTT client, a container, a Node-RED flow — can be a Synacl gateway. The contract it speaks is public: the Synacl Gateway Protocol.
Register it
- Open Gateways → Add gateway and choose Software gateway.
- Give it a name and save. Leave Gateway ID blank to get one of the form
gw_…, or type your own — letters, digits and_ . : -, 3–64 characters, starting with a letter or digit (/,+and#would break MQTT topics; an invalid id is refused withGATEWAY_CHIP_INVALID, a duplicate with 409). The gateway appears in your list as offline. - The connection details are shown right after saving, and again any time from the gateway's Connection Info:
| Field | What it is |
|---|---|
| Broker | mqtt.synacl.com, port 8883, TLS |
| Username | The gateway's broker username — this is its identity |
| Password | 24 characters, generated. Reveal or copy it again from Connection Info at any time; an administrator can rotate it. |
| Topic prefix | tenants/{tenantId}/sources/gateway/{gw_…} — every topic the gateway uses starts with this |
The tenantId in the prefix is the account owner's id. Team members registering a gateway get the same prefix.
A software gateway has no firmware we manage: Flash, Firmware update and Channel are hidden for it, and calling those actions on it answers FIRMWARE_NOT_APPLICABLE. Restart, resend config, reset and delete work as for any gateway.
Speak the protocol
The minimum a gateway does, in order:
- Connect with a Last Will on
{prefix}/status={"online":false}(retained). - Publish
{prefix}/status={"online":true,"ts":…}retained, and repeat every 60 s. - Publish a capability report on
{prefix}/firmware/response— theprotocolslist decides which device protocols you can assign to this gateway in the app. - Publish
{prefix}/config/request={"hash":0}and receive the device list on{prefix}/config/push. - For each device, publish readings on
{prefix}/devices/{deviceId}/dataand presence on{prefix}/devices/{deviceId}/status.
The gateway turns online in the app when its first status arrives. Add devices under it as you would under an ESP32; the protocols offered are the ones your capability report listed. Every payload, number and edge case is on the protocol page, with a JSON Schema per message.
Coming soon: a reference gateway
npx synacl-gateway — an Apache-2.0 Node.js gateway (github.com/synacl-iot/synacl-gateway) that implements the protocol and ships with three drivers: host metrics (CPU, memory, disk of the machine it runs on), a bridge from a local MQTT broker, and Modbus TCP. Point it at your Connection Info and it does the steps above for you. It is not published yet; this article will link the setup guide when it is.
Just a device, not a gateway? A single sensor with its own MQTT client does not need a gateway at all — see connect a direct MQTT device.