@aaqu/node-red-modbus-tcp

Node-RED nodes for Modbus TCP client communication.

Support

Disclaimer

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. The author makes no guarantees regarding the reliability, accuracy, or suitability of this software for any particular purpose. Use at your own risk. The author shall not be liable for any damages arising from the use of this software in production environments, industrial automation, or any other application.

Features

• Modbus TCP Client - Connect to Modbus TCP servers (PLCs, RTUs, simulators)
• Read Operations - FC01-FC04, FC24 (FIFO Queue)
• Write Operations - FC05, FC06, FC15, FC16, FC22 (Mask Write)
• Read/Write Combined - FC23 (atomic Read/Write Multiple Registers)
• Diagnostics - FC17 (Report Server ID), FC43/14 (Read Device Identification)
• File Records - FC20 (Read), FC21 (Write)
• Response validation - byte-count check on read responses (rejects malformed frames)
• Auto-reconnect - Automatic reconnection on connection loss
• Heartbeat - Application-layer keep-alive for unstable links
• Dynamic configuration - Override parameters via msg properties
• External Data mode - Hide GUI fields and require parameters from msg only
• 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) | | Log Connection Errors | boolean | true | Log connection errors to console | | TCP Keep-Alive | boolean | true | Enable TCP keep-alive probes | | Keep-Alive Delay | number | 10000 | Initial delay before first keep-alive probe (ms) | | Heartbeat | boolean | false | Send periodic Modbus requests to keep connection active | | Heartbeat Interval | number | 5000 | Interval between heartbeat requests (ms) | | Include Raw Response | boolean | false | Include raw Modbus frame buffer in msg.raw |

Connection Keep-Alive Options

The client provides multiple options to maintain stable connections:

1. TCP Keep-Alive - System-level TCP probes. May not work with all devices.
2. Heartbeat - Application-level Modbus requests. More reliable for devices that close idle connections.

Recommendation: If your device closes idle connections, enable Heartbeat. It sends periodic read requests (FC03) that are ignored but keep the connection active. Heartbeat is skipped when there are pending requests to avoid interference.

aaqu-modbus-read

Reads data from a Modbus server.

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | Server | config | - | Reference to aaqu-modbus-client node | | External Data | checkbox | false | When enabled, Unit ID/Address/Quantity are hidden and must come from msg | | 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 | | Read FIFO Queue | FC24 | Read FIFO queue at a single address | 31 (server-defined) |

For FC24 (FIFO), the quantity field is ignored — the server returns whatever the queue depth is at that address. Output:

msg.payload = [val1, val2, ...];   // Array of 16-bit values from the FIFO
msg.fifoCount = 3;                 // Number of values returned

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

External Data Mode

When External Data checkbox is enabled, the GUI fields for Unit ID, Address, and Quantity are hidden. These values must be provided in the incoming message:

msg.unitId = 1;           // Required
msg.address = 100;        // Required
msg.quantity = 10;        // Required
msg.functionCode = 3;     // Optional (uses node config if not provided)

This mode is useful when parameters come from external sources (database, API, other nodes) and you don't want to configure them statically in the node.

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 | | External Data | checkbox | false | When enabled, Unit ID/Address are hidden and must come from msg | | 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 | | Mask Write Register | FC22 | Apply (current AND andMask) OR (orMask AND NOT andMask) to a register | masks 0-65535 |

For FC22 (Mask Write), msg.payload is ignored. Required:

msg.andMask = 0xF2;
msg.orMask  = 0x25;
msg.address = 0x0010;     // (or from node config)
msg.unitId  = 1;

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

External Data Mode

When External Data checkbox is enabled, the GUI fields for Unit ID and Address are hidden. These values must be provided in the incoming message:

msg.payload = 1234;       // Value to write
msg.unitId = 1;           // Required
msg.address = 100;        // Required
msg.functionCode = 6;     // Optional (uses node config if not provided)

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. This node operates in forced external data mode - Unit ID and Address must always be provided via the incoming message.

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | Server | config | - | Reference to aaqu-modbus-client node | | Function | select | FC16 | Function code (FC15 or FC16) |

Note: Unit ID and Address are not configurable in the node. They must be provided in msg.unitId and msg.address.

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 = 1;                  // Required: Modbus Unit ID (1-255)
msg.address = 100;               // Required: Starting address (0-65535)
msg.functionCode = 16;           // Optional: Override function code

