Nodbus-Plus

A Modbus protocol library for Node.js, written entirely in JavaScript. It supports both Modbus Serial and Modbus TCP.

Introduction

Nodbus-Plus is a Modbus protocol stack for Node.js. You can use its API to create your own Modbus client and server, or use its built-in client and server for quick Modbus communication in just minutes.

Installation

npm install nodbus-plus

Quick Start

Creating a Modbus Server

const nodbus = require('nodbus-plus');

// TCP server configuration (uses default values if not specified)
const cfg = {
    inputs: 2048,            // Number of discrete inputs
    coils: 2048,             // Number of coils
    holdingRegisters: 2048,  // Number of holding registers
    inputRegisters: 2048,    // Number of input registers
    port: 502                // Port on which to listen
};

let server = nodbus.createTcpServer('tcp', cfg);

The first argument specifies the transport layer type. Supported options are 'tcp', 'udp4', and 'udp6'.
To create a serial server instead, use createSerialServer:

// Serial server configuration
const cfg = {
    address: 1,                    // Modbus slave address (1–247)
    transmissionMode: 0,           // 0 = RTU, 1 = ASCII
    inputs: 2048,                  // Number of discrete inputs
    coils: 2048,                   // Number of coils
    holdingRegisters: 2048,        // Number of holding registers
    inputRegisters: 2048,          // Number of input registers
    port: 'COM1'                   // Serial port path (e.g., 'COM1' on Windows, '/dev/ttyUSB0' on Linux)
};

let server = nodbus.createSerialServer('serial', cfg);

Listen for Server Events

// Emitted when server starts listening
server.on('listening', (port) => {
    console.log('Server listening on port:', port);
});

// Emitted when a request is received from a client
server.on('request', (socket, req) => {
    console.log('Request received:', req);
});

// Emitted before sending a response to client
server.on('response', (socket, res) => {
    console.log('Response:', res);
});

// Emitted when an error occurs
server.on('error', (err) => {
    console.error('Error:', err);
});

Finally, start the server:

server.start();

Creating a Modbus Client

To create a Modbus client, use createTcpClient or createSerialClient:

const nodbus = require('nodbus-plus');

let client = nodbus.createSerialClient();

// Emitted when client establishes connection with the server
client.on('connection', (id) => {
    console.log('Connection established:', id);
});

// Emitted when an error occurs
client.on('error', (err) => {
    console.error('Error:', err);
});

// Emitted when a request is sent to server
client.on('request', (id, req) => {
    console.log('Request sent to device:', id);
});

// Emitted when a response timeout occurs
client.on('req-timeout', (id, adu) => {
    console.error('Request timeout for device:', id);
});

// Emitted when a response is received
client.on('response', (id, res) => {
    console.log('Response from device:', id, res);
});

Add channels to the client. Each channel represents a connection to a Modbus device:

// Channel configuration
const channelCfg = {
    ip: '127.0.0.1',      // Target device IP address
    port: 502,            // Target device port
    timeout: 250          // Request timeout in milliseconds
};

client.addChannel('device1', 'tcp1', channelCfg);
client.connect('device1');

Once connected, use available Modbus functions to exchange data:

// Read 2 coils starting at address 0 from device at Modbus address 1
client.readCoils('device1', 1, 0, 2);

Documentation

For comprehensive API documentation, visit the official documentation.

Getting Started

New to Nodbus-Plus? The Getting Started Guide provides installation instructions and basic usage examples.

Examples

See the ./samples directory for example programs demonstrating library usage.

Features

• Full Modbus Protocol Support: Read/write coils, discrete inputs, holding registers, and input registers.
• Modbus Serial (RTU/ASCII): Serial communication with RTU and ASCII transmission modes.
• Modbus TCP: TCP/IP network communication with standard Modbus TCP protocol.
• Pure JavaScript: No native dependencies; works on any Node.js environment.
• Client & Server: Create both Modbus clients and servers with the same library.
• Event-Driven: Asynchronous event-based API for responsive applications.

Contributing

Contributions are welcome! If you find a bug or have a feature suggestion, please open an issue.

License

MIT License. See LICENSE.md for details.