@aaqu/node-red-modbus-tcp 0.2.0

aaqu modbus tcp

npm install @aaqu/node-red-modbus-tcp

aaqu modbus tcp

Node-RED nodes for Modbus TCP client communication.

Features

• Modbus TCP Client - Connect to Modbus TCP servers (PLCs, RTUs, simulators)
• Read Operations - FC01, FC02, FC03, FC04
• Write Operations - FC05, FC06, FC15, FC16
• Auto-reconnect - Automatic reconnection on connection loss
• Dynamic configuration - Override parameters via msg properties
• Unit ID per node - Different Unit IDs for each operation
• No external dependencies - Uses only native Node.js modules
• Multi-language support - English, Polish, Chinese, Japanese

Installation

From npm

npm install @aaqu/node-red-modbus-tcp

From source

cd ~/.node-red
npm install /path/to/aaqu-modbus-tcp

After installation, restart Node-RED and refresh the browser.

Nodes

aaqu-modbus-client (Configuration Node)

Manages the TCP connection to a Modbus server. Shared by all operation nodes.

Property	Type	Default	Description
Host	string	localhost	IP address or hostname of Modbus server
Port	number	502	TCP port number
Timeout	number	5000	Request timeout in milliseconds
Auto Reconnect	boolean	true	Automatically reconnect on connection loss
Reconnect Interval	number	5000	Time between reconnection attempts (ms)

aaqu-modbus-read

Reads data from a Modbus server.

Properties

Property	Type	Default	Description
Server	config	-	Reference to aaqu-modbus-client node
Unit ID	number	1	Modbus unit identifier (1-255)
Function	select	FC03	Function code (FC01-FC04)
Address	number	0	Starting address (0-65535)
Quantity	number	1	Number of items to read

Supported Functions

Function	Code	Description	Max Quantity
Read Coils	FC01	Read coil status (bits)	2000
Read Discrete Inputs	FC02	Read discrete input status (bits)	2000
Read Holding Registers	FC03	Read holding registers (16-bit)	125
Read Input Registers	FC04	Read input registers (16-bit)	125

Input Message (optional overrides)

msg.unitId = 2;           // Override Unit ID
msg.functionCode = 3;     // Override function code
msg.address = 100;        // Override starting address
msg.quantity = 10;        // Override quantity

Output Message

msg.payload = [100, 101, 102, ...];  // Array of read values
msg.modbus = {
    unitId: 1,
    functionCode: 3,
    address: 0,
    quantity: 10,
    byteCount: 20
};

aaqu-modbus-write

Writes a single value to a Modbus server.

Properties

Property	Type	Default	Description
Server	config	-	Reference to aaqu-modbus-client node
Unit ID	number	1	Modbus unit identifier (1-255)
Function	select	FC06	Function code (FC05 or FC06)
Address	number	0	Address to write (0-65535)

Supported Functions

Function	Code	Description	Value Range
Write Single Coil	FC05	Write single coil	true/false
Write Single Register	FC06	Write single register	0-65535

Input Message

msg.payload = 1234;       // Value to write (number for registers, boolean for coils)
msg.unitId = 2;           // Optional: Override Unit ID
msg.functionCode = 6;     // Optional: Override function code
msg.address = 100;        // Optional: Override address

Output Message

msg.payload = 1234;       // Original payload (unchanged)
msg.modbus = {
    unitId: 1,
    functionCode: 6,
    address: 100,
    value: 1234
};

aaqu-modbus-write-multiple

Writes multiple values to a Modbus server.

Properties

Property	Type	Default	Description
Server	config	-	Reference to aaqu-modbus-client node
Unit ID	number	1	Modbus unit identifier (1-255)
Function	select	FC16	Function code (FC15 or FC16)
Address	number	0	Starting address (0-65535)

Supported Functions

Function	Code	Description	Max Quantity
Write Multiple Coils	FC15	Write multiple coils	1968
Write Multiple Registers	FC16	Write multiple registers	123

Input Message

msg.payload = [100, 200, 300];  // Array of values to write
msg.unitId = 2;                  // Optional: Override Unit ID
msg.functionCode = 16;           // Optional: Override function code
msg.address = 100;               // Optional: Override starting address

Output Message

msg.payload = [100, 200, 300];  // Original payload (unchanged)
msg.modbus = {
    unitId: 1,
    functionCode: 16,
    address: 100,
    quantity: 3
};

Examples

Read 10 Holding Registers

[inject] -> [aaqu-modbus-read] -> [debug]

Configure aaqu-modbus-read:

• Function: FC03 - Read Holding Registers
• Address: 0
• Quantity: 10
• Unit ID: 1

Write Single Register

[inject (payload: 1234)] -> [aaqu-modbus-write] -> [debug]

Configure aaqu-modbus-write:

• Function: FC06 - Write Single Register
• Address: 0
• Unit ID: 1

Write Multiple Registers

[inject (payload: [100, 200, 300])] -> [aaqu-modbus-write-multiple] -> [debug]

Configure aaqu-modbus-write-multiple:

• Function: FC16 - Write Multiple Registers
• Address: 100
• Unit ID: 1

Dynamic Configuration

Use a function node to set parameters dynamically:

msg.unitId = 2;
msg.address = flow.get('startAddress') || 0;
msg.quantity = 5;
return msg;

Error Handling

Errors are reported through Node-RED's standard error handling:

1. Node status - Visual indicator (red ring with error message)
2. Catch node - Use a catch node to handle errors programmatically
3. Debug sidebar - Errors appear in the debug sidebar

Common Errors

Error	Description	Solution
Not connected	No connection to server	Check host/port, network connectivity
Request timeout	Server didn't respond in time	Increase timeout, check server
Illegal Data Address	Invalid address	Check address range
Illegal Data Value	Invalid value	Check value range
Illegal Function	Function not supported	Check server capabilities

Modbus Protocol Reference

Address Space

Type	Address Range	Description
Coils	0-65535	Read/Write single bits
Discrete Inputs	0-65535	Read-only single bits
Holding Registers	0-65535	Read/Write 16-bit values
Input Registers	0-65535	Read-only 16-bit values

Data Types

• Coils/Discrete Inputs: Boolean (true/false)
• Registers: 16-bit unsigned integer (0-65535)

For larger data types (32-bit, float, etc.), read multiple consecutive registers and combine them in a function node.

Unit ID

The Unit ID (also called Slave ID) identifies the target device when multiple devices share a connection (e.g., through a gateway). Valid range: 1-255.

Testing

Run the test suite:

npm test

Supported Languages

Language	Locale
English	en-US
Polish	pl-PL
Chinese (Simplified)	zh-CN
Japanese	ja-JP

Requirements

• Node.js >= 14.0.0
• Node-RED >= 2.0.0
• No external dependencies (uses native Node.js net module)

License

MIT

Author

Aaqu

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: npm test
5. Submit a pull request

Changelog

0.2.0

• Fixed node names to be unique (added aaqu- prefix)
• Changed palette category to "Aaqu Portal"
• Renamed locale files to match new node names

0.1.3

• Update README

0.1.2

• Test github actions

0.1.1

• Added to npm registry
• Updated README

0.1.0

• Initial release
• Support for FC01, FC02, FC03, FC04 (read operations)
• Support for FC05, FC06, FC15, FC16 (write operations)
• Auto-reconnect functionality
• Unit ID configuration per node
• Dynamic parameter override via message properties