@csllc/cs1816

TypeScript package for communicating with CS181x BLE/USB dongles — small hardware devices that provide wireless access to an attached local device or system over Bluetooth Low Energy or USB.

Installation

npm install @csllc/cs1816

Overview

The CS181x dongle acts as a BLE peripheral and connects by wire to a motor controller or other local device. This package runs on the BLE central side (mobile app, Node.js desktop, etc.) and handles:

• Inspecting and reading dongle device information
• Reading and writing device memory and objects
• Configuring the dongle's hardware interface (I2C, serial, CAN)
• Monitoring variables via watchers and the super watcher
• Sending commands such as keyswitch control and device reset

Two concrete dongle implementations are provided:

• BleDongle — for BLE connections. Requires a Ble-compatible adapter such as @csllc/noble-ble or @csllc/mb-conn-noble-mac.
• UsbDongle — for USB/serial connections. Requires a Connection from @csllc/mb-conn-node-serial.

Both follow the same lifecycle: construct, then call initialize() to open the connection, create the MODBUS Master, and inspect device objects.

The exported serviceUuid string is the BLE service UUID that CS181x dongles advertise. Use it with your BLE manager's scan function to discover dongles.

Usage

BLE dongle

import { BleDongle, serviceUuid } from '@csllc/cs1816';
import { NobleMacBleManager } from '@csllc/mb-conn-noble-mac';

await NobleMacBleManager.initialize();

// Scan for a dongle advertising serviceUuid
await NobleMacBleManager.startScan([serviceUuid], (peripheral) => {
  console.log('Found dongle:', peripheral.name);
});
// ... stop scan, get peripheral reference ...

// Construct and initialize — BleDongle handles BLE connect, UART discovery,
// and Master creation internally
const dongle = new BleDongle(NobleMacBleManager, peripheral, {
  logger: myLogger,
});
await dongle.initialize();

const info = await dongle.readDongleInfo();
console.log('Model:', info.model, 'SW:', info.sw);

USB dongle

import { UsbDongle } from '@csllc/cs1816';
import { SerialConnection } from '@csllc/mb-conn-node-serial';

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

// Construct and initialize — UsbDongle opens the serial port and creates
// the MODBUS Master internally
const dongle = new UsbDongle(connection, { logger: myLogger });
await dongle.initialize();

const info = await dongle.readDongleInfo();
console.log('Model:', info.model, 'SW:', info.sw);

Reading dongle info

const info = await dongle.readDongleInfo();
// info: { model, serial, fw, hw, sw, mfr, product }

// After readDongleInfo(), softwareRevision is also available in multiple formats:
console.log(dongle.softwareRevision.string); // "1.10.0"
console.log(dongle.softwareRevision.scalar); // 0x010A00
console.log(dongle.softwareRevision.bytes); // { major: 1, minor: 10, patch: 0 }

Reading and writing memory

// Read 128 bytes starting at address 0x0300 from unit 1
const data = await dongle.readMemory(1, 0x0300, 128);

// Write bytes to unit 1 at address 0x0310
await dongle.writeMemory(1, 0x0310, [0x01, 0x02, 0x03]);

// Write with readback verification
await dongle.writeVerifyMemory(1, 0x0310, [0x01, 0x02, 0x03]);

Reading and writing objects

// Read object 0 from the dongle itself (unit ID is dongle.ID = 0xFE)
const config = await dongle.readObject(dongle.ID, 0);

// Write bytes to object 5 on unit 1
await dongle.writeObject(1, 5, [0xab, 0xcd]);

Access key

// Read the 128-byte cloud access key (object 0 on the dongle)
const key = await dongle.readAccessKey();

// Write a new access key
await dongle.writeAccessKey([...Array(128).keys()]);

Configuration and keyswitch

// Configure I2C interface
await dongle.configureI2c();

// Enable the keyswitch output
await dongle.keyswitch(true);

// Monitor interface status changes
await dongle.onInterfaceUpdate((iface, dongle) => {
  console.log('Interface status changed:', iface);
});

Watchers

// Watch 1 byte at address 0x0086 on unit 1
const slot = await dongle.watch(
  1,
  0x0086,
  1,
  undefined,
  (data, address, unit) => {
    console.log('Variable changed:', data[0]);
  },
);

// Cancel the watcher
dongle.unwatch(slot);

// Cancel all watchers
await dongle.unwatchAll();

Super watcher

The super watcher monitors a larger number of single-byte variables. Register all variables before calling updateSuperWatcher().

await dongle.clearSuperWatcher();

await dongle.superWatch(1, 0x0086, (data, address, unit) => {
  console.log(`Address ${address} on unit ${unit} changed:`, data);
});
await dongle.superWatch(1, 0x0087, (data, address, unit) => {
  console.log(`Address ${address} changed:`, data);
});

