modbus-rs 0.14.0 → 0.15.1

package/index.d.ts

@@ -1,82 +1,260 @@
 /* auto-generated by NAPI-RS */
 /* eslint-disable */
-/** Physical serial port in ASCII mode. Factory for device clients. */
+/**
+ *  Physical serial port in ASCII mode. Factory for device clients.
+ * Manages a physical serial port connection in ASCII mode.
+ * This class is a factory for creating lightweight `AsyncSerialModbusClient` instances
+ * that are bound to a specific unit ID and share the underlying serial connection.
+ *
+ * Use the static `open` method to establish a connection.
+ */
 export declare class AsyncAsciiTransport {
-  /** Opens the serial port in ASCII mode. */
+  /**
+   *  Opens the serial port in ASCII mode.
+   * Opens a serial port and establishes a connection in ASCII mode.
+   * @param opts Options for the serial ASCII transport.
+   * @param opts.portPath The path to the serial port (e.g., '/dev/ttyUSB0', 'COM3').
+   * @param opts.baudRate The baud rate for the serial communication.
+   * @returns A `Promise` that resolves to an `AsyncAsciiTransport` instance.
+   */
   static open(opts: AsciiTransportOptions): Promise<AsyncAsciiTransport>
-  /** Creates a device client bound to the specified unit ID. */
+  /**
+   *  Creates a device client bound to the specified unit ID.
+   * Creates a lightweight device client that communicates through this transport.
+   * The client is bound to a specific Modbus unit ID.
+   * @param opts Options specifying the unit ID.
+   */
   createClient(opts: CreateClientOptions): AsyncSerialModbusClient
-  /** Sets the per-request timeout in milliseconds. */
+  /**
+   *  Sets the per-request timeout in milliseconds.
+   * Sets the timeout for individual Modbus requests made through this transport.
+   * @param timeout_ms The timeout duration in milliseconds.
+   */
   setRequestTimeout(timeoutMs: number): void
-  /** Clears the per-request timeout. */
+  /**
+   *  Clears the per-request timeout.
+   * Clears any previously set per-request timeout.
+   */
   clearRequestTimeout(): void
-  /** Returns whether there are pending requests. */
+  /**
+   *  Returns whether there are pending requests.
+   * Checks if there are any Modbus requests currently in-flight on this transport.
+   */
   get pendingRequests(): boolean
-  /** Closes the transport. */
+  /**
+   *  Closes the transport.
+   * Closes the underlying serial port connection.
+   */
   close(): Promise<void>
-  /** Reconnects the transport after a disconnect. */
+  /**
+   *  Reconnects the transport after a disconnect.
+   * Attempts to re-establish the serial connection if it has been closed.
+   */
   reconnect(): Promise<void>
 }
 
-/** Physical serial port in RTU mode. Factory for device clients. */
+/**
+ *  Physical serial port in RTU mode. Factory for device clients.
+ * Manages a physical serial port connection in RTU mode.
+ * This class is a factory for creating lightweight `AsyncSerialModbusClient` instances
+ * that are bound to a specific unit ID and share the underlying serial connection.
+ *
+ * Use the static `open` method to establish a connection.
+ */
 export declare class AsyncRtuTransport {
-  /** Opens the serial port in RTU mode. */
+  /**
+   *  Opens the serial port in RTU mode.
+   * Opens a serial port and establishes a connection in RTU mode.
+   * @param opts Options for the serial RTU transport.
+   * @param opts.portPath The path to the serial port (e.g., '/dev/ttyUSB0', 'COM3').
+   * @param opts.baudRate The baud rate for the serial communication.
+   * @returns A `Promise` that resolves to an `AsyncRtuTransport` instance.
+   */
   static open(opts: RtuTransportOptions): Promise<AsyncRtuTransport>
-  /** Creates a device client bound to the specified unit ID. */
+  /**
+   *  Creates a device client bound to the specified unit ID.
+   * Creates a lightweight device client that communicates through this transport.
+   * The client is bound to a specific Modbus unit ID.
+   * @param opts Options specifying the unit ID.
+   */
   createClient(opts: CreateClientOptions): AsyncSerialModbusClient
-  /** Sets the per-request timeout in milliseconds. */
+  /**
+   *  Sets the per-request timeout in milliseconds.
+   * Sets the timeout for individual Modbus requests made through this transport.
+   * @param timeout_ms The timeout duration in milliseconds.
+   */
   setRequestTimeout(timeoutMs: number): void
-  /** Clears the per-request timeout. */
+  /**
+   *  Clears the per-request timeout.
+   * Clears any previously set per-request timeout.
+   */
   clearRequestTimeout(): void
-  /** Returns whether there are pending requests. */
+  /**
+   *  Returns whether there are pending requests.
+   * Checks if there are any Modbus requests currently in-flight on this transport.
+   */
   get pendingRequests(): boolean
-  /** Closes the transport. */
+  /**
+   *  Closes the transport.
+   * Closes the underlying serial port connection.
+   */
   close(): Promise<void>
-  /** Reconnects the transport after a disconnect. */
+  /**
+   *  Reconnects the transport after a disconnect.
+   * Attempts to re-establish the serial connection if it has been closed.
+   */
   reconnect(): Promise<void>
 }
 
