v0.61.3
ReferenceHardwareModbusConnect to a server

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

  1. In the devices toolbar, click (Connect device), then select Modbus server. You can also run the “Connect Modbus server” command.
  2. Enter a name for the server.
  3. In Transport, select TCP for a server on the network, or Serial for a device on a serial port.
  4. 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 is 502.
  5. For serial, enter the port in Serial port, such as /dev/ttyUSB0 on Linux or COM3 on Windows. Then select the Baud rate, Parity, and Stop bits of the device.
  6. Enter the Unit ID. Keep 255 for a TCP server you reach directly. For a unit behind a gateway or on a serial line, enter its unit ID.
  7. In Byte order, select the order in which the device sends its bytes. See byte and word order.
  8. 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.
  9. If the device is slow or limits its requests, change the settings in the Timing and Requests sections. See connection options.
  10. 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:

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.

Console label Python field Default Notes
Transport transport tcp tcp for Modbus TCP, or rtu for Modbus RTU on a serial port.
Host host TCP only. An IPv4 address, an IPv6 address, or a hostname.
Port port 502 TCP only. Python has no default.
Serial port serial_port RTU only. Such as /dev/ttyUSB0 or COM3.
Baud rate baud_rate 19200 RTU only. See serial devices.
Parity parity even RTU only. none, even, or odd.
Stop bits stop_bits 1 RTU only. 1 or 2.
Connect from rack The Driver that connects to the server.
Unit ID unit_id 255, or 1 for RTU The unit that requests go to: 0 to 255 for TCP, and 1 to 247 for RTU.
Byte order swap_bytes, swap_words Word swap See the table below.
Timeout timeout_ms 1000 The time to connect, and to wait for each reply, from 1 to 60000 milliseconds.
Retries retries 1 How many times the Driver sends a request again at once after a fault, from 0 to 10.
Request delay delay_ms 0 The wait between requests on the connection, from 0 to 5000 milliseconds.
Max registers max_registers 125 The most registers in one read, from 1 to 125.
Max gap max_gap 125 The widest gap between channels that one read spans. 0 reads only yours.
Write codes write_codes multiple multiple writes with function codes 15 and 16. single uses 05 and 06.
Mask write (FC22) mask_write_supported false Bit writes in a holding register use function code 22, in one request.

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.

Byte order swap_bytes swap_words
Big-endian (ABCD) False True
Byte swap (BADC) True True
Word swap (CDAB) False False
Little-endian (DCBA) True False

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:

Count Meaning
Requests The requests that the Driver sent, retries included.
Retries The requests that the Driver sent again after a timeout or a fault.
Timeouts The requests that the unit did not answer in time.
Exceptions The requests that the unit, or a gateway in front of it, rejected.
Last response The time from the last answered request to its reply.
Longest response The longest time from a request to its reply.

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

  • Connection refused
    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.

  • Connection timed out
    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.

  • Gateway target device failed to respond
    Cause

    The gateway is on, but the unit behind it does not answer.

    Fix

    Check the unit, its wiring, and the Unit ID.

  • No such file or directory
    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.

  • Permission denied
    Cause

    The Driver cannot open the serial port.

    Fix

    On Linux, add the user that runs the Driver to the dialout group.

  • 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.