# 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](https://docs.synnaxlabs.com/reference/hardware/modbus/read-task) and the [write task](https://docs.synnaxlabs.com/reference/hardware/modbus/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

[Enterprise](https://docs.synnaxlabs.com/reference/get-started/editions "Needs Synnax Enterprise")

**Console**

1. In the [devices toolbar](https://docs.synnaxlabs.com/reference/hardware/devices#devices-toolbar), click (**Connect device**), then select **Modbus TCP server**. You can also run the “Connect Modbus server” command.
2. Enter a name for the server.
3. In **Host**, enter the IPv4 address of the server, such as `192.168.1.20`.
4. In **Port**, enter the port of the server. The default is `502`.
5. 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.
6. If the device sends its bytes or words in a different order, turn on **Swap bytes** or **Swap words**. See [byte and word order](https://docs.synnaxlabs.com/reference/hardware/modbus/read-task#byte-and-word-order).
7. 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.

[](https://synnax.nyc3.cdn.digitaloceanspaces.com/docs/device-drivers/modbus/connect-server/modbus-connect-dark.mp4#t=0.001)

**Python**

```python
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.

**TypeScript**

```typescript
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](https://docs.synnaxlabs.com/reference/hardware/devices#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](https://docs.synnaxlabs.com/reference/hardware/troubleshooting#failed-to-reach-device-or-failed-to-reach-server).