-/** Lightweight device client sharing the serial transport. */
+/**
+ *  Lightweight device client sharing the serial transport.
+ * A lightweight Modbus client that sends requests for a specific unit ID
+ * over a shared `AsyncRtuTransport` or `AsyncAsciiTransport`.
+ */
 export declare class AsyncSerialModbusClient {
-  /** Reads holding registers (FC03). */
+  /**
+   *  Reads holding registers (FC03).
+   * Reads one or more holding registers (Function Code 03).
+   * @param opts Options for reading registers.
+   * @param opts.address The starting register address.
+   * @param opts.quantity The number of registers to read.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readHoldingRegisters(opts: ReadRegistersOptions): Promise<number[]>
-  /** Reads input registers (FC04). */
+  /**
+   *  Reads input registers (FC04).
+   * Reads one or more input registers (Function Code 04).
+   * @param opts Options for reading registers.
+   * @param opts.address The starting register address.
+   * @param opts.quantity The number of registers to read.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readInputRegisters(opts: ReadRegistersOptions): Promise<number[]>
-  /** Writes a single register (FC06). */
+  /**
+   *  Writes a single register (FC06).
+   * Writes a single holding register (Function Code 06).
+   * @param opts Options for writing a single register.
+   * @param opts.address The register address.
+   * @param opts.value The 16-bit value to write.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   writeSingleRegister(opts: WriteSingleRegisterOptions): Promise<void>
-  /** Writes multiple registers (FC16). */
+  /**
+   *  Writes multiple registers (FC16).
+   * Writes multiple consecutive holding registers (Function Code 16).
+   * @param opts Options for writing multiple registers.
+   * @param opts.address The starting register address.
+   * @param opts.values An array of 16-bit values to write.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   writeMultipleRegisters(opts: WriteMultipleRegistersOptions): Promise<void>
-  /** Reads and writes multiple registers atomically (FC23). */
+  /**
+   *  Reads and writes multiple registers atomically (FC23).
+   * Performs an atomic read/write operation on multiple registers (Function Code 23).
+   * @param opts Options for the read/write operation.
+   * @param opts.read_address The starting address for the read operation.
+   * @param opts.read_quantity The number of registers to read.
+   * @param opts.write_address The starting address for the write operation.
+   * @param opts.write_values An array of 16-bit values to write.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readWriteMultipleRegisters(opts: ReadWriteMultipleRegistersOptions): Promise<number[]>
-  /** Reads coils (FC01). */
+  /**
+   *  Reads coils (FC01).
+   * Reads the status of one or more coils (Function Code 01).
+   * @param opts Options for reading bits.
+   * @param opts.address The starting coil address.
+   * @param opts.quantity The number of coils to read.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readCoils(opts: ReadBitsOptions): Promise<boolean[]>
-  /** Writes a single coil (FC05). */
+  /**
+   *  Writes a single coil (FC05).
+   * Writes a single coil (Function Code 05).
+   * @param opts Options for writing a single coil.
+   * @param opts.address The coil address.
+   * @param opts.value The boolean value to write (true for ON, false for OFF).
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   writeSingleCoil(opts: WriteSingleCoilOptions): Promise<void>
-  /** Writes multiple coils (FC15). */
+  /**
+   *  Writes multiple coils (FC15).
+   * Writes multiple consecutive coils (Function Code 15).
+   * @param opts Options for writing multiple coils.
+   * @param opts.address The starting coil address.
+   * @param opts.values An array of boolean values to write.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   writeMultipleCoils(opts: WriteMultipleCoilsOptions): Promise<void>
-  /** Reads discrete inputs (FC02). */
+  /**
+   *  Reads discrete inputs (FC02).
+   * Reads the status of one or more discrete inputs (Function Code 02).
+   * @param opts Options for reading bits.
+   * @param opts.address The starting discrete input address.
+   * @param opts.quantity The number of discrete inputs to read.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readDiscreteInputs(opts: ReadBitsOptions): Promise<boolean[]>
-  /** Reads FIFO queue (FC24). */
+  /**
+   *  Reads FIFO queue (FC24).
+   * Reads from a FIFO queue register (Function Code 24).
+   * @param opts Options for reading the FIFO queue.
+   * @param opts.address The FIFO pointer address.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readFifoQueue(opts: ReadFifoQueueOptions): Promise<FifoQueueResponse>
-  /** Reads file records (FC20). */
+  /**
+   *  Reads file records (FC20).
+   * Reads one or more file records (Function Code 20).
+   * @param opts Options for reading file records.
+   * @param opts.requests An array of file record read sub-requests.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readFileRecord(opts: ReadFileRecordOptions): Promise<number[][]>
-  /** Writes file records (FC21). */
+  /**
+   *  Writes file records (FC21).
+   * Writes one or more file records (Function Code 21).
+   * @param opts Options for writing file records.
+   * @param opts.requests An array of file record write sub-requests.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   writeFileRecord(opts: WriteFileRecordOptions): Promise<void>
-  /** Reads exception status (FC07). */
+  /**
+   *  Reads exception status (FC07).
+   * Reads the device's exception status byte (Function Code 07).
+   */
   readExceptionStatus(): Promise<number>
-  /** Sends a diagnostics request (FC08). */
+  /**
+   *  Sends a diagnostics request (FC08).
+   * Executes a diagnostic function on the device (Function Code 08).
+   * @param opts Options for the diagnostics request.
+   * @param opts.sub_function The diagnostic sub-function code.
+   * @param opts.data Data to be sent with the request.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   diagnostics(opts: DiagnosticsOptions): Promise<DiagnosticsResponse>
-  /** Reads device identification (FC43/MEI14). */
+  /**
+   *  Reads device identification (FC43/MEI14).
+   * Reads device identification information (Function Code 43, MEI 14).
+   * @param opts Options for reading device identification.
+   * @param opts.read_device_id_code The category of objects to read (e.g., basic, regular).
+   * @param opts.object_id The ID of the first object to read.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readDeviceIdentification(opts: ReadDeviceIdentificationOptions): Promise<DeviceIdentificationResponse>
 }
 
-/** Async Modbus Serial server supporting RTU and ASCII transports. */
+/**
+ *  Async Modbus Serial server supporting RTU and ASCII transports.
+ * An asynchronous Modbus server that listens on a serial port for incoming requests.
+ * It supports both RTU and ASCII transport modes.
+ * Use the static `bindRtu` or `bindAscii` methods to create and start a server instance.
+ */
 export declare class AsyncSerialModbusServer {
-  /** Binds and starts a new Serial RTU server. */
-  static bindRtu(opts: SerialServerOptions, handlers: object): AsyncSerialModbusServer
-  /** Binds and starts a new Serial ASCII server. */
-  static bindAscii(opts: SerialServerOptions, handlers: object): AsyncSerialModbusServer
-  /** Stops the server. */
+  /**
+   *  Stops the server.
+   * Stops the server and closes the serial port.
+   */
   shutdown(): Promise<void>
 }
 
@@ -98,73 +276,222 @@ export declare class AsyncTcpGateway {
   shutdown(): Promise<void>
 }
 
-/** Lightweight device client sharing the TCP transport. */
+/**
+ *  Lightweight device client sharing the TCP transport.
+ * A lightweight Modbus client that sends requests for a specific unit ID
+ * over a shared `AsyncTcpTransport`.
+ */
 export declare class AsyncTcpModbusClient {
-  /** Reads holding registers (FC03). */
+  /**
+   *  Reads holding registers (FC03).
+   * Reads one or more holding registers (Function Code 03).
+   * @param opts Options for reading registers.
+   * @param opts.address The starting register address.
+   * @param opts.quantity The number of registers to read.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readHoldingRegisters(opts: ReadRegistersOptions): Promise<number[]>
-  /** Reads input registers (FC04). */
+  /**
+   *  Reads input registers (FC04).
+   * Reads one or more input registers (Function Code 04).
+   * @param opts Options for reading registers.
+   * @param opts.address The starting register address.
+   * @param opts.quantity The number of registers to read.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readInputRegisters(opts: ReadRegistersOptions): Promise<number[]>
-  /** Writes a single register (FC06). */
+  /**
+   *  Writes a single register (FC06).
+   * Writes a single holding register (Function Code 06).
+   * @param opts Options for writing a single register.
+   * @param opts.address The register address.
+   * @param opts.value The 16-bit value to write.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   writeSingleRegister(opts: WriteSingleRegisterOptions): Promise<void>
-  /** Writes multiple registers (FC16). */
+  /**
+   *  Writes multiple registers (FC16).
+   * Writes multiple consecutive holding registers (Function Code 16).
+   * @param opts Options for writing multiple registers.
+   * @param opts.address The starting register address.
+   * @param opts.values An array of 16-bit values to write.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   writeMultipleRegisters(opts: WriteMultipleRegistersOptions): Promise<void>
-  /** Reads and writes multiple registers atomically (FC23). */
+  /**
+   *  Reads and writes multiple registers atomically (FC23).
+   * Performs an atomic read/write operation on multiple registers (Function Code 23).
+   * @param opts Options for the read/write operation.
+   * @param opts.read_address The starting address for the read operation.
+   * @param opts.read_quantity The number of registers to read.
+   * @param opts.write_address The starting address for the write operation.
+   * @param opts.write_values An array of 16-bit values to write.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readWriteMultipleRegisters(opts: ReadWriteMultipleRegistersOptions): Promise<number[]>
-  /** Reads coils (FC01). */
+  /**
+   *  Reads coils (FC01).
+   * Reads the status of one or more coils (Function Code 01).
+   * @param opts Options for reading bits.
+   * @param opts.address The starting coil address.
+   * @param opts.quantity The number of coils to read.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readCoils(opts: ReadBitsOptions): Promise<boolean[]>
-  /** Writes a single coil (FC05). */
+  /**
+   *  Writes a single coil (FC05).
+   * Writes a single coil (Function Code 05).
+   * @param opts Options for writing a single coil.
+   * @param opts.address The coil address.
+   * @param opts.value The boolean value to write (true for ON, false for OFF).
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   writeSingleCoil(opts: WriteSingleCoilOptions): Promise<void>
-  /** Writes multiple coils (FC15). */
+  /**
+   *  Writes multiple coils (FC15).
+   * Writes multiple consecutive coils (Function Code 15).
+   * @param opts Options for writing multiple coils.
+   * @param opts.address The starting coil address.
+   * @param opts.values An array of boolean values to write.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   writeMultipleCoils(opts: WriteMultipleCoilsOptions): Promise<void>
-  /** Reads discrete inputs (FC02). */
+  /**
+   *  Reads discrete inputs (FC02).
+   * Reads the status of one or more discrete inputs (Function Code 02).
+   * @param opts Options for reading bits.
+   * @param opts.address The starting discrete input address.
+   * @param opts.quantity The number of discrete inputs to read.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readDiscreteInputs(opts: ReadBitsOptions): Promise<boolean[]>
-  /** Reads FIFO queue (FC24). */
+  /**
+   *  Reads FIFO queue (FC24).
+   * Reads from a FIFO queue register (Function Code 24).
+   * @param opts Options for reading the FIFO queue.
+   * @param opts.address The FIFO pointer address.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readFifoQueue(opts: ReadFifoQueueOptions): Promise<FifoQueueResponse>
-  /** Reads file records (FC20). */
+  /**
+   *  Reads file records (FC20).
+   * Reads one or more file records (Function Code 20).
+   * @param opts Options for reading file records.
+   * @param opts.requests An array of file record read sub-requests.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readFileRecord(opts: ReadFileRecordOptions): Promise<number[][]>
-  /** Writes file records (FC21). */
+  /**
+   *  Writes file records (FC21).
+   * Writes one or more file records (Function Code 21).
+   * @param opts Options for writing file records.
+   * @param opts.requests An array of file record write sub-requests.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   writeFileRecord(opts: WriteFileRecordOptions): Promise<void>
-  /** Reads exception status (FC07). */
+  /**
+   *  Reads exception status (FC07).
+   * Reads the device's exception status byte (Function Code 07).
+   */
   readExceptionStatus(): Promise<number>
-  /** Sends a diagnostics request (FC08). */
+  /**
+   *  Sends a diagnostics request (FC08).
+   * Executes a diagnostic function on the device (Function Code 08).
+   * @param opts Options for the diagnostics request.
+   * @param opts.sub_function The diagnostic sub-function code.
+   * @param opts.data Data to be sent with the request.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   diagnostics(opts: DiagnosticsOptions): Promise<DiagnosticsResponse>
-  /** Reads device identification (FC43/MEI14). */
+  /**
+   *  Reads device identification (FC43/MEI14).
+   * Reads device identification information (Function Code 43, MEI 14).
+   * @param opts Options for reading device identification.
+   * @param opts.read_device_id_code The category of objects to read (e.g., basic, regular).
+   * @param opts.object_id The ID of the first object to read.
+   * @param opts.signal An optional `AbortSignal` to cancel the operation.
+   */
   readDeviceIdentification(opts: ReadDeviceIdentificationOptions): Promise<DeviceIdentificationResponse>
 }
 
 /**
- * Async Modbus TCP server.
+ *  Async Modbus TCP server.
  *
- * Binds to a TCP port and handles incoming Modbus requests using JS callbacks.
+ *  Binds to a TCP port and handles incoming Modbus requests using JS callbacks.
+ * An asynchronous Modbus TCP server that listens for incoming client connections.
  */
 export declare class AsyncTcpModbusServer {
   /**
-   * Creates and starts a new TCP server.
+   *  Creates and starts a new TCP server.
+   * Creates and starts a new Modbus TCP server.
    *
-   * @param opts - Server bind options.
-   * @param handlers - Object containing handler functions for each Modbus operation.
-   * @returns A running server instance.
+   * @param opts Server bind options.
+   * @param opts.host The host address to bind to (e.g., '0.0.0.0').
+   * @param opts.port The TCP port to listen on.
+   * @param opts.unitId The Modbus unit ID the server will respond to.
+   * @param handlers An object containing callback functions to handle Modbus requests (matches the `ServerHandlers` interface in TypeScript).
+   * @returns A `Promise` that resolves to a running `AsyncTcpModbusServer` instance.
+   */
+  static bind(opts: TcpServerOptions, handlers: ServerHandlers): Promise<AsyncTcpModbusServer>
+  /**
+   *  Stops the server.
+   * Stops the server and closes all active connections.
    */
-  static bind(opts: TcpServerOptions, handlers: object): AsyncTcpModbusServer
-  /** Stops the server. */
   shutdown(): Promise<void>
 }
 
-/** Physical TCP socket connection to a Modbus device or gateway. */
+/**
+ *  Physical TCP socket connection to a Modbus device or gateway.
+ * Manages a physical TCP socket connection to a Modbus device or gateway.
+ * This class is a factory for creating lightweight `AsyncTcpModbusClient` instances
+ * that are bound to a specific unit ID and share the underlying TCP connection.
+ *
+ * Use the static `connect` method to establish a connection.
+ */
 export declare class AsyncTcpTransport {
-  /** Connects to a Modbus TCP device or gateway. */
+  /**
+   *  Connects to a Modbus TCP device or gateway.
+   * Establishes a connection to a Modbus TCP device or gateway.
+   *
+   * @param opts - Connection options including host, port, and timeout settings.
+   * @param opts.host - Target host address (IP or hostname).
+   * @param opts.port - Target TCP port (typically 502).
+   */
   static connect(opts: TcpTransportOptions): Promise<AsyncTcpTransport>
-  /** Creates a device client bound to the specified unit ID. */
-  createClient(opts?: CreateClientOptions | undefined | null): AsyncTcpModbusClient
-  /** Sets the per-request timeout in milliseconds. */
+  /**
+   *  Creates a device client bound to the specified unit ID.
+   * Creates a lightweight device client that communicates through this transport.
+   * The client is bound to a specific Modbus unit ID.
+   *
+   * @param opts - Options specifying the unit ID.
+   */
+  createClient(opts: CreateClientOptions): AsyncTcpModbusClient
+  /**
+   *  Sets the per-request timeout in milliseconds.
+   * Sets the timeout for individual Modbus requests made through this transport.
+   *
+   * @param timeout_ms - The timeout duration in milliseconds.
+   */
   setRequestTimeout(timeoutMs: number): void
-  /** Clears the per-request timeout. */
+  /**
+   *  Clears the per-request timeout.
+   * Clears any previously set per-request timeout, reverting to the default behavior.
+   */
   clearRequestTimeout(): void
-  /** Returns whether there are pending requests. */
+  /**
+   *  Returns whether there are pending requests.
+   * Checks if there are any Modbus requests currently in-flight on this transport.
+   */
   get pendingRequests(): boolean
-  /** Closes the connection. */
+  /**
+   *  Closes the connection.
+   * Closes the underlying TCP connection and shuts down the transport.
+   */
   close(): Promise<void>
-  /** Reconnects the transport after a disconnect. */
+  /**
+   *  Reconnects the transport after a disconnect.
+   * Attempts to re-establish the TCP connection if it has been closed.
+   */
   reconnect(): Promise<void>
 }
 
@@ -184,31 +511,37 @@ export interface AsciiTransportOptions {
   responseTimeoutMs?: number
   /** Per-request timeout in milliseconds. */
   requestTimeoutMs?: number
+  /** Number of retry attempts on failure (0 = none). Default: 0. */
+  retryAttempts?: number
+  /** Delay between retry attempts in milliseconds. */
+  retryDelayMs?: number
+  /** Backoff strategy: "immediate", "fixed", or "exponential". Default: "immediate". */
+  retryBackoffStrategy?: string
 }
 
 /** Options for creating a device client. */
 export interface CreateClientOptions {
-  /** Modbus unit ID (1-247). */
-  unitId?: number
+  /** Modbus unit ID (slave address) from 1 to 247. */
+  unitId: number
 }
 
 /** Device identification object. */
 export interface DeviceIdentificationObject {
-  /** Object ID. */
+  /** The object ID. */
   id: number
-  /** Object value as string. */
+  /** The value of the object, represented as a string. */
   value: string
 }
 
 /** Response from device identification request. */
 export interface DeviceIdentificationResponse {
-  /** Conformity level. */
+  /** The conformity level of the device. */
   conformityLevel: number
-  /** Whether more objects follow. */
+  /** Indicates if more objects are available to be read. */
   moreFollows: boolean
-  /** Next object ID if more follows. */
+  /** The ID of the next object to read if `moreFollows` is true. */
   nextObjectId: number
-  /** Retrieved objects. */
+  /** An array of device identification objects. */
   objects: Array<DeviceIdentificationObject>
 }
 
@@ -216,24 +549,27 @@ export interface DeviceIdentificationResponse {
 export interface DiagnosticsOptions {
   /** Diagnostic sub-function code. */
   subFunction: number
-  /** Data words for the request. */
+  /** Data to be sent with the diagnostics request. */
   data: Array<number>
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
 }
 
 /** Handler request for diagnostics. */
 export interface DiagnosticsRequest {
+  /** The unit ID of the device that sent the request. */
   unitId: number
+  /** The diagnostic sub-function code to execute. */
   subFunction: number
+  /** Data sent with the diagnostics request. */
   data: Array<number>
 }
 
 /** Response from diagnostics request. */
 export interface DiagnosticsResponse {
-  /** Echoed sub-function code. */
+  /** The sub-function code from the request. */
   subFunction: number
-  /** Response data words. */
+  /** The data returned by the diagnostics function. */
   data: Array<number>
 }
 
@@ -247,29 +583,47 @@ export interface DownstreamConfig {
 
 /** Response from reading FIFO queue. */
 export interface FifoQueueResponse {
-  /** Number of values in the queue. */
-  count: number
   /** Queue values. */
   values: Array<number>
 }
 
 /** A single file record read sub-request. */
 export interface FileRecordReadRequest {
-  /** File number (1-65535). */
+  /** The file number (1-65535). */
   fileNumber: number
-  /** Starting record number. */
+  /** The starting record number within the file. */
   recordNumber: number
-  /** Number of records to read. */
+  /** The number of records to read. */
+  recordLength: number
+}
+
+/** A single file record read sub-request on the server side. */
+export interface FileRecordReadServerSubRequest {
+  /** The file number (1-65535). */
+  fileNumber: number
+  /** The starting record number within the file. */
+  recordNumber: number
+  /** The number of records to read. */
   recordLength: number
 }
 
 /** A single file record write sub-request. */
 export interface FileRecordWriteRequest {
-  /** File number (1-65535). */
+  /** The file number (1-65535). */
+  fileNumber: number
+  /** The starting record number within the file. */
+  recordNumber: number
+  /** The record data to write, as an array of 16-bit values. */
+  recordData: Array<number>
+}
+
+/** A single file record write sub-request on the server side. */
+export interface FileRecordWriteSubRequest {
+  /** The file number (1-65535). */
   fileNumber: number
-  /** Starting record number. */
+  /** The starting record number within the file. */
   recordNumber: number
-  /** Record data to write. */
+  /** The record data to write, as an array of 16-bit values. */
   recordData: Array<number>
 }
 
@@ -289,20 +643,41 @@ export interface GatewayConfig {
   routes: Array<RouteEntry>
 }
 
+/** Stable error code: The connection was closed. */
+export const MODBUS_ERROR_CODE_CONNECTION_CLOSED: string
+
+/** Stable error code: Modbus protocol exception received. */
+export const MODBUS_ERROR_CODE_EXCEPTION: string
+
+/** Stable error code: Internal library error. */
+export const MODBUS_ERROR_CODE_INTERNAL: string
+
+/** Stable error code: Invalid argument passed to the API. */
+export const MODBUS_ERROR_CODE_INVALID_ARGUMENT: string
+
+/** Stable error code: Request timed out. */
+export const MODBUS_ERROR_CODE_TIMEOUT: string
+
+/** Stable error code: Transport/framing error. */
+export const MODBUS_ERROR_CODE_TRANSPORT: string
+
 /** Options for reading coils or discrete inputs. */
 export interface ReadBitsOptions {
   /** Starting address. */
   address: number
-  /** Number of bits to read. */
+  /** Number of bits (coils or discrete inputs) to read. */
   quantity: number
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
 }
 
 /** Handler request for reading coils. */
 export interface ReadCoilsRequest {
+  /** The unit ID of the device that sent the request. */
   unitId: number
+  /** The starting address of the coils to read. */
   address: number
+  /** The number of coils to read. */
   quantity: number
 }
 
@@ -310,52 +685,77 @@ export interface ReadCoilsRequest {
 export interface ReadDeviceIdentificationOptions {
   /** Read device ID code (1=basic, 2=regular, 3=extended, 4=individual). */
   readDeviceIdCode: number
-  /** Starting object ID. */
+  /** The ID of the first object to read. */
   objectId: number
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
 }
 
 /** Handler request for reading discrete inputs. */
 export interface ReadDiscreteInputsRequest {
+  /** The unit ID of the device that sent the request. */
   unitId: number
+  /** The starting address of the discrete inputs to read. */
   address: number
+  /** The number of discrete inputs to read. */
   quantity: number
 }
 
+/** Handler request for reading exception status. */
+export interface ReadExceptionStatusRequest {
+  /** The unit ID of the device that sent the request. */
+  unitId: number
+}
+
 /** Options for reading FIFO queue. */
 export interface ReadFifoQueueOptions {
   /** FIFO pointer address. */
   address: number
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
 }
 
 /** Handler request for reading FIFO queue. */
 export interface ReadFifoQueueRequest {
+  /** The unit ID of the device that sent the request. */
   unitId: number
+  /** The address of the FIFO queue pointer register. */
   address: number
 }
 
 /** Options for reading file records. */
 export interface ReadFileRecordOptions {
-  /** Array of sub-requests. */
+  /** An array of file record read sub-requests. */
   requests: Array<FileRecordReadRequest>
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
+}
+
+/** Handler request for reading file records. */
+export interface ReadFileRecordRequest {
+  /** The unit ID of the device that sent the request. */
+  unitId: number
+  /** An array of file record read sub-requests. */
+  requests: Array<FileRecordReadServerSubRequest>
 }
 
 /** Handler request for reading holding registers. */
 export interface ReadHoldingRegistersRequest {
+  /** The unit ID of the device that sent the request. */
   unitId: number
+  /** The starting address of the holding registers to read. */
   address: number
+  /** The number of holding registers to read. */
   quantity: number
 }
 
 /** Handler request for reading input registers. */
 export interface ReadInputRegistersRequest {
+  /** The unit ID of the device that sent the request. */
   unitId: number
+  /** The starting address of the input registers to read. */
   address: number
+  /** The number of input registers to read. */
   quantity: number
 }
 
@@ -363,24 +763,38 @@ export interface ReadInputRegistersRequest {
 export interface ReadRegistersOptions {
   /** Starting register address. */
   address: number
-  /** Number of registers to read. */
+  /** Number of registers to read (quantity). */
   quantity: number
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
 }
 
 /** Options for read/write multiple registers (FC23). */
 export interface ReadWriteMultipleRegistersOptions {
   /** Starting address for read operation. */
   readAddress: number
-  /** Number of registers to read. */
+  /** Number of registers to read (quantity). */
   readQuantity: number
   /** Starting address for write operation. */
   writeAddress: number
-  /** Values to write. */
+  /** An array of 16-bit values to write. */
+  writeValues: Array<number>
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
+}
+
+/** Handler request for read/write multiple registers (FC23). */
+export interface ReadWriteMultipleRegistersRequest {
+  /** The unit ID of the device that sent the request. */
+  unitId: number
+  /** The starting address for the read operation. */
+  readAddress: number
+  /** The number of registers to read. */
+  readQuantity: number
+  /** The starting address for the write operation. */
+  writeAddress: number
+  /** The array of 16-bit values to write. */
   writeValues: Array<number>
-  /** Optional abort signal to cancel the request. */
-  signal?: object
 }
 
 /** Route entry mapping unit ID to a downstream channel. */
@@ -407,6 +821,12 @@ export interface RtuTransportOptions {
   responseTimeoutMs?: number
   /** Per-request timeout in milliseconds. */
   requestTimeoutMs?: number
+  /** Number of retry attempts on failure (0 = none). Default: 0. */
+  retryAttempts?: number
+  /** Delay between retry attempts in milliseconds. */
+  retryDelayMs?: number
+  /** Backoff strategy: "immediate", "fixed", or "exponential". Default: "immediate". */
+  retryBackoffStrategy?: string
 }
 
 /** Server bind options for serial port. */
@@ -421,7 +841,7 @@ export interface SerialServerOptions {
   parity?: string
   /** Stop bits (1 or 2). */
   stopBits?: number
-  /** Modbus unit ID (1-247). */
+  /** Modbus unit ID (1-247) for the server to respond to. */
   unitId: number
   /** Response timeout in milliseconds. */
   responseTimeoutMs?: number
@@ -429,13 +849,18 @@ export interface SerialServerOptions {
 
 /** Handler response for diagnostics. */
 export interface ServerDiagnosticsResponse {
+  /** The sub-function code from the request. */
   subFunction: number
+  /** The data to be returned by the diagnostics function. */
   data: Array<number>
 }
 
 /** Response that may include an exception code. */
 export interface ServerExceptionResponse {
-  /** Modbus exception code if this is an error response. */
+  /**
+   * The Modbus exception code (e.g., 1 for Illegal Function).
+   *  Modbus exception code if this is an error response.
+   */
   exception?: number
 }
 
@@ -455,32 +880,49 @@ export interface TcpTransportOptions {
   host: string
   /** Target TCP port (typically 502). */
   port: number
-  /** Per-request timeout in milliseconds (optional). */
-  timeoutMs?: number
+  /** Per-request timeout in milliseconds. */
+  requestTimeoutMs?: number
+  /** Number of retry attempts on failure. Default: 0 (no retries). */
+  retryAttempts?: number
+  /** Delay between retry attempts in milliseconds. */
+  retryDelayMs?: number
+  /** Backoff strategy for retries: "immediate", "fixed", or "exponential". Default: "immediate". */
+  retryBackoffStrategy?: string
 }
 
 /** Options for writing file records. */
 export interface WriteFileRecordOptions {
-  /** Array of sub-requests. */
+  /** An array of file record write sub-requests. */
   requests: Array<FileRecordWriteRequest>
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
+}
+
+/** Handler request for writing file records. */
+export interface WriteFileRecordRequest {
+  /** The unit ID of the device that sent the request. */
+  unitId: number
+  /** An array of file record write sub-requests. */
+  requests: Array<FileRecordWriteSubRequest>
 }
 
 /** Options for writing multiple coils. */
 export interface WriteMultipleCoilsOptions {
   /** Starting coil address. */
   address: number
-  /** Values to write. */
+  /** An array of boolean values to write. */
   values: Array<boolean>
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
 }
 
 /** Handler request for writing multiple coils. */
 export interface WriteMultipleCoilsRequest {
+  /** The unit ID of the device that sent the request. */
   unitId: number
+  /** The starting address of the coils to write to. */
   address: number
+  /** The array of boolean values to write. */
   values: Array<boolean>
 }
 
@@ -488,16 +930,19 @@ export interface WriteMultipleCoilsRequest {
 export interface WriteMultipleRegistersOptions {
   /** Starting register address. */
   address: number
-  /** Values to write. */
+  /** An array of 16-bit values to write. */
   values: Array<number>
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
 }
 
 /** Handler request for writing multiple registers. */
 export interface WriteMultipleRegistersRequest {
+  /** The unit ID of the device that sent the request. */
   unitId: number
+  /** The starting address of the registers to write to. */
   address: number
+  /** The array of 16-bit values to write. */
   values: Array<number>
 }
 
@@ -505,16 +950,19 @@ export interface WriteMultipleRegistersRequest {
 export interface WriteSingleCoilOptions {
   /** Coil address. */
   address: number
-  /** Value to write. */
+  /** The boolean value to write (true for ON, false for OFF). */
   value: boolean
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
 }
 
 /** Handler request for writing a single coil. */
 export interface WriteSingleCoilRequest {
+  /** The unit ID of the device that sent the request. */
   unitId: number
+  /** The address of the coil to write to. */
   address: number
+  /** The value to write (true for ON, false for OFF). */
   value: boolean
 }
 
@@ -522,15 +970,181 @@ export interface WriteSingleCoilRequest {
 export interface WriteSingleRegisterOptions {
   /** Register address. */
   address: number
-  /** Value to write. */
+  /** The 16-bit value to write to the register. */
   value: number
-  /** Optional abort signal to cancel the request. */
-  signal?: object
+  /** An optional `AbortSignal` to cancel the asynchronous operation. */
+  signal?: AbortSignal
 }
 
 /** Handler request for writing a single register. */
 export interface WriteSingleRegisterRequest {
+  /** The unit ID of the device that sent the request. */
   unitId: number
+  /** The address of the register to write to. */
   address: number
+  /** The 16-bit value to write. */
   value: number
 }
+
+export interface ModbusException {
+  exception: number;
+}
+
+/**
+ * Callback functions to handle Modbus server requests.
+ * 
+ * Each handler corresponds to a specific Modbus function code. If a handler is not provided,
+ * the server will respond with an "Illegal Function" exception (0x01).
+ * 
+ * Handlers can return the expected data directly or return a Promise for async operations.
+ * To return a Modbus exception, return an object matching the `ModbusException` interface.
+ */
+export interface ServerHandlers {
+  /**
+   * Handle Read Coils (FC 01).
+   * @param req The request object.
+   * @param req.address The starting coil address (0x0000 to 0xFFFF).
+   * @param req.quantity The number of coils to read (1 to 2000).
+   * @returns An array of booleans representing the coil states, or a ModbusException.
+   */
+  onReadCoils?: (req: ReadCoilsRequest) => boolean[] | ModbusException | Promise<boolean[] | ModbusException>;
+
+  /**
+   * Handle Read Discrete Inputs (FC 02).
+   * @param req The request object.
+   * @param req.address The starting discrete input address (0x0000 to 0xFFFF).
+   * @param req.quantity The number of inputs to read (1 to 2000).
+   * @returns An array of booleans representing the input states, or a ModbusException.
+   */
+  onReadDiscreteInputs?: (req: ReadDiscreteInputsRequest) => boolean[] | ModbusException | Promise<boolean[] | ModbusException>;
+
+  /**
+   * Handle Read Holding Registers (FC 03).
+   * @param req The request object.
+   * @param req.address The starting holding register address (0x0000 to 0xFFFF).
+   * @param req.quantity The number of registers to read (1 to 125).
+   * @returns An array of 16-bit numbers representing the registers, or a ModbusException.
+   */
+  onReadHoldingRegisters?: (req: ReadHoldingRegistersRequest) => number[] | ModbusException | Promise<number[] | ModbusException>;
+
+  /**
+   * Handle Read Input Registers (FC 04).
+   * @param req The request object.
+   * @param req.address The starting input register address (0x0000 to 0xFFFF).
+   * @param req.quantity The number of registers to read (1 to 125).
+   * @returns An array of 16-bit numbers representing the registers, or a ModbusException.
+   */
+  onReadInputRegisters?: (req: ReadInputRegistersRequest) => number[] | ModbusException | Promise<number[] | ModbusException>;
+
+  /**
+   * Handle Write Single Coil (FC 05).
+   * @param req The request object.
+   * @param req.address The address of the coil to write (0x0000 to 0xFFFF).
+   * @param req.value The boolean value to write (true for ON, false for OFF).
+   * @returns void on success, or a ModbusException.
+   */
+  onWriteSingleCoil?: (req: WriteSingleCoilRequest) => void | ModbusException | Promise<void | ModbusException>;
+
+  /**
+   * Handle Write Single Register (FC 06).
+   * @param req The request object.
+   * @param req.address The address of the register to write (0x0000 to 0xFFFF).
+   * @param req.value The 16-bit value to write.
+   * @returns void on success, or a ModbusException.
+   */
+  onWriteSingleRegister?: (req: WriteSingleRegisterRequest) => void | ModbusException | Promise<void | ModbusException>;
+
+  /**
+   * Handle Read Exception Status (FC 07).
+   * @param req The read exception status request object (empty).
+   * @returns An 8-bit exception status byte, or a ModbusException.
+   */
+  onReadExceptionStatus?: (req: ReadExceptionStatusRequest) => number | ModbusException | Promise<number | ModbusException>;
+
+  /**
+   * Handle Diagnostics (FC 08).
+   * @param req The diagnostics request object.
+   * @param req.subFunction The 16-bit sub-function code.
+   * @param req.data The 16-bit data payload for the sub-function.
+   * @returns A response containing the sub-function and data, or a ModbusException.
+   */
+  onDiagnostics?: (req: DiagnosticsRequest) => ServerDiagnosticsResponse | ModbusException | Promise<ServerDiagnosticsResponse | ModbusException>;
+
+  /**
+   * Handle Write Multiple Coils (FC 15).
+   * @param req The request object.
+   * @param req.address The starting address of the coils to write.
+   * @param req.values An array of booleans to write.
+   * @returns void on success, or a ModbusException.
+   */
+  onWriteMultipleCoils?: (req: WriteMultipleCoilsRequest) => void | ModbusException | Promise<void | ModbusException>;
+
+  /**
+   * Handle Write Multiple Registers (FC 16).
+   * @param req The request object.
+   * @param req.address The starting address of the registers to write.
+   * @param req.values An array of 16-bit numbers to write.
+   * @returns void on success, or a ModbusException.
+   */
+  onWriteMultipleRegisters?: (req: WriteMultipleRegistersRequest) => void | ModbusException | Promise<void | ModbusException>;
+
+  /**
+   * Handle Read File Record (FC 20).
+   * @param req The request object.
+   * @param req.subRequests An array of sub-requests, each with `fileNumber`, `recordNumber`, and `recordLength`.
+   * @returns An array of register arrays for each sub-request, or a ModbusException.
+   */
+  onReadFileRecord?: (req: ReadFileRecordRequest) => number[][] | ModbusException | Promise<number[][] | ModbusException>;
+
+  /**
+   * Handle Write File Record (FC 21).
+   * @param req The request object.
+   * @param req.subRequests An array of sub-requests, each with `fileNumber`, `recordNumber`, and `recordData` (a number array).
+   * @returns void on success, or a ModbusException.
+   */
+  onWriteFileRecord?: (req: WriteFileRecordRequest) => void | ModbusException | Promise<void | ModbusException>;
+
+  /**
+   * Handle Read/Write Multiple Registers (FC 23).
+   * @param req The request containing addresses and values to read and write.
+   * @param req.readAddress The starting address for the read operation.
+   * @param req.readQuantity The number of registers to read.
+   * @param req.writeAddress The starting address for the write operation.
+   * @param req.values An array of 16-bit numbers to write.
+   * @returns An array of 16-bit numbers read, or a ModbusException.
+   */
+  onReadWriteMultipleRegisters?: (req: ReadWriteMultipleRegistersRequest) => number[] | ModbusException | Promise<number[] | ModbusException>;
+
+  /**
+   * Handle Read FIFO Queue (FC 24).
+   * @param req The request object containing the FIFO pointer `address`.
+   * @returns An array of 16-bit numbers from the queue, or a ModbusException.
+   */
+  onReadFifoQueue?: (req: ReadFifoQueueRequest) => number[] | ModbusException | Promise<number[] | ModbusException>;
+}
+
+/**
+ * Stable error codes for identifying Modbus-related errors.
+ * These can be used with the `getModbusErrorCode` helper to check for specific error types.
+ */
+export declare const ModbusErrorCode: {
+  /** A Modbus exception response was received from the server (e.g., illegal function). */
+  readonly EXCEPTION: 'MODBUS_EXCEPTION';
+  /** The request timed out waiting for a response. */
+  readonly TIMEOUT: 'MODBUS_TIMEOUT';
+  /** A transport-level error occurred (e.g., framing error, checksum mismatch). */
+  readonly TRANSPORT: 'MODBUS_TRANSPORT';
+  /** An invalid argument was provided to a client or server function. */
+  readonly INVALID_ARGUMENT: 'MODBUS_INVALID_ARGUMENT';
+  /** The underlying connection was closed. */
+  readonly CONNECTION_CLOSED: 'MODBUS_CONNECTION_CLOSED';
+  /** An unexpected internal error occurred within the library. */
+  readonly INTERNAL: 'MODBUS_INTERNAL';
+};
+
+/**
+ * Extracts a stable error code from a Modbus error object.
+ * @param err The error object.
+ * @returns The corresponding code from `ModbusErrorCode`, or undefined if not a Modbus error.
+ */
+export declare function getModbusErrorCode(err: Error): string | undefined;