Modbus TCP/RTU Guide

Overview

ControlBird speaks Modbus in both directions. As a client, it polls PLCs, variable-frequency drives, power meters, and sensors and writes their register values straight into Store entities. As a server, it exposes selected entity fields at fixed register addresses so external SCADA systems and Modbus masters can read and write them. Both TCP and RTU (serial) transports are supported on the client side, and TCP is supported on the server side.

Every part of a Modbus integration is created and monitored through the Device Manager app in the Platform UI. There are no manual configuration files to edit. For a hands-on introduction, see walkthrough step 7: Connect a Device, and for securing TCP connections see the Certificates guide.

Architecture

A Modbus integration is assembled from three layers of entities. The controller manages the connection lifecycle, the endpoint carries the transport parameters, and the mappers bind individual registers to entity fields.

The client-side ModbusController uses TCP or RTU based on the endpoint type it references. Both the TCP and RTU endpoints share common settings: logging, connection health monitoring, and TLS.

Supported Function Codes

ControlBird implements the standard Modbus function codes for reading and writing the four register types. Function codes are selected automatically from the mapper's RegisterType and Direction.

Register types

Client Configuration (TCP)

To poll a device over Modbus TCP, create a ModbusTcpEndpoint that points at the remote server, then attach it to a ModbusController.

Client Configuration (RTU / Serial)

For serial devices, create a ModbusRtuEndpoint instead. A ModbusController referencing it will automatically use the RTU transport. The serial parameters must match the device exactly.

Mapping Registers

A ModbusMapper binds a register range on the device to a field on a target entity. The controller connects at startup, then each mapper polls its registers at the configured interval and writes the decoded value into the Store.

Data types and word order

Register values can be decoded as INT16, UINT16, INT32, UINT32, INT64, FLOAT32, FLOAT64, or BLOB (raw binary). Multi-register values combine consecutive 16-bit registers using RegisterCount. A 32-bit value spans 2 registers; a 64-bit value spans 4.

• ByteOrder controls the order of bytes within each register. BigEndian is the Modbus standard.
• WordOrder controls how the 16-bit registers are combined. HighWordFirst is standard; LowWordFirst swaps the 16-bit word pairs for non-standard devices.

Example mapper configurations

# 32-bit integer from holding registers 100-101
RegisterType   = HoldingRegister
Address        = 100
RegisterCount  = 2
ByteOrder      = BigEndian
WordOrder      = HighWordFirst
PollIntervalMs = 1000
Direction      = Read

# 32-bit float from input registers 0-1
RegisterType   = InputRegister
Address        = 0
RegisterCount  = 2
ByteOrder      = BigEndian
Direction      = Read   # TargetField is a Float value

# Single coil (on/off) at address 10
RegisterType   = Coil
Address        = 10
RegisterCount  = 1
Direction      = Read   # TargetField is a Bool value

Server Mode

ControlBird can also act as a Modbus TCP server, presenting entity fields to external masters. Create a ModbusTcpServerEndpoint that binds a listen address and port, attach it to a ModbusTcpServerController, then add ModbusServerMapper entities to expose individual fields.

Server mappers use Get and Put directions, which differ from the client's Read and Write. Get services client reads of the field, and Put accepts client writes into the field. Each server mapper defines a StartAddress in the server's address space.

# Expose an entity field as holding register 200
StartAddress  = 200
RegisterType  = HoldingRegister
RegisterCount = 1
Direction     = Get        # serviced when a client reads
SourcePath    = entity.field

Setup Workflow

1. Create a ModbusTcpEndpoint or ModbusRtuEndpoint with the device's connection details.
2. Create a ModbusController that references the endpoint (TCP vs RTU is auto-detected).
3. Add ModbusMapper entities specifying register type, address, count, byte/word order, poll interval, direction, and target field.
4. The controller connects at startup; mappers poll their registers and update target values.
5. For server mode, create a ModbusTcpServerEndpoint, a ModbusTcpServerController, and ModbusServerMapper entities for each exposed field.
6. Enable per-endpoint communication logging while bringing a device online, then disable it once stable.

Limitations

• RTU is supported on the client side only; there is no RTU server.
• The server is poll-only: no server-initiated pushes or subscriptions.
• Coils and discrete inputs map to boolean fields only and cannot carry numeric values.
• Word order applies only to multi-register values (RegisterCount > 1).
• The default port 502 is below 1024, so binding it on Unix requires elevated privileges.