Modbus TCP Route

Modbus TCP Overview

The MODBUS_TCP route enables communication with PLCs, RTUs, and industrial devices using the Modbus TCP/IP protocol. It supports reading and writing registers and coils with configurable polling intervals and automatic batch optimization.

Modbus TCP is one of the most widely supported industrial protocols. If your device supports Modbus, this route provides a reliable way to integrate it with MQTT.

Basic Syntax

DEFINE ROUTE ModbusDevice WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH PORT '502'
        WITH SLAVE_ID '1'
    ADD MAPPING SensorReadings
        WITH EVERY 500 MILLISECONDS
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "modbus/temperature"

Connection Configuration

MODBUS_CONFIG Parameters

HOST

string

required

Modbus TCP server hostname or IP address.

PORT

integer

Modbus TCP port. Default: 502.

SLAVE_ID

integer

Modbus slave/unit ID (1-247). Default: 1.

CONNECTION_TIMEOUT

integer

Connection timeout in milliseconds. Default: 5000.

READ_TIMEOUT

integer

Read operation timeout in milliseconds. Default: 1000.

WRITE_TIMEOUT

integer

Write operation timeout in milliseconds. Default: 1000.

RETRY_COUNT

integer

Number of retry attempts on failure. Default: 3.

RETRY_DELAY

integer

Delay between retries in milliseconds. Default: 100.

Connection Example

ADD MODBUS_CONFIG
    WITH HOST "192.168.1.100"
    WITH PORT '502'
    WITH SLAVE_ID '1'
    WITH CONNECTION_TIMEOUT '5000'
    WITH READ_TIMEOUT '1000'
    WITH WRITE_TIMEOUT '1000'
    WITH RETRY_COUNT '3'
    WITH RETRY_DELAY '100'

Address Types

Modbus defines four address spaces:

Address Type	Description	Function Codes	Typical Use
`HOLDING_REGISTER`	Read/Write 16-bit registers	FC03, FC06, FC16	Setpoints, configuration
`INPUT_REGISTER`	Read-only 16-bit registers	FC04	Sensor values, measurements
`COIL`	Read/Write single bits	FC01, FC05, FC15	Digital outputs, controls
`DISCRETE_INPUT`	Read-only single bits	FC02	Digital inputs, status

Most Modbus devices use Holding Registers for configuration and Input Registers for measured values. Check your device documentation for the correct address type.

Data Types

DATA_TYPE

string

required

The data type determines how raw register values are interpreted:

Data Type	Size	Description
`BOOL`	1 bit	Boolean value (for coils/discrete inputs)
`INT8`	8 bits	Signed 8-bit integer
`UINT8`	8 bits	Unsigned 8-bit integer
`INT16`	16 bits	Signed 16-bit integer (1 register)
`UINT16`	16 bits	Unsigned 16-bit integer (1 register)
`INT32`	32 bits	Signed 32-bit integer (2 registers)
`UINT32`	32 bits	Unsigned 32-bit integer (2 registers)
`INT64`	64 bits	Signed 64-bit integer (4 registers)
`UINT64`	64 bits	Unsigned 64-bit integer (4 registers)
`FLOAT`	32 bits	32-bit floating point (2 registers)
`DOUBLE`	64 bits	64-bit floating point (4 registers)
`STRING`	Variable	ASCII string across multiple registers

TAG Configuration

Complete TAG Parameters

ADD TAG TemperatureSensor
    WITH ADDRESS "100"
    WITH ADDRESS_TYPE "HOLDING_REGISTER"
    WITH DATA_TYPE "FLOAT"
    WITH SOURCE_TOPIC "modbus/sensors/temperature"
    WITH SCALING "0.1"
    WITH OFFSET "0"
    WITH UNIT "°C"
    WITH DECIMAL_PLACES "2"
    WITH MIN_VALUE "-40"
    WITH MAX_VALUE "150"
    WITH DEADBAND "0.5"
    WITH PUBLISH_MODE "JSON"
    WITH WRITABLE "true"
    WITH DESTINATION_TOPIC "modbus/sensors/temperature/set"
    WITH BYTE_ORDER "BIGENDIAN"
    WITH WORD_ORDER "BIGENDIAN"
    WITH DESCRIPTION "Main process temperature sensor"

TAG Parameters Reference

Address Configuration

ADDRESS

string

required

ADDRESS_TYPE

string

required

Type of Modbus address: HOLDING_REGISTER, INPUT_REGISTER, COIL, or DISCRETE_INPUT.

Value Transformation

SCALING

double

Multiplier applied to raw value. Default: 1.0. Example: Raw value 245 with SCALING “0.1” becomes 24.5.

OFFSET

double

Value added after scaling. Default: 0.0. Formula: result = (raw * scaling) + offset.

DECIMAL_PLACES

integer

Number of decimal places in published value. Default: 2.

Filtering

MIN_VALUE

double

Minimum allowed value. Values below this threshold are not published.

MAX_VALUE

double

Maximum allowed value. Values above this threshold are not published.

DEADBAND

double

Minimum change required to publish a new value. Default: 0.0.

Publishing

SOURCE_TOPIC

string

MQTT topic to publish read values.

PUBLISH_MODE

string

Output format: VALUE_ONLY or JSON. Default: VALUE_ONLY.

UNIT

string

Engineering unit for documentation (e.g., °C, bar, RPM).

DESCRIPTION

string

Human-readable description of the TAG.

Write Configuration

WRITABLE

boolean

Allow writing to this register/coil. Default: false.

DESTINATION_TOPIC

string

MQTT topic to subscribe for write commands.

Byte Ordering

BYTE_ORDER

string

Byte order for multi-byte values: BIGENDIAN or LITTLEENDIAN. Default: BIGENDIAN.

WORD_ORDER

string

Word order for 32/64-bit values: BIGENDIAN or LITTLEENDIAN. Default: BIGENDIAN.

Different manufacturers use different byte/word ordering. If values appear incorrect, try changing BYTE_ORDER or WORD_ORDER.

Event-Based Operations

For on-demand Modbus operations (not polling), use the EVENT syntax:

ADD EVENT ReadOnDemand
    WITH SOURCE_TOPIC "modbus/commands/read"
    WITH DESTINATION_TOPIC "modbus/responses/read"
    WITH QUERY '{"operation": "READ_HOLDING_REGISTERS", "start_address": 0, "count": 10}'

Supported Operations

Operation	Description
`READ_HOLDING_REGISTERS`	Read holding registers (FC03)
`READ_INPUT_REGISTERS`	Read input registers (FC04)
`READ_COILS`	Read coils (FC01)
`READ_DISCRETE_INPUTS`	Read discrete inputs (FC02)
`WRITE_SINGLE_REGISTER`	Write single holding register (FC06)
`WRITE_MULTIPLE_REGISTERS`	Write multiple holding registers (FC16)
`WRITE_SINGLE_COIL`	Write single coil (FC05)
`WRITE_MULTIPLE_COILS`	Write multiple coils (FC15)

Complete Examples

Basic Sensor Reading
Multiple Polling Rates
Bidirectional Control
Coils and Digital I/O

Read temperature and pressure from a Modbus device:

DEFINE ROUTE ProcessSensors WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH PORT '502'
        WITH SLAVE_ID '1'
    ADD MAPPING Sensors
        WITH EVERY 1 SECOND
        ADD TAG Temperature
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "process/temperature"
            WITH SCALING "0.1"
            WITH UNIT "°C"
        ADD TAG Pressure
            WITH ADDRESS "102"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "process/pressure"
            WITH UNIT "bar"

Group TAGs by update frequency:

DEFINE ROUTE PLCConnection WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.50"
        WITH PORT '502'
        WITH SLAVE_ID '1'
    
    ADD MAPPING FastLoop
        WITH EVERY 100 MILLISECONDS
        ADD TAG MotorSpeed
            WITH ADDRESS "200"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "plc/motor/speed"
        ADD TAG MotorCurrent
            WITH ADDRESS "201"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "plc/motor/current"
    
    ADD MAPPING SlowLoop
        WITH EVERY 5 SECONDS
        ADD TAG TotalRuntime
            WITH ADDRESS "300"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "UINT32"
            WITH SOURCE_TOPIC "plc/stats/runtime"
        ADD TAG FaultCode
            WITH ADDRESS "400"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "UINT16"
            WITH SOURCE_TOPIC "plc/status/fault"

Read values and write setpoints:

DEFINE ROUTE ControlSystem WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.100"
        WITH PORT '502'
        WITH SLAVE_ID '1'
    ADD MAPPING ControlLoop
        WITH EVERY 500 MILLISECONDS
        ADD TAG ProcessValue
            WITH ADDRESS "100"
            WITH ADDRESS_TYPE "INPUT_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "control/pv"
            WITH PUBLISH_MODE "JSON"
        ADD TAG Setpoint
            WITH ADDRESS "200"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "control/sp"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "control/sp/set"
            WITH MIN_VALUE "0"
            WITH MAX_VALUE "100"
        ADD TAG OutputValue
            WITH ADDRESS "300"
            WITH ADDRESS_TYPE "HOLDING_REGISTER"
            WITH DATA_TYPE "FLOAT"
            WITH SOURCE_TOPIC "control/output"

Read digital inputs and control outputs:

DEFINE ROUTE DigitalIO WITH TYPE MODBUS_TCP
    ADD MODBUS_CONFIG
        WITH HOST "192.168.1.75"
        WITH PORT '502'
        WITH SLAVE_ID '1'
    ADD MAPPING DigitalInputs
        WITH EVERY 100 MILLISECONDS
        ADD TAG StartButton
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "DISCRETE_INPUT"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "io/inputs/start"
        ADD TAG StopButton
            WITH ADDRESS "1"
            WITH ADDRESS_TYPE "DISCRETE_INPUT"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "io/inputs/stop"
        ADD TAG RunningLight
            WITH ADDRESS "0"
            WITH ADDRESS_TYPE "COIL"
            WITH DATA_TYPE "BOOL"
            WITH SOURCE_TOPIC "io/outputs/running"
            WITH WRITABLE "true"
            WITH DESTINATION_TOPIC "io/outputs/running/set"

Troubleshooting

Connection Timeout

Verify IP address and port are correct
Check firewall settings (port 502 must be open)
Ensure device is powered on and connected to network
Try increasing CONNECTION_TIMEOUT

Incorrect Values

Verify ADDRESS matches device documentation
Check BYTE_ORDER and WORD_ORDER settings
Confirm DATA_TYPE matches register size
Verify SCALING and OFFSET calculations

Write Operations Fail

Ensure WRITABLE is set to “true”
Verify ADDRESS_TYPE is HOLDING_REGISTER or COIL
Check device permissions for write operations
Verify value is within MIN_VALUE and MAX_VALUE

Slave ID Errors

Confirm correct SLAVE_ID (usually 1 for TCP devices)
Some gateways use different slave IDs for different devices
Check device documentation for correct unit ID

Next Steps

Modbus Serial

Connect to RS-232/RS-485 Modbus RTU devices.

Industrial Overview

Learn common patterns for all industrial routes.

Quick Start

MQTT Broker

LoT Language

LoT Notebooks

Actions

Routes

Models

Rules

Modbus TCP Overview

Basic Syntax

Connection Configuration

MODBUS_CONFIG Parameters

Connection Example

Address Types

Data Types

TAG Configuration

Complete TAG Parameters

TAG Parameters Reference

Event-Based Operations

Supported Operations

Complete Examples

Troubleshooting

Next Steps

Modbus Serial

Industrial Overview

Quick Start

MQTT Broker

LoT Language

LoT Notebooks

Actions

Routes

Models

Rules

​Modbus TCP Overview

​Basic Syntax

​Connection Configuration

​MODBUS_CONFIG Parameters

​Connection Example

​Address Types

​Data Types

​TAG Configuration

​Complete TAG Parameters

​TAG Parameters Reference

​Event-Based Operations

​Supported Operations

​Complete Examples

​Troubleshooting

​Next Steps

Modbus Serial

Industrial Overview

Modbus TCP Overview

Basic Syntax

Connection Configuration

MODBUS_CONFIG Parameters

Connection Example

Address Types

Data Types

TAG Configuration

Complete TAG Parameters

TAG Parameters Reference

Event-Based Operations

Supported Operations

Complete Examples

Troubleshooting

Next Steps