Connect a Modbus server
Connect a Modbus TCP or Modbus RTU server, such as a PLC or an I/O module, to Synnax.
The Modbus integration reads and writes the coils and registers of Modbus TCP servers and of Modbus RTU servers on a serial port, such as PLCs and remote I/O modules. Modbus ASCII and Modbus RTU over TCP are not supported. In Synnax, a Modbus server is one unit at an IP address and port, or on a serial port. The read task and the write task add the addresses.
To reach several units behind one gateway or on one serial line, connect one server for each unit, with the same address and a different unit ID. Servers on the same host and port, or on the same serial port, share one connection, and their requests take turns.
Prerequisites
- Supported
- WindowsmacOSLinuxDocker
- Not supported
- NI Linux RT
- A running Driver that can reach the server on the network. Synnax Desktop runs one for you.
- For a serial device, a Driver on the computer that the serial adapter connects to. An RS-485 adapter must switch its transmit direction by itself, as most USB adapters do.
Connect a server
Console
Python
TypeScript
- In the devices toolbar, click (Connect device), then select Modbus server. You can also run the “Connect Modbus server” command.
- Enter a name for the server.
- In Transport, select TCP for a server on the network, or Serial for a device on a serial port.
- For TCP, enter the IP address or hostname of the server in Host, such as
192.168.1.20, and its port in Port. The default port is502. - For serial, enter the port in Serial port, such as
/dev/ttyUSB0on Linux orCOM3on Windows. Then select the Baud rate, Parity, and Stop bits of the device. - Enter the Unit ID. Keep
255for a TCP server you reach directly. For a unit behind a gateway or on a serial line, enter its unit ID. - In Byte order, select the order in which the device sends its bytes. See byte and word order.
- In Connect from, select the Driver that connects to the server. If only one running Driver has Modbus enabled, the Console selects it for you.
- If the device is slow or limits its requests, change the settings in the Timing and Requests sections. See connection options.
- Click Connect.
The Console asks the Driver to read holding register 0 of the unit before it saves the server. Any reply, an exception from the unit included, shows that the unit answers. A gateway exception that says the unit did not respond counts as no answer. If the unit does not answer, the dialog shows the error and keeps your entries.
A server on a serial port uses the same dialog:
from synnax import modbus
rack = client.racks.retrieve_embedded_rack()
device = client.devices.create(
modbus.Device(
name="Pump skid PLC",
host="192.168.1.20",
port=502,
location="192.168.1.20:502",
rack=rack.key,
configured=True,
)
)For a serial device, pass transport="rtu" and the line settings:
device = client.devices.create(
modbus.Device(
name="Flow meter",
transport="rtu",
serial_port="/dev/ttyUSB0",
baud_rate=9600,
parity="none",
unit_id=3,
location="/dev/ttyUSB0",
rack=rack.key,
configured=True,
)
)Python does not test the connection. Pass the key of a rack, or the device has no
Driver. Pass configured=True, or the Console asks you to configure the server.
const rack = await client.racks.retrieve({ name: "Node 1 Embedded Driver" });
await client.devices.create({
key: crypto.randomUUID(),
name: "Pump skid PLC",
rack: rack.key,
location: "192.168.1.20:502",
make: "Modbus",
model: "Modbus",
configured: true,
properties: {
connection: { host: "192.168.1.20", port: 502, swapBytes: false, swapWords: false },
read: { index: 0, channels: {} },
write: { channels: {} },
},
});For a serial device, set connection to the serial fields:
connection: {
transport: "rtu",
serialPort: "/dev/ttyUSB0",
baudRate: 9600,
parity: "none",
stopBits: 1,
unitId: 3,
swapBytes: false,
swapWords: false,
},TypeScript does not test the connection.
After you connect a server, the Driver checks the unit every few seconds and shows the result as the server status in the devices toolbar. If a task got a reply from the unit since the last check, the Driver sends no request. Otherwise it reads holding register 0. See device statuses.
Connection options
The dialog puts the options in three sections. Connection holds the transport, the
address, the unit ID, the byte order, and Connect from. Timing holds the
timeout, the retries, and the request delay. Requests holds the other options. The
Timeout and Request delay fields take a duration, such as 500ms or 2s.
Byte order sets the order of every register channel of the server. A channel can override it. The letters show the bytes of a 32-bit value in the order the device sends them, with A the most significant byte.
A request that times out or loses its connection is sent again at once, up to Retries times. When the unit does not reply to three attempts in a row, the Driver stops sending requests to it for 10 seconds, so that a unit that is off does not slow down the other units on the connection. A connection that fails does not count toward the three.
Diagnostics
To see how the requests to a server go, right-click the server in the devices toolbar and select Edit connection. The Diagnostics section shows the counts that the Driver reports for the unit:
The counts start again from zero when the Driver restarts. Many timeouts point to a Timeout that is too short or a unit that is busy. Many exceptions point to an address that the unit does not have.
Serial devices
All servers on one serial port must use the same line settings. When a task or a check uses a server whose settings differ from the settings in use on the port, it fails with an error that names both. The Driver always uses 8 data bits, as Modbus RTU requires. The baud rate is one of 1200, 2400, 4800, 9600, 19200, 38400, 57600, 115200, or 230400, the rates that the Driver can set on Linux, macOS, and Windows. Between two requests, the Driver waits for the silence of 3.5 characters that Modbus RTU requires, or 1.75 ms above 19200 baud.
On Linux, the user that runs the Driver needs access to the serial port. This usually
means that the user is in the dialout group.
Troubleshooting
- Cause
The Driver cannot open a connection to the address and the port, or the connection times out.
- Fix
Check the address and the port. Make sure that the server allows Modbus TCP connections from the computer that runs the Driver.
- Cause
The server accepts the connection, but the unit does not answer.
- Fix
Check the Unit ID. A gateway needs the unit ID of the device behind it. Some servers answer only unit 1 or unit 0.
- Cause
The gateway is on, but the unit behind it does not answer.
- Fix
Check the unit, its wiring, and the Unit ID.
- Cause
The serial port does not exist on the computer that runs the Driver.
- Fix
Check the port name and that the adapter is plugged in.
- Cause
The Driver cannot open the serial port.
- Fix
On Linux, add the user that runs the Driver to the
dialoutgroup.
- A serial device does not answer.
- Cause
The line settings of the server do not match the device, or the wires are swapped.
- Fix
Check that the baud rate, parity, and stop bits match the device, and that the device uses 8 data bits. On an RS-485 line, check that the A and B wires are not swapped.
For other problems, see Troubleshoot hardware.