Synacl Gateway Protocol v1

Protocol v1 · 24 message schemas · Published 25 Sep 2026 · index.json · topics.json

This page is the contract between a gateway and Synacl. A gateway is anything that connects to the Synacl MQTT broker with gateway credentials, publishes readings for the devices behind it, and accepts configuration and commands. The Synacl ESP32 firmware implements it; so can a Raspberry Pi script, a PLC, a container next to your SCADA, or a Node-RED flow. Every message has a JSON Schema you can validate against, and the whole contract is machine-readable at /protocol/v1/index.json.

What this is, and why it is open

Synacl is the platform: the broker, the storage, the dashboards, rules, monitors, macros and the MCP server for AI agents. The gateway is the piece in your building, and there is no reason it has to be our hardware. The ESP32 firmware is the reference implementation, not the only one.

So the contract is published in full. Nothing on this page is a simplification: the uplink schemas describe what the platform's validators accept, the downlink schemas describe what the platform sends, and the numbers (heartbeats, windows, rate limits, batch sizes) are the ones in the code. Where the reference firmware does something odd, the known quirks section says so rather than hiding it.

Identity and credentials

A gateway is registered in the app before it connects. For an ESP32 the web flasher does this. For anything else: Gateways → Add gateway → Software gateway. The gateway's Connection Info then shows everything below; the password is shown once.

Devices without a gateway. A device that speaks MQTT itself uses tenants/{tenantId}/devices/{deviceId}/… with its own credentials — the {dev} prefix in the topic table. The data, status, alert and command messages are the same ones described here; registration is covered in connect a direct MQTT device and the actuator command contract.

Topic tree

Everything a gateway publishes or subscribes to sits under its prefix. Levels are the conformance levels: implement Core and the platform treats you as a gateway; the rest is what your hardware can do.

{gw} = tenants/{tenantId}/sources/gateway/{chipId} (a gateway and everything behind it) · {dev} = tenants/{tenantId}/devices/{deviceId} (a device that connects on its own, without a gateway).

Core — every gateway implements these

Optional — implement what your hardware can do; the platform copes without them

Experimental — may change without a version bump — do not build on them yet

QoS and retain. The QoS in the table is what the reference firmware publishes with. The platform's own subscriptions are shared subscriptions at QoS 0, so a QoS 1 publish is acknowledged by the broker but reaches the platform at most once; publish at QoS 1 for the broker's benefit, not for end-to-end delivery. The platform publishes to a gateway at QoS 1 and never retained: a command or config push sent while you are disconnected is not queued for you. That is deliberate — a stale actuator command replayed after an outage is worse than a lost one — and it is why the lifecycle re-requests the config on every connect.

Connection lifecycle

1. Connect with TLS, the username and password from Connection Info, a clean session, and a Last Will on {gw}/status with payload {"online":false}, retained, QoS 1.
2. Subscribe to {gw}/config/push, {gw}/cmd and {gw}/devices/+/cmd. Add {gw}/firmware/request, {gw}/macros/push, {gw}/macros/run and {gw}/macros/abort if you implement those optional parts.
3. Announce yourself by publishing {gw}/status retained: {"online":true,"ts":<epoch ms>} plus whatever you know (ip, fw, rssi, uplink). Repeat it every 60 s. Readers treat a gateway as stale after 180 s without one.
4. Report capabilities on {gw}/firmware/response: {version, schemaVersion: 2, board, mac, protocols[], sensorModels{}, buffering, jobs, modbusFormats, configChunked, maxConfigBytes, mqttPayloadBytes, debug}. The platform gates what it will ask of you by this message — a device protocol not in protocols[] cannot be assigned to a device under this gateway in the app.
5. Ask for the config on {gw}/config/request: {"hash": <n>}, where n is the FNV-1a 32-bit hash of the raw bytes of the last config/push you applied, or 0 if you have none.
6. Receive {gw}/config/push. One of three payloads: the full document, {"unchanged":true}, or a chunk (see the config document). Apply the document, persist the exact bytes, and re-send config/request with the new hash — that round trip is what clears the "applying configuration" state on the gateway page.
7. Run the data loop for every device in the document: publish readings on {gw}/devices/{deviceId}/data and presence on {gw}/devices/{deviceId}/status.
8. Repeat 5–6 on every reconnect. config/push is not retained, so a reconnecting gateway must ask. There is one unsolicited case: while you are connected, editing the gateway's devices or network settings in the app pushes a new document immediately — apply it and answer with config/request and the new hash, exactly as in step 6.

