modbus-webserial 0.10.0 → 0.10.3

package/README.md

@@ -1,7 +1,8 @@
 # modbus-webserial
 
-Tiny zero-dependency library for communicating with a Modbus-RTU serial device from the browser via WebSerial.
+Zero-dependency library for communicating with a Modbus-RTU serial device from the browser via WebSerial.
 
+[![Mentioned in Awesome](https://awesome.re/mentioned-badge.svg)](https://github.com/louisfoster/awesome-web-serial#code-utilities)
 ![npm](https://img.shields.io/npm/v/modbus-webserial)
 ![size](https://img.shields.io/bundlephobia/minzip/modbus-webserial)
 ![dependencies](https://img.shields.io/badge/dependencies-0-brightgreen)
@@ -10,14 +11,13 @@ Tiny zero-dependency library for communicating with a Modbus-RTU serial device f
 ![types](https://img.shields.io/npm/types/modbus-webserial)
 ![esm](https://img.shields.io/badge/esm-%F0%9F%9A%80-green)
 
-## Install
-
-```bash
-npm install modbus-webserial
-```
 
 ## Usage
-**Connect  → read/write in browser**
+**Try the web UI at**
+**[modbuswebui.dev](https://modbuswebui.dev/)**
+
+
+**Establish connection and read/write in browser**
 ```javascript
 import { ModbusRTU } from 'modbus-webserial';
 
@@ -25,13 +25,25 @@ import { ModbusRTU } from 'modbus-webserial';
 const client = await ModbusRTU.openWebSerial({ baudRate: 9600 });
 client.setID(1);
 
-// Read holding registers 0x00 and 0x01
+// Read two holding registers from 0x0000 (0x0000 and 0x0001)
 const { data } = await client.readHoldingRegisters(0, 2);
 console.log('HR0=', data[0], 'HR1=', data[1]);
 
-// Write values to holding registers 0x00 and 0x01
+// Write values to holding registers 0x00 and 0x01 (i.e. two registers from 0x0000)
 await client.writeRegisters(0, [0x0A, 0x0B]);
 ```
+**You can also manually supply the port** 
+```javascript
+const [port] = await navigator.serial.getPorts()
+const client = await ModbusRTU.openWebSerial({ baudRate: 9600, port })
+
+// or on connect
+navigator.serial.addEventListener("connect", ({target: port}) => {
+   const client = await ModbusRTU.openWebSerial({ baudRate: 9600, port })
+})
+```
+
+---
 **Can also be used *without* WebSerial for building modbus frames in any environment**
 ```javascript
 import {
@@ -42,15 +54,18 @@ import {
 // Build a “Read Holding Registers” frame (ID=1, addr=0, qty=2)
 const rawRead = buildReadHoldingRegisters(1, 0x00, 2);
 console.log(rawRead);
-// → Uint8Array [0x01, 0x03, 0x00, 0x00, 0x00, 0x02, CRC_LO, CRC_HI]
+// Uint8Array [0x01, 0x03, 0x00, 0x00, 0x00, 0x02, CRC_LO, CRC_HI]
 
 // Build a “Write Multiple Registers” frame (ID=1, addr=0, values=[10,11])
 const rawWrite = buildWriteRegisters(1, 0x00, [0x0A, 0x0B]);
 console.log(rawWrite);
-// → Uint8Array [0x01, 0x10, 0x00, 0x00, 0x00, 0x02, 0x04, 0x00,0x0A, 0x00,0x0B, CRC_LO, CRC_HI]
+// Uint8Array [0x01, 0x10, 0x00, 0x00, 0x00, 0x02, 0x04, 0x00,0x0A, 0x00,0x0B, CRC_LO, CRC_HI]
 ```
 > [!TIP]
 > Check `src/index.ts` (or `dist/index.js`) for all exports 
+
+---
+
 ## Supported Functions
 
 ### Modbus Data Functions
@@ -86,6 +101,11 @@ Utility and configuration methods exposed on `ModbusRTU`:
 | `getID()`                | Get the current slave ID            |
 | `setTimeout(ms)`         | Set transaction timeout (ms)        |
 | `getTimeout()`           | Get current timeout (ms)            |
+| `getPort()`              | Get 'SerialPort' instance[^1]          |
+
+[^1]: The returned `SerialPort` instance from `getPort` can be used to access properties such as `usbVendorId` and `usbProductId` for retrieving information about the connected USB device.
+
+---
 
 ## Examples
 
@@ -96,6 +116,25 @@ The following demos are fully self‑contained HTML files, served via GitHub Pag
 * [64‑Register Smoke Test](https://anttikotajarvi.github.io/modbus-webserial/examples/smoke-test/)
   Automated loop testing read/write of 64 registers, coils, and discrete inputs with live counters and error logging.
 
+* [Modbus Web-UI](https://modbuswebui.dev)
+  MB Master web app with UX fetures etc.
+
+--- 
+
+## Behavior
+### CRC policy (strict vs resync)
+
+By default the transport uses **strict** CRC checking: if a received Modbus RTU frame fails CRC validation, the request fails with `CrcError`.
+
+You can switch to a more tolerant mode that tries to recover from occasional line noise:
+
+```js
+const client = await ModbusRTU.openWebSerial({
+  baudRate: 9600,
+  crcPolicy: { mode: "resync", maxResyncDrops: 32 },
+});
+```
+
 ## Current state
 * **v0.10**: Full modbus data-access coverage
 * **v0.9**: Full passing tests, smoke test passed, complete README, build scripts in place
@@ -104,8 +143,4 @@ The following demos are fully self‑contained HTML files, served via GitHub Pag
 
 ## Roadmap
 
-* **v1.0.0**: Finalize API, apply bug fixes, refine docs, production-ready release
-
----
-
-© 2025 Antti Kotajärvi
+* **v1.0.0**: Create and document more tests for different boards using different browsers.

package/dist/index.d.ts

@@ -2,10 +2,18 @@ interface WebSerialOptions {
     baudRate?: number;
     dataBits?: 7 | 8;
     stopBits?: 1 | 2;
-    parity?: 'none' | 'even' | 'odd';
+    parity?: "none" | "even" | "odd";
     requestFilters?: SerialPortFilter[];
+    port?: SerialPort;
     timeout?: number;
+    crcPolicy?: CrcPolicy;
 }
+type CrcPolicy = {
+    mode: "strict";
+} | {
+    mode: "resync";
+    maxResyncDrops?: number;
+};
 
 /** Result payloads returned by high-level helpers */
 interface ReadCoilResult {
@@ -61,6 +69,7 @@ declare class ModbusRTU {
     getID(): number;
     setTimeout(ms: number): void;
     getTimeout(): number;
+    getPort(): SerialPort;
     /** FC 01 – coils */
     readCoils(addr: number, qty: number): Promise<ReadCoilResult>;
     /** FC 02 – discrete inputs */
@@ -193,6 +202,11 @@ declare function crc16(buf: Uint8Array): number;
 declare class CrcError extends Error {
     constructor();
 }
+declare class ResyncError extends Error {
+    readonly drops: number;
+    readonly maxDrops: number;
+    constructor(drops: number, maxDrops: number);
+}
 declare class TimeoutError extends Error {
     constructor();
 }
@@ -201,4 +215,4 @@ declare class ExceptionError extends Error {
     constructor(code: number);
 }
 
-export { CrcError, ExceptionError, type MaskWriteResult, ModbusRTU, type ReadFifoResult, type ReadRegisterResult, TimeoutError, type WebSerialOptions, type WriteFileResult, type WriteRegisterResult, buildMaskWriteRegister, buildReadCoils, buildReadDiscreteInputs, buildReadFifoQueue, buildReadFileRecord, buildReadHolding, buildReadInputRegisters, buildReadWriteMultiple, buildWriteFileRecord, buildWriteMultiple, buildWriteMultipleCoils, buildWriteSingle, buildWriteSingleCoil, crc16, parseMaskWriteRegister, parseReadCoils, parseReadDiscreteInputs, parseReadFifoQueue, parseReadFileRecord, parseReadHolding, parseReadInputRegisters, parseReadWriteMultiple, parseWriteSingle, parseWriteSingleCoil };
+export { CrcError, ExceptionError, type MaskWriteResult, ModbusRTU, type ReadFifoResult, type ReadRegisterResult, ResyncError, TimeoutError, type WebSerialOptions, type WriteFileResult, type WriteRegisterResult, buildMaskWriteRegister, buildReadCoils, buildReadDiscreteInputs, buildReadFifoQueue, buildReadFileRecord, buildReadHolding, buildReadInputRegisters, buildReadWriteMultiple, buildWriteFileRecord, buildWriteMultiple, buildWriteMultipleCoils, buildWriteSingle, buildWriteSingleCoil, crc16, parseMaskWriteRegister, parseReadCoils, parseReadDiscreteInputs, parseReadFifoQueue, parseReadFileRecord, parseReadHolding, parseReadInputRegisters, parseReadWriteMultiple, parseWriteSingle, parseWriteSingleCoil };

package/dist/index.js

@@ -15,6 +15,14 @@ var CrcError = class extends Error {
     super("CRC check failed");
   }
 };
+var ResyncError = class extends Error {
+  constructor(drops, maxDrops) {
+    super(`Resync failed (dropped ${drops}/${maxDrops} bytes)`);
+    this.name = "ResyncError";
+    this.drops = drops;
+    this.maxDrops = maxDrops;
+  }
+};
 var TimeoutError = class extends Error {
   constructor() {
     super("Modbus response timed out");
@@ -41,12 +49,16 @@ function crc16(buf) {
 }
 
 // src/transport/webserial.ts
+var DEFAULT_CRC_POLICY = { mode: "strict" };
+var DEFAULT_MAX_RESYNC_DROPS = 32;
 var WebSerialTransport = class _WebSerialTransport {
   constructor() {
     this.timeout = 500;
     this.rxBuf = new Uint8Array(0);
+    // rolling buffer across calls
+    this.strictCrc = true;
+    this.maxResyncDrops = DEFAULT_MAX_RESYNC_DROPS;
   }
-  // rolling buffer across calls
   // timeout gelpers
   setTimeout(ms) {
     this.timeout = ms;
@@ -54,6 +66,9 @@ var WebSerialTransport = class _WebSerialTransport {
   getTimeout() {
     return this.timeout;
   }
+  getPort() {
+    return this.port;
+  }
   // ----------------------------------------------------------------
   // Factory
   // ----------------------------------------------------------------
@@ -63,72 +78,127 @@ var WebSerialTransport = class _WebSerialTransport {
     return t;
   }
   async init(opts) {
-    var _a, _b, _c, _d, _e, _f;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _i;
     this.timeout = (_a = opts.timeout) != null ? _a : 500;
-    this.port = await navigator.serial.requestPort({ filters: (_b = opts.requestFilters) != null ? _b : [] });
+    this.port = (_c = opts.port) != null ? _c : await navigator.serial.requestPort({
+      filters: (_b = opts.requestFilters) != null ? _b : []
+    });
     await this.port.open({
-      baudRate: (_c = opts.baudRate) != null ? _c : 9600,
-      dataBits: (_d = opts.dataBits) != null ? _d : 8,
-      stopBits: (_e = opts.stopBits) != null ? _e : 1,
-      parity: (_f = opts.parity) != null ? _f : "none"
+      baudRate: (_d = opts.baudRate) != null ? _d : 9600,
+      dataBits: (_e = opts.dataBits) != null ? _e : 8,
+      stopBits: (_f = opts.stopBits) != null ? _f : 1,
+      parity: (_g = opts.parity) != null ? _g : "none"
     });
     this.reader = this.port.readable.getReader();
     this.writer = this.port.writable.getWriter();
+    const policy = (_h = opts.crcPolicy) != null ? _h : DEFAULT_CRC_POLICY;
+    if (policy.mode === "strict") {
+      this.strictCrc = true;
+      this.maxResyncDrops = 0;
+    } else {
+      this.strictCrc = false;
+      this.maxResyncDrops = (_i = policy.maxResyncDrops) != null ? _i : DEFAULT_MAX_RESYNC_DROPS;
+    }
   }
   // ----------------------------------------------------------------
   //  transact(): Send `req` and await a response whose function-code matches the request
   // ---------------------------------------------------------------- */
   async transact(req) {
     await this.writer.write(req);
+    const STRICT_CRC = this.strictCrc;
+    const MAX_RESYNC_DROPS = this.maxResyncDrops;
     const expectedFC = req[1] & 127;
     const deadline = Date.now() + this.timeout;
+    let State;
+    ((State2) => {
+      State2[State2["TRY_EXTRACT"] = 0] = "TRY_EXTRACT";
+      State2[State2["HAVE_FRAME"] = 1] = "HAVE_FRAME";
+      State2[State2["BAD_CRC"] = 2] = "BAD_CRC";
+      State2[State2["NEED_READ"] = 3] = "NEED_READ";
+    })(State || (State = {}));
+    let state = 0 /* TRY_EXTRACT */;
+    let frame = null;
+    let discardedBytes = 0;
     while (true) {
-      while (this.rxBuf.length < 3) {
-        if (Date.now() > deadline) throw new TimeoutError();
-        const { value } = await this.reader.read();
-        if (!value) throw new TimeoutError();
-        this.rxBuf = concat(this.rxBuf, value);
-      }
-      const need = this.frameLengthIfComplete(this.rxBuf);
-      if (need === 0) {
-        if (Date.now() > deadline) throw new TimeoutError();
-        const { value } = await this.reader.read();
-        if (!value) throw new TimeoutError();
-        this.rxBuf = concat(this.rxBuf, value);
-        continue;
-      }
-      const frame = this.rxBuf.slice(0, need);
-      this.rxBuf = this.rxBuf.slice(need);
-      const crc = crc16(frame.subarray(0, frame.length - 2));
-      const crcOk = (crc & 255) === frame[frame.length - 2] && crc >> 8 === frame[frame.length - 1];
-      if (!crcOk) {
-        this.rxBuf = this.rxBuf.slice(1);
-        throw new CrcError();
-      }
-      const fc = frame[1] & 127;
-      if (fc === expectedFC) {
-        return frame;
-      } else {
-        continue;
+      switch (state) {
+        case 0 /* TRY_EXTRACT */: {
+          frame = this.extractFrame();
+          if (!frame) {
+            state = 3 /* NEED_READ */;
+            break;
+          }
+          state = 1 /* HAVE_FRAME */;
+        }
+        case 1 /* HAVE_FRAME */: {
+          if (this.crcOk(frame)) {
+            const fc = frame[1] & 127;
+            if (fc === expectedFC) return frame;
+            frame = null;
+            state = 0 /* TRY_EXTRACT */;
+            continue;
+          }
+          state = 2 /* BAD_CRC */;
+        }
+        case 2 /* BAD_CRC */: {
+          if (STRICT_CRC) throw new CrcError();
+          discardedBytes += frame ? frame.length : 0;
+          frame = null;
+          if (discardedBytes >= MAX_RESYNC_DROPS) {
+            throw new ResyncError(discardedBytes, MAX_RESYNC_DROPS);
+          }
+          if (this.rxBuf.length > 0) {
+            state = 0 /* TRY_EXTRACT */;
+            continue;
+          }
+          state = 3 /* NEED_READ */;
+        }
+        case 3 /* NEED_READ */: {
+          if (Date.now() > deadline) throw new TimeoutError();
+          const { value } = await this.reader.read();
+          if (!value) throw new TimeoutError();
+          this.rxBuf = concat(this.rxBuf, value);
+          state = 0 /* TRY_EXTRACT */;
+          continue;
+        }
+        default:
+          throw new Error("invalid state");
       }
     }
   }
+  extractFrame() {
+    if (this.rxBuf.length < 3) return null;
+    const need = this.frameLengthIfComplete(this.rxBuf);
+    if (need === 0) return null;
+    const frame = this.rxBuf.slice(0, need);
+    this.rxBuf = this.rxBuf.slice(need);
+    return frame;
+  }
+  crcOk(frame) {
+    const crc = crc16(frame.subarray(0, frame.length - 2));
+    const crcOk = (crc & 255) === frame[frame.length - 2] && crc >> 8 === frame[frame.length - 1];
+    return crcOk;
+  }
   // ----------------------------------------------------------------
   //  Determine expected length; return 0 if we still need more bytes
   // ----------------------------------------------------------------
   frameLengthIfComplete(buf) {
     if (buf.length < 3) return 0;
+    const id = buf[0];
     const fc = buf[1];
+    if (id === 0 || id > 247) return 0;
     if (fc & 128) return buf.length >= 5 ? 5 : 0;
     if (fc === 1 || fc === 2 || fc === 3 || fc === 4) {
-      const need = 3 + buf[2] + 2;
+      const byteCount = buf[2];
+      if (byteCount > 252) {
+        return buf.length >= 8 ? 8 : 0;
+      }
+      const need = 3 + byteCount + 2;
       return buf.length >= need ? need : 0;
     }
     if (fc === 5 || fc === 6 || fc === 15 || fc === 16)
       return buf.length >= 8 ? 8 : 0;
     return buf.length >= 8 ? 8 : 0;
   }
-  // -- close port --
   async close() {
     var _a, _b, _c;
     await ((_a = this.reader) == null ? void 0 : _a.cancel());
@@ -504,6 +574,9 @@ var ModbusRTU = class _ModbusRTU {
   getTimeout() {
     return this.transport.getTimeout();
   }
+  getPort() {
+    return this.transport.getPort();
+  }
   /* =========================  READ  =============================== */
   /** FC 01 – coils */
   async readCoils(addr, qty) {
@@ -593,6 +666,7 @@ export {
   CrcError,
   ExceptionError,
   ModbusRTU,
+  ResyncError,
   TimeoutError,
   buildMaskWriteRegister,
   buildReadCoils,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "modbus-webserial",
-  "version": "0.10.0",
+  "version": "0.10.3",
   "description": "Tiny TypeScript library for speaking Modbus-RTU from the browser via Web Serial",
   "type": "module",
   "author": "Antti Kotajärvi <antti.kotajarvi@hotmail.com>",