njs-modbus 2.1.0 → 3.1.0

package/README.md

@@ -1,8 +1,8 @@
 # njs-modbus
 
-A pure JavaScript implementation of MODBUS for NodeJS.
+English | [简体中文](./README.zh-CN.md)
 
-<div>
+A pure JavaScript implementation of Modbus for Node.js.
 
 <!-- prettier-ignore-start -->
 [![npm download](http://img.shields.io/npm/dw/njs-modbus.svg?style=flat-square)](http://www.npm-stats.com/~packages/njs-modbus)
@@ -11,194 +11,371 @@ A pure JavaScript implementation of MODBUS for NodeJS.
 [![CI](https://img.shields.io/github/actions/workflow/status/xiejay97/njs-modbus/ci.yml?branch=main&style=flat-square)](https://github.com/xiejay97/njs-modbus/actions)
 <!-- prettier-ignore-end -->
 
-</div>
-
-## Introduction
-
-`njs-modbus` is designed as a layered architecture, including the physical layer and the application layer:
-
-- Physical layer implements Serial Port, TCP/IP and UDP/IP.
-- Application layer implements RTU, ASCII and TCP.
-
-`njs-modbus` provide both client and server.
-
 ## Features
 
-- Full modbus standard protocol implementation
-- Support for custom function codes
-- Support broadcasting
-- Very lightweight project
-- Full typescript
-
-### Supported function codes
-
-| Code  |                               |
-| ----- | ----------------------------- |
-| 01    | Read Coils                    |
-| 02    | Read Discrete Inputs          |
-| 03    | Read Holding Registers        |
-| 04    | Read Input Register           |
-| 05    | Write Single Coil             |
-| 06    | Write Single Register         |
-| 15    | Write Multiple Coils          |
-| 16    | Write Multiple Registers      |
-| 17    | Report Server ID              |
-| 22    | Mask Write Register           |
-| 23    | Read/Write Multiple Registers |
-| 43/14 | Read device Identification    |
-
-### Supported protocols
-
-- Modbus RTU
-- Modbus ASCII
-- Modbus TCP/IP
-- Modbus UDP/IP
-- Modbus RTU/ASCII Over TCP/IP
-- Modbus RTU/ASCII Over UDP/IP
-
-#### Installation
+- **Protocols:** Modbus TCP, RTU, ASCII
+- **Transports:** Serial, TCP client/server, UDP client/server
+- **Master:** FIFO or pipelined concurrent requests (TCP only)
+- **Slave:** Per-connection FIFO or concurrent processing (TCP only)
+- **Custom function codes** with pluggable framing
+- **Broadcasting** (unit = 0)
+- **Full TypeScript**
+- **Zero runtime dependencies** (peer-depends on `serialport` for serial)
+
+| Code | Name |
+|------|------|
+| 01 | Read Coils |
+| 02 | Read Discrete Inputs |
+| 03 | Read Holding Registers |
+| 04 | Read Input Registers |
+| 05 | Write Single Coil |
+| 06 | Write Single Register |
+| 15 | Write Multiple Coils |
+| 16 | Write Multiple Registers |
+| 17 | Report Server ID |
+| 22 | Mask Write Register |
+| 23 | Read/Write Multiple Registers |
+| 43/14 | Read Device Identification |
+
+## Installation
 
 ```bash
 npm install njs-modbus
 ```
 
-## Examples
+For serial transport, also install the peer dependency:
 
-### Modbus RTU Master
+```bash
+npm install serialport
+```
+
+## Quick Start
+
+### TCP Master
 
 ```typescript
-import { SerialPhysicalLayer, RtuApplicationLayer, ModbusMaster } from 'njs-modbus';
+import { ModbusMaster } from 'njs-modbus';
 
-const physicalLayer = new SerialPhysicalLayer({ path: 'COM1', baudRate: 9600, dataBits: 8, parity: 'none', stopBits: 1 });
-const applicationLayer = new RtuApplicationLayer(physicalLayer);
+const master = new ModbusMaster({
+  physical: { type: 'TCP_CLIENT' },
+  protocol: { type: 'TCP' },
+});
 
-const modbusMaster = new ModbusMaster(applicationLayer, physicalLayer);
+await master.open({ port: 502, host: '192.168.1.10' });
 
-modbusMaster
-  .open()
-  .then(() => {
-    console.log('opened');
-    modbusMaster.readHoldingRegisters(1, 0, 10).then((res) => {
-      console.log(res);
-    });
-  })
-  .catch((error) => {
-    console.log(error);
-  });
+const res = await master.readHoldingRegisters(1, 0, 10);
+console.log(res.data);
+
+await master.close();
 ```
 
-### Modbus RTU Slave
+### TCP Slave
 
 ```typescript
-import type { ModbusSlaveModel } from 'njs-modbus';
-import { SerialPhysicalLayer, RtuApplicationLayer, ModbusSlave } from 'njs-modbus';
+import { ModbusSlave } from 'njs-modbus';
 
-const physicalLayer = new SerialPhysicalLayer({ path: 'COM1', baudRate: 9600, dataBits: 8, parity: 'none', stopBits: 1 });
-const applicationLayer = new RtuApplicationLayer(physicalLayer);
+const slave = new ModbusSlave({
+  physical: { type: 'TCP_SERVER' },
+  protocol: { type: 'TCP' },
+});
 
-const slave1Data = {
-  discreteInputs: new Map<number, boolean>(),
-  coils: new Map<number, boolean>(),
-  inputRegisters: new Map<number, number>(),
-  holdingRegisters: new Map<number, number>(),
-};
-const slave1: ModbusSlaveModel = {
-  readDiscreteInputs: (address, length) => {
-    return Array.from({ length }).map((_, i) => {
-      const discreteInput = slave1Data.discreteInputs.get(address + i);
-      if (typeof discreteInput === 'undefined') {
-        return false;
-      }
-      return discreteInput;
-    });
+slave.add({
+  unit: 1,
+  readHoldingRegisters: (address, length) => {
+    return Array.from({ length }, (_, i) => address + i);
   },
+});
 
-  readCoils: (address, length) => {
-    return Array.from({ length }).map((_, i) => {
-      const coil = slave1Data.coils.get(address + i);
-      if (typeof coil === 'undefined') {
-        return false;
-      }
-      return coil;
-    });
-  },
-  writeSingleCoil: (address, value) => {
-    slave1Data.coils.set(address, value);
+await slave.open({ port: 502 });
+```
+
+### Serial RTU Master
+
+```typescript
+const master = new ModbusMaster({
+  physical: {
+    type: 'SERIAL',
+    opts: { path: '/dev/ttyUSB0', baudRate: 9600 },
   },
+  protocol: { type: 'RTU' },
+});
+
+await master.open();
+const res = await master.readHoldingRegisters(1, 0, 10);
+await master.close();
+```
+
+### RTU over TCP
+
+```typescript
+const master = new ModbusMaster({
+  physical: { type: 'TCP_CLIENT' },
+  protocol: { type: 'RTU' },
+});
+```
+
+## Physical Layers
+
+All physical layers expose `open()` / `close()`, a `state` property, and events: `'open'`, `'connect'`, `'close'`, `'error'`.
+
+| Type | Class | `open(...)` args |
+|------|-------|-----------------|
+| `SERIAL` | `SerialPhysicalLayer` | none |
+| `TCP_CLIENT` | `TcpClientPhysicalLayer` | `SocketConnectOpts` |
+| `TCP_SERVER` | `TcpServerPhysicalLayer` | `ListenOptions` |
+| `UDP_CLIENT` | `UdpClientPhysicalLayer` | `{ port, address }` |
+| `UDP_SERVER` | `UdpServerPhysicalLayer` | `BindOptions` |
+| `CUSTOM` | *(user-provided)* | *(user-defined)* |
+
+### Server options
 
-  readInputRegisters: (address, length) => {
-    return Array.from({ length }).map((_, i) => {
-      const inputRegister = slave1Data.inputRegisters.get(address + i);
-      if (typeof inputRegister === 'undefined') {
-        return 0;
-      }
-      return inputRegister;
-    });
+```typescript
+const slave = new ModbusSlave({
+  physical: {
+    type: 'TCP_SERVER',
+    opts: {
+      whitelist: ['192.168.1.10', '10.0.0.5'], // IPv4-mapped IPv6 normalized automatically
+      maxConnections: 10,
+      idleTimeout: 30000, // evict inactive connections, 0 = disable
+    },
   },
+  protocol: { type: 'TCP' },
+});
+```
 
-  readHoldingRegisters: (address, length) => {
-    return Array.from({ length }).map((_, i) => {
-      const holdingRegister = slave1Data.holdingRegisters.get(address + i);
-      if (typeof holdingRegister === 'undefined') {
-        return 0;
-      }
-      return holdingRegister;
-    });
+### Physical layer options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `whitelist` | `string[]` | Allowed client IPs. `::ffff:` prefix is stripped automatically. |
+| `maxConnections` | `number` | Max concurrent connections. New connections are silently dropped when exceeded. |
+| `idleTimeout` | `number` | Idle timeout in ms before evicting a connection. Default `30000`. Pass `0` to disable. |
+| `socketOpts` / `serverOpts` | `object` | Forwarded to Node.js `createSocket()` / `createServer()`. |
+
+## Master API
+
+```typescript
+new ModbusMaster({
+  physical: { type: 'TCP_CLIENT' },
+  protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
+  timeout?: 1000,                     // per-request timeout (ms)
+  concurrent?: false,                 // pipelined mode (TCP only)
+})
+```
+
+RTU framing options:
+
+```typescript
+protocol: {
+  type: 'RTU',
+  opts: {
+    // Either a bare number (milliseconds), or `{ unit: 'bit' | 'ms', value: N }`.
+    // Use `0` to disable the timer entirely (useful for lossless transports
+    // such as RTU-over-TCP).
+    intervalBetweenFrames: 20,                          // 20 ms
+    interCharTimeout: { unit: 'bit', value: 10 },       // bit-time, needs baudRate
+    poolSize: 1024,
   },
-  writeSingleRegister: (address, value) => {
-    slave1Data.holdingRegisters.set(address, value);
+}
+```
+
+ASCII options:
+
+```typescript
+protocol: {
+  type: 'ASCII',
+  opts: {
+    lenientHex: true, // accept lowercase hex (a-f). Default: false (strict uppercase per spec)
   },
+}
+```
+
+### Methods
+
+| Method | Description |
+|--------|-------------|
+| `open(...args)` | Open the physical layer. Can only be called once; after `close()` the instance is dead. |
+| `close()` | Close immediately. In-flight and queued requests are rejected. |
+| `readCoils(unit, address, length, timeout?)` | FC 01 |
+| `readDiscreteInputs(unit, address, length, timeout?)` | FC 02 |
+| `readHoldingRegisters(unit, address, length, timeout?)` | FC 03 |
+| `readInputRegisters(unit, address, length, timeout?)` | FC 04 |
+| `writeSingleCoil(unit, address, value, timeout?)` | FC 05 |
+| `writeSingleRegister(unit, address, value, timeout?)` | FC 06 |
+| `writeMultipleCoils(unit, address, values, timeout?)` | FC 15 |
+| `writeMultipleRegisters(unit, address, values, timeout?)` | FC 16 |
+| `reportServerId(unit, serverIdLength?, timeout?)` | FC 17 |
+| `maskWriteRegister(unit, address, andMask, orMask, timeout?)` | FC 22 |
+| `readAndWriteMultipleRegisters(unit, read, write, timeout?)` | FC 23 |
+| `readDeviceIdentification(unit, readDeviceIDCode, objectId, timeout?)` | FC 43/14 |
+| `sendCustomFC(unit, fc, data, timeout?)` | Send a user-defined function code |
+| `addCustomFunctionCode(cfc)` | Register custom FC for framing |
+| `removeCustomFunctionCode(fc)` | Unregister custom FC |
+
+Broadcast (`unit = 0`) resolves `void` — slaves never respond.
+
+## Slave API
+
+```typescript
+new ModbusSlave({
+  physical: { type: 'TCP_SERVER' },
+  protocol: { type: 'TCP' },
+  concurrent?: false, // per-connection concurrent (TCP only)
+})
+```
+
+### Register a model
+
+```typescript
+slave.add({
+  unit: 1,
+
+  // Optional: intercept any FC before default dispatch
+  interceptor?: (fc, data) => Buffer | undefined,
+
+  readCoils?: (address, length) => boolean[],
+  readDiscreteInputs?: (address, length) => boolean[],
+  readHoldingRegisters?: (address, length) => number[],
+  readInputRegisters?: (address, length) => number[],
+
+  writeSingleCoil?: (address, value) => void,
+  writeMultipleCoils?: (address, values) => void,
 
-  reportServerId: () => ({ additionalData: [1, 2, 3] }),
-
-  readDeviceIdentification: () => ({
-    0x00: 'Basic:VendorName',
-    0x01: 'Basic:ProductCode',
-    0x02: 'Basic:MajorMinorRevision',
-    0x03: 'Regular:VendorUrl',
-    0x04: 'Regular:ProductName',
-    0x05: 'Regular:ModelName',
-    0x06: 'Regular:UserApplicationName',
-    0x80: 'Extended:Extended',
-    0xff: 'Extended:Extended',
+  writeSingleRegister?: (address, value) => void,
+  writeMultipleRegisters?: (address, values) => void,
+
+  maskWriteRegister?: (address, andMask, orMask) => void,
+
+  reportServerId?: () => ServerId,
+  readDeviceIdentification?: () => { [index: number]: string },
+
+  // Optional address range validation
+  getAddressRange?: () => ({
+    discreteInputs?: [number, number] | [number, number][];
+    coils?: [number, number] | [number, number][];
+    inputRegisters?: [number, number] | [number, number][];
+    holdingRegisters?: [number, number] | [number, number][];
   }),
+});
+```
+
+Missing handlers return `ILLEGAL_FUNCTION`. Out-of-range addresses return `ILLEGAL_DATA_ADDRESS`. Handler throws become `SERVER_DEVICE_FAILURE` unless the error is a `ModbusError`.
+
+| Method | Description |
+|--------|-------------|
+| `add(model)` | Register a slave model |
+| `remove(unit)` | Remove a slave model |
+| `open(...args)` | Open the physical layer. One-shot: cannot reopen after `close()`. |
+| `close()` | Close immediately |
+| `addCustomFunctionCode(cfc)` | Register a custom FC |
+| `removeCustomFunctionCode(fc)` | Unregister a custom FC |
+
+## Custom Function Codes
+
+```typescript
+import type { CustomFunctionCode } from 'njs-modbus';
+
+const cfc: CustomFunctionCode = {
+  fc: 0x50,
+  predictRequestLength: (buffer) => {
+    if (buffer.length < 2) return null;
+    return 4 + buffer[1];
+  },
+  predictResponseLength: (buffer) => {
+    if (buffer.length < 2) return null;
+    return 4 + buffer[1];
+  },
+  handle: async (data, unit) => {
+    return Buffer.from([data[1], data[0]]);
+  },
 };
 
-const modbusSlave = new ModbusSlave(applicationLayer, physicalLayer);
-modbusSlave.add(slave1);
+// Slave: framing + dispatch
+slave.addCustomFunctionCode(cfc);
 
-modbusSlave
-  .open()
-  .then(() => {
-    console.log('opened');
-  })
-  .catch((error) => {
-    console.log(error);
-  });
+// Master: framing only
+master.addCustomFunctionCode(cfc);
+const response = await master.sendCustomFC(1, 0x50, [0xab, 0xcd]);
 ```
 
-For more advanced examples, check out [examples](/examples) included in the repository. If you have created any utilities that meet a specific need, feel free to submit them so others can benefit.
+## Error Handling
 
-## Broadcasts (unit = 0)
+```typescript
+import { ErrorCode, ModbusError, getErrorByCode } from 'njs-modbus';
+
+// ErrorCode.ILLEGAL_FUNCTION          = 0x01
+// ErrorCode.ILLEGAL_DATA_ADDRESS      = 0x02
+// ErrorCode.ILLEGAL_DATA_VALUE        = 0x03
+// ErrorCode.SERVER_DEVICE_FAILURE     = 0x04
+// ErrorCode.ACKNOWLEDGE               = 0x05
+// ErrorCode.SERVER_DEVICE_BUSY        = 0x06
+// ErrorCode.MEMORY_PARITY_ERROR       = 0x08
+// ErrorCode.GATEWAY_PATH_UNAVAILABLE  = 0x0a
+// ErrorCode.GATEWAY_TARGET_DEVICE_FAILED_TO_RESPOND = 0x0b
+
+slave.add({
+  unit: 1,
+  readHoldingRegisters: (address) => {
+    if (address > 100) {
+      throw getErrorByCode(ErrorCode.ILLEGAL_DATA_ADDRESS);
+    }
+    return [42];
+  },
+});
+```
 
-Slaves never respond to broadcast requests, so the master's `write*(0, ...)` Promise resolves as soon as the bytes are flushed to the wire.
+## Performance
 
-If you broadcast over serial (RTU or ASCII), per Modbus over Serial Line V1.02 §2.4.1 you must wait a **turnaround delay** before sending the next request — slow slaves need time to apply the broadcast write that produced no response. The library does not insert this delay automatically because the right value is workload-specific (fast sensors vs. PLCs writing to flash differ by orders of magnitude). Insert it yourself in your call site:
+Benchmarked against [jsmodbus](https://github.com/Cloud-Automation/node-modbus) and [modbus-serial](https://github.com/yaacov/node-modbus-serial).
 
-```typescript
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+| Metric | njs-modbus | jsmodbus | modbus-serial |
+|--------|-----------|----------|---------------|
+| TCP Throughput | **5,527 ops/sec** | 3,239 (0.59x) | 371 (0.07x) |
+| TCP P99 Latency | **2.71 ms** | 4.73 ms (1.75x) | 12.48 ms (4.61x) |
+| TCP CPU Efficiency | **1,116 µs/op** | 1,950 (1.75x) | 16,715 (14.98x) |
+| Concurrent (8 conn) | **5,274 ops/sec** | 3,416 (0.65x) | 1,815 (0.34x) |
+| RTU CPU Efficiency | **1,762 µs/op** | 1,760 (1.00x) | 2,144 (1.22x) |
+| TCP Res Encode | **2.04M ops/sec** | 373K (0.18x) | 411K (0.20x) |
+| TCP Res Decode | **1.91M ops/sec** | 538K (0.28x) | 231K (0.12x) |
+
+<details>
+<summary>Full benchmark results</summary>
+
+Node.js v24.15.0 · linux x64 · 3 runs × 300 s · [full report](./benchmark/RESULTS.md)
 
-await master.writeSingleRegister(0, 0x0000, 0x1234); // broadcast
-await sleep(100); // turnaround — tune per devices
-await master.writeSingleRegister(1, 0x0000, 0x5678); // unicast to next slave
+### TCP Throughput (Single Connection)
+
+```
+njs-modbus    │ 5,527 ops/sec 🏆   CPU: 1,116 µs/op
+jsmodbus      │ 3,239 ops/sec (0.59x)  CPU: 1,950 µs/op
+modbus-serial │   371 ops/sec (0.07x)  CPU: 16,715 µs/op
 ```
 
-A safe lower bound is the RTU t3.5 inter-frame silence (e.g. ~4 ms at 9600 baud, ~1.75 ms above 19200 baud). Many real-world PLCs need 50–100 ms after a broadcast write. Modbus TCP/UDP do not require this delay (TCP gives synchronous acks; broadcasting on TCP is uncommon anyway).
+### Concurrent (8 Connections)
 
-## Contributing
+```
+njs-modbus    │ 5,274 ops/sec 🏆   CPU: 1,392 µs/op
+jsmodbus      │ 3,416 ops/sec (0.65x)  CPU: 2,131 µs/op
+modbus-serial │ 1,815 ops/sec (0.34x)  CPU: 3,962 µs/op
+```
+
+### RTU Serial (115200 baud simulated)
+
+```
+njs-modbus    │ 44 ops/sec   CPU: 1,762 µs/op
+jsmodbus      │ 44 ops/sec   CPU: 1,760 µs/op
+modbus-serial │ 44 ops/sec   CPU: 2,144 µs/op
+```
+
+### Encode / Decode (CPU Micro-benchmark)
+
+```
+tcpResEncode: njs-modbus 2.04M ops/sec  (jsmodbus 0.18x, modbus-serial 0.20x)
+tcpResDecode: njs-modbus 1.91M ops/sec  (jsmodbus 0.28x, modbus-serial 0.12x)
+```
 
-Please read our [contributing guide](/CODE_OF_CONDUCT.md) first.
+</details>
 
 ## License
 
-[![gitHub license](https://img.shields.io/github/license/xiejay97/njs-modbus?style=flat-square)](/LICENSE)
+[![license](https://img.shields.io/github/license/xiejay97/njs-modbus?style=flat-square)](/LICENSE)