modbus-rs 0.14.0 → 0.15.1

package/README.md

@@ -5,10 +5,13 @@ High-performance Modbus TCP/RTU/ASCII client, server, and gateway for Node.js, p
 ## Features
 
 - **Async/Promise-based API** - All operations return Promises
-- **TCP Client** - Full Modbus TCP/IP client implementation
+- **TCP Client** - Full Modbus TCP/IP client implementation (supports communicating with multiple unit IDs behind a single IP address and a serial port)
 - **Serial Client** - Modbus RTU and ASCII over serial port
-- **TCP Server** - Build Modbus TCP servers with JavaScript handlers
-- **TCP Gateway** - Route requests to multiple downstream servers based on unit ID
+- **TCP & Serial Servers** - Build Modbus TCP servers, or Serial RTU and ASCII servers, using custom JavaScript handlers to respond to incoming requests
+- **Modbus Gateway** - Deploy high-performance gateways supporting WebSockets, TCP, and Serial (RTU/ASCII) as upstream channels, and TCP/Serial (RTU/ASCII) as downstream channels (WebSocket downstream support planned for a future release), dynamically routing requests based on unit ID mapping tables
+- **Thread Safety & Concurrency** - Rust-backed concurrent architecture ensures safe access across multiple async execution contexts
+- **Safety Locks** - Integrated bus locking to prevent command collisions and state corruption
+- **Multi-drop Serial Support** - Manage and communicate with multiple device unit IDs on a single physical RTU/ASCII bus
 - **High Performance** - Native Rust core with napi-rs bindings
 - **Type Safe** - Full TypeScript definitions included
 - **Cross Platform** - Pre-built binaries for Linux, macOS, and Windows
@@ -33,7 +36,7 @@ async function main() {
   const transport = await AsyncTcpTransport.connect({
     host: '127.0.0.1',
     port: 502,
-    timeoutMs: 5000,
+    requestTimeoutMs: 5000,
   });
 
   const client = transport.createClient({ unitId: 1 });
@@ -96,8 +99,8 @@ const { AsyncTcpModbusServer } = require('modbus-rs');
 
 const holdingRegisters = new Array(1000).fill(0);
 
-function main() {
-  const server = AsyncTcpModbusServer.bind(
+async function main() {
+  const server = await AsyncTcpModbusServer.bind(
     { host: '0.0.0.0', port: 502, unitId: 1 },
     {
       onReadHoldingRegisters: (req) => {
@@ -117,11 +120,7 @@ function main() {
   });
 }
 
-try {
-  main();
-} catch (err) {
-  console.error(err);
-}
+main().catch(console.error);
 ```
 
 ### TCP Gateway
@@ -155,6 +154,37 @@ async function main() {
 main().catch(console.error);
 ```
 
+## 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.
+
+
+## Error Handling with Code Constants
+
+Error code constants are now exported:
+
+```js
+const { getModbusErrorCode, ModbusErrorCode } = require('modbus-rs');
+
+try {
+  await client.readHoldingRegisters({ address: 0, quantity: 10 });
+} catch (err) {
+  const code = getModbusErrorCode(err);
+  switch (code) {
+    case ModbusErrorCode.EXCEPTION:      console.error('Modbus exception'); break;
+    case ModbusErrorCode.TIMEOUT:        console.error('Request timed out'); break;
+    case ModbusErrorCode.CONNECTION_CLOSED: console.error('Disconnected'); break;
+    default:                             console.error('Unknown error:', err.message);
+  }
+}
+```
+
+## Known Limitations
+
+- **AbortSignal**: Uses `signal.onabort` instead of `signal.addEventListener`. Only one abort handler per signal object is supported.
+- **Gateway route limit**: `AsyncTcpGateway` supports a maximum of **64 routing entries**. Attempting to add more will throw at `bind()` time.
+- **Gateway Downstream**: WebSockets are currently not supported as a downstream channel (support is planned for a future release).
+
 ## API Reference
 
 ### AsyncTcpTransport
@@ -162,7 +192,7 @@ main().catch(console.error);
 - `static connect(opts: TcpTransportOptions): Promise<AsyncTcpTransport>` - Connect to a Modbus TCP server
 - `close(): Promise<void>` - Close the connection
 - `reconnect(): Promise<void>` - Re-establish the connection
-- `createClient(opts?: CreateClientOptions): AsyncTcpModbusClient` - Create a logical client instance bound to a specific unit ID (defaults to `1`)
+- `createClient(opts: CreateClientOptions): AsyncTcpModbusClient` - Create a logical client instance bound to a specific unit ID (required)
 - `setRequestTimeout(ms: number): void` - Set a global request timeout (in milliseconds)
 - `clearRequestTimeout(): void` - Clear the global request timeout
 - `pendingRequests: boolean` - (Getter) Returns whether there are requests currently in flight
@@ -199,31 +229,19 @@ These logical clients contain all the Modbus function code methods:
 
 ### AsyncTcpModbusServer
 
-- `bind(opts, handlers)` - Create and start a TCP server
-- `shutdown()` - Stop the server
-
-### AsyncTcpGateway
+- `static bind(opts, handlers): Promise<AsyncTcpModbusServer>` - Create and start a TCP server
+- `shutdown(): Promise<void>` - Stop the server
 
-- `bind(opts, config)` - Create and start a gateway
-- `shutdown()` - Stop the gateway
+### AsyncSerialModbusServer
 
-## Error Handling
+- `static bindRtu(opts, handlers): Promise<AsyncSerialModbusServer>` - Create and start a Serial RTU server
+- `static bindAscii(opts, handlers): Promise<AsyncSerialModbusServer>` - Create and start a Serial ASCII server
+- `shutdown(): Promise<void>` - Stop the server
 
-All errors are thrown as JavaScript Error objects with descriptive messages:
+### AsyncTcpGateway
 
-```javascript
-try {
-  await client.readHoldingRegisters({ address: 0, quantity: 10 });
-} catch (err) {
-  if (err.message.includes('MODBUS_EXCEPTION')) {
-    console.error('Modbus exception:', err.message);
-  } else if (err.message.includes('MODBUS_TIMEOUT')) {
-    console.error('Request timed out');
-  } else {
-    console.error('Error:', err.message);
-  }
-}
-```
+- `static bind(opts, config): Promise<AsyncTcpGateway>` - Create and start a gateway
+- `shutdown(): Promise<void>` - Stop the gateway
 
 ## Supported platforms