await dongle.updateSuperWatcher();

Batch registration

registerWatchers() and registerSuperWatchers() provide a simpler way to set up multiple watchers at once, without needing to handle BLE vs USB differences — the dongle subclass manages the transport-specific details internally.

import type { WatcherRegistration, SuperWatcherRegistration } from '@csllc/cs1816';

const watchers: WatcherRegistration[] = [
  { unit: 1, address: 0x0064, length: 2, cb: (value) => console.log('Voltage:', value) },
  { unit: 1, address: 0x0038, length: 1, cb: (value) => console.log('Fault:', value) },
];

const slots = await dongle.registerWatchers(watchers);
console.log('Registered in slots:', slots);

// Tear down all watchers (e.g. when the device interface goes down)
dongle.teardownWatchers();

Resetting a device

await dongle.reset(1);

API Reference

Exported symbols

| Symbol | Type | Description | | ---------------------- | ---------------------- | ------------------------------------------------------------ | | Dongle | abstract class | Abstract base class for all dongle types. | | UsbDongle | class extends Dongle | USB/serial dongle. Creates RTU Master internally. | | BleDongle | class extends Dongle | BLE dongle. Creates IP Master internally. | | DeviceInterface | class | Decoded hardware interface status (mode, protocol, up/down). | | Watcher | class | Represents a registered watcher slot. | | serviceUuid | string | BLE service UUID advertised by CS181x dongles. | | DONGLE_UUIDS | object | All BLE service and characteristic UUIDs for CS181x. | | ConfigureCommand | class | Configure dongle hardware interface (mode, protocol). | | DongleMode | enum | Hardware interface mode values. | | DongleProtocol | enum | Protocol values. | | KeySwitchCommand | class | Set keyswitch output state. | | WatchCommand | class | Set watcher slots on the device. | | WatchMaskedCommand | class | Set watcher slots with per-bit change masks. | | UnwatchCommand | class | Cancel specific watcher slots. | | UnwatchAllCommand | class | Cancel all watcher slots. | | SuperWatchCommand | class | Set superwatcher addresses. | | GetWatcherCommand | class | Query the device's watcher table. | | WatcherType | enum | Watcher query type. | | ResetCommand | class | Send a reset command to a device. | | DongleSlaveIdRequest | class | Report slave ID request. | | WatcherRegistration | interface | Configuration for registering a watcher. | | SuperWatcherRegistration | interface | Configuration for registering a superwatcher. | | WatcherCallback | type | Callback type for watcher/superwatcher updates. |

abstract class Dongle

Abstract base class managing MODBUS commands, watcher registry, and high-level dongle operations. All MODBUS operations use Master.requestAsync() with typed Request/Response classes.

Constructor

new Dongle(options: DongleOptions)

The constructor is lightweight — it stores options and initializes watcher arrays. The Master and connection are created by subclasses during initialize().

DongleOptions

| Property | Type | Default | Description | | ----------------------- | -------------- | -------------------------- | ------------------------------------------------ | | logger | DongleLogger | (stub) | Winston/pino-compatible logger for debug output. | | maxConcurrentRequests | number | 2 | Maximum simultaneous in-flight requests. | | defaultMaxRetries | number | 2 | Default retry count per transaction. | | defaultTimeout | number | 6500 | Default response timeout in milliseconds. | | retryOnException | number[] | [0x04, 0x06, 0x0A, 0x0B] | Exception codes that trigger a retry. |

Properties

| Property | Type | Description | | ------------------ | ----------------- | ------------------------------------------------------- | | ID | number | The dongle's Modbus unit address (0xFE). | | master | Master | The MODBUS Master instance (set during initialize()). | | peripheral | Connection | The underlying connection (set during initialize()). | | softwareRevision | DongleSwVersion | Software version (set after readDongleInfo()). | | watchers | Watcher[] | Array of registered watcher slots (max 15). | | superWatchers | Watcher[] | Array of super watcher slots (max 25). |

Methods

