@flux-control/effect-modbus-rs

Type-safe Modbus communication via Effect-TS, wrapping the modbus-rs npm bindings (Rust napi-rs under the hood).

Transport services

• SerialTransportService — Abstract serial transport (ASCII or RTU).
• RtuTransportService — Serial RTU transport (RS-232/485).
• AsciiTransportService — Serial ASCII transport.
• TcpTransportService — TCP/IP transport (Modbus/TCP).

Browser (WASM) transport services

• WasmSerialTransportService — Abstract Web Serial transport (ASCII or RTU).
• WasmRtuTransportService — Web Serial RTU transport.
• WasmAsciiTransportService — Web Serial ASCII transport.
• WasmWsTransportService — TCP-over-WebSocket transport (Modbus/TCP via a WS gateway).
• requestSerialPort — Requests a Web Serial port handle (user-gesture gated).

Server layers

Run a server layer with Layer.launch and execute with a runtime:

Layer.launch(tcpServerLayer({ host: "0.0.0.0", port: 502, unitId: 1 }, handlers)).pipe(Effect.runPromise)
Copy

• serialRtuServerLayer — Serial RTU server.
• serialAsciiServerLayer — Serial ASCII server.
• tcpServerLayer — TCP server.
• tcpGatewayLayer — TCP gateway.
• wasmWsServerLayer — Browser WS-gateway server (experimental upstream surface).
• wasmSerialRtuServerLayer / wasmSerialAsciiServerLayer — Browser Web Serial servers (experimental).

Errors

All Modbus operations fail with a ModbusError discriminated union. Use Effect.catchTags to handle specific variants:

Effect.catchTags(effect, {
  ModbusTimeoutError: ...,
  ModbusTransportError: ...,
})
Copy

Resilience

Nothing retries or reconnects implicitly — a transport behaves exactly as it always has until a policy is attached, so timing stays predictable by default. Resilience is configured on the transport, which owns it for every client derived from it:

TcpTransportService.Default({
  host, port,
  retry: RetryPolicies.tcp(),      // applied to every operation
  reconnect: {},                   // supervised reconnect + circuit breaker
})
Copy

Policies are error-aware: transient failures (timeouts, framing errors, a busy device) back off exponentially with jitter (on by default), while deterministic ones (illegal address, invalid argument) fail immediately.

Override per client — one bus, several device types — or per operation. Both replace the policy rather than composing with it:

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

With reconnect enabled, the transport runs one supervised reconnect for the whole application and refuses operations with ModbusCircuitOpenError while the link is down, instead of letting every caller queue requests onto a dead bus. Watch ConnectionState via transport.connectionState.

retryModbus remains for retrying a compound operation — a read-modify-write driven as a unit — over a RetryPolicies.none() client. Note that it wraps rather than replaces: unlike the two overrides above, it is piped around an effect the client has already wrapped in its own retry, so over a policied client the two nest and attempt counts multiply.

Resilience lives at this layer and only at this layer. modbus-rs's own transport-level retryAttempts / retryDelayMs / retryBackoffStrategy are not accepted by any transport constructor here: they retry beneath the Effect boundary where neither the policy, the circuit breaker, nor the logs can see them, and they reconnect inline, racing the supervisor fiber that owns reconnection. See UpstreamRetryOptionKey.