njs-modbus 2.1.0 → 3.1.0

package/README.zh-CN.md

@@ -0,0 +1,380 @@
+# njs-modbus
+
+[English](./README.md) | 简体中文
+
+Node.js 的纯 JavaScript Modbus 实现。
+
+<!-- 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 -->
+
+## 特性
+
+- **协议：** Modbus TCP、RTU、ASCII
+- **传输：** 串口、TCP 客户端/服务端、UDP 客户端/服务端
+- **主站：** FIFO 或流水线并发请求（仅 TCP）
+- **从站：** 每连接 FIFO 或并发处理（仅 TCP）
+- **自定义功能码**，支持可插拔帧解析
+- **广播**（单元号 = 0）
+- **完整 TypeScript**
+- **零运行时依赖**（仅在使用串口时 peer-depends `serialport`）
+
+| 码值 | 名称 |
+|------|------|
+| 01 | 读取线圈 |
+| 02 | 读取离散输入 |
+| 03 | 读取保持寄存器 |
+| 04 | 读取输入寄存器 |
+| 05 | 写单个线圈 |
+| 06 | 写单个寄存器 |
+| 15 | 写多个线圈 |
+| 16 | 写多个寄存器 |
+| 17 | 报告服务器 ID |
+| 22 | 掩码写寄存器 |
+| 23 | 读/写多个寄存器 |
+| 43/14 | 读取设备标识 |
+
+## 安装
+
+```bash
+npm install njs-modbus
+```
+
+使用串口传输时，还需安装 peer dependency：
+
+```bash
+npm install serialport
+```
+
+## 快速开始
+
+### TCP 主站
+
+```typescript
+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();
+```
+
+### TCP 从站
+
+```typescript
+import { ModbusSlave } from 'njs-modbus';
+
+const slave = new ModbusSlave({
+  physical: { type: 'TCP_SERVER' },
+  protocol: { type: 'TCP' },
+});
+
+slave.add({
+  unit: 1,
+  readHoldingRegisters: (address, length) => {
+    return Array.from({ length }, (_, i) => address + i);
+  },
+});
+
+await slave.open({ port: 502 });
+```
+
+### 串口 RTU 主站
+
+```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' },
+});
+```
+
+## 物理层
+
+所有物理层暴露 `open()` / `close()`、`state` 属性，以及事件：`'open'`、`'connect'`、`'close'`、`'error'`。
+
+| 类型 | 类 | `open(...)` 参数 |
+|------|-------|-----------------|
+| `SERIAL` | `SerialPhysicalLayer` | 无 |
+| `TCP_CLIENT` | `TcpClientPhysicalLayer` | `SocketConnectOpts` |
+| `TCP_SERVER` | `TcpServerPhysicalLayer` | `ListenOptions` |
+| `UDP_CLIENT` | `UdpClientPhysicalLayer` | `{ port, address }` |
+| `UDP_SERVER` | `UdpServerPhysicalLayer` | `BindOptions` |
+| `CUSTOM` | *(用户自定义)* | *(自定义)* |
+
+### 服务端配置
+
+```typescript
+const slave = new ModbusSlave({
+  physical: {
+    type: 'TCP_SERVER',
+    opts: {
+      whitelist: ['192.168.1.10', '10.0.0.5'], // IPv4-mapped IPv6 自动规范化
+      maxConnections: 10,
+      idleTimeout: 30000, // 驱逐不活跃连接，0 = 禁用
+    },
+  },
+  protocol: { type: 'TCP' },
+});
+```
+
+### 物理层选项
+
+| 选项 | 类型 | 说明 |
+|--------|------|-------------|
+| `whitelist` | `string[]` | 允许的客户端 IP。`::ffff:` 前缀自动剥离。 |
+| `maxConnections` | `number` | 最大并发连接数。超出后新连接静默丢弃。 |
+| `idleTimeout` | `number` | 空闲超时（毫秒），超时后驱逐连接。默认 `30000`，传 `0` 禁用。 |
+| `socketOpts` / `serverOpts` | `object` | 透传给 Node.js `createSocket()` / `createServer()`。 |
+
+## 主站 API
+
+```typescript
+new ModbusMaster({
+  physical: { type: 'TCP_CLIENT' },
+  protocol: { type: 'TCP' },          // 'TCP' | 'RTU' | 'ASCII'
+  timeout?: 1000,                     // 单次请求超时（毫秒）
+  concurrent?: false,                 // 流水线模式（仅 TCP）
+})
+```
+
+RTU 帧选项：
+
+```typescript
+protocol: {
+  type: 'RTU',
+  opts: {
+    // 既可以传裸数字（毫秒），也可以传 `{ unit: 'bit' | 'ms', value: N }`。
+    // 传 `0` 显式禁用该定时器（适用于 RTU-over-TCP 等无丢包传输）。
+    intervalBetweenFrames: 20,                          // 20 毫秒
+    interCharTimeout: { unit: 'bit', value: 10 },       // 按 bit-time，需 baudRate
+    poolSize: 1024,
+  },
+}
+```
+
+ASCII 选项：
+
+```typescript
+protocol: {
+  type: 'ASCII',
+  opts: {
+    lenientHex: true, // 接受小写十六进制 (a-f)。默认：false（按规范仅大写）
+  },
+}
+```
+
+### 方法
+
+| 方法 | 说明 |
+|--------|-------------|
+| `open(...args)` | 打开物理层。只能调用一次；`close()` 后实例永久失效。 |
+| `close()` | 立即关闭。进行中和队列中的请求会被 reject。 |
+| `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?)` | 发送用户自定义功能码 |
+| `addCustomFunctionCode(cfc)` | 注册自定义功能码用于帧解析 |
+| `removeCustomFunctionCode(fc)` | 注销自定义功能码 |
+
+广播（`unit = 0`）resolve `void` — 从站不响应。
+
+## 从站 API
+
+```typescript
+new ModbusSlave({
+  physical: { type: 'TCP_SERVER' },
+  protocol: { type: 'TCP' },
+  concurrent?: false, // 每连接并发（仅 TCP）
+})
+```
+
+### 注册模型
+
+```typescript
+slave.add({
+  unit: 1,
+
+  // 可选：在默认分发前拦截任意功能码
+  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 },
+
+  // 可选地址范围校验
+  getAddressRange?: () => ({
+    discreteInputs?: [number, number] | [number, number][];
+    coils?: [number, number] | [number, number][];
+    inputRegisters?: [number, number] | [number, number][];
+    holdingRegisters?: [number, number] | [number, number][];
+  }),
+});
+```
+
+缺失的处理器返回 `ILLEGAL_FUNCTION`。越界地址返回 `ILLEGAL_DATA_ADDRESS`。处理器抛出的异常变为 `SERVER_DEVICE_FAILURE`，除非错误是 `ModbusError`。
+
+| 方法 | 说明 |
+|--------|-------------|
+| `add(model)` | 注册从站模型 |
+| `remove(unit)` | 移除从站模型 |
+| `open(...args)` | 打开物理层。一次性：close() 后不可重新打开。 |
+| `close()` | 立即关闭 |
+| `addCustomFunctionCode(cfc)` | 注册自定义功能码 |
+| `removeCustomFunctionCode(fc)` | 注销自定义功能码 |
+
+## 自定义功能码
+
+```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.addCustomFunctionCode(cfc);
+
+// 主站：仅帧解析
+master.addCustomFunctionCode(cfc);
+const response = await master.sendCustomFC(1, 0x50, [0xab, 0xcd]);
+```
+
+## 错误处理
+
+```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];
+  },
+});
+```
+
+## 性能
+
+与 [jsmodbus](https://github.com/Cloud-Automation/node-modbus) 和 [modbus-serial](https://github.com/yaacov/node-modbus-serial) 的对比。
+
+| 指标 | njs-modbus | jsmodbus | modbus-serial |
+|------|-----------|----------|---------------|
+| TCP 吞吐量 | **5,527 ops/sec** | 3,239 (0.59x) | 371 (0.07x) |
+| TCP P99 延迟 | **2.71 ms** | 4.73 ms (1.75x) | 12.48 ms (4.61x) |
+| TCP CPU 效率 | **1,116 µs/op** | 1,950 (1.75x) | 16,715 (14.98x) |
+| 并发 (8 连接) | **5,274 ops/sec** | 3,416 (0.65x) | 1,815 (0.34x) |
+| RTU CPU 效率 | **1,762 µs/op** | 1,760 (1.00x) | 2,144 (1.22x) |
+| TCP 响应编码 | **2.04M ops/sec** | 373K (0.18x) | 411K (0.20x) |
+| TCP 响应解码 | **1.91M ops/sec** | 538K (0.28x) | 231K (0.12x) |
+
+<details>
+<summary>完整基准测试结果</summary>
+
+Node.js v24.15.0 · linux x64 · 3 次运行 × 300 秒 · [完整报告](./benchmark/RESULTS.md)
+
+### TCP 吞吐量（单连接）
+
+```
+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
+```
+
+### 并发（8 连接）
+
+```
+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 串口（模拟 115200 波特率）
+
+```
+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
+```
+
+### 编码 / 解码（CPU 微基准测试）
+
+```
+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)
+```
+
+</details>
+
+## 许可证
+
+[![license](https://img.shields.io/github/license/xiejay97/njs-modbus?style=flat-square)](/LICENSE)