Modbus Integration Guide

Communicate with PLCs, drives, meters, and sensors using MaestroHub's Modbus connector. This guide explains connection options, function authoring, pipeline usage, and advanced tuning for reliable operations.

Overview

With the Modbus connector you gain:

• Support for TCP, RTU, and ASCII transports through a single configuration model
• Reusable read/write functions covering coils, discrete inputs, holding registers, and input registers (FC01–FC06, FC15–FC16)
• Rich data type support — raw, int16, uint16, int32, uint32, float32, int64, float64, bool, string, hex, and bits
• Connection diagnostics including retries, timeouts, health checks, and automatic reconnection
• Quick Add for bulk function creation via table entry or CSV import

Connection Configuration

Creating a Modbus Connection

Navigate to Connections → New Connection → Modbus and configure the following settings. The form is organized into five tabs: Connection, Transport, Advanced, Functions, and Health.

1. Profile Information

Field	Default	Description
Profile Name	—	A descriptive name for this connection profile (required, max 100 characters). Must be unique across all connections.
Description	—	Optional description for this Modbus connection

2. Connection Mode Settings

Field	Default	Description
Transport Mode	tcp	Modbus communication protocol: TCP (Ethernet), RTU (Serial Binary), or ASCII (Serial Text) — required
Unit ID	1	Modbus slave unit identifier (0–247)

3. TCP Transport Settings

(Only displayed when Transport Mode = TCP)

Field	Default	Description
IP Address:Port	localhost:502	Target device address in host:port format (standard Modbus TCP port is 502) — required
Connect Timeout (ms)	3000	Maximum time to wait for TCP connection (1,000–60,000 ms)
Enable TCP Keep-Alive	true	Send periodic keep-alive probes to detect connection failures
Keep Alive Period (ms)	30000	TCP keep-alive probe interval (1,000–1,800,000 ms)

4. Serial Transport Settings

(Only displayed when Transport Mode = RTU or ASCII)

Field	Default (RTU)	Default (ASCII)	Description
Serial Device	/dev/ttyUSB0	/dev/ttyUSB0	Serial port device path (e.g., /dev/ttyUSB0 on Linux, COM3 on Windows) — required
Baud Rate	9600	9600	Serial communication speed (1200/2400/4800/9600/19200/38400/57600/115200) — required
Data Bits	8	7	Number of data bits per character (7 or 8) — required
Parity	N (None)	E (Even)	Error detection method (N=None / E=Even / O=Odd) — required
Stop Bits	1	1	Number of stop bits per character (1 or 2) — required
RS-485 Mode	false	false	Enable RS-485 transceiver mode (direction control)

5. Advanced Settings

The Advanced tab contains timeout, retry, and serial timing options:

5a. Timeout & Retry Configuration

Field	Default	Description
Request Timeout (ms)	5000	Maximum time to wait for a Modbus response (1,000–60,000 ms)
Idle Timeout (ms)	10000	Close connection after idle period (0–600,000 ms; 0 = never)
Retry Count	2	Number of retries on communication failure (0–10)
Retry Delay (ms)	500	Delay between retry attempts (100–60,000 ms)

5b. Serial Advanced Options

(Only displayed when Transport Mode = RTU or ASCII)

Field	Default	Description
Inter-Frame Delay (ms)	0	Silent interval between frames (0–10,000 ms; 0 = automatic per Modbus spec)
Inter-Character Delay (ms)	0	Delay between characters (0–1,000 ms; 0 = automatic)
Read Timeout (ms)	0	Low-level serial read timeout (0–10,000 ms; 0 = use default)

6. Health Check Configuration

Health check is always enabled for Modbus connections to ensure reliable device communication.

6a. Basic Health Check Settings

Field	Default	Description
Health Check Method	status	Health check type: Status (connection test only) or Read (perform an actual device read)
Retry Count	1	Number of retries for failed health checks (0–10)
Check Interval (ms)	30000	How often to perform health checks (1,000–86,400,000 ms; 1 s – 24 h)

6b. Read Method Fields

(Only displayed when Health Check Method = Read)

