Connect a Modbus TCP device
Modbus TCP devices are polled over the network by a gateway on the same LAN. That gateway can be an ESP32 running the Synacl firmware or a software gateway running synacl-gateway — the fields below are the same for both.
Protocol: modbus-tcp
Connection fields:
| Field | Meaning |
|---|---|
modbusId |
Unit/slave ID the device answers on, 1–247 |
ip |
Device IP address on the LAN |
port |
TCP port (default 502) |
tickDuration |
Publish interval in ms — how often readings are sent to Synacl. Cannot be shorter than your plan's minimum publish interval (see sizing your publish rate); a faster value is rejected when you save |
readIntervalMs |
Optional. How often the gateway reads the device (drives gateway-side alerts) |
Set the Modbus Device ID. One IP address often fronts several Modbus units — a serial-to-Ethernet converter or a multi-meter panel answers for each of them on the same socket, distinguished only by unit ID. Leave it at 1 only if the device genuinely is unit 1; otherwise reads either time out or, worse, return another unit's registers.
Steps
- Give the device a static IP (or DHCP reservation) on the gateway's network.
- Add a device with protocol modbus-tcp and enter the fields above.
- Map registers to tags.
If reads time out, check the port before anything else. A ping proves the device is powered and
on the network; it says nothing about whether the Modbus server is listening. The common mistake is a
port copied from somewhere else on the platform — the gateway's broker port 8883 is MQTT, not
Modbus — and it fails exactly like a dead device: no response, a three-second timeout every poll,
while ping to the same address still succeeds. Test the port itself from a machine on that LAN
(nc -vz <ip> 502), then confirm the unit ID. From firmware 1.5.1 the gateway names the address and
port it tried, so the device page shows TCP connect failed to 192.168.1.50:8883 rather than a bare
connection error.
Publish interval vs read interval. These are two different things:
- Publish interval is how often readings reach Synacl. It counts against your plan's rate limit. Devices on a gateway publish at most once per 10 seconds, so lower values change nothing.
- Read interval is how often the gateway actually queries the device. Threshold alerts and macros running on the gateway react at this rate, so leave it fast even when you publish slowly — you can poll a pump every 10 seconds for a trip condition while only reporting to the cloud once a minute. (Alarm limits evaluated in the cloud react at the publish interval instead — they only see what reaches Synacl.)
Directly-polled Modbus TCP devices (no gateway) have no separate read interval — the backend poller
reads and stores in one step, and it skips any device set below 1000 ms entirely. The poller decodes
every Modbus data format itself (s16, u32, s32, f32, either word
order), so 32-bit and float registers need no gateway firmware here.
Auto-disable after repeated failures: for a directly-polled Modbus-TCP device, if a poll fails
10 times in a row Synacl stops querying it and marks it Polling disabled (a device/poll-disabled
event is raised). Fix the cause, then click Re-enable polling on the device page — querying resumes
within about a minute. See My device shows offline.