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/input registers, and masked writes
- Rich parameter validation to control data types, scaling, and unit conversion
- Connection diagnostics including retries, timeouts, and optional debug tracing
Connection Configuration
Creating a Modbus Connection
In Connections → New Connection → Modbus, define the physical link to your device:
1. Profile Information
| Field | Default | Description |
|---|---|---|
| Profile Name | - | A descriptive name for this connection profile (required, max 100 characters) |
| Description | - | Optional description for this Modbus connection |
2. Connection Mode Settings
| Field | Default | Description |
|---|---|---|
| Transport Mode | tcp | Modbus communication protocol (tcp/rtu/ascii) – required |
| Unit ID | 1 | Modbus slave unit identifier (0-247) – required |
3. TCP Transport Settings
(Only displayed when Transport Mode = TCP)
| Field | Default | Description |
|---|---|---|
| IP Address:Port | 192.168.1.10:502 | Target device IP address and port (standard Modbus TCP port is 502) – required |
| Connect Timeout (ms) | 3000 | Maximum time to wait for TCP connection (1000-60000 ms) |
| Keep Alive Period (ms) | 30000 | TCP keep-alive probe interval (1000-1800000 ms) |
| Enable TCP Keep-Alive | true | Send periodic keep-alive probes to detect connection failures |
4. Serial Transport Settings
(Only displayed when Transport Mode = RTU or ASCII)
| Field | Default | Description |
|---|---|---|
| Serial Device | /dev/ttyUSB0 | Serial port device path (e.g., /dev/ttyUSB0 on Linux, COM3 on Windows) – required |
| Baud Rate | 9600 | Serial communication speed in bits per second (1200/2400/4800/9600/19200/38400/57600/115200) – required |
| Parity | N (None) | Error detection method for serial communication (N=None/E=Even/O=Odd) – required |
| Data Bits | 8 | Number of data bits per character (7 or 8) – required |
| Stop Bits | 1 | Number of stop bits per character (1 or 2) – required |
| RS-485 Mode | false | Enable RS-485 specific handling (direction control, etc.) |
5. Timeout Configuration
| Field | Default | Description |
|---|---|---|
| Request Timeout (ms) | 5000 | Maximum time to wait for Modbus response (1000-60000 ms) |
| Idle Timeout (ms) | 10000 | Close connection after idle period (0-600000 ms, 0 = never) |
| Retry Count | 2 | Number of retries on communication failure (0-10) |
| Retry Delay (ms) | 500 | Delay between retry attempts (100-60000 ms) |
6. Serial Advanced Options
(Only displayed when Transport Mode = RTU or ASCII)
| Field | Default | Description |
|---|---|---|
| Inter-Frame Delay (ms) | 0 | Silent interval between frames (0-10000 ms, 0 = automatic) |
| Inter-Character Delay (ms) | 0 | Delay between characters (0-1000 ms, 0 = automatic) |
| Read Timeout (ms) | 0 | Low-level read timeout (0-10000 ms, 0 = use default) |
7. Health Check Configuration
7a. Basic Health Check Settings
| Field | Default | Description |
|---|---|---|
| Health Check Method | Status Only | Health check type: "Status Only (Connection Test)" or "Read Communication (Device Data)" – required |
| Retry Count | 1 | Number of retries for failed health checks (0-10) |
| Check Interval (ms) | 30000 | How often to perform health checks (1000-86400000 ms, 1s-24h) |
7b. Additional Fields
(Only displayed when Health Check Method = "Read Communication")
| Field | Default | Description |
|---|---|---|
| Register Type | - | Type of register/coil to read (coil/discrete/input/holding) – required for read method |
| Address | - | Starting address to read (0-65535) – required for read method |
| Quantity | - | Number of registers/coils to read (1-2000) – required for read method |
| Timeout (ms) | - | Health check request timeout (1000-60000 ms) – required for read method |
| Expected Value (Optional) | - | Expected value for validation (0-65535, leave empty to skip) |
Register Type Options
- Coil: FC01 - Read Coils
- Discrete: FC02 - Read Discrete Inputs
- Input: FC04 - Read Input Registers
- Holding: FC03 - Read Holding Registers
8. Connection Labels
| Field | Default | Description |
|---|---|---|
| Labels | - | Key-value pairs to categorize and organize this Modbus connection (max 10 labels) |
Example Labels
environment: production– Deployment environmentline: line-1– Production lineequipment: plc– Equipment typelocation: factory-floor– Physical location
- 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.
Function Builder
Creating Modbus Functions
After the connection is in place:
- Navigate to Functions → New Function
- Choose Modbus Read or Modbus Write
- Select the Modbus connection profile
- Define register addresses, counts, scaling factors, and output mappings
Configure Modbus read operations with addressing, scaling, and output aliases
Author Modbus write functions with validation and safety checks
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-65535) |
| Quantity | Number | Yes | 1 | Number of coils to read in sequence (1-2000) |
Use Cases: Read relay states, check digital outputs, monitor coil status, bulk coil reading
Read Discrete Inputs
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-65535) |
| Quantity | Number | Yes | 8 | Number of discrete inputs to read (1-2000) |
Use Cases: Read sensor states, monitor switch positions, check digital inputs, bulk input scanning
Read Holding Registers
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-65535) |
| Quantity | Number | Yes | 10 | Number of registers to read (1-125) |
Use Cases: Read setpoints, get configuration values, monitor process variables, bulk data acquisition
Read Input Registers
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-65535) |
| Quantity | Number | Yes | 4 | Number of registers to read (1-125) |
Use Cases: Read sensor values, get measurement data, monitor input signals, data logging operations
Write Single Coil
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-65535) |
| Coil Value | Boolean | Yes | true | State to write to the coil (true=ON, false=OFF) |
Use Cases: Control relay states, set digital outputs, toggle equipment on/off, actuator control
Write Single Register
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-65535) |
| Register Value | Number | Yes | 0 | 16-bit value to write (0-65535) |
Use Cases: Set configuration values, update setpoints, write control parameters, individual register updates
Write Multiple Coils
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-65535) |
| Coil Values | Array | Yes | [true, false] | Array of boolean values for each coil (1-1968 coils) |
Use Cases: Control multiple relays, set digital output patterns, bulk coil updates, equipment sequences
Write Multiple Registers
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-65535) |
| Register Values | Array | Yes | [0, 0] | Array of 16-bit values for consecutive registers (1-123 registers, each 0-65535) |
Use Cases: Bulk configuration updates, set multiple setpoints, write parameter blocks, data download operations
Using Parameters
Parameter placeholders ((parameterName)) appear in the function editor for validation.
| 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
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.