modbus-serial

Install the package using npm. If you encounter installation issues, you can try building from source with specific flags.

npm install modbus-serial

If you have problems installing, try:

npm install modbus-serial --unsafe-perm --build-from-source

The serialport package is an optional dependency. If it is not installed, you can still use TCP/UDP functionality, but serial-specific APIs will fail at runtime.

Skip optional dependencies

To install without serialport (smaller dependency tree, no native serial build):

npm install modbus-serial --no-optional

Or set optional=false in your .npmrc.

Install serialport explicitly

If you skipped the optional dependency but later need serial RTU/ASCII, install it manually:

npm install serialport

Compatibility Note

The package targets serialport 13.x, which requires Node.js 20 or newer. For older Node.js releases, you must explicitly install a compatible major version (e.g., 12.x).

The ModbusRTU class is used to perform Modbus RTU operations over a serial port. You must provide an instance of a serial port (typically from the serialport package) to the constructor.

To use it:

1. Instantiate ModbusRTU with your serial port.
2. Call .open(callback) to initialize the connection.
3. Use the writeFC* methods to perform Modbus function calls.
4. Handle the response in the provided callback function.

const ModbusRTU = require('modbus-serial').ModbusRTU;
// Assuming 'port' is a valid SerialPort instance
const modbus = new ModbusRTU(port);

modbus.open((err) => {
  if (err) return console.error(err);
  
  // Example: Read Holding Registers (FC3)
  modbus.writeFC3(1, 0, 10, (err, res) => {
    if (err) return console.error(err);
    console.log(res.data);
  });
});

This example demonstrates connecting to a serial port, setting the slave ID, writing values to registers, and then reading them back.

// create an empty modbus client
const ModbusRTU = require("modbus-serial");
const client = new ModbusRTU();

// open connection to a serial port
client.connectRTUBuffered("/dev/ttyUSB0", { baudRate: 9600 }, write);

function write() {
    client.setID(1);

    // write the values 0, 0xffff to registers starting at address 5
    // on device number 1.
    client.writeRegisters(5, [0 , 0xffff])
        .then(read);
}

function read() {
    // read the 2 registers starting at address 5
    // on device number 1.
    client.readHoldingRegisters(5, 2)
        .then(console.log);
}

Use client.send to perform Modbus write operations. You can pass an array of values to the value key to write to multiple addresses.

// Write 2 values to address: 10009 and 10011
const response = await client.send({
    unit: 1,
    fc: 16,
    address: 10009,
    value: [10999, 10888],
    type: 'int32',
});

The setWorkerOptions method allows you to configure the behavior of the worker class, which manages data retrieval and typecasting. You can control concurrency and debugging modes.

const client = new ModbusRTU()

// ... connect client ...

client.setWorkerOptions({
    maxConcurrentRequests: 10, // limits the number of simultaneous requests sent
    debug: true
})

Use client.send to perform Modbus read operations. The worker automatically handles typecasting to types like int32, uint32, and float. Note that requesting a type like int32 will automatically read the required number of registers (e.g., 2 registers for one int32 value).

// Read 4 values starting from 10009 register.
// Under the hood it will read 8 registers due to int32 type
const response = await client.send({
    unit: 1,
    fc: 3,
    address: 10009,
    quantity: 4,
    type: 'int32',
});

When using serial connections (like connectRTUBuffered or connectAsciiSerial), you can pass an options object. This object is passed directly to serialport's openOptions. Default settings are 9600, 8, n, 1.

Example of setting a custom baud rate and parity:

client.connectRTUBuffered("/dev/ttyUSB0", { baudRate: 9600, parity: 'even' });

Client Serial (Requires serialport)

• modbus-RTU: Over serial line (ModbusRTU)
• modbus-RTU (RTUBufferedPort): Over buffered serial line
• modbus-ASCII (AsciiPort): Over serial line

Client TCP/UDP

• modbus-TCP (TcpPort): Over TCP/IP line
• modbus-RTU (UdpPort): Over C701 server or UDP to serial bridge
• modbus-RTU (TcpRTUBufferedPort): Over TCP/IP line (buffered device)
• modbus-RTU (TelnetPort): Over Telnet server (TCP/IP serial bridge)

Server

• modbus-TCP (ServerTCP): Over TCP/IP line

The following Modbus function codes are implemented by the library: