njs-modbus 1.4.0 → 2.0.0

package/README.md

@@ -66,7 +66,6 @@ npm install njs-modbus
 ### Modbus RTU Master
 
 ```typescript
-import type { ModbusSlaveModel } from 'njs-modbus';
 import { SerialPhysicalLayer, RtuApplicationLayer, ModbusMaster } from 'njs-modbus';
 
 const physicalLayer = new SerialPhysicalLayer({ path: 'COM1', baudRate: 9600, dataBits: 8, parity: 'none', stopBits: 1 });
@@ -90,21 +89,22 @@ modbusMaster
 ### Modbus RTU Slave
 
 ```typescript
+import type { ModbusSlaveModel } from 'njs-modbus';
 import { SerialPhysicalLayer, RtuApplicationLayer, ModbusSlave } from 'njs-modbus';
 
-const MB_SERVER = {
+const physicalLayer = new SerialPhysicalLayer({ path: 'COM1', baudRate: 9600, dataBits: 8, parity: 'none', stopBits: 1 });
+const applicationLayer = new RtuApplicationLayer(physicalLayer);
+
+const slave1Data = {
   discreteInputs: new Map<number, boolean>(),
   coils: new Map<number, boolean>(),
   inputRegisters: new Map<number, number>(),
   holdingRegisters: new Map<number, number>(),
 };
-
-const physicalLayer = new SerialPhysicalLayer({ path: 'COM1', baudRate: 9600, dataBits: 8, parity: 'none', stopBits: 1 });
-const applicationLayer = new RtuApplicationLayer(physicalLayer);
 const slave1: ModbusSlaveModel = {
   readDiscreteInputs: (address, length) => {
     return Array.from({ length }).map((_, i) => {
-      const discreteInput = MB_SERVER.discreteInputs.get(address + i);
+      const discreteInput = slave1Data.discreteInputs.get(address + i);
       if (typeof discreteInput === 'undefined') {
         return false;
       }
@@ -114,7 +114,7 @@ const slave1: ModbusSlaveModel = {
 
   readCoils: (address, length) => {
     return Array.from({ length }).map((_, i) => {
-      const coil = MB_SERVER.coils.get(address + i);
+      const coil = slave1Data.coils.get(address + i);
       if (typeof coil === 'undefined') {
         return false;
       }
@@ -122,12 +122,12 @@ const slave1: ModbusSlaveModel = {
     });
   },
   writeSingleCoil: (address, value) => {
-    MB_SERVER.coils.set(address, value);
+    slave1Data.coils.set(address, value);
   },
 
   readInputRegisters: (address, length) => {
     return Array.from({ length }).map((_, i) => {
-      const inputRegister = MB_SERVER.inputRegisters.get(address + i);
+      const inputRegister = slave1Data.inputRegisters.get(address + i);
       if (typeof inputRegister === 'undefined') {
         return 0;
       }
@@ -137,7 +137,7 @@ const slave1: ModbusSlaveModel = {
 
   readHoldingRegisters: (address, length) => {
     return Array.from({ length }).map((_, i) => {
-      const holdingRegister = MB_SERVER.holdingRegisters.get(address + i);
+      const holdingRegister = slave1Data.holdingRegisters.get(address + i);
       if (typeof holdingRegister === 'undefined') {
         return 0;
       }
@@ -145,7 +145,7 @@ const slave1: ModbusSlaveModel = {
     });
   },
   writeSingleRegister: (address, value) => {
-    MB_SERVER.holdingRegisters.set(address, value);
+    slave1Data.holdingRegisters.set(address, value);
   },
 
   reportServerId: () => ({ additionalData: [1, 2, 3] }),
@@ -178,6 +178,22 @@ modbusSlave
 
 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.
 
+## Broadcasts (unit = 0)
+
+Slaves never respond to broadcast requests, so the master's `write*(0, ...)` Promise resolves as soon as the bytes are flushed to the wire.
+
+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
+const sleep = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));
+
+await master.writeSingleRegister(0, 0x0000, 0x1234); // broadcast
+await sleep(100);                                     // turnaround — tune per devices
+await master.writeSingleRegister(1, 0x0000, 0x5678); // unicast to next slave
+```
+
+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).
+
 ## Contributing
 
 Please read our [contributing guide](/CODE_OF_CONDUCT.md) first.