modbus-rs-wasm 0.13.0 → 0.14.1

package/README.md

@@ -2,7 +2,7 @@
 
 Browser-native WebAssembly bindings for [modbus-rs](https://github.com/Raghava-Ch/modbus-rs), enabling Modbus TCP (via WebSockets) and Modbus RTU/ASCII (via Web Serial) directly in the browser.
 
-> **Note:** If you are building a Node.js backend application, use the native [`modbus-rs`](https://www.npmjs.com/package/modbus-rs) package instead.
+> **Note:** This package is designed for browser-native environments (using WebSockets and Web Serial). If you are building a Node.js backend application, use the native [`modbus-rs`](https://www.npmjs.com/package/modbus-rs) package instead. Running this package in pure Node.js requires `--experimental-wasm-modules` and is not officially supported.
 
 ## Installation
 
@@ -10,29 +10,49 @@ Browser-native WebAssembly bindings for [modbus-rs](https://github.com/Raghava-C
 npm install modbus-rs-wasm
 ```
 
-## Quick Start (Modbus TCP via WebSocket Gateway)
+## Integration & Frameworks (Vite, Svelte, React, etc.)
 
-First, run the gateway [modbus-gateway](https://github.com/Raghava-Ch/modbus-gateway).
+No custom resolver aliases or configuration workarounds are required starting in `v0.14.0`. Standard package entry points are resolved automatically based on your builder/bundler targets.
+
+### Web (Direct / HTML / Vanilla JS)
+When loading the package in browser environments without a bundler, import the web entry point and await the initialization promise:
 
 ```javascript
-import { WasmModbusClient } from 'modbus-rs-wasm';
+import init, { WasmTcpTransport } from 'modbus-rs-wasm/dist/web/modbus-rs.js';
 
-async function readRegisters() {
-  // Connect to a WebSocket proxy that forwards to a Modbus TCP device
-  // (e.g. ws_url, unit_id, response_timeout_ms, retries, tick_interval_ms)
-  const client = new WasmModbusClient('ws://localhost:8502', 1, 5000, 3, 20);
+await init();
+const transport = new WasmTcpTransport('ws://localhost:8502', { 
+  responseTimeoutMs: 5000, 
+  retryAttempts: 3, 
+  tickIntervalMs: 20 
+});
+const client = transport.create_client({ unitId: 1 });
+```
 
-  try {
-    // Read 10 holding registers starting at address 0
-    const registers = await client.read_holding_registers(0, 10);
-    console.log('Holding registers:', registers); // Uint16Array
-  } catch (error) {
-    console.error('Failed to read registers:', error);
-  }
-}
+### Bundlers & Frameworks (Vite, SvelteKit, Next.js, etc.)
+When using modern bundlers, the root import automatically maps to the bundler target:
+
+```javascript
+import { WasmTcpTransport } from 'modbus-rs-wasm';
 ```
+*(Make sure your bundler is configured to load WebAssembly, e.g., using `vite-plugin-wasm` and `vite-plugin-top-level-await` in Vite).*
 
-## Quick Start (Modbus RTU via Web Serial)
+## Quick Start
+
+### Examples
+Ready-to-run HTML examples demonstrating both Modbus client and server functionality in the browser:
+
+- **[wasm_client/network_smoke.html](./examples/wasm_client/network_smoke.html)**: WebSocket Modbus TCP client example.
+- **[wasm_client/serial_smoke.html](./examples/wasm_client/serial_smoke.html)**: Web Serial Modbus RTU client example.
+- **[wasm_server/network_smoke.html](./examples/wasm_server/network_smoke.html)**: WebSocket Modbus TCP server example.
+- **[wasm_server/serial_smoke.html](./examples/wasm_server/serial_smoke.html)**: Web Serial Modbus RTU server example.
+
+To run the examples locally:
+```bash
+npx serve examples/
+```
+
+### Modbus RTU via Web Serial
 
 *Web Serial requires a Chromium-based browser (Chrome, Edge, Opera) and must be initiated by a user gesture (e.g., button click).*
 
@@ -41,19 +61,29 @@ If you are using modbus-rs on Node.js, you can use the native [`modbus-rs`](http
 If you have limitation on serial port using browser, then you may be interested in connecting serial port over ws/tcp so you can use the gateway application [modbus-gateway](https://github.com/Raghava-Ch/modbus-gateway).
 
 ```javascript
-import { request_serial_port, WasmSerialModbusClient } from 'modbus-rs-wasm';
+import { request_serial_port, WasmSerialTransport } from 'modbus-rs-wasm';
 
 document.getElementById('connect-btn').addEventListener('click', async () => {
   try {
     // 1. Prompt user to select a serial port
     const portHandle = await request_serial_port();
     
-    // 2. Connect client (handle, unit_id, mode, baud, data_bits, stop_bits, parity, timeout, retries, tick)
-    const client = new WasmSerialModbusClient(
-      portHandle, 1, 'rtu', 19200, 8, 1, 'even', 1000, 3, 20
-    );
-
-    // 3. Read coils
+    // 2. Create RTU Transport
+    const transport = new WasmSerialTransport(portHandle, {
+      mode: 'rtu',
+      baudRate: 19200,
+      dataBits: 8,
+      stopBits: 1,
+      parity: 'even',
+      responseTimeoutMs: 1000,
+      retryAttempts: 3,
+      tickIntervalMs: 20
+    });
+
+    // 3. Spawn a client for a specific slave (Unit ID)
+    const client = transport.create_client({ unitId: 10 });
+
+    // 4. Read coils
     const coils = await client.read_coils(0, 8);
     console.log('Coils:', coils); // Uint8Array
     
@@ -63,6 +93,101 @@ document.getElementById('connect-btn').addEventListener('click', async () => {
 });
 ```
 
+### Modbus TCP via WebSocket Gateway
+First, run the gateway [modbus-gateway](https://github.com/Raghava-Ch/modbus-gateway).
+
+```javascript
+import { WasmTcpTransport } from 'modbus-rs-wasm';
+
+async function readRegisters() {
+  // 1. Connect to a WebSocket proxy that forwards to a Modbus TCP device
+  const transport = new WasmTcpTransport('ws://localhost:8502', { 
+    responseTimeoutMs: 5000, 
+    retryAttempts: 3, 
+    tickIntervalMs: 20 
+  });
+
+  // 2. Spawn a client attached to Unit ID 1
+  const client = transport.create_client({ unitId: 1 });
+
+  try {
+    // 3. Read 10 holding registers starting at address 0
+    const registers = await client.read_holding_registers(0, 10);
+    console.log('Holding registers:', registers); // Uint16Array
+  } catch (error) {
+    console.error('Failed to read registers:', error);
+  }
+}
+```
+
+### Modbus server demo with modbus-rs-wasm
+
+The `modbus-rs-wasm` package also provides building blocks for server simulation inside the browser. You can instantiate a `WasmTcpServer` or `WasmSerialServer` by providing a configuration and a JavaScript callback to process incoming requests.
+
+Here is a quick example of setting up a simulated server via a WebSocket TCP gateway:
+
+```javascript
+import { WasmTcpGatewayConfig, WasmTcpServer } from 'modbus-rs-wasm';
+
+async function simulateServer() {
+  // 1. Configure the server (e.g., pointing to a WebSocket gateway)
+  const config = new WasmTcpGatewayConfig("ws://localhost:8080");
+
+  // 2. Create the server and define the request handler
+  const server = new WasmTcpServer(config, async (request) => {
+    console.log("Received Modbus request:", request);
+    
+    // Simulate processing the request
+    // The handler can be fully asynchronous and return a Promise
+    return {
+      // Return appropriate response fields based on the request
+      success: true,
+      data: [100, 200, 300]
+    };
+  });
+
+  // 3. Start the server
+  server.start();
+  
+  // Observe the server status
+  console.log("Server running:", server.is_running());
+  console.log("Server status:", server.status_snapshot());
+}
+```
+
+### Serial Server Simulation
+
+You can also create a simulated serial server (RTU or ASCII) and attach a browser `SerialPort` to it using the Web Serial API:
+
+```javascript
+import { WasmSerialServerConfig, WasmSerialServer } from 'modbus-rs-wasm';
+
+async function simulateSerialServer() {
+  // 1. Request a serial port from the user (requires user gesture)
+  const port = await navigator.serial.requestPort();
+  
+  // 2. Configure the server for RTU or ASCII mode
+  const config = WasmSerialServerConfig.rtu(); // or .ascii()
+
+  // 3. Create the server with a request handler callback
+  const server = new WasmSerialServer(config, async (request) => {
+    console.log("Received Modbus request via Serial:", request);
+    return {
+      success: true,
+      data: [100, 200, 300]
+    };
+  });
+
+  // 4. Attach the browser serial port
+  server.attach_serial_port(port);
+
+  // 5. Start the server
+  server.start();
+  
+  console.log("Serial Server running:", server.is_running());
+}
+```
+
 ## License
 
 GPL-3.0-only — see [LICENSE](./LICENSE). A commercial license is available for proprietary use.

package/dist/bundler/modbus-rs.d.ts

@@ -1,10 +1,35 @@
 /* tslint:disable */
 /* eslint-disable */
 
+export interface WasmSerialTransportOptions {
+    mode?: "rtu" | "ascii";
+    baudRate: number;
+    dataBits?: 5 | 6 | 7 | 8;
+    stopBits?: 1 | 2;
+    parity?: "none" | "even" | "odd";
+    responseTimeoutMs?: number;
+    retryAttempts?: number;
+    tickIntervalMs?: number;
+}
+
+
+
+export interface WasmTcpTransportOptions {
+    responseTimeoutMs?: number;
+    retryAttempts?: number;
+    tickIntervalMs?: number;
+}
+export interface WasmCreateClientOptions {
+    unitId?: number;
+}
+
+
+
 /**
- * Browser-facing Modbus client that communicates over a WebSocket transport.
+ * Browser-facing Modbus client bound to a specific unit ID.
  */
 export class WasmModbusClient {
+    private constructor();
     free(): void;
     [Symbol.dispose](): void;
     /**
@@ -28,13 +53,11 @@ export class WasmModbusClient {
      */
     get_comm_event_log(): Promise<any>;
     /**
-     * Returns `true` if there are in-flight Modbus requests waiting for
-     * response/timeout resolution.
+     * Returns `true` if there are in-flight Modbus requests.
      */
     has_pending_requests(): boolean;
     /**
-     * Returns `true` when the underlying WebSocket is open and the transport
-     * considers itself connected.
+     * Returns `true` when the underlying WebSocket is open.
      */
     is_connected(): boolean;
     /**
@@ -44,17 +67,6 @@ export class WasmModbusClient {
      * Returns a `Promise` resolving with `true` or rejects on error.
      */
     mask_write_register(address: number, and_mask: number, or_mask: number): Promise<any>;
-    /**
-     * Create a new Modbus master client and immediately start the background tick loop.
-     *
-     * # Arguments
-     * - `ws_url`           — WebSocket URL of the Modbus/TCP gateway (e.g. `"ws://192.168.1.1:8502"`).
-     * - `unit_id`          — Modbus unit ID / slave address of the target device (1–247).
-     * - `response_timeout_ms` — How long (ms) to wait before retrying or failing a request.
-     * - `retry_attempts`   — Number of retries before reporting an error to JS.
-     * - `tick_interval_ms` — How often (ms) the tick loop calls `poll()`. 20 ms is a safe default.
-     */
-    constructor(ws_url: string, unit_id: number, response_timeout_ms: number, retry_attempts: number, tick_interval_ms: number);
     /**
      * Read `quantity` coils starting at `address`.
      *
@@ -142,11 +154,6 @@ export class WasmModbusClient {
      * Returns a `Promise` resolving with a `Uint16Array` (the values read) or rejects on error.
      */
     read_write_multiple_registers(read_address: number, read_quantity: number, write_address: number, _write_quantity: number, values: Uint16Array): Promise<any>;
-    /**
-     * Drop all pending in-flight requests and attempt to reconnect the WebSocket.
-     * Outstanding Promises for dropped requests will be rejected with `"ConnectionLost"`.
-     */
-    reconnect(): boolean;
     /**
      * Report Server ID (FC 17).
      *
@@ -188,9 +195,10 @@ export class WasmModbusClient {
 }
 
 /**
- * Browser-facing Modbus client that communicates over Web Serial RTU or ASCII.
+ * Browser-facing Modbus client bound to a specific serial unit ID.
  */
 export class WasmSerialModbusClient {
+    private constructor();
     free(): void;
     [Symbol.dispose](): void;
     /**
@@ -214,12 +222,11 @@ export class WasmSerialModbusClient {
      */
     get_comm_event_log(): Promise<any>;
     /**
-     * Returns `true` if there are in-flight Modbus requests waiting for
-     * response/timeout resolution.
+     * Returns `true` if there are in-flight Modbus requests.
      */
     has_pending_requests(): boolean;
     /**
-     * Returns `true` when the serial port is open and the transport considers itself connected.
+     * Returns `true` when the serial port is open.
      */
     is_connected(): boolean;
     /**
@@ -229,13 +236,6 @@ export class WasmSerialModbusClient {
      * Returns a `Promise` resolving with `true` or rejects on error.
      */
     mask_write_register(address: number, and_mask: number, or_mask: number): Promise<any>;
-    /**
-     * Creates a Modbus serial client over browser Web Serial.
-     *
-     * `mode` accepts "rtu" or "ascii" (case-insensitive).
-     * `parity` accepts "none", "even", or "odd".
-     */
-    constructor(port_handle: WasmSerialPortHandle, unit_id: number, mode: string, baud_rate: number, data_bits: number, stop_bits: number, parity: string, response_timeout_ms: number, retry_attempts: number, tick_interval_ms: number);
     /**
      * Read `quantity` coils starting at `address`.
      *
@@ -320,11 +320,6 @@ export class WasmSerialModbusClient {
      * Returns a `Promise` resolving with a `Uint16Array` (the values read) or rejects on error.
      */
     read_write_multiple_registers(read_address: number, read_quantity: number, write_address: number, _write_quantity: number, values: Uint16Array): Promise<any>;
-    /**
-     * Drop all pending in-flight requests and attempt to reopen the serial port.
-     * Outstanding Promises for dropped requests will be rejected with `"ConnectionLost"`.
-     */
-    reconnect(): boolean;
     /**
      * Report Server ID (FC 17).
      *
@@ -461,6 +456,41 @@ export class WasmSerialServerConfig {
     static rtu(): WasmSerialServerConfig;
 }
 
+/**
+ * Connection and polling manager for browser Modbus Serial clients.
+ */
+export class WasmSerialTransport {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Closes the serial port connection and rejects all pending requests.
+     */
+    close(): void;
+    /**
+     * Creates a device client bound to the specified unit ID.
+     */
+    createClient(options?: WasmCreateClientOptions | null): WasmSerialModbusClient;
+    /**
+     * Returns `true` if there are in-flight Modbus requests.
+     */
+    has_pending_requests(): boolean;
+    /**
+     * Returns `true` when the serial port is open and connected.
+     */
+    is_connected(): boolean;
+    /**
+     * Creates a new Serial (RTU) transport using the provided `port_handle`.
+     *
+     * The transport claims the underlying serial stream and manages the
+     * read/write loop, allowing multiple clients to multiplex requests over it.
+     */
+    constructor(port_handle: WasmSerialPortHandle, options?: WasmSerialTransportOptions | null);
+    /**
+     * Drop all pending in-flight requests and attempt to reopen the serial port.
+     */
+    reconnect(): boolean;
+}
+
 /**
  * High-level design descriptor for phased server binding rollout.
  */
@@ -637,6 +667,41 @@ export class WasmTcpServer {
     ws_url(): string;
 }
 
+/**
+ * Connection and background polling manager for browser Modbus TCP clients.
+ */
+export class WasmTcpTransport {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Closes the connection and rejects all pending requests.
+     */
+    close(): void;
+    /**
+     * Creates a device client bound to the specified unit ID.
+     */
+    createClient(options?: WasmCreateClientOptions | null): WasmModbusClient;
+    /**
+     * Returns `true` if there are in-flight Modbus requests.
+     */
+    has_pending_requests(): boolean;
+    /**
+     * Returns `true` when the underlying WebSocket is open and connected.
+     */
+    is_connected(): boolean;
+    /**
+     * Creates a new TCP/WebSocket transport.
+     *
+     * This establishes a connection to the provided `ws_url` and handles
+     * the underlying read/write loops.
+     */
+    constructor(ws_url: string, options?: WasmTcpTransportOptions | null);
+    /**
+     * Drop all pending in-flight requests and attempt to reconnect.
+     */
+    reconnect(): boolean;
+}
+
 /**
  * Requests a browser serial port from `navigator.serial.requestPort()`.
  *

package/dist/bundler/modbus-rs.js

@@ -5,5 +5,5 @@ import { __wbg_set_wasm } from "./modbus-rs_bg.js";
 __wbg_set_wasm(wasm);
 wasm.__wbindgen_start();
 export {
-    WasmModbusClient, WasmSerialModbusClient, WasmSerialPortHandle, WasmSerialServer, WasmSerialServerConfig, WasmServerBindingPlan, WasmServerStatusSnapshot, WasmServerTransportKind, WasmTcpGatewayConfig, WasmTcpServer, request_serial_port
+    WasmModbusClient, WasmSerialModbusClient, WasmSerialPortHandle, WasmSerialServer, WasmSerialServerConfig, WasmSerialTransport, WasmServerBindingPlan, WasmServerStatusSnapshot, WasmServerTransportKind, WasmTcpGatewayConfig, WasmTcpServer, WasmTcpTransport, request_serial_port
 } from "./modbus-rs_bg.js";