@matter/nodejs-ble 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/NobleBleChannel.ts

@@ -0,0 +1,337 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Channel,
+    ChannelType,
+    InternalError,
+    Logger,
+    NetInterface,
+    ServerAddress,
+    Time,
+    TransportInterface,
+    createPromise,
+} from "@matter/general";
+import {
+    BLE_MATTER_C1_CHARACTERISTIC_UUID,
+    BLE_MATTER_C2_CHARACTERISTIC_UUID,
+    BLE_MATTER_C3_CHARACTERISTIC_UUID,
+    BLE_MATTER_SERVICE_UUID,
+    BLE_MAXIMUM_BTP_MTU,
+    BTP_CONN_RSP_TIMEOUT_MS,
+    BTP_MAXIMUM_WINDOW_SIZE,
+    BTP_SUPPORTED_VERSIONS,
+    Ble,
+    BleChannel,
+    BleError,
+    BtpFlowError,
+    BtpSessionHandler,
+} from "@project-chip/matter.js/ble";
+import { BtpCodec } from "@project-chip/matter.js/codec";
+import type { Characteristic, Peripheral } from "@stoprocent/noble";
+import { BleScanner } from "./BleScanner.js";
+
+const logger = Logger.get("BleChannel");
+
+/**
+ * Convert a UUID in noble's format to a proper UUID.
+ *
+ * @param {string} uuid - UUID to convert
+ * @returns {string} UUID
+ */
+function nobleUuidToUuid(uuid: string): string {
+    uuid = uuid.toUpperCase();
+
+    if (uuid.length !== 32) {
+        return uuid;
+    }
+
+    const parts = [
+        uuid.substring(0, 8),
+        uuid.substring(8, 12),
+        uuid.substring(12, 16),
+        uuid.substring(16, 20),
+        uuid.substring(20, 32),
+    ];
+
+    return parts.join("-");
+}
+
+export class NobleBleCentralInterface implements NetInterface {
+    private openChannels: Map<ServerAddress, Peripheral> = new Map();
+    private onMatterMessageListener: ((socket: Channel<Uint8Array>, data: Uint8Array) => void) | undefined;
+
+    openChannel(address: ServerAddress, tryCount = 1): Promise<Channel<Uint8Array>> {
+        return new Promise((resolve, reject) => {
+            if (this.onMatterMessageListener === undefined) {
+                reject(new InternalError(`Network Interface was not added to the system yet.`));
+                return;
+            }
+            if (address.type !== "ble") {
+                reject(new InternalError(`Unsupported address type ${address.type}.`));
+                return;
+            }
+
+            // Get the peripheral by address and connect to it.
+            const { peripheral, hasAdditionalAdvertisementData } = (
+                Ble.get().getBleScanner() as BleScanner
+            ).getDiscoveredDevice(address.peripheralAddress);
+
+            if (tryCount > 3) {
+                reject(new BleError(`Failed to connect to peripheral ${peripheral.address}`));
+                return;
+            }
+
+            logger.debug("BLE peripheral state", peripheral.state);
+            if (peripheral.state === "connected" || peripheral.state === "connecting") {
+                reject(
+                    new BleError(
+                        `Peripheral ${address.peripheralAddress} is already connected or connecting. Only one connection supported right now.`,
+                    ),
+                );
+                return;
+            }
+            if (this.openChannels.has(address)) {
+                reject(
+                    new BleError(
+                        `Peripheral ${address.peripheralAddress} is already connected. Only one connection supported right now.`,
+                    ),
+                );
+                return;
+            }
+            if (peripheral.state !== "disconnected") {
+                // Try to cleanup strange "in between" states
+                peripheral.disconnectAsync().then(() => this.openChannel(address, tryCount), reject);
+                return;
+            }
+
+            // eslint-disable-next-line @typescript-eslint/no-misused-promises
+            peripheral.once("connect", async () => {
+                if (this.onMatterMessageListener === undefined) {
+                    reject(new InternalError(`Network Interface was not added to the system yet.`));
+                    return;
+                }
+
+                const services = await peripheral.discoverServicesAsync([BLE_MATTER_SERVICE_UUID]);
+                logger.debug(`Found services: ${services.map(s => s.uuid).join(", ")}`);
+
+                for (const service of services) {
+                    logger.debug(`found service: ${service.uuid}`);
+                    if (service.uuid !== BLE_MATTER_SERVICE_UUID) continue;
+
+                    // So, discover its characteristics.
+                    const characteristics = await service.discoverCharacteristicsAsync();
+
+                    let characteristicC1ForWrite: Characteristic | undefined;
+                    let characteristicC2ForSubscribe: Characteristic | undefined;
+                    let additionalCommissioningRelatedData: Uint8Array | undefined;
+
+                    for (const characteristic of characteristics) {
+                        // Loop through each characteristic and match them to the UUIDs that we know about.
+                        logger.debug("found characteristic:", characteristic.uuid, characteristic.properties);
+
+                        switch (nobleUuidToUuid(characteristic.uuid)) {
+                            case BLE_MATTER_C1_CHARACTERISTIC_UUID:
+                                logger.debug("found C1 characteristic");
+                                characteristicC1ForWrite = characteristic;
+                                break;
+
+                            case BLE_MATTER_C2_CHARACTERISTIC_UUID:
+                                logger.debug("found C2 characteristic");
+                                characteristicC2ForSubscribe = characteristic;
+                                break;
+
+                            case BLE_MATTER_C3_CHARACTERISTIC_UUID:
+                                logger.debug("found C3 characteristic");
+                                if (hasAdditionalAdvertisementData) {
+                                    logger.debug("reading additional commissioning related data");
+                                    const data = await characteristic.readAsync();
+                                    additionalCommissioningRelatedData = new Uint8Array(data);
+                                    logger.debug("additional data", data);
+                                }
+                        }
+                    }
+
+                    if (!characteristicC1ForWrite || !characteristicC2ForSubscribe) {
+                        logger.debug("missing characteristics");
+                        continue;
+                    }
+
+                    peripheral.removeAllListeners("disconnect");
+                    this.openChannels.set(address, peripheral);
+                    resolve(
+                        await NobleBleChannel.create(
+                            peripheral,
+                            characteristicC1ForWrite,
+                            characteristicC2ForSubscribe,
+                            this.onMatterMessageListener,
+                            additionalCommissioningRelatedData,
+                        ),
+                    );
+                    return;
+                }
+
+                peripheral.removeAllListeners("disconnect");
+                reject(new BleError(`Peripheral ${peripheral.address} does not have the required characteristics`));
+            });
+            const reTryHandler = async (error?: any) => {
+                if (error) {
+                    logger.error(
+                        `Peripheral ${peripheral.address} disconnected while trying to connect, try again`,
+                        error,
+                    );
+                } else {
+                    logger.info(`Peripheral ${peripheral.address} disconnected while trying to connect, try gain`);
+                }
+                // Cleanup listeners and try again
+                peripheral.removeAllListeners("disconnect");
+                peripheral.removeAllListeners("connect");
+                this.openChannel(address, tryCount + 1)
+                    .then(resolve)
+                    .catch(reject);
+            };
+            // eslint-disable-next-line @typescript-eslint/no-misused-promises
+            peripheral.once("disconnect", reTryHandler);
+            logger.debug(`Connect to Peripheral now (try ${tryCount})`);
+            peripheral.connectAsync().catch(reTryHandler);
+        });
+    }
+
+    onData(listener: (socket: Channel<Uint8Array>, data: Uint8Array) => void): TransportInterface.Listener {
+        this.onMatterMessageListener = listener;
+        return {
+            close: async () => await this.close(),
+        };
+    }
+
+    async close() {
+        for (const peripheral of this.openChannels.values()) {
+            await peripheral.disconnectAsync();
+        }
+    }
+
+    supports(type: ChannelType, _address?: string) {
+        if (type !== ChannelType.BLE) {
+            return false;
+        }
+        return true;
+    }
+}
+
+export class NobleBleChannel extends BleChannel<Uint8Array> {
+    static async create(
+        peripheral: Peripheral,
+        characteristicC1ForWrite: Characteristic,
+        characteristicC2ForSubscribe: Characteristic,
+        onMatterMessageListener: (socket: Channel<Uint8Array>, data: Uint8Array) => void,
+        _additionalCommissioningRelatedData?: Uint8Array,
+    ): Promise<NobleBleChannel> {
+        let mtu = peripheral.mtu ?? 0;
+        if (mtu > BLE_MAXIMUM_BTP_MTU) {
+            mtu = BLE_MAXIMUM_BTP_MTU;
+        }
+        logger.debug(`Using MTU=${mtu} (Peripheral MTU=${peripheral.mtu})`);
+        const btpHandshakeRequest = BtpCodec.encodeBtpHandshakeRequest({
+            versions: BTP_SUPPORTED_VERSIONS,
+            attMtu: mtu,
+            clientWindowSize: BTP_MAXIMUM_WINDOW_SIZE,
+        });
+        logger.debug(`sending BTP handshake request: ${Logger.toJSON(btpHandshakeRequest)}`);
+        await characteristicC1ForWrite.writeAsync(Buffer.from(btpHandshakeRequest.buffer), false);
+
+        const btpHandshakeTimeout = Time.getTimer("BLE handshake timeout", BTP_CONN_RSP_TIMEOUT_MS, async () => {
+            await peripheral.disconnectAsync();
+            logger.debug("Handshake Response not received. Disconnected from peripheral");
+        }).start();
+
+        logger.debug("subscribing to C2 characteristic");
+        await characteristicC2ForSubscribe.subscribeAsync();
+
+        const { promise: handshakeResponseReceivedPromise, resolver } = createPromise<Buffer>();
+
+        characteristicC2ForSubscribe.once("data", (data, isNotification) => {
+            logger.debug(`received first data on C2: ${data.toString("hex")} (isNotification: ${isNotification})`);
+
+            if (data[0] === 0x65 && data[1] === 0x6c && data.length === 6) {
+                // Check if the first two bytes and length match the Matter handshake
+                logger.info(`Received Matter handshake response: ${data.toString("hex")}.`);
+                btpHandshakeTimeout.stop();
+                resolver(data);
+            }
+        });
+
+        const handshakeResponse = await handshakeResponseReceivedPromise;
+
+        const btpSession = await BtpSessionHandler.createAsCentral(
+            new Uint8Array(handshakeResponse),
+            // callback to write data to characteristic C1
+            async (data: Uint8Array) => {
+                return await characteristicC1ForWrite.writeAsync(Buffer.from(data.buffer), false);
+            },
+            // callback to disconnect the BLE connection
+            async () =>
+                void characteristicC2ForSubscribe
+                    .unsubscribeAsync()
+                    .then(() => peripheral.disconnectAsync().then(() => logger.debug("disconnected from peripheral"))),
+            // callback to forward decoded and de-assembled Matter messages to ExchangeManager
+            async (data: Uint8Array) => {
+                if (onMatterMessageListener === undefined) {
+                    throw new InternalError(`No listener registered for Matter messages`);
+                }
+                onMatterMessageListener(nobleChannel, data);
+            },
+        );
+
+        characteristicC2ForSubscribe.on("data", (data, isNotification) => {
+            logger.debug(`received data on C2: ${data.toString("hex")} (isNotification: ${isNotification})`);
+
+            void btpSession.handleIncomingBleData(new Uint8Array(data));
+        });
+
+        const nobleChannel = new NobleBleChannel(peripheral, btpSession);
+        return nobleChannel;
+    }
+
+    private connected = true;
+
+    constructor(
+        private readonly peripheral: Peripheral,
+        private readonly btpSession: BtpSessionHandler,
+    ) {
+        super();
+        peripheral.once("disconnect", () => {
+            logger.debug(`Disconnected from peripheral ${peripheral.address}`);
+            this.connected = false;
+            void this.btpSession.close();
+        });
+    }
+
+    /**
+     * Send a Matter message to the connected device - need to do BTP assembly first.
+     *
+     * @param data
+     */
+    async send(data: Uint8Array) {
+        if (!this.connected) {
+            logger.debug("Cannot send data because not connected to peripheral.");
+            return;
+        }
+        if (this.btpSession === undefined) {
+            throw new BtpFlowError(`Cannot send data, no BTP session initialized`);
+        }
+        await this.btpSession.sendMatterMessage(data);
+    }
+
+    // Channel<Uint8Array>
+    get name() {
+        return `${this.type}://${this.peripheral.address}`;
+    }
+
+    async close() {
+        await this.btpSession.close();
+        await this.peripheral.disconnectAsync();
+    }
+}

