@serialpilot/driver-modbus-rtu

Typed Modbus RTU master driver for SerialPilot. Talks to Modbus RTU slaves over RS-485 (or RS-232 with adapters) for industrial automation, building management, and energy/utility metering.

Install

npm install serialpilot @serialpilot/driver-modbus-rtu

Quick start

import { SerialPilot } from 'serialpilot'
import { ModbusRtuMaster } from '@serialpilot/driver-modbus-rtu'

const port = new SerialPilot({ path: '/dev/ttyUSB0', baudRate: 9600 })
const modbus = new ModbusRtuMaster({ transport: port })

await modbus.open()

// Read 10 holding registers from slave 1, starting at address 0
const regs = await modbus.readHoldingRegisters(1, 0, 10)
console.log(regs)   // [12, 0, 1234, …]

// Write a single register
await modbus.writeSingleRegister(1, 100, 0x00FF)

// Write multiple registers
await modbus.writeMultipleRegisters(1, 200, [1, 2, 3, 4])

await modbus.close()

API

class ModbusRtuMaster extends Device

| Method | Function code | Returns | | --- | --- | --- | | readHoldingRegisters(slave, addr, qty, opts?) | 0x03 | Promise<number[]> | | readInputRegisters(slave, addr, qty, opts?) | 0x04 | Promise<number[]> | | writeSingleRegister(slave, addr, value, opts?) | 0x06 | Promise<void> | | writeMultipleRegisters(slave, addr, values, opts?) | 0x10 | Promise<void> |

Each method accepts opts: { timeoutMs?: number } (default 1000 ms).

Errors

All methods reject with a typed ModbusError (Error with .code):

| Code | Meaning | | --- | --- | | EXCEPTION | Slave returned a Modbus exception. .exceptionCode is set (e.g. 1=Illegal Function, 2=Illegal Data Address, 3=Illegal Data Value, 4=Slave Device Failure). | | CRC_MISMATCH | Received frame failed CRC-16 verification. | | ADDRESS_MISMATCH | Response slave address ≠ request slave address. | | FUNCTION_MISMATCH | Response function code ≠ expected (and not an exception). | | TIMEOUT | No complete frame received within timeoutMs. | | CLOSED | Device was closed while the request was in flight. | | WRITE_FAILED | Transport write() failed mid-request. | | INVALID_RESPONSE | Frame structurally malformed (e.g. read response byteCount mismatch). |

Limitations (v0.1)

• Master role only. Slave/server role is a future minor.
• No coil function codes. FC 0x01, 0x02, 0x05, 0x0F deferred to v0.2; holding/input registers cover the majority of real-world Modbus traffic.
• No diagnostic FCs (0x07, 0x08, 0x0B, 0x0C). Niche; deferred.
• No TCP / ASCII transport. RTU only — TCP is a different framing model and a separate package.
• No 3.5-character-time inter-frame silence. v0.1 uses length-driven framing (response length is determined from the FC + byte-count byte) plus a per-call timeout. Adequate for single-master scenarios on USB-RS485 adapters; less robust on busy multi-master RS-485 networks.
• No broadcast writes (slave address 0).
• No float helpers. Two consecutive 16-bit registers as a 32-bit float (with vendor-specific byte ordering) is left to the caller for v0.1; helpers may come in v0.2.

License

MIT