@csllc/mb-conn-node-serial

A Connection subclass for MODBUS over a Node.js serial port, backed by @serialport/stream, plus a scan() utility to enumerate available serial ports.

Installation

npm install @csllc/mb-conn-node-serial

Overview

This package provides:

• SerialConnection — Extends Connection from @csllc/modbus-types. It bridges Node.js Buffer-based serialport data events to the ArrayBuffer-based Connection API expected by RtuTransport.
• scan() — Async function that lists all available serial ports on the current machine.

To run MODBUS RTU over a serial port, pair SerialConnection with RtuTransport and createMaster from @csllc/modbus-types.

Usage

List available serial ports

import { scan } from '@csllc/mb-conn-node-serial';

const ports = await scan();
// ports is an array of SerialConnectionInfo:
// [{ id: '/dev/ttyUSB0', type: 'serial', path: '/dev/ttyUSB0' }, ...]
console.log(ports);

Open a port and create a MODBUS RTU master

import { SerialConnection, scan } from '@csllc/mb-conn-node-serial';
import { createMaster } from '@csllc/modbus-types';

const ports = await scan();
if (ports.length === 0) throw new Error('No serial ports found');

const connection = new SerialConnection(
  ports[0],          // SerialConnectionInfo — must have .path
  {
    baudRate: 9600,
    dataBits: 8,
    parity: 'none',
    stopBits: 1,
  }
);

const master = createMaster({
  transport: { type: 'rtu', connection },
  defaultUnit: 1,
  defaultTimeout: 500,
  defaultMaxRetries: 2,
});

await connection.open();

master.on('connected', async () => {
  const response = await master.requestAsync(
    new (await import('@csllc/modbus-types')).Functions.ReadHoldingRegistersRequest({
      address: 0,
      quantity: 4,
    })
  );
  console.log('registers:', response);
  await connection.close();
});

Using a custom serialport binding (e.g. for mocking in tests)

import { SerialConnection } from '@csllc/mb-conn-node-serial';
import { MockBinding } from '@serialport/binding-mock';

MockBinding.createPort('/dev/ttyUSB0', { echo: false });

const connection = new SerialConnection(
  { id: '/dev/ttyUSB0', type: 'serial', path: '/dev/ttyUSB0' },
  { baudRate: 9600, binding: MockBinding }
);

API Reference

scan(): Promise<SerialConnectionInfo[]>

Enumerates all serial ports currently available on the system.

Returns: A promise that resolves to an array of SerialConnectionInfo objects.

Each entry has:

| Property | Type | Description | |---|---|---| | id | string | Same as path; unique identifier for this port. | | type | string | Always 'serial'. | | path | string | The OS device path (e.g. /dev/ttyUSB0 or COM3). |

class SerialConnection extends Connection

A Connection implementation backed by @serialport/stream. Translates between the Node.js Buffer API used by serialport and the ArrayBuffer API used by @csllc/modbus-types.

Constructor

new SerialConnection(port: SerialConnectionInfo, options: SerialConnectionOptions)

SerialConnectionInfo

| Property | Type | Description | |---|---|---| | id | string | Unique identifier for this connection. | | type | string | Connection type string. | | path | string | Serial port device path. |

SerialConnectionOptions

| Property | Type | Required | Description | |---|---|---|---| | baudRate | number | yes | Baud rate (e.g. 9600, 115200). | | dataBits | 5 \| 6 \| 7 \| 8 | no | Data bits per character. Defaults to 8. | | parity | 'none' \| 'even' \| 'odd' | no | Parity mode. Defaults to 'none'. | | stopBits | 1 \| 2 | no | Stop bits. Defaults to 1. | | binding | BindingInterface | no | Custom serialport binding (useful for testing). Defaults to the platform auto-detected binding. |

Methods

| Method | Returns | Description | |---|---|---| | open() | Promise<void> | Opens the serial port. Emits open on success. | | close() | Promise<void> | Closes the serial port. Emits close. | | write(data) | Promise<boolean> | Writes an ArrayBuffer to the port. Returns true. | | isOpen() | boolean | Returns true if the port is currently open. | | drain() | Promise<void> | Waits for all queued write data to be transmitted. | | destroy() | Promise<void> | Closes the port if open and cleans up. |

Events

Inherited from Connection (EventEmitter):

| Event | Args | Description | |---|---|---| | open | — | Port has opened successfully. | | close | — | Port has closed. | | data | data: ArrayBuffer | Bytes received from the serial port. | | error | err: Error | A serialport error occurred. |

interface SerialConnectionOptions

interface SerialConnectionOptions {
  baudRate: number;
  dataBits?: 5 | 6 | 7 | 8;
  parity?: 'none' | 'even' | 'odd';
  stopBits?: 1 | 2;
  binding?: BindingInterface;
}