The config document

The full config/push is the list of devices the platform wants this gateway to read, plus optional network settings:

{ "devices": [ { "_id": "…", "protocol": "rs485", "conn": { … }, "tags": [ { "name": "voltage", … } ] } ],
  "success": true,
  "net": { … } }

Each device carries its _id (the {deviceId} in its topics), its protocol, the connection settings for that protocol (conn) and its tags. A tag's name is the key you use in values when you publish a reading for that device; a tag key that is absent means the firmware default given in the schema. The document is authoritative: replace your whole device set with it, and stop polling anything it no longer lists — a gateway the platform does not recognise gets devices: []. Directly connected devices are never included. The exact fields per protocol are in the config-push schema; a gateway ignores what it does not understand.

Hashing. The hash identifies the document you hold, so the platform can answer {"unchanged":true} instead of re-sending it. It is FNV-1a, 32-bit (seed 0x811c9dc5, prime 0x01000193), computed over the raw UTF-8 bytes of the config/push payload exactly as received — not over a re-serialised copy, which would change key order and whitespace. The platform emits a deterministic payload (devices sorted by id, tag keys in a fixed order, defaults omitted, net last) precisely so that an unchanged configuration hashes the same every time. Persist those bytes; on boot, hash them and ask.

function fnv1a32(bytes) {                  // bytes: the config/push payload, byte for byte
  let h = 0x811c9dc5;
  for (const b of bytes) { h ^= b; h = Math.imul(h, 0x01000193) >>> 0; }
  return h >>> 0;                           // publish as a JSON number: {"hash": 2166136261}
}

Chunking. A large fleet on one gateway can outgrow the largest MQTT payload a small device can hold. A gateway that can receive only bounded payloads adds cap — how many payload bytes fit in one MQTT packet — to config/request (max, the largest document it can store, is informational). When the document is larger than cap, the platform answers with one chunk {p, n, h, d} instead: part p (0-based) of n, h the hash of the complete document, d a base64 slice of its UTF-8 bytes that decodes on its own. Decode and append in p order, asking for each next part with {"hash": …, "cap": …, "part": p + 1} — the platform keeps no transfer state, so any part can be served by any worker. After part n − 1 the reassembled bytes must hash to h; from then on h is the hash you send. The configChunked, maxConfigBytes and mqttPayloadBytes fields of the capability report tell the platform the same limits up front. The field list is in the config-request schema.

The data loop

For each device in the config document, poll it at the interval in its conn (tickDuration or sampleIntervalMs, depending on the protocol — or whatever a later set/interval command set) and publish:

The numbers that govern presence:

A device is also marked online whenever a reading for it arrives, so a device that reports data faster than every 90 s stays online through its data alone; the status message is what carries reachable:false and a reason.

Commands and acknowledgements

The platform sends commands on two topics. Gateway-level commands change the gateway itself; device-level commands act on one device and are acknowledged.

Echo the correlationId exactly; the platform matches the ack to the command by it and shows the confirmed value on the device page, in dashboards and in the mobile app — the applied value is reported only when the ack arrives. Through a gateway a Modbus write is always a single write and register_type selects the function (coil = FC05, holding = FC06); switch on it, not on fc. The exact fields, including the actuator variants (on/off, level, position, move, speed), are in the device-cmd and gateway-cmd schemas.

Store-and-forward

If the uplink drops, buffer readings and send them later on {gw}/data/backfill:

{ "batch": [ { "deviceId": "…", "ts": 1758780000000, "values": { "voltage": 2301 } }, … ] }

