Connect a Modbus server

Connect a Modbus TCP 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, such as PLCs and remote I/O modules. Modbus RTU and Modbus ASCII are not supported. In Synnax, a Modbus server is one IP address and port. The read task and the write task add the addresses.

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.

Connect a server

In the devices toolbar, click (Connect device), then select Modbus TCP server. You can also run the “Connect Modbus server” command.
Enter a name for the server.
In Host, enter the IPv4 address of the server, such as 192.168.1.20.
In Port, enter the port of the server. The default is 502.
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 sends its bytes or words in a different order, turn on Swap bytes or Swap words. See byte and word order.
Click Connect.

The Console connects to the server before it saves it. If the connection fails, the dialog shows the error and keeps your entries.

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,
    )
)

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: {} },
  },
});

TypeScript does not test the connection.

After you connect a server, the Driver connects to it again every few seconds and shows the result as the server status in the devices toolbar. See device statuses.

Connection options

Console label	Python field	Default	Notes
Host	`host`		An IPv4 address. Hostnames, such as `localhost`, fail.
Port	`port`	`502`	The TCP port. Python has no default.
Connect from	`rack`		The Driver that connects to the server.
Swap bytes	`swap_bytes`	Off	Swaps the two bytes in each register.
Swap words	`swap_words`	Off	Puts the high word first in 32-bit and 64-bit values.

Swap bytes and Swap words set the default for every register channel of the server. A channel can override them. The Driver always sends unit ID 255. There is no option to change it.

Troubleshooting

Connect fails with a hostname

The Driver accepts only IPv4 addresses. Enter the address of the server. For a server on the same computer as the Driver, enter 127.0.0.1.

Connect fails with “Connection refused” or a timeout

Check the address and the port. Make sure that the server allows Modbus TCP connections from the computer that runs the Driver.

The server connects but does not answer requests

The server, or the gateway in front of it, needs a unit ID other than 255. The Driver cannot send a different unit ID.

For other problems, see Troubleshoot hardware.

Previous in LabJack

Write task

Read task