Field	Default	Description
Register Type	holding	Type of register/coil to read: coil (FC01), discrete (FC02), holding (FC03), or input (FC04) — required
Address	0	Starting address to read (0–65,535) — required
Quantity	1	Number of registers/coils to read (1–2,000 for coils/discrete; 1–125 for registers) — required
Timeout (ms)	3000	Health check request timeout (1,000–60,000 ms) — required
Expected Value	—	Optional expected value for validation (0–65,535; leave empty to skip)

7. Connection Labels

Field	Default	Description
Labels	—	Key-value pairs to categorize and organize this Modbus connection (max 10 labels)

Example Labels

• environment: production — Deployment environment
• line: line-1 — Production line
• equipment: plc — Equipment type
• location: factory-floor — Physical location

Notes

• Health Check is always enabled for Modbus connections to ensure reliable device communication.
• Fields marked as "required" must be filled out before creating or saving the connection.
• TCP and Serial settings are mutually exclusive based on the selected Transport Mode.
• All timeout values are in milliseconds (ms).
• The form includes real-time validation for all required fields.
• ASCII mode defaults to 7 data bits and Even parity per the Modbus ASCII specification.

Function Builder

Creating Modbus Functions

After the connection is saved:

1. Open the connection and navigate to the Functions tab
2. Click New Function to open the function type selection dialog
3. Choose a Read function (FC01–FC04) or a Write function (FC05–FC06, FC15–FC16)
4. Fill in the Basic tab (name, description, labels) and the Configuration tab (addresses, values)
5. Use the Test button to validate the function before saving

Each function has two configuration tabs:

• Basic — Function name (required, max 100 characters, must be unique within the connection), optional description, and labels
• Configuration — Function-specific parameters (address, quantity, values, data type)

Configure Modbus read operations with addressing, scaling, and output aliases

Author Modbus write functions with validation and safety checks

Quick Add: Bulk Function Creation

For scenarios where you need to create multiple Modbus functions at once, the Quick Add feature streamlines the process by allowing you to define many functions in a single operation.

When to Use Quick Add

• Setting up a new Modbus connection with dozens of tags to monitor
• Migrating existing tag lists from spreadsheets or documentation
• Standardizing function creation across multiple similar devices
• Quickly prototyping data collection without creating functions one by one

How to Use Quick Add

1. Navigate to your Modbus connection in Connections
2. Click Quick Add Functions button
3. Choose your input method:
   • Table Entry: Add rows directly in the interface
   • CSV Import: Upload a CSV file with function definitions

Quick Add Functions dialog with table entry and CSV import options

Table Columns

Column	Description	Example
Function Name	Unique name for the function	Temperature_Sensor_1
Type	Modbus function code	Read Holding Registers (FC03)
Address	Starting register address	40001
Quantity	Number of registers to read	1
Data Type	Value interpretation	float32, uint16, int32

Supported Function Types in Quick Add

• Read Coils (FC01)
• Read Discrete Inputs (FC02)
• Read Holding Registers (FC03)
• Read Input Registers (FC04)
• Write Single Coil (FC05)
• Write Single Register (FC06)
• Write Multiple Coils (FC15)
• Write Multiple Registers (FC16)

CSV Import Format

name,functionType,address,quantity,dataType
Temperature,read.holdingRegisters,40001,1,float32
Pressure,read.holdingRegisters,40003,1,uint16
FlowRate,read.inputRegisters,30001,2,float32
MotorStatus,read.coils,0,8,boolean

Validation Rules

• Function names must be unique within the connection
• Addresses must be in range 0–65,535
• Read operations: quantity must be at least 1
• Register limit: Total registers (quantity × data type register count) cannot exceed 125
• Example: Reading 50 Float32 values requires 100 registers (50 × 2)

Best Practices

• Use descriptive function names that reflect the physical sensor or control point
• Group related functions together using consistent naming (e.g., Tank1_Temperature, Tank1_Pressure)
• Validate your CSV file with a small batch before importing hundreds of functions
• Consider data type register counts when planning bulk reads to stay within the 125 register limit

Data Types

Modbus register data can be interpreted using the following data types. The data type determines how raw 16-bit register values are converted into meaningful values.