| Method | Returns | Description | | -------------------------------------------------- | -------------------------- | --------------------------------------------------------------------------------------------- | | initialize() | Promise<void> | Opens connection, creates Master, inspects device objects. Must be called after construction. | | destroy() | void | Destroys the master and clears watcher state. | | readDongleInfo() | Promise<DongleInfo> | Reads model, serial, firmware, hardware, software revision, and manufacturer. | | readInterface() | Promise<DeviceInterface> | Reads the current interface status object. | | readMemory(unit, address, length, options?) | Promise<number[]> | Reads bytes from device memory. | | writeMemory(unit, address, data, options?) | Promise<any> | Writes bytes to device memory. | | writeVerifyMemory(unit, address, data, options?) | Promise<any> | Writes and verifies bytes at device memory. | | readObject(unit, objectId, options?) | Promise<number[]> | Reads a MODBUS object by ID. | | writeObject(unit, objectId, data, options?) | Promise<number> | Writes data to an object. Returns status. | | readAccessKey() | Promise<number[]> | Reads the dongle's 128-byte cloud access key (object 0). | | writeAccessKey(data) | Promise<any> | Writes the dongle's cloud access key. | | command(unit, opcode, data?) | Promise<any> | Sends an FN_COMMAND with opcode and optional data. | | configure(options?) | Promise<any> | Sends the configuration command. | | configureI2c(options?) | Promise<void> | Configures I2C hardware interface. | | keyswitch(isEnabled, options?) | Promise<any> | Sets the keyswitch output state. | | onInterfaceUpdate(cb) | Promise<void> | Registers a callback for interface status changes. | | watch(unit, address, length, mask?, cb) | Promise<number> | Sets up a watcher. Returns the slot number. | | unwatch(slot) | void | Removes watcher at slot. | | unwatchAll(options?) | Promise<any> | Removes all watchers. | | superWatch(unit, address, cb) | Promise<number> | Registers a super watcher address. Returns slot. | | updateSuperWatcher(options?) | Promise<void> | Activates all registered super watchers. | | clearSuperWatcher(options?) | Promise<any> | Disables and clears super watcher slots. | | registerWatchers(registrations) | Promise<number[]> | Registers watchers from an array of configs. Returns slot indices. | | registerSuperWatchers(registrations) | Promise<number[]> | Registers superwatchers from an array of configs. Returns slot indices. | | teardownWatchers() | void | Resets all watcher and superwatcher slots to empty. | | reset(unit, options?) | Promise<number> | Sends a reset command. |

class UsbDongle extends Dongle

USB/serial dongle implementation. Creates a MODBUS Master with RTU transport over the supplied Connection.

Constructor

new UsbDongle(connection: Connection, options: DongleOptions)

The connection is a SerialConnection (or any Connection subclass). The Master is created during initialize(), not in the constructor.

class BleDongle extends Dongle

BLE dongle implementation. Connects to the BLE peripheral, discovers UART characteristics, creates an internal BLE UART connection, and creates a MODBUS Master with IP transport.

Constructor

new BleDongle(ble: Ble, blePeripheral: BlePeripheral, options: DongleOptions)

• ble — a Ble-compatible adapter (e.g. NobleBleManager, NobleMacBleManager)
• blePeripheral — the discovered BlePeripheral from scanning

initialize() handles BLE connect, characteristic discovery, UART connection setup, and Master creation.

DONGLE_UUIDS

Object containing all BLE service and characteristic UUIDs for CS181x dongles:

import { DONGLE_UUIDS } from '@csllc/cs1816';

DONGLE_UUIDS.uuidUartService; // '49535343-FE7D-4AE5-8FA9-9FAFD205E455'
DONGLE_UUIDS.uuidRx; // UART RX characteristic
DONGLE_UUIDS.uuidTx; // UART TX characteristic
DONGLE_UUIDS.uuidControllerService; // '6765ED1F-4DE1-49E1-4771-A14380C90000'
DONGLE_UUIDS.uuidDeviceInformation; // '180A'
// ... and more

class Watcher

Represents a single registered watcher slot. Normally constructed internally by Dongle.watch().

Properties

| Property | Type | Description | | --------- | ---------- | -------------------------------------------------------------------- | | unit | number | Slave unit being watched. | | address | number | Memory address being watched. | | length | number | Number of bytes being watched. | | hasMask | boolean | Whether a change mask is active. | | cb | function | Callback: (value: number[], address: number, unit: number) => void |

interface DongleInfo

Returned by readDongleInfo().

interface DongleInfo {
  model: string;
  serial: string;
  fw: string;
  hw: string;
  sw: string | undefined;
  mfr: string;
  product: string;
}

interface DongleLogger

interface DongleLogger {
  log(level: string, message: string, ...args: any[]): void;
  child(context: Record<string, any>): DongleLogger;
}

Message Classes

All message classes extend CommandRequest from @csllc/modbus-types:

• ConfigureCommand — Configure hardware interface
• KeySwitchCommand — Set keyswitch state
• WatchCommand / WatchMaskedCommand — Set watchers
• UnwatchCommand / UnwatchAllCommand — Cancel watchers
• SuperWatchCommand — Set super watcher addresses
• GetWatcherCommand — Query watcher table
• ResetCommand — Reset device
• DongleSlaveIdRequest — Report slave ID