njs-modbus 3.0.2 → 3.1.0

package/README.md

@@ -125,6 +125,7 @@ All physical layers expose `open()` / `close()`, a `state` property, and events:
 | `TCP_SERVER` | `TcpServerPhysicalLayer` | `ListenOptions` |
 | `UDP_CLIENT` | `UdpClientPhysicalLayer` | `{ port, address }` |
 | `UDP_SERVER` | `UdpServerPhysicalLayer` | `BindOptions` |
+| `CUSTOM` | *(user-provided)* | *(user-defined)* |
 
 ### Server options
 
@@ -162,19 +163,33 @@ new ModbusMaster({
 })
 ```
 
-RTU / ASCII framing options:
+RTU framing options:
 
 ```typescript
 protocol: {
   type: 'RTU',
   opts: {
-    intervalBetweenFrames: { unit: 'ms', value: 20 },
-    interCharTimeout: { unit: 'bit', value: 10 },
+    // 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,
   },
 }
 ```
 
+ASCII options:
+
+```typescript
+protocol: {
+  type: 'ASCII',
+  opts: {
+    lenientHex: true, // accept lowercase hex (a-f). Default: false (strict uppercase per spec)
+  },
+}
+```
+
 ### Methods
 
 | Method | Description |
@@ -309,6 +324,58 @@ slave.add({
 });
 ```
 
+## Performance
+
+Benchmarked against [jsmodbus](https://github.com/Cloud-Automation/node-modbus) and [modbus-serial](https://github.com/yaacov/node-modbus-serial).
+
+| 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)
+
+### 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
+```
+
+### Concurrent (8 Connections)
+
+```
+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)
+```
+
+</details>
+
 ## License
 
 [![license](https://img.shields.io/github/license/xiejay97/njs-modbus?style=flat-square)](/LICENSE)

package/README.zh-CN.md

@@ -125,6 +125,7 @@ const master = new ModbusMaster({
 | `TCP_SERVER` | `TcpServerPhysicalLayer` | `ListenOptions` |
 | `UDP_CLIENT` | `UdpClientPhysicalLayer` | `{ port, address }` |
 | `UDP_SERVER` | `UdpServerPhysicalLayer` | `BindOptions` |
+| `CUSTOM` | *(用户自定义)* | *(自定义)* |
 
 ### 服务端配置
 
@@ -162,19 +163,32 @@ new ModbusMaster({
 })
 ```
 
-RTU / ASCII 帧选项：
+RTU 帧选项：
 
 ```typescript
 protocol: {
   type: 'RTU',
   opts: {
-    intervalBetweenFrames: { unit: 'ms', value: 20 },
-    interCharTimeout: { unit: 'bit', value: 10 },
+    // 既可以传裸数字（毫秒），也可以传 `{ 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（按规范仅大写）
+  },
+}
+```
+
 ### 方法
 
 | 方法 | 说明 |
@@ -309,6 +323,58 @@ slave.add({
 });
 ```
 
+## 性能
+
+与 [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)