Never replay buffered readings on the live data topic. The rate limiter measures the gap between arrivals, not the timestamps you send, so a burst of catch-up readings is a run of violations, and 20 violations in 24 hours suspends the device. The backfill topic is exempt from that gate. Backfilled readings are written to history only: they do not update live widgets, do not evaluate rules and do not become the device's last value. Store-and-forward is enabled per account — see gateway offline buffering.

Validation and rate limits

What happens when you get it wrong is worth knowing before you get it wrong:

The per-device minimum interval comes from the plan: half of the plan's advertised cadence, so a device polled at the advertised rate has headroom for jitter but not for double-sending. Plan cadences are in the plan comparison and understanding rate limits. A late reading — one delayed past the next one by the network — is skipped, not counted.

Because nothing is sent back for an invalid message, validate against the schemas on your side before publishing. The schemas are plain draft-07 and load into any validator; the examples under /protocol/v1/examples/ are known-valid payloads to test yours against.

Message reference

One entry per message: the property table generated from its JSON Schema, then a valid example. Property tables show one level of nesting; the linked schema has everything.

Uplink — gateway to platform

source-status — gateway presence

The retained heartbeat, and the Last Will ({"online":false}). Core.

{
  "online": true,
  "ts": 1758801600000,
  "ip": "192.168.1.42",
  "fw": "1.5.4",
  "rssi": -61,
  "uplink": "wifi",
  "bufRam": 0,
  "bufFlash": 0,
  "bufDropped": 0,
  "flashErrors": 0,
  "flashWearPct": 1
}

The Last Will, exactly:

{
  "online": false
}

firmware-response — capability report and OTA progress

Two shapes on one topic: the capability report published after connect, and progress reports during an over-the-air update requested on firmware/request. Core (the report); optional (OTA).

{
  "version": "1.5.4",
  "schemaVersion": 2,
  "board": "nodemcu-32s",
  "mac": "123456789012345",
  "debug": true,
  "ethernet": true,
  "buffering": true,
  "modbusFormats": true,
  "net": {
    "mode": "auto",
    "addr": "dhcp",
    "ip": "",
    "mask": "",
    "gw": "",
    "dns": ""
  },
  "protocols": [
    "rs485",
    "modbus-tcp",
    "mqtt-direct",
    "http",
    "gpio-digital-in",
    "gpio-digital-out",
    "gpio-analog",
    "gpio-pwm",
    "gpio-stepper",
    "gpio-servo",
    "gpio-motor",
    "i2c",
    "spi",
    "1-wire",
    "uart",
    "can",
    "mbus",
    "gps"
  ],
  "sensorModels": {
    "i2c": [
      "BME280",
      "BMP280",
      "SHT31",
      "ADS1115",
      "generic"
    ],
    "spi": [
      "MAX31855",
      "MAX6675"
    ]
  }
}

OTA progress on the same topic:

{
  "correlationId": "b7e4c2a1-5d3f-4a9e-8c7b-6f5e4d3c2b1a",
  "status": "downloading",
  "progress": 40,
  "ts": 1758801600000
}

config-request — ask for the config

hash is the FNV-1a 32-bit of the raw bytes of the last applied config/push, 0 if none. cap, max and part are for chunked delivery. An empty object is a valid request. Core.

{
  "hash": 3735928559
}

Pulling part 2 of a chunked transfer:

{
  "hash": 3735928559,
  "cap": 3900,
  "max": 16384,
  "part": 2
}

data — a reading

Raw values keyed by tag name. q and seq are optional. Core.

{
  "ts": 1758801600000,
  "seq": 1042,
  "q": "good",
  "values": {
    "voltage": 231.6,
    "current": 4.12,
    "power_factor": 0.97
  }
}

device-status — device presence

Retained. reachable:false with a reason when the device stops answering. Core.

{
  "ts": 1758801600000,
  "reachable": true
}

data-backfill — store-and-forward batch

Oldest first, ≤ 40 records, ≤ 3500 bytes, one batch per second. Optional.