Data Type	Registers	Description
raw	Variable	No conversion — returns array of raw 16-bit unsigned values
bool	1	Single bit/coil value (true/false)
int16	1	Signed 16-bit integer (−32,768 to 32,767)
uint16	1	Unsigned 16-bit integer (0 to 65,535)
int32	2	Signed 32-bit integer
uint32	2	Unsigned 32-bit integer
float32	2	IEEE 754 single-precision floating point
int64	4	Signed 64-bit integer
float64	4	IEEE 754 double-precision floating point
string	Variable	ASCII text (2 characters per register, null-terminated)
hex	Variable	Hexadecimal string representation (e.g., FF00 00A1)
bits	Variable	Bit array — 16 bits per register, MSB first

Register Counts

When reading multi-register data types, set the Quantity field to match the register count. For example, reading a float32 value requires a quantity of at least 2 registers, and float64 requires 4.

Read Coils (modbus.read.coils)

Purpose: Read status of discrete outputs (coils) using Function Code 01. Coils can be either ON (true) or OFF (false), allowing reading of multiple coil states in a single operation.

Configuration Fields

Field	Type	Required	Default	Description
Starting Address	Number	Yes	0	First coil address to read (0–65,535)
Quantity	Number	Yes	1	Number of coils to read in sequence (1–2,000)

Use Cases: Read relay states, check digital outputs, monitor coil status, bulk coil reading

Read Discrete Inputs (modbus.read.discreteInputs)

Purpose: Read status of discrete inputs using Function Code 02. These are typically read-only digital inputs from sensors, switches, or other devices.

Configuration Fields

Field	Type	Required	Default	Description
Starting Address	Number	Yes	10000	First discrete input address to read (0–65,535)
Quantity	Number	Yes	8	Number of discrete inputs to read (1–2,000)

Use Cases: Read sensor states, monitor switch positions, check digital inputs, bulk input scanning

Read Holding Registers (modbus.read.holdingRegisters)

Purpose: Read values from holding registers using Function Code 03. These are read-write 16-bit registers used for configuration, setpoints, and other operational data. This is the most common Modbus operation.

Configuration Fields

Field	Type	Required	Default	Description
Starting Address	Number	Yes	40001	First holding register address to read (0–65,535)
Quantity	Number	Yes	10	Number of registers to read (1–125)
Data Type	Select	No	raw	Data type for value conversion (see Data Types table)

Use Cases: Read setpoints, get configuration values, monitor process variables, bulk data acquisition

Read Input Registers (modbus.read.inputRegisters)

Purpose: Read values from input registers using Function Code 04. These are typically read-only 16-bit registers containing measurement data, sensor readings, and status information.

Configuration Fields

Field	Type	Required	Default	Description
Starting Address	Number	Yes	30001	First input register address to read (0–65,535)
Quantity	Number	Yes	4	Number of registers to read (1–125)
Data Type	Select	No	raw	Data type for value conversion (see Data Types table)

Use Cases: Read sensor values, get measurement data, monitor input signals, data logging operations

Write Single Coil (modbus.write.singleCoil)

Purpose: Write a single coil (discrete output) to ON or OFF state using Function Code 05. Used for controlling individual relays, digital outputs, or other binary actuators.

Configuration Fields

Field	Type	Required	Default	Description
Coil Address	Number	Yes	0	Address of the coil to write (0–65,535)
Coil Value	Boolean	Yes	true	State to write to the coil (true = ON, false = OFF). Supports parameter templates.

Use Cases: Control relay states, set digital outputs, toggle equipment on/off, actuator control

Write Single Register (modbus.write.singleRegister)

Purpose: Write a single 16-bit value to a holding register using Function Code 06. Used for setting configuration values, setpoints, and other control parameters.

Configuration Fields

Field	Type	Required	Default	Description
Register Address	Number	Yes	40001	Address of the register to write (0–65,535)
Register Value	Number	Yes	0	16-bit value to write (0–65,535). Supports parameter templates.

Use Cases: Set configuration values, update setpoints, write control parameters, individual register updates

Write Multiple Coils (modbus.write.multipleCoils)

Purpose: Write multiple coils (discrete outputs) in a single operation using Function Code 15. Allows efficient bulk control of relays, digital outputs, or other binary devices.

Configuration Fields

