njs-modbus 2.0.1 → 3.0.2

package/README.md

@@ -1,203 +1,314 @@
 # 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)
 [![npm latest package](http://img.shields.io/npm/v/njs-modbus/latest.svg?style=flat-square)](https://www.npmjs.com/package/njs-modbus)
 [![npm bundle size](https://img.shields.io/bundlephobia/minzip/njs-modbus?style=flat-square)](https://bundlephobia.com/package/njs-modbus)
+[![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:
+
+```bash
+npm install serialport
+```
+
+## Quick Start
 
-### Modbus RTU Master
+### TCP Master
 
 ```typescript
-import { SerialPhysicalLayer, RtuApplicationLayer, ModbusMaster } from 'njs-modbus';
-
-const physicalLayer = new SerialPhysicalLayer({ path: 'COM1', baudRate: 9600, dataBits: 8, parity: 'none', stopBits: 1 });
-const applicationLayer = new RtuApplicationLayer(physicalLayer);
-
-const modbusMaster = new ModbusMaster(applicationLayer, physicalLayer);
-
-modbusMaster
-  .open()
-  .then(() => {
-    console.log('opened');
-    modbusMaster.readHoldingRegisters(1, 0, 10).then((res) => {
-      console.log(res);
-    });
-  })
-  .catch((error) => {
-    console.log(error);
-  });
+import { ModbusMaster } from 'njs-modbus';
+
+const master = new ModbusMaster({
+  physical: { type: 'TCP_CLIENT' },
+  protocol: { type: 'TCP' },
+});
+
+await master.open({ port: 502, host: '192.168.1.10' });
+
+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 });
+```
 
-  readInputRegisters: (address, length) => {
-    return Array.from({ length }).map((_, i) => {
-      const inputRegister = slave1Data.inputRegisters.get(address + i);
-      if (typeof inputRegister === 'undefined') {
-        return 0;
-      }
-      return inputRegister;
-    });
-  },
+### Serial RTU Master
 
-  readHoldingRegisters: (address, length) => {
-    return Array.from({ length }).map((_, i) => {
-      const holdingRegister = slave1Data.holdingRegisters.get(address + i);
-      if (typeof holdingRegister === 'undefined') {
-        return 0;
-      }
-      return holdingRegister;
-    });
+```typescript
+const master = new ModbusMaster({
+  physical: {
+    type: 'SERIAL',
+    opts: { path: '/dev/ttyUSB0', baudRate: 9600 },
   },
-  writeSingleRegister: (address, value) => {
-    slave1Data.holdingRegisters.set(address, value);
+  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` |
+
+### Server options
+
+```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' },
+});
+```
 
-  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',
-  }),
-};
+### 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()`. |
 
-const modbusSlave = new ModbusSlave(applicationLayer, physicalLayer);
-modbusSlave.add(slave1);
-
-modbusSlave
-  .open()
-  .then(() => {
-    console.log('opened');
-  })
-  .catch((error) => {
-    console.log(error);
-  });
+## 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)
+})
 ```
 
-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.
+RTU / ASCII framing options:
 
-## Broadcasts (unit = 0)
+```typescript
+protocol: {
+  type: 'RTU',
+  opts: {
+    intervalBetweenFrames: { unit: 'ms', value: 20 },
+    interCharTimeout: { unit: 'bit', value: 10 },
+    poolSize: 1024,
+  },
+}
+```
 
-Slaves never respond to broadcast requests, so the master's `write*(0, ...)` Promise resolves as soon as the bytes are flushed to the wire.
+### 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
 
-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:
+```typescript
+new ModbusSlave({
+  physical: { type: 'TCP_SERVER' },
+  protocol: { type: 'TCP' },
+  concurrent?: false, // per-connection concurrent (TCP only)
+})
+```
+
+### Register a model
 
 ```typescript
-const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+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,
+
+  writeSingleRegister?: (address, value) => void,
+  writeMultipleRegisters?: (address, values) => void,
+
+  maskWriteRegister?: (address, andMask, orMask) => void,
+
+  reportServerId?: () => ServerId,
+  readDeviceIdentification?: () => { [index: number]: string },
 
-await master.writeSingleRegister(0, 0x0000, 0x1234); // broadcast
-await sleep(100);                                     // turnaround — tune per devices
-await master.writeSingleRegister(1, 0x0000, 0x5678); // unicast to next slave
+  // 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][];
+  }),
+});
 ```
 
-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).
+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]]);
+  },
+};
+
+// Slave: framing + dispatch
+slave.addCustomFunctionCode(cfc);
+
+// Master: framing only
+master.addCustomFunctionCode(cfc);
+const response = await master.sendCustomFC(1, 0x50, [0xab, 0xcd]);
+```
 
-## Contributing
+## Error Handling
 
-Please read our [contributing guide](/CODE_OF_CONDUCT.md) first.
+```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];
+  },
+});
+```
 
 ## 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)