{
  "batch": [
    {
      "deviceId": "66f1a2b3c4d5e6f708192a3b",
      "ts": 1758801420000,
      "values": {
        "voltage": 230.9,
        "current": 4.02
      },
      "q": "good",
      "seq": 1001
    },
    {
      "deviceId": "66f1a2b3c4d5e6f708192a3d",
      "ts": 1758801425000,
      "values": {
        "temperature": 22.8,
        "humidity": 51.2
      },
      "q": "good",
      "seq": 388
    },
    {
      "deviceId": "66f1a2b3c4d5e6f708192a3b",
      "ts": 1758801480000,
      "values": {
        "voltage": 231.1,
        "current": 4.05
      },
      "q": "good",
      "seq": 1002
    }
  ]
}

alert — a gateway-evaluated threshold

Optional.

{
  "ts": 1758801600000,
  "severity": "warning",
  "code": "THRESHOLD_VIOLATION",
  "message": "temperature 81.2 is above 80",
  "tag": "temperature",
  "value": 81.2
}

cmd-ack — command acknowledgement

Optional (required if you accept device commands). An ack without a correlationId is rejected.

{
  "correlationId": "b7e4c2a1-5d3f-4a9e-8c7b-6f5e4d3c2b1a",
  "status": "ok",
  "value": 1,
  "error": null,
  "ts": 1758801600000
}

A failed command:

{
  "correlationId": "b7e4c2a1-5d3f-4a9e-8c7b-6f5e4d3c2b1a",
  "status": "error",
  "value": 0,
  "error": "device unreachable",
  "ts": 1758801600000
}

A successful write whose applied value could not be read back — value: null is accepted and leaves the confirmed state untouched (the reference firmware serialises a NaN this way):

{
  "correlationId": "b7e4c2a1-5d3f-4a9e-8c7b-6f5e4d3c2b1a",
  "status": "ok",
  "value": null,
  "error": null,
  "ts": 1758801600000
}

job-event — a job boundary

A limit switch or similar input opening or closing a bounded run; the payload names the job. Optional, gateway-level.

{
  "event": "start",
  "ts": 1758801600000,
  "localJobId": 57,
  "signal": "door_switch",
  "seq": 3
}

macro-run-status — macro lifecycle

started, step, done or error for a macro running on the gateway. Optional.

{
  "runId": "3f9d2c1e-7b4a-4e8f-9a6b-2d1c0e5f7a8b",
  "macroId": "66f1a2b3c4d5e6f708192b01",
  "phase": "started",
  "ts": 1758801600000
}

macro-step — a macro asks the platform to do a step

Sent by a macro whose next instruction runs on the platform side. Optional.

{
  "runId": "3f9d2c1e-7b4a-4e8f-9a6b-2d1c0e5f7a8b",
  "macroId": "66f1a2b3c4d5e6f708192b01",
  "stepId": 0,
  "ts": 1758801600000
}

debug-response — diagnostics snapshot

The reply to a debug/diag command. Optional.

{
  "correlationId": "b7e4c2a1-5d3f-4a9e-8c7b-6f5e4d3c2b1a",
  "ts": 1758801600000,
  "ip": "192.168.1.42",
  "rssi": -61,
  "uptimeMs": 86400000,
  "freeHeap": 98304,
  "minFreeHeap": 61440,
  "maxAllocHeap": 65524,
  "ble": {
    "started": false,
    "advTotal": 0,
    "slotsSeen": 0,
    "released": true
  },
  "fw": "1.5.4",
  "mqttConnected": true,
  "configHash": 3735928559,
  "uplink": "wifi",
  "devices": [
    {
      "id": "66f1a2b3c4d5e6f708192a3b",
      "name": "Energy meter",
      "protocol": "rs485",
      "online": true,
      "lastPollMs": 850
    },
    {
      "id": "66f1a2b3c4d5e6f708192a3d",
      "name": "Room climate",
      "protocol": "i2c",
      "online": false,
      "lastPollMs": 30500,
      "lastError": "i2c nack at 0x76"
    }
  ],
  "recentLogs": [
    "[net] MQTT connected",
    "[modbus] read ok 66f1a2b3c4d5e6f708192a3b"
  ]
}

