Virtual Modbus TCP & RTU Devices

The virtual Modbus devices are software-based interfaces for communication via Modbus TCP or Modbus RTU. They map the data exchanged with external Modbus devices to the process image of the RevPi. This allows other software components to access the Modbus data in the same way as input and output data from an expansion module.

A RevPi can be used as either a Modbus client or a Modbus server:

As a Modbus client, the RevPi initiates communication and reads data from or writes data to a Modbus server.
As a Modbus server, the RevPi provides data and responds to requests from a Modbus client.

The required interface is configured as a virtual device in the PiCtory application. Different variants are available depending on the transmission type, role, and required process image size:

Modbus TCP
Modbus RTU

Modbus TCP Server
Modbus TCP Server (512 I/O words)
Modbus TCP Client
Modbus TCP Client (150 input words)

Modbus RTU Server
Modbus RTU Server (512 I/O words)
Modbus RTU Client
Modbus RTU Client (150 input words)

Each virtual Modbus device provides up to 32 input registers and 32 output registers in the process image. For larger amounts of data, up to 30 additional virtual Modbus devices can be configured.

Virtual Modbus devices are suitable for applications such as:

Connecting sensors, actuators, and measuring devices
Exchanging data with controllers and gateways
Providing process values to other Modbus devices
Transferring measured values, setpoints, and control commands to the process image

Note	As of RevPi Bookworm (08/2025) the firewall on the RevPi must also be enabled to allow the default ports of the Modbus server: ▷ Add the service revpi-modbus-default to the firewall settings in Cockpit, see Firewall.

Modbus client and Modbus server #

In the Modbus protocol, each device assumes one of two roles:

Modbus client

The Modbus client initiates communication:

Reads registers from a Modbus server
Writes registers to a Modbus server
Initiates all Modbus requests

Modbus server

The Modbus server provides its data in the form of registers:

Responds to requests from a Modbus client
Provides registers for reading or writing

Transmission Types #

Modbus TCP
Modbus RTU

Communication over TCP/IP networks
Based on the Modbus protocol
Device identification by IP address and Unit ID

Serial communication
Binary data transmission
Uses a server address to address bus participants

How Modbus Registers Work:

A Modbus register is a 16-bit memory location (2 bytes) used to store and transmit data. On the RevPi, registers are represented as input or output words in the process image.

Different registers may be implemented depending on the device. Depending on the manufacturer, register addressing starts at either address 0 or address 1.

Register Types

Modbus defines four logical memory areas.

Holding Registers (40001 … 49999)
- Readable and writable
- Typically used for setpoints and configuration data
- Function codes 03, 06, and 16
Input Registers (30001 … 39999)
- Read-only
- Typically used for measured values
- Function code 04
Coils (00001 … 09999)
- Individual bits
- Readable and writable
- Typically used for digital outputs
- Function codes 01, 05, and 15
Discrete Inputs (10001 … 19999)
- Individual bits
- Read-only
- Typically used for digital inputs
- Function code 02

Addressing

The same address is represented differently depending on the context.

Protocol level: 0-based addressing (0 … 65535)
User representation: 1-based addressing with a range prefix (e.g., 40001)

Example: Holding Register 40001 is transmitted as address 0 in the Modbus protocol.

Data Formats

Because a register contains only 16 bits, larger data types are distributed across multiple registers.

32-bit integer or float: 2 registers
64-bit integer or double: 4 registers
Strings: One or two characters per register, depending on the device

Byte and Word Order

Within a register, Modbus uses big-endian byte order by default.

For data types that occupy multiple registers, the register order (word order) may also vary by manufacturer.

Modbus Function Codes #

The supported function codes depend on the device.

Code	Function
0x01	Read Coils
0x02	Read Discrete Inputs
0x03	Read Holding Registers
0x04	Read Input Registers
0x05	Write Single Coil
0x06	Write Single Register
0x0F	Write Multiple Coils
0x10	Write Multiple Registers

Code

Function

0x01

Read Coils

0x02

Read Discrete Inputs

0x03

Read Holding Registers

0x04

Read Input Registers

0x05

Write Single Coil

0x06

Write Single Register

0x0F

Write Multiple Coils

0x10

Write Multiple Registers

Configuring Communication #

Modbus TCP
Modbus RTU

The following parameters are required:

Server IP address
TCP port (default: 502)
Unit ID

The Unit ID is used depending on the device architecture:

For a direct Modbus TCP device, it identifies the addressed server.
Behind a Modbus TCP-to-RTU gateway, it addresses the required RTU Server (1 … 247). Unit ID 255 is often used to address the gateway itself. Refer to the documentation from the respective manufacturer for the applicable setting.

Configure the serial interface using the following parameters:

Baud rate
Data bits
Parity
Stop bits
Server address: The server address uniquely identifies the required Modbus server on an RTU bus.
Permitted address range: 1 … 247
Address 0 is reserved for broadcast messages.
Each server on the same bus requires a unique address.

Communication Sequence #

The Modbus client establishes a connection to the Modbus server.
The client sends a function code and the required register address.
The server responds to the request with the requested data or confirms the write operation.

Examples #

Modbus TCP
Modbus RTU

Required information:

Server IP address: 192.168.0.103
TCP port: 502
Unit ID: 255
Register: 1000
Function: Read Holding Registers