@csllc/mb-conn-noble-mac

MODBUS-over-BLE connection package for macOS, using noble-mac and Apple's CoreBluetooth API.

Not production-ready. This package is intended for testing MODBUS-over-BLE functionality on macOS during development. Apple's Bluetooth stack and APIs evolve with each macOS release, and noble-mac's compatibility with future versions is not guaranteed. For production deployments, consider @csllc/mb-conn-noble-ble (which uses @abandonware/noble) or a React Native solution with @csllc/rn-mb-ble.

Why noble-mac?

Standard Noble (@abandonware/noble) communicates with macOS Bluetooth via an undocumented XPC protocol that Apple can change at any time. noble-mac uses the official CoreBluetooth API instead, which tends to be more stable across macOS updates. The trade-off is that noble-mac is less actively maintained and may lag behind Noble's feature set.

Exported Interface

BleConnection

A Connection subclass (from @csllc/modbus-types) that bridges BLE transparent UART characteristics to the MODBUS connection API.

import { BleConnection } from '@csllc/mb-conn-noble-mac';

const connection = new BleConnection(ble, peripheral, rxChar, txChar);
await connection.open(); // subscribes to UART RX notifications
await connection.write(buf); // writes to UART TX characteristic
await connection.close(); // unsubscribes and disconnects

• open() — Subscribes to the UART RX characteristic. Incoming BLE notifications are converted to ArrayBuffer and emitted as 'data' events, feeding IpTransport automatically.
• write(data: ArrayBuffer) — Forwards bytes to the UART TX characteristic via BLE write. Emits a 'write' event.
• close() — Unsubscribes from RX notifications and disconnects the peripheral. Emits 'close'.
• isOpen() — Returns true if the connection is active.
• destroy() — Closes the connection (if open) and removes all event listeners.

Events: 'open', 'close', 'data', 'write', 'error'

NobleMacBleManager

Implements the Ble interface from @csllc/blejs-types, wrapping noble-mac. Can be used directly or passed to BleConnection and BleDongle.

import { NobleMacBleManager } from '@csllc/mb-conn-noble-mac';

await NobleMacBleManager.initialize();
await NobleMacBleManager.startScan([], (peripheral) => { ... });
await NobleMacBleManager.connect(peripheral);
const chars = await NobleMacBleManager.findCharacteristics(peripheral, serviceUuid, wanted);

scan(serviceUuids?, duration?)

Convenience function that initializes noble-mac, scans for peripherals, and returns an array of BleConnectionInfo objects.

import { scan } from '@csllc/mb-conn-noble-mac';

const peripherals = await scan(['180a'], 5000);
// [{ id: '...', type: 'ble', peripheralId: '...', name: 'CS1816' }]

BleConnectionInfo

interface BleConnectionInfo {
  id: string; // unique identifier
  type: 'ble'; // connection type discriminator
  peripheralId: string; // BLE peripheral ID
  name?: string; // advertised local name
}

Usage with MODBUS

import { createMaster } from '@csllc/modbus-types';
import { BleConnection, NobleMacBleManager } from '@csllc/mb-conn-noble-mac';
import { BleDongle, DONGLE_UUIDS } from '@csllc/cs1816';

// 1. Initialize and connect
await NobleMacBleManager.initialize();
await NobleMacBleManager.startScan([], cb);
// ... find peripheral ...
await NobleMacBleManager.connect(peripheral);

// 2. Discover UART characteristics
const chars = await NobleMacBleManager.findCharacteristics(
  peripheral,
  DONGLE_UUIDS.uuidUartService,
  [
    { name: 'rx', characteristic: DONGLE_UUIDS.uuidRx, required: true },
    { name: 'tx', characteristic: DONGLE_UUIDS.uuidTx, required: true },
  ],
);

// 3. Create the MODBUS stack
const connection = new BleConnection(
  NobleMacBleManager,
  peripheral,
  chars.get('rx')!,
  chars.get('tx')!,
);
const master = createMaster({
  transport: { type: 'ip', connection },
  defaultUnit: 1,
});
const dongle = new BleDongle(NobleMacBleManager, master, {});

// 4. Open and use
await connection.open();

Platform Support

• macOS: Primary target. Uses CoreBluetooth via noble-mac.
• Linux/Windows: noble-mac falls back to standard Noble on non-Mac platforms, but this is untested. Use @csllc/mb-conn-noble-ble instead.