debug-log — live log lines

Published while a log tail started by debug/logs/start is active. Optional.

{
  "ts": 1758801600000,
  "seq": 12,
  "lines": [
    "[modbus] 66f1a2b3c4d5e6f708192a3b read 2 regs @30000 ok",
    "[net] rssi -61"
  ]
}

ble-discovery — sensors heard nearby

The reply to a ble/scan command. Optional.

{
  "correlationId": "b7e4c2a1-5d3f-4a9e-8c7b-6f5e4d3c2b1a",
  "ts": 1758801600000,
  "durationMs": 15000,
  "ignored": 4,
  "devices": [
    {
      "mac": "A4:C1:38:12:34:56",
      "rssi": -61,
      "name": "ATC_123456",
      "format": "pvvx",
      "encrypted": false,
      "fields": {
        "temperature": 21.5,
        "humidity": 48,
        "battery": 91
      }
    },
    {
      "mac": "D4:11:22:33:44:55",
      "rssi": -80,
      "format": "bthome",
      "encrypted": true,
      "fields": {}
    }
  ]
}

image-meta and image-chunk — an event image

Metadata first, then ordered base64 chunks. Experimental — the shape may change.

{
  "imageId": "img-123456789012345-1758801600000",
  "ts": 1758801600000,
  "trigger": "motion",
  "samples": [
    0.82,
    0.91
  ],
  "format": "jpeg",
  "width": 640,
  "height": 480,
  "size": 38912,
  "chunks": 26
}

{
  "imageId": "img-123456789012345-1758801600000",
  "idx": 0,
  "data": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAgGBgcGBQgHBwcJCQgKDBQNDAsLDBkSEw8UHRofHh0aHBwgJC4nICIsIxwcKDcpLDAxNDQ0Hyc5PTgyPC4zNDL/"
}

Downlink — platform to gateway

config-push — the config document

The full document, {"unchanged":true}, or a chunk. Core.

{
  "devices": [
    {
      "_id": "66f1a2b3c4d5e6f708192a3b",
      "protocol": "rs485",
      "conn": {
        "modbusId": 1,
        "baudRate": 9600,
        "dataBits": 8,
        "stopBits": 1,
        "parity": 0,
        "tickDuration": 10000
      },
      "tags": [
        {
          "name": "voltage",
          "registerType": "input",
          "mbFormat": "f32"
        },
        {
          "name": "current",
          "mbAddress": 6,
          "registerType": "input",
          "mbFormat": "f32",
          "mbWordOrder": "little"
        },
        {
          "name": "energy_kwh",
          "mbAddress": 342,
          "registerType": "input",
          "mbFormat": "u32",
          "isIntervalRead": false,
          "scaleFactor": 0.01
        }
      ]
    },
    {
      "_id": "66f1a2b3c4d5e6f708192a3c",
      "protocol": "gpio-digital-out",
      "conn": {
        "pinNumber": 26,
        "activeHigh": true,
        "defaultState": 0
      },
      "tags": [
        {
          "name": "relay",
          "gpioPin": 26
        }
      ]
    },
    {
      "_id": "66f1a2b3c4d5e6f708192a3d",
      "protocol": "i2c",
      "conn": {
        "sdaPin": 21,
        "sclPin": 22,
        "clockHz": 100000,
        "sampleIntervalMs": 30000
      },
      "tags": [
        {
          "name": "temperature",
          "i2cAddress": 118,
          "sensorModel": "BME280",
          "thresholdStart": -10,
          "thresholdEnd": 80
        },
        {
          "name": "humidity",
          "i2cAddress": 118,
          "sensorModel": "BME280"
        }
      ]
    }
  ],
  "success": true
}

The two short answers — nothing changed, and one part of a chunked transfer:

{
  "unchanged": true
}

{
  "p": 0,
  "n": 3,
  "h": 3735928559,
  "d": "eyJkZXZpY2VzIjpbeyJfaWQiOiI2NmYxYTJiM2M0ZDVlNmY3MDgxOTJhM2IiLCJwcm90b2NvbCI6InJzNDg1In1dfQ=="
}

