modbus-rs-wasm 0.14.1 → 0.15.0

package/README.md

@@ -12,13 +12,13 @@ npm install modbus-rs-wasm
 
 ## Integration & Frameworks (Vite, Svelte, React, etc.)
 
-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.
+No custom resolver aliases are required. 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:
+When loading the package in browser environments without a bundler (e.g. from CDNs like unpkg or jsDelivr), import the web entry point and await the initialization promise:
 
 ```javascript
-import init, { WasmTcpTransport } from 'modbus-rs-wasm/dist/web/modbus-rs.js';
+import init, { WasmTcpTransport } from 'modbus-rs-wasm/web';
 
 await init();
 const transport = new WasmTcpTransport('ws://localhost:8502', { 
@@ -29,27 +29,87 @@ const transport = new WasmTcpTransport('ws://localhost:8502', {
 const client = transport.create_client({ unitId: 1 });
 ```
 
-### Bundlers & Frameworks (Vite, SvelteKit, Next.js, etc.)
-When using modern bundlers, the root import automatically maps to the bundler target:
+### Bundlers & Modern Frameworks
+
+When using modern bundlers (Vite, Webpack, Next.js, etc.), the root import maps to the bundler target where WebAssembly is loaded automatically:
 
 ```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).*
+
+Because WASM is an asynchronous module dependency, you must configure your bundler to support WASM loader options:
+
+#### 1. Vite (React, Svelte, Vue, SolidJS, etc. via Vite)
+Vite requires helper plugins to support WebAssembly. Install `vite-plugin-wasm` and `vite-plugin-top-level-await`:
+
+```bash
+npm install -D vite-plugin-wasm vite-plugin-top-level-await
+```
+
+In your `vite.config.ts`, register the plugins and **exclude** `modbus-rs-wasm` from dependency pre-bundling (to prevent Esbuild from trying to optimize the WASM module):
+
+```typescript
+import { defineConfig } from 'vite';
+import wasm from 'vite-plugin-wasm';
+import topLevelAwait from 'vite-plugin-top-level-await';
+
+export default defineConfig({
+  plugins: [wasm(), topLevelAwait()],
+  optimizeDeps: {
+    exclude: ['modbus-rs-wasm']
+  }
+});
+```
+
+#### 2. Webpack 5 (React, Angular, or custom Webpack setups)
+Webpack 5 supports WebAssembly natively but it is disabled by default. You need to enable the `asyncWebAssembly` experiment in your `webpack.config.js`:
+
+```javascript
+module.exports = {
+  // ...
+  experiments: {
+    asyncWebAssembly: true,
+  },
+};
+```
+
+#### 3. Next.js (Webpack mode)
+Configure `next.config.js` to enable WebAssembly support inside Next.js's internal Webpack runner:
+
+```javascript
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  webpack(config) {
+    config.experiments = {
+      ...config.experiments,
+      asyncWebAssembly: true,
+    };
+    return config;
+  },
+};
+
+module.exports = nextConfig;
+```
 
 ## 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.
+- **[wasm_client/network_smoke.html](https://github.com/Raghava-Ch/modbus-rs/blob/main/mbus-ffi/wasm/examples/wasm_client/network_smoke.html)**: WebSocket Modbus TCP client example.
+- **[wasm_client/serial_smoke.html](https://github.com/Raghava-Ch/modbus-rs/blob/main/mbus-ffi/wasm/examples/wasm_client/serial_smoke.html)**: Web Serial Modbus RTU client example.
+- **[wasm_server/network_smoke.html](https://github.com/Raghava-Ch/modbus-rs/blob/main/mbus-ffi/wasm/examples/wasm_server/network_smoke.html)**: WebSocket Modbus TCP server example.
+- **[wasm_server/serial_smoke.html](https://github.com/Raghava-Ch/modbus-rs/blob/main/mbus-ffi/wasm/examples/wasm_server/serial_smoke.html)**: Web Serial Modbus RTU server example.
+- **[Demo Application](https://modbus-lab.vercel.app)**: Live web application demonstrating modbus-rs-wasm in action. [modbus-lab.vercel.app](https://modbus-lab.vercel.app)
+- **[Real-World Example Source Code](https://github.com/Raghava-Ch/modbus-lab)**: Repository containing the source code for the demo web client and Tauri-based desktop client/server simulators.
 
 To run the examples locally:
 ```bash
-npx serve examples/
+# clone the repo
+cd modbus-rs/mbus-ffi/wasm
+npx serve ./
+# Navigate to example folder with chromium based web browser run the examples.
+# you can also use the tauri desktop client and server simulator.
 ```
 
 ### Modbus RTU via Web Serial
@@ -76,16 +136,15 @@ document.getElementById('connect-btn').addEventListener('click', async () => {
       stopBits: 1,
       parity: 'even',
       responseTimeoutMs: 1000,
-      retryAttempts: 3,
-      tickIntervalMs: 20
+      retryAttempts: 3
     });
 
     // 3. Spawn a client for a specific slave (Unit ID)
-    const client = transport.create_client({ unitId: 10 });
+    const client = transport.createClient({ unitId: 10 });
 
     // 4. Read coils
-    const coils = await client.read_coils(0, 8);
-    console.log('Coils:', coils); // Uint8Array
+    const coils = await client.readCoils({ address: 0, quantity: 8 });
+    console.log('Coils:', coils); // boolean[]
     
   } catch (err) {
     console.error('Serial error:', err);
@@ -101,18 +160,17 @@ 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', { 
+  const transport = await WasmTcpTransport.connect('ws://localhost:8502', { 
     responseTimeoutMs: 5000, 
-    retryAttempts: 3, 
-    tickIntervalMs: 20 
+    retryAttempts: 3
   });
 
   // 2. Spawn a client attached to Unit ID 1
-  const client = transport.create_client({ unitId: 1 });
+  const client = transport.createClient({ unitId: 1 });
 
   try {
     // 3. Read 10 holding registers starting at address 0
-    const registers = await client.read_holding_registers(0, 10);
+    const registers = await client.readHoldingRegisters({ address: 0, quantity: 10 });
     console.log('Holding registers:', registers); // Uint16Array
   } catch (error) {
     console.error('Failed to read registers:', error);
@@ -122,36 +180,40 @@ async function readRegisters() {
 
 ### 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.
+The `modbus-rs-wasm` package also provides building blocks for server simulation inside the browser. You can bind a `WasmTcpServer` or `WasmSerialServer` by providing configurations and an object implementing `ServerHandlers` callback methods.
 
 Here is a quick example of setting up a simulated server via a WebSocket TCP gateway:
 
 ```javascript
-import { WasmTcpGatewayConfig, WasmTcpServer } from 'modbus-rs-wasm';
+import { 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]
-    };
+  // 1. Define the request handlers
+  const handlers = {
+    onReadHoldingRegisters: async (request) => {
+      console.log("Received Modbus request:", request);
+      
+      // Callbacks can return values synchronously or as Promises
+      return [100, 200, 300];
+    }
+  };
+
+  // 2. Bind the server
+  const server = await WasmTcpServer.bind(
+    {
+      wsUrl: "ws://localhost:8080",
+      unitId: 1
+    },
+    handlers
+  );
+
+  // 3. Start the event loop (runs asynchronously in background)
+  server.serve().catch(err => {
+    console.error("Server crashed:", err);
   });
-
-  // 3. Start the server
-  server.start();
   
-  // Observe the server status
-  console.log("Server running:", server.is_running());
-  console.log("Server status:", server.status_snapshot());
+  // To stop the server later:
+  // await server.shutdown();
 }
 ```
 
@@ -160,34 +222,41 @@ async function simulateServer() {
 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';
+import { 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]
-    };
+  // 2. Define the request handlers
+  const handlers = {
+    onReadHoldingRegisters: (request) => {
+      console.log("Received Modbus request via Serial:", request);
+      return [100, 200, 300];
+    }
+  };
+
+  // 3. Bind the server for RTU mode
+  const server = await WasmSerialServer.bindRtu(
+    {
+      serialPort: port,
+      unitId: 1,
+      baudRate: 19200
+    },
+    handlers
+  );
+
+  // 4. Start the event loop
+  server.serve().catch(err => {
+    console.error("Serial Server crashed:", err);
   });
-
-  // 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());
 }
 ```
 
+## Migration Guide
+
+Detailed step-by-step migration guides are available in the [Migration Guides](https://github.com/Raghava-Ch/modbus-rs/tree/main/documentation/migrations) directory.
+
 ## License
 
 GPL-3.0-only — see [LICENSE](./LICENSE). A commercial license is available for proprietary use.