package/src/NobleBleClient.ts

@@ -0,0 +1,117 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "@matter/general";
+import { require } from "@matter/nodejs-ble/require";
+import { BLE_MATTER_SERVICE_UUID } from "@project-chip/matter.js/ble";
+import type { Peripheral } from "@stoprocent/noble";
+import { BleOptions } from "./NodeJsBle.js";
+
+const logger = Logger.get("NobleBleClient");
+let noble: typeof import("@stoprocent/noble");
+
+function loadNoble(hciId?: number) {
+    // load noble driver with the correct device selected
+    if (hciId !== undefined) {
+        process.env.NOBLE_HCI_DEVICE_ID = hciId.toString();
+    }
+    noble = require("@stoprocent/noble");
+    if (typeof noble.on !== "function") {
+        // The following commit broke the default exported instance of noble:
+        // https://github.com/abandonware/noble/commit/b67eea246f719947fc45b1b52b856e61637a8a8e
+        noble = (noble as any)({ extended: false });
+    }
+}
+
+export class NobleBleClient {
+    private readonly discoveredPeripherals = new Map<
+        string,
+        { peripheral: Peripheral; matterServiceData: Uint8Array }
+    >();
+    private shouldScan = false;
+    private isScanning = false;
+    private nobleState = "unknown";
+    private deviceDiscoveredCallback: ((peripheral: Peripheral, manufacturerData: Uint8Array) => void) | undefined;
+
+    constructor(options?: BleOptions) {
+        loadNoble(options?.hciId);
+        /*try {
+            noble.reset();
+        } catch (error: any) {
+            logger.debug(
+                `Error resetting BLE device via noble (can be ignored, we just tried): ${
+                    (error as unknown as Error).message
+                }`,
+            );
+        }*/
+        noble.on("stateChange", state => {
+            this.nobleState = state;
+            logger.debug(`Noble state changed to ${state}`);
+            if (state === "poweredOn") {
+                if (this.shouldScan) {
+                    void this.startScanning();
+                }
+            } else {
+                void this.stopScanning();
+            }
+        });
+        noble.on("discover", peripheral => this.handleDiscoveredDevice(peripheral));
+        noble.on("scanStart", () => (this.isScanning = true));
+        noble.on("scanStop", () => (this.isScanning = false));
+    }
+
+    public setDiscoveryCallback(callback: (peripheral: Peripheral, manufacturerData: Uint8Array) => void) {
+        this.deviceDiscoveredCallback = callback;
+        for (const { peripheral, matterServiceData } of this.discoveredPeripherals.values()) {
+            this.deviceDiscoveredCallback(peripheral, matterServiceData);
+        }
+    }
+
+    public async startScanning() {
+        if (this.isScanning) return;
+
+        this.shouldScan = true;
+        if (this.nobleState === "poweredOn") {
+            logger.debug("Start BLE scanning for Matter Services ...");
+            await noble.startScanningAsync([BLE_MATTER_SERVICE_UUID], false);
+        } else {
+            logger.debug("noble state is not poweredOn ... delay scanning till poweredOn");
+        }
+    }
+
+    public async stopScanning() {
+        this.shouldScan = false;
+        logger.debug("Stop BLE scanning for Matter Services ...");
+        await noble.stopScanningAsync();
+    }
+
+    private handleDiscoveredDevice(peripheral: Peripheral) {
+        // The advertisement data contains a name, power level (if available), certain advertised service uuids,
+        // as well as manufacturer data.
+        // {"localName":"MATTER-3840","serviceData":[{"uuid":"fff6","data":{"type":"Buffer","data":[0,0,15,241,255,1,128,0]}}],"serviceUuids":["fff6"],"solicitationServiceUuids":[],"serviceSolicitationUuids":[]}
+        logger.debug(
+            `Found peripheral ${peripheral.address} (${peripheral.advertisement.localName}): ${Logger.toJSON(
+                peripheral.advertisement,
+            )}`,
+        );
+
+        if (!peripheral.connectable) {
+            logger.info(`Peripheral ${peripheral.address} is not connectable ... ignoring`);
+            return;
+        }
+        const matterServiceData = peripheral.advertisement.serviceData.find(
+            serviceData => serviceData.uuid === BLE_MATTER_SERVICE_UUID,
+        );
+        if (matterServiceData === undefined || matterServiceData.data.length !== 8) {
+            logger.info(`Peripheral ${peripheral.address} does not advertise Matter Service ... ignoring`);
+            return;
+        }
+
+        this.discoveredPeripherals.set(peripheral.address, { peripheral, matterServiceData: matterServiceData.data });
+
+        this.deviceDiscoveredCallback?.(peripheral, matterServiceData.data);
+    }
+}

package/src/NodeJsBle.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { NetInterface, TransportInterface } from "@matter/general";
+import { Ble } from "@project-chip/matter.js/ble";
+import { InstanceBroadcaster, Scanner } from "@project-chip/matter.js/common";
+import { BleBroadcaster } from "./BleBroadcaster.js";
+import { BlePeripheralInterface } from "./BlePeripheralInterface.js";
+import { BleScanner } from "./BleScanner.js";
+import { BlenoBleServer } from "./BlenoBleServer.js";
+import { NobleBleCentralInterface } from "./NobleBleChannel.js";
+import { NobleBleClient } from "./NobleBleClient.js";
+
+export type BleOptions = {
+    hciId?: number;
+};
+
+export class NodeJsBle extends Ble {
+    private blePeripheral: BlenoBleServer | undefined;
+    private bleCentral: NobleBleClient | undefined;
+
+    constructor(private readonly options?: BleOptions) {
+        super();
+    }
+
+    getBlePeripheralInterface(): TransportInterface {
+        if (this.blePeripheral === undefined) {
+            this.blePeripheral = new BlenoBleServer(this.options);
+        }
+        return new BlePeripheralInterface(this.blePeripheral);
+    }
+
+    getBleCentralInterface(): NetInterface {
+        if (this.bleCentral === undefined) {
+            this.bleCentral = new NobleBleClient(this.options);
+        }
+        return new NobleBleCentralInterface();
+    }
+
+    getBleBroadcaster(additionalAdvertisementData?: Uint8Array): InstanceBroadcaster {
+        if (this.blePeripheral === undefined) {
+            this.blePeripheral = new BlenoBleServer(this.options);
+        }
+        return new BleBroadcaster(this.blePeripheral, additionalAdvertisementData);
+    }
+
+    getBleScanner(): Scanner {
+        if (this.bleCentral === undefined) {
+            this.bleCentral = new NobleBleClient(this.options);
+        }
+        return new BleScanner(this.bleCentral);
+    }
+}

package/src/index.ts

@@ -0,0 +1,9 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+export * from "./BleBroadcaster.js";
+export * from "./BleScanner.js";
+export * from "./NodeJsBle.js";

package/src/tsconfig.json

@@ -0,0 +1,16 @@
+{
+    "extends": "../../tools/tsc/tsconfig.lib.json",
+    "compilerOptions": {
+        "types": [
+            "node"
+        ]
+    },
+    "references": [
+        {
+            "path": "../../general/src"
+        },
+        {
+            "path": "../../matter.js/src"
+        }
+    ]
+}