gateway-cmd — a gateway-level command

Not acknowledged. Ignore what you do not implement. Optional.

{
  "command": "restart"
}

device-cmd — a device-level command

Answered on cmd/ack whenever it carries a correlationId. Read control is gateway-only; a directly connected device receives Modbus and actuator writes. Optional.

{
  "correlationId": "b7e4c2a1-5d3f-4a9e-8c7b-6f5e4d3c2b1a",
  "fc": 6,
  "address": 12,
  "value": 1500,
  "register_type": "holding"
}

A Modbus coil write through a gateway, and a poll-interval change:

{
  "correlationId": "b7e4c2a1-5d3f-4a9e-8c7b-6f5e4d3c2b1a",
  "fc": 5,
  "address": 3,
  "value": 1,
  "register_type": "coil"
}

{
  "command": "set/interval",
  "interval": 5000
}

firmware-request — start an OTA update

Optional. Report progress on firmware/response.

{
  "type": "update",
  "version": "1.5.4"
}

macros-push, macros-run, macros-abort — macros

The program set for this gateway, a request to run one, and a request to stop one. Optional. Abort is a network message: it cannot reach a gateway that is offline, so it is not a safety function.

{
  "macros": [
    {
      "macroId": "66f1a2b3c4d5e6f708192b01",
      "program": {
        "v": 1,
        "name": "Pulse pump",
        "params": [
          {
            "name": "ms",
            "default": 2000,
            "min": 100,
            "max": 10000
          }
        ],
        "vars": [
          "ms"
        ],
        "instructions": [
          {
            "op": "DWRITE",
            "dev": "66f1a2b3c4d5e6f708192a3c",
            "value": {
              "lit": 1
            }
          },
          {
            "op": "WAIT",
            "ms": {
              "var": "ms"
            }
          },
          {
            "op": "DWRITE",
            "dev": "66f1a2b3c4d5e6f708192a3c",
            "value": {
              "lit": 0
            }
          },
          {
            "op": "EMIT",
            "message": "pump pulsed",
            "severity": "info"
          }
        ]
      }
    }
  ]
}

{
  "macroId": "66f1a2b3c4d5e6f708192b01",
  "runId": "3f9d2c1e-7b4a-4e8f-9a6b-2d1c0e5f7a8b",
  "params": {
    "ms": 2000
  }
}

{
  "runId": "3f9d2c1e-7b4a-4e8f-9a6b-2d1c0e5f7a8b"
}

macro-program — one macro

The program format carried inside macros/push. Optional.

{
  "v": 1,
  "name": "Pulse pump",
  "params": [
    {
      "name": "ms",
      "default": 2000,
      "min": 100,
      "max": 10000
    }
  ],
  "vars": [
    "ms"
  ],
  "instructions": [
    {
      "op": "DWRITE",
      "dev": "66f1a2b3c4d5e6f708192a3c",
      "value": {
        "lit": 1
      }
    },
    {
      "op": "WAIT",
      "ms": {
        "var": "ms"
      }
    },
    {
      "op": "DWRITE",
      "dev": "66f1a2b3c4d5e6f708192a3c",
      "value": {
        "lit": 0
      }
    },
    {
      "op": "EMIT",
      "message": "pump pulsed",
      "severity": "info"
    }
  ]
}

Known quirks

Documented rather than fixed. A new implementation should tolerate all of them and need not reproduce any of them.

Conformance levels

Implementations

Versioning policy

• v1 is frozen. A message a v1 gateway sends today validates against these schemas indefinitely.
• Additions are announced in the changelog. A new optional property or a new optional topic is an addition; a gateway that ignores unknown keys and topics is unaffected.
• $ids never move. https://synacl.com/protocol/v1/schemas/<name>.json stays where it is; a validator that fetches by $id keeps working.
• A change that would break a conforming v1 gateway is a v2, with its own prefix, its own $ids and its own page. v1 would stay published.