Field	Type	Required	Default	Description
Starting Address	Number	Yes	0	First coil address to write (0–65,535)
Coil Values	Array	Yes	[true, false]	Array of boolean values for each coil (1–1,968 coils). Supports parameter templates.

Use Cases: Control multiple relays, set digital output patterns, bulk coil updates, equipment sequences

Write Multiple Registers (modbus.write.multipleRegisters)

Purpose: Write multiple 16-bit values to consecutive holding registers using Function Code 16. Allows efficient bulk updates of configuration data, setpoints, and control parameters.

Configuration Fields

Field	Type	Required	Default	Description
Starting Address	Number	Yes	40001	First register address to write (0–65,535)
Register Values	Array	Yes	[0, 0]	Array of 16-bit values for consecutive registers (1–123 registers, each 0–65,535). Supports parameter templates.

Use Cases: Bulk configuration updates, set multiple setpoints, write parameter blocks, data download operations

Using Parameters

Parameter placeholders ((parameterName)) can be used in write function fields (value, values, address) to make functions dynamic at execution time.

Configuration	Description	Example
Type	Validate expected value type	number, boolean, array, json
Required	Force critical inputs	Required / Optional
Default Value	Provide safe fallbacks	false, 250.0
Description	Document purpose	"Start/Stop command flag", "Setpoint in °C"

Parameter configuration for Modbus scaling, coercion, and safety notes

Testing Functions

Every Modbus function can be tested before saving using the built-in Test dialog:

1. Click the Test button in the function form
2. The dialog shows an Execution Overview with the current configuration
3. Override any parameter values in the Test Parameters section
4. Click Execute Test to run the function against the live device
5. View the result in the integrated JSON viewer, including execution duration and timestamp

The test dialog supports two modes:

• Config-only Testing (create mode) — Tests the function configuration before saving
• Function with Overrides (edit mode) — Tests the saved function with current form modifications

Pipeline Integration

Use the Modbus connection functions you define here as nodes inside the Pipeline Designer to synchronize PLC registers with the rest of your pipeline. Drag in the read or write node, bind parameters to upstream outputs or constants, and set retries or guard conditions before issuing commands.

For orchestration strategies that mix Modbus with other data sources, check the Connector Nodes page to see how these nodes slot into larger automation flows.

Modbus read node with connection, function, and parameter bindings

Common Use Cases

Equipment Monitoring

Poll holding and input registers for temperature, flow, vibration, or energy metrics, then forward the data to historians or MQTT topics.

Control and Setpoint Management

Validate operator inputs and write them back to coils or registers to adjust production processes safely.

Data Normalization

Convert raw register values into engineering units, status codes, or structured JSON for downstream analytics using the built-in data type conversions (float32, int32, etc.).

Troubleshooting

Connection Issues

Symptom	Possible Cause	Solution
Connection timeout	Device not reachable	Verify network connectivity, IP address, and port. Standard Modbus TCP port is 502.
Invalid address format	Malformed host:port	Ensure address is in host:port format (e.g., 192.168.1.10:502). Port must be 1–65,535.
Serial port error	Wrong device path	Verify the serial device path (/dev/ttyUSB0, COM3, etc.) and that the port is not in use.
Unit ID mismatch	Wrong slave address	Confirm the Unit ID matches the device's configured slave address (0–247).
Health check fails	Device unresponsive	Check the health check method and register settings. Try switching to Status method first.

Function Issues

Symptom	Possible Cause	Solution
Illegal function error	Unsupported function code	Verify the device supports the requested function code (e.g., not all devices support FC15/FC16).
Illegal data address	Address out of range	Check that the starting address and quantity don't exceed the device's address space.
Incorrect values	Wrong data type	Ensure the data type matches the device's register format (e.g., float32 for IEEE 754 values).
Register limit exceeded	Too many registers	Reduce quantity — maximum is 125 for register reads and 2,000 for coil/discrete reads.
Timeout on write	Device busy	Increase the request timeout or add retry logic. Check if the device is in a protected mode.

Testing Functions

Use the Test button in the Function Builder to validate your configuration before using it in pipelines. The test dialog lets you override parameters for one-off operations and displays the full response with execution timing.