@flux-control/effect-modbus-rs

Provides typed Effect services for native and browser Modbus transports and servers. Transport services use Context.Service and scoped layers. They open on first client access and close when the provided scope ends.

Build the package with bun run build before using package imports. The build creates dist/, which the package export map uses.

Native transports: SerialTransportService, RtuTransportService, AsciiTransportService, and TcpTransportService. Browser transports: WasmSerialTransportService, WasmRtuTransportService, WasmAsciiTransportService, and WasmWsTransportService. Call requestSerialPort from a user-gesture handler to request a Web Serial port.

Server layers include serialRtuServerLayer, serialAsciiServerLayer, tcpServerLayer, and tcpGatewayLayer. Browser server layers are experimental upstream surfaces.

Raw operations and result types

transport.withClient(unitId) returns a typed client. Register reads return Uint16Array; coil and discrete-input reads return CoilState[]. Operations fail with a variant of ModbusError. Use Effect.catchTags to handle specific variants. The union has eight variants, including ModbusCircuitOpenError. The batching declaration error is separate.

Register batching

planWrites and planReads plan the supplied registers without state or I/O. For example:

planWrites([{ address: 2000, value: 10 }, { address: 2001, value: 20 }]);
// One multiple-register write step for addresses 2000 and 2001.
Copy

createWriteDebouncer and createReadDebouncer collect separate calls only when configured with positive windows. Without a window, calls are not debounced. writeAll and readAll also collect when their windows are positive. Their Now variants flush the pending group immediately. Grouping does not make separate application operations atomic. A pending write can be superseded, and the cache can suppress a write based on its recorded value. Therefore, each call is not guaranteed to produce a separate device write. The cache records acknowledged writes from this process; it does not answer reads.

withBatchingClient combines planning, optional collection, and optional caching. It is separate from withClient, which exposes raw Modbus operations. Once a batching client exists for a unit, raw FC06, FC16, and FC23 operations for that unit fail. Raw reads, coil operations, and other operations remain available. A batching client does not extend ModbusOperations.

const raw = yield* transport.withClient(3);
const registers = yield* raw.readHoldingRegisters({ address: 2000, quantity: 2 });
// registers is Uint16Array.

const batch = yield* transport.withBatchingClient(3, {
  debounce: { writes: { window: '250 millis', maxHold: '1 second' } },
});
yield* batch.write({ address: 2000, value: 512 });
yield* batch.readAll([0, 1, 32]);
Copy

Retry and reconnection

Retry and reconnection are opt-in. A transport retry policy applies to its clients. Client and operation overrides replace that policy. For example:

TcpTransportService.make({ host, port, retry: RetryPolicies.tcp(), reconnect: {} });
const meter = yield* transport.withClient(1, { retry: RetryPolicies.serial() });
yield* meter.withRetry(RetryPolicies.none()).writeSingleCoil({ address: 0, value });
Copy

A configured reconnect supervisor owns reconnection for the transport and guards operations while the connection is down. Watch ConnectionState through transport.connectionState. retryModbus wraps an Effect; use it with a RetryPolicies.none() client for a compound operation. It does not replace a client's policy. Upstream transport retry options are excluded; see UpstreamRetryOptionKey.