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

package/src/BleBroadcaster.ts

@@ -0,0 +1,126 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ImplementationError, Logger } from "@matter/general";
+import { BtpCodec } from "@project-chip/matter.js/codec";
+import { VendorId } from "@project-chip/matter.js/datatype";
+import {
+    CommissionerInstanceData,
+    CommissioningModeInstanceData,
+    InstanceBroadcaster,
+} from "@project-chip/matter.js/fabric";
+import { BlenoBleServer } from "./BlenoBleServer.js";
+
+const logger = Logger.get("BleBroadcaster");
+
+export class BleBroadcaster implements InstanceBroadcaster {
+    #blenoServer: BlenoBleServer;
+    #additionalAdvertisementData?: Uint8Array;
+    #vendorId: VendorId | undefined;
+    #productId: number | undefined;
+    #discriminator: number | undefined;
+    #advertise = false;
+    #isClosed = false;
+
+    constructor(blenoServer: BlenoBleServer, additionalAdvertisementData?: Uint8Array) {
+        this.#blenoServer = blenoServer;
+        this.#additionalAdvertisementData = additionalAdvertisementData;
+    }
+
+    async setCommissionMode(
+        mode: number,
+        { name: deviceName, deviceType, vendorId, productId, discriminator }: CommissioningModeInstanceData,
+    ) {
+        this.#assertOpen();
+        if (mode !== 1) {
+            this.#advertise = false;
+            logger.info(
+                `skip BLE announce because of commissioning mode ${mode} ${deviceName} ${deviceType} ${vendorId} ${productId} ${discriminator}`,
+            );
+            await this.#blenoServer.stopAdvertising();
+            return;
+        }
+        logger.debug(
+            `set data for commissioning mode ${mode} ${deviceName} ${deviceType} ${vendorId} ${productId} ${discriminator}`,
+        );
+        this.#productId = productId;
+        this.#vendorId = vendorId;
+        this.#discriminator = discriminator;
+        process.env["BLENO_DEVICE_NAME"] = deviceName;
+        this.#advertise = true;
+    }
+
+    async setFabrics() {
+        this.#assertOpen();
+        this.#advertise = false;
+        logger.info(`skip BLE announce because announcing an operational device is not supported`);
+        await this.#blenoServer.stopAdvertising();
+        return; // Not needed because we only advertise un-commissioned devices
+    }
+
+    async setCommissionerInfo(_commissionerData: CommissionerInstanceData) {
+        this.#assertOpen();
+        this.#advertise = false;
+        logger.error(`skip BLE announce because announcing a commissioner is not supported`);
+    }
+
+    async announce() {
+        this.#assertOpen();
+        if (this.#vendorId === undefined || this.#productId === undefined || this.#discriminator === undefined) {
+            logger.debug(
+                `skip BLE announce because of missing commissioning data vendorId, productId or discriminator`,
+            );
+            return;
+        }
+        if (!this.#advertise) {
+            logger.debug(`skip BLE announce because nothing to advertise`);
+            return;
+        }
+
+        const advertisementData = BtpCodec.encodeBleAdvertisementData(
+            this.#discriminator,
+            this.#vendorId,
+            this.#productId,
+            this.#additionalAdvertisementData !== undefined && this.#additionalAdvertisementData.length > 0,
+        );
+
+        // TODO if needed implement this according to the spec 5.4.2.5.3. (first 30s 20-60ms, 150-1285ms after)
+        process.env["BLENO_ADVERTISING_INTERVAL"] = "100"; // use statically 100ms for now
+
+        await this.#blenoServer.advertise(advertisementData, this.#additionalAdvertisementData);
+    }
+
+    async expireCommissioningAnnouncement() {
+        this.#assertOpen();
+        this.#advertise = false;
+        await this.#blenoServer.stopAdvertising();
+    }
+
+    async expireFabricAnnouncement() {
+        // nothing to do
+    }
+
+    async expireAllAnnouncements() {
+        this.#assertOpen();
+        this.#advertise = false;
+        await this.#blenoServer.stopAdvertising();
+    }
+
+    async close() {
+        if (this.#isClosed) {
+            return;
+        }
+        this.#isClosed = true;
+
+        await this.#blenoServer.stopAdvertising();
+    }
+
+    #assertOpen() {
+        if (this.#isClosed) {
+            throw new ImplementationError("Illegal operation on closed BleBroadcaster");
+        }
+    }
+}

package/src/BlePeripheralInterface.ts

@@ -0,0 +1,36 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Channel, ChannelType, TransportInterface } from "@matter/general";
+import { BlenoBleServer } from "./BlenoBleServer.js";
+
+export class BlePeripheralInterface implements TransportInterface {
+    constructor(private readonly blenoServer: BlenoBleServer) {}
+
+    // TransportInterface
+    onData(listener: (socket: Channel<Uint8Array>, data: Uint8Array) => void): TransportInterface.Listener {
+        this.blenoServer.setMatterMessageListener(listener);
+        return {
+            close: async () => await this.close(),
+        };
+    }
+
+    async close() {
+        await this.blenoServer.close();
+    }
+
+    supports(type: ChannelType, address?: string) {
+        if (type === ChannelType.BLE) {
+            return true;
+        }
+
+        if (address === undefined) {
+            return true;
+        }
+
+        return this.blenoServer.clientAddress === address;
+    }
+}

package/src/BleScanner.ts

@@ -0,0 +1,279 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, ChannelType, createPromise, Logger, Time, Timer } from "@matter/general";
+import { BleError } from "@project-chip/matter.js/ble";
+import { BtpCodec } from "@project-chip/matter.js/codec";
+import { CommissionableDevice, CommissionableDeviceIdentifiers, Scanner } from "@project-chip/matter.js/common";
+import { VendorId } from "@project-chip/matter.js/datatype";
+import type { Peripheral } from "@stoprocent/noble";
+import { NobleBleClient } from "./NobleBleClient.js";
+
+const logger = Logger.get("BleScanner");
+
+export type DiscoveredBleDevice = {
+    deviceData: CommissionableDeviceData;
+    peripheral: Peripheral;
+    hasAdditionalAdvertisementData: boolean;
+};
+
+type CommissionableDeviceData = CommissionableDevice & {
+    SD: number; // Additional Field for Short discriminator
+};
+
+export class BleScanner implements Scanner {
+    get type() {
+        return ChannelType.BLE;
+    }
+
+    private readonly recordWaiters = new Map<
+        string,
+        {
+            resolver: () => void;
+            timer: Timer;
+            resolveOnUpdatedRecords: boolean;
+        }
+    >();
+    private readonly discoveredMatterDevices = new Map<string, DiscoveredBleDevice>();
+
+    constructor(private readonly nobleClient: NobleBleClient) {
+        this.nobleClient.setDiscoveryCallback((address, manufacturerData) =>
+            this.handleDiscoveredDevice(address, manufacturerData),
+        );
+    }
+
+    public getDiscoveredDevice(address: string): DiscoveredBleDevice {
+        const device = this.discoveredMatterDevices.get(address);
+        if (device === undefined) {
+            throw new BleError(`No device found for address ${address}`);
+        }
+        return device;
+    }
+
+    /**
+     * Registers a deferred promise for a specific queryId together with a timeout and return the promise.
+     * The promise will be resolved when the timer runs out latest.
+     */
+    private async registerWaiterPromise(queryId: string, timeoutSeconds: number, resolveOnUpdatedRecords = true) {
+        const { promise, resolver } = createPromise<void>();
+        const timer = Time.getTimer("BLE query timeout", timeoutSeconds * 1000, () =>
+            this.finishWaiter(queryId, true),
+        ).start();
+        this.recordWaiters.set(queryId, { resolver, timer, resolveOnUpdatedRecords });
+        logger.debug(
+            `Registered waiter for query ${queryId} with timeout ${timeoutSeconds} seconds${
+                resolveOnUpdatedRecords ? "" : " (not resolving on updated records)"
+            }`,
+        );
+        await promise;
+    }
+
+    /**
+     * Remove a waiter promise for a specific queryId and stop the connected timer. If required also resolve the
+     * promise.
+     */
+    private finishWaiter(queryId: string, resolvePromise: boolean, isUpdatedRecord = false) {
+        const waiter = this.recordWaiters.get(queryId);
+        if (waiter === undefined) return;
+        const { timer, resolver, resolveOnUpdatedRecords } = waiter;
+        if (isUpdatedRecord && !resolveOnUpdatedRecords) return;
+        logger.debug(`Finishing waiter for query ${queryId}, resolving: ${resolvePromise}`);
+        timer.stop();
+        if (resolvePromise) {
+            resolver();
+        }
+        this.recordWaiters.delete(queryId);
+    }
+
+    cancelCommissionableDeviceDiscovery(identifier: CommissionableDeviceIdentifiers) {
+        const queryKey = this.buildCommissionableQueryIdentifier(identifier);
+        this.finishWaiter(queryKey, true);
+    }
+
+    private handleDiscoveredDevice(peripheral: Peripheral, manufacturerServiceData: Uint8Array) {
+        logger.debug(
+            `Discovered device ${peripheral.address} ${manufacturerServiceData === undefined ? undefined : Bytes.toHex(manufacturerServiceData)}`,
+        );
+
+        try {
+            const { discriminator, vendorId, productId, hasAdditionalAdvertisementData } =
+                BtpCodec.decodeBleAdvertisementServiceData(manufacturerServiceData);
+
+            const commissionableDevice: CommissionableDeviceData = {
+                deviceIdentifier: peripheral.address,
+                D: discriminator,
+                SD: (discriminator >> 8) & 0x0f,
+                VP: `${vendorId}+${productId}`,
+                CM: 1, // Can be no other mode,
+                addresses: [{ type: "ble", peripheralAddress: peripheral.address }],
+            };
+            logger.debug(`Discovered device ${peripheral.address} data: ${Logger.toJSON(commissionableDevice)}`);
+
+            const deviceExisting = this.discoveredMatterDevices.has(peripheral.address);
+
+            this.discoveredMatterDevices.set(peripheral.address, {
+                deviceData: commissionableDevice,
+                peripheral: peripheral,
+                hasAdditionalAdvertisementData,
+            });
+
+            const queryKey = this.findCommissionableQueryIdentifier(commissionableDevice);
+            if (queryKey !== undefined) {
+                this.finishWaiter(queryKey, true, deviceExisting);
+            }
+        } catch (error) {
+            logger.debug(`Seems not to be a valid Matter device: Failed to decode device data: ${error}`);
+        }
+    }
+
+    private findCommissionableQueryIdentifier(record: CommissionableDeviceData) {
+        const longDiscriminatorQueryId = this.buildCommissionableQueryIdentifier({ longDiscriminator: record.D });
+        if (this.recordWaiters.has(longDiscriminatorQueryId)) {
+            return longDiscriminatorQueryId;
+        }
+
+        const shortDiscriminatorQueryId = this.buildCommissionableQueryIdentifier({ shortDiscriminator: record.SD });
+        if (this.recordWaiters.has(shortDiscriminatorQueryId)) {
+            return shortDiscriminatorQueryId;
+        }
+
+        if (record.VP !== undefined) {
+            const vendorIdQueryId = this.buildCommissionableQueryIdentifier({
+                vendorId: VendorId(parseInt(record.VP.split("+")[0])),
+            });
+            if (this.recordWaiters.has(vendorIdQueryId)) {
+                return vendorIdQueryId;
+            }
+            if (record.VP.includes("+")) {
+                const productIdQueryId = this.buildCommissionableQueryIdentifier({
+                    vendorId: VendorId(parseInt(record.VP.split("+")[1])),
+                });
+                if (this.recordWaiters.has(productIdQueryId)) {
+                    return productIdQueryId;
+                }
+            }
+        }
+
+        if (this.recordWaiters.has("*")) {
+            return "*";
+        }
+
+        return undefined;
+    }
+
+    /**
+     * Builds an identifier string for commissionable queries based on the given identifier object.
+     * Some identifiers are identical to the official DNS-SD identifiers, others are custom.
+     */
+    private buildCommissionableQueryIdentifier(identifier: CommissionableDeviceIdentifiers) {
+        if ("longDiscriminator" in identifier) {
+            return `D:${identifier.longDiscriminator}`;
+        } else if ("shortDiscriminator" in identifier) {
+            return `SD:${identifier.shortDiscriminator}`;
+        } else if ("vendorId" in identifier) {
+            return `V:${identifier.vendorId}`;
+        } else if ("productId" in identifier) {
+            // Custom identifier because normally productId is only included in TXT record
+            return `P:${identifier.productId}`;
+        } else return "*";
+    }
+
+    private getCommissionableDevices(identifier: CommissionableDeviceIdentifiers) {
+        const storedRecords = Array.from(this.discoveredMatterDevices.values());
+
+        const foundRecords = new Array<DiscoveredBleDevice>();
+        if ("longDiscriminator" in identifier) {
+            foundRecords.push(...storedRecords.filter(({ deviceData: { D } }) => D === identifier.longDiscriminator));
+        } else if ("shortDiscriminator" in identifier) {
+            foundRecords.push(
+                ...storedRecords.filter(({ deviceData: { SD } }) => SD === identifier.shortDiscriminator),
+            );
+        } else if ("vendorId" in identifier) {
+            foundRecords.push(
+                ...storedRecords.filter(
+                    ({ deviceData: { VP } }) =>
+                        VP === `${identifier.vendorId}` || VP?.startsWith(`${identifier.vendorId}+`),
+                ),
+            );
+        } else if ("productId" in identifier) {
+            foundRecords.push(
+                ...storedRecords.filter(({ deviceData: { VP } }) => VP?.endsWith(`+${identifier.productId}`)),
+            );
+        } else {
+            foundRecords.push(...storedRecords.filter(({ deviceData: { CM } }) => CM === 1 || CM === 2));
+        }
+
+        return foundRecords;
+    }
+
+    async findOperationalDevice(): Promise<undefined> {
+        logger.info(`skip BLE scan because scanning for operational devices is not supported`);
+        return undefined;
+    }
+
+    getDiscoveredOperationalDevice(): undefined {
+        logger.info(`skip BLE scan because scanning for operational devices is not supported`);
+        return undefined;
+    }
+
+    async findCommissionableDevices(
+        identifier: CommissionableDeviceIdentifiers,
+        timeoutSeconds = 10,
+    ): Promise<CommissionableDevice[]> {
+        let storedRecords = this.getCommissionableDevices(identifier);
+        if (storedRecords.length === 0) {
+            const queryKey = this.buildCommissionableQueryIdentifier(identifier);
+
+            await this.nobleClient.startScanning();
+            await this.registerWaiterPromise(queryKey, timeoutSeconds);
+
+            storedRecords = this.getCommissionableDevices(identifier);
+            await this.nobleClient.stopScanning();
+        }
+        return storedRecords.map(({ deviceData }) => deviceData);
+    }
+
+    async findCommissionableDevicesContinuously(
+        identifier: CommissionableDeviceIdentifiers,
+        callback: (device: CommissionableDevice) => void,
+        timeoutSeconds = 60,
+    ): Promise<CommissionableDevice[]> {
+        const discoveredDevices = new Set<string>();
+
+        const discoveryEndTime = Time.nowMs() + timeoutSeconds * 1000;
+        const queryKey = this.buildCommissionableQueryIdentifier(identifier);
+        await this.nobleClient.startScanning();
+
+        while (true) {
+            this.getCommissionableDevices(identifier).forEach(({ deviceData }) => {
+                const { deviceIdentifier } = deviceData;
+                if (!discoveredDevices.has(deviceIdentifier)) {
+                    discoveredDevices.add(deviceIdentifier);
+                    callback(deviceData);
+                }
+            });
+
+            const remainingTime = Math.ceil((discoveryEndTime - Time.nowMs()) / 1000);
+            if (remainingTime <= 0) {
+                break;
+            }
+            await this.registerWaiterPromise(queryKey, remainingTime, false);
+        }
+        await this.nobleClient.stopScanning();
+        return this.getCommissionableDevices(identifier).map(({ deviceData }) => deviceData);
+    }
+
+    getDiscoveredCommissionableDevices(identifier: CommissionableDeviceIdentifiers): CommissionableDevice[] {
+        return this.getCommissionableDevices(identifier).map(({ deviceData }) => deviceData);
+    }
+
+    close(): void {
+        void this.nobleClient.stopScanning();
+        [...this.recordWaiters.keys()].forEach(queryId =>
+            this.finishWaiter(queryId, !!this.recordWaiters.get(queryId)?.timer),
+        );
+    }
+}