Output Message

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

Why External Data Mode?

This node is designed for dynamic, data-driven scenarios where parameters come from external sources (database, API, other nodes). This makes it ideal for:

• Multi-device communication with varying addresses
• Dynamic write operations based on external configuration
• Integration with SCADA systems and databases

aaqu-modbus-read-write

Atomic Read/Write Multiple Registers (FC23 / 0x17). The write is performed first, then the read — both in a single transaction.

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | Server | config | - | Reference to aaqu-modbus-client node | | External Data | checkbox | false | When enabled, read/write addresses come from msg | | Unit ID | number | 1 | Modbus unit identifier (1-255) | | Read Address | number | 0 | Starting read address (0-65535) | | Read Quantity | number | 1 | Number of registers to read (1-125) | | Write Address | number | 0 | Starting write address (0-65535) |

Input Message

msg.payload = [100, 200, 300];  // Values to write (1-121 registers)
// External Data ON additionally requires:
msg.unitId = 1;
msg.readAddress = 0;
msg.readQuantity = 5;
msg.writeAddress = 100;

Output Message

msg.payload = [/* read register bytes */];
msg.requestModbus = {
    functionCode: 23,
    readAddress: 0, readQuantity: 5,
    writeAddress: 100, writeQuantity: 3,
    unitId: 1, byteCount: 10
};

aaqu-modbus-diagnostic

Diagnostic operations: Report Server ID (FC17) and Read Device Identification (FC43 / MEI 0x0E).

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | Server | config | - | Reference to aaqu-modbus-client node | | Unit ID | number | 1 | Modbus unit identifier (1-255) | | Operation | select | reportServerId | reportServerId or readDeviceIdentification | | ID Code | select | 1 - Basic | Only for Read Device ID: 1=Basic, 2=Regular, 3=Extended, 4=Specific | | Object ID | number | 0 | Only for Read Device ID. 0=VendorName, 1=ProductCode, 2=Revision, 3=VendorUrl, 4=ProductName, 5=ModelName, 6=UserApplicationName |

Output Message

For reportServerId:

msg.payload = {
    serverId: 0x42,
    runIndicator: true,
    additionalData: <Buffer ...>
};

For readDeviceIdentification:

msg.payload = {
    conformityLevel: 0x01,
    moreFollows: false,
    nextObjectId: 0,
    objects: { 0: 'VendorName', 1: 'ProductCode', 2: 'v1.0' }
};

aaqu-modbus-file

Extended file record access: Read File Record (FC20) and Write File Record (FC21).

Properties

| Property | Type | Default | Description | |----------|------|---------|-------------| | Server | config | - | Reference to aaqu-modbus-client node | | Unit ID | number | 1 | Modbus unit identifier (1-255) | | Operation | select | read | read or write |

Input Message

For read:

msg.payload = [
    { fileNumber: 4, recordNumber: 1, recordLength: 2 },
    { fileNumber: 4, recordNumber: 5, recordLength: 1 }
];

For write:

msg.payload = [
    { fileNumber: 4, recordNumber: 7, recordData: [0x06AF, 0x04BE] }
];

Limits: file number 1-65535, record number 0-9999, up to 122 16-bit words per record. Whole PDU must fit in 253 bytes.

Output Message

For read, msg.payload is an array of { recordData: [uint16, ...] }. For write, msg.payload is an echo of the request descriptors.

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] -> [function] -> [aaqu-modbus-write-multiple] -> [debug]

Inject node sends payload, Function node adds required properties:

msg.payload = [100, 200, 300];
msg.unitId = 1;
msg.address = 100;
return msg;

Configure aaqu-modbus-write-multiple:

• Function: FC16 - Write Multiple Registers

Dynamic Configuration

Use a function node to set parameters dynamically:

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

External Data Mode

When you need all parameters to come from external sources (database, API, etc.), enable External Data checkbox. This hides the GUI fields and requires values in the message:

[inject] -> [function] -> [aaqu-modbus-read (External Data: ON)] -> [debug]

Function node:

msg.unitId = msg.payload.deviceId;
msg.address = msg.payload.registerAddress;
msg.quantity = msg.payload.count;
return msg;

This is useful for:

• Reading device configuration from database
• Dynamic polling based on external schedules
• Multi-device scanning with varying parameters

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

See CHANGELOG.md for the full version history.