@matter/protocol 0.16.10 → 0.16.11-alpha.0-20260225-033797f3c

package/src/common/BleScanner.ts

@@ -0,0 +1,387 @@
+/**
+ * @license
+ * Copyright 2022-2026 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {
+    Bytes,
+    ChannelType,
+    createPromise,
+    Diagnostic,
+    Duration,
+    Logger,
+    MaybePromise,
+    Millis,
+    Seconds,
+    Time,
+    Timer,
+    Timespan,
+} from "#general";
+import { VendorId } from "#types";
+import { BleError } from "../ble/Ble.js";
+import { BtpCodec } from "../codec/BtpCodec.js";
+import { CommissionableDevice, CommissionableDeviceIdentifiers, Scanner } from "./Scanner.js";
+
+const logger = Logger.get("BleScanner");
+
+export interface BlePeripheral {
+    readonly address: string;
+}
+
+export interface BleScannerClient {
+    setDiscoveryCallback(callback: (peripheral: BlePeripheral, data: Bytes) => void): void;
+    startScanning(): Promise<void>;
+    stopScanning(): Promise<void>;
+}
+
+export type CommissionableDeviceData = CommissionableDevice & {
+    SD: number; // Additional Field for Short discriminator
+};
+
+export type DiscoveredBleDevice = {
+    deviceData: CommissionableDeviceData;
+    peripheral: BlePeripheral;
+    hasAdditionalAdvertisementData: boolean;
+};
+
+export class BleScanner implements Scanner {
+    readonly type = ChannelType.BLE;
+
+    readonly #client: BleScannerClient;
+    readonly #recordWaiters = new Map<
+        string,
+        {
+            resolver: () => void;
+            timer?: Timer;
+            resolveOnUpdatedRecords: boolean;
+            cancelResolver?: (value: void) => void;
+        }
+    >();
+    readonly #discoveredMatterDevices = new Map<string, DiscoveredBleDevice>();
+
+    constructor(client: BleScannerClient) {
+        this.#client = client;
+        this.#client.setDiscoveryCallback((peripheral, manufacturerData) =>
+            this.#handleDiscoveredDevice(peripheral, 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.
+     */
+    async #registerWaiterPromise(
+        queryId: string,
+        timeout?: Duration,
+        resolveOnUpdatedRecords = true,
+        cancelResolver?: (value: void) => void,
+    ) {
+        const { promise, resolver } = createPromise<void>();
+        let timer;
+        if (timeout) {
+            timer = Time.getTimer("BLE query timeout", timeout, () => {
+                cancelResolver?.();
+                this.#finishWaiter(queryId, true);
+            }).start();
+        }
+        this.#recordWaiters.set(queryId, { resolver, timer, resolveOnUpdatedRecords, cancelResolver });
+        logger.debug(
+            `Registered waiter for query ${queryId} with timeout ${timeout === undefined ? "(none)" : Duration.format(timeout)} ${
+                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.
+     */
+    #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, resolvePromise = true) {
+        const queryKey = this.#buildCommissionableQueryIdentifier(identifier);
+        if (queryKey === undefined) return;
+        const { cancelResolver } = this.#recordWaiters.get(queryKey) ?? {};
+        // Mark as canceled to not loop further in discovery, if cancel-resolver is used
+        cancelResolver?.();
+        this.#finishWaiter(queryKey, resolvePromise);
+    }
+
+    #handleDiscoveredDevice(peripheral: BlePeripheral, manufacturerServiceData: Bytes) {
+        const address = peripheral.address;
+
+        try {
+            const { discriminator, vendorId, productId, hasAdditionalAdvertisementData } =
+                BtpCodec.decodeBleAdvertisementServiceData(manufacturerServiceData);
+
+            const deviceData: CommissionableDeviceData = {
+                deviceIdentifier: address,
+                D: discriminator,
+                SD: (discriminator >> 8) & 0x0f,
+                VP: `${vendorId}+${productId}`,
+                CM: 1, // Can be no other mode,
+                addresses: [{ type: "ble", peripheralAddress: address }],
+            };
+            const deviceExisting = this.#discoveredMatterDevices.has(address);
+
+            logger.debug(
+                `${deviceExisting ? "Re-" : ""}Discovered device ${address} data: ${Diagnostic.json(deviceData)}`,
+            );
+
+            this.#discoveredMatterDevices.set(address, {
+                deviceData,
+                peripheral,
+                hasAdditionalAdvertisementData,
+            });
+
+            const queryKey = this.#findCommissionableQueryIdentifier(deviceData);
+            if (queryKey !== undefined) {
+                this.#finishWaiter(queryKey, true, deviceExisting);
+            }
+        } catch (error) {
+            logger.debug(
+                `Discovered device ${address} ${manufacturerServiceData === undefined ? undefined : Bytes.toHex(manufacturerServiceData)} does not seem to be a valid Matter device: ${error}`,
+            );
+        }
+    }
+
+    #findCommissionableQueryIdentifier(record: CommissionableDeviceData) {
+        const longDiscriminatorQueryId = this.#buildCommissionableQueryIdentifier({ longDiscriminator: record.D });
+        if (longDiscriminatorQueryId !== undefined && this.#recordWaiters.has(longDiscriminatorQueryId)) {
+            return longDiscriminatorQueryId;
+        }
+
+        const shortDiscriminatorQueryId = this.#buildCommissionableQueryIdentifier({ shortDiscriminator: record.SD });
+        if (shortDiscriminatorQueryId !== undefined && this.#recordWaiters.has(shortDiscriminatorQueryId)) {
+            return shortDiscriminatorQueryId;
+        }
+
+        if (record.VP !== undefined) {
+            const vpParts = record.VP.split("+");
+            const vendorId = VendorId(parseInt(vpParts[0]));
+            const productId = vpParts[1] !== undefined ? parseInt(vpParts[1]) : undefined;
+
+            // Check vendorId+productId combo first (most specific)
+            if (productId !== undefined) {
+                const vendorProductQueryId = this.#buildCommissionableQueryIdentifier({
+                    vendorId,
+                    productId,
+                });
+                if (vendorProductQueryId !== undefined && this.#recordWaiters.has(vendorProductQueryId)) {
+                    return vendorProductQueryId;
+                }
+            }
+
+            const vendorIdQueryId = this.#buildCommissionableQueryIdentifier({ vendorId });
+            if (vendorIdQueryId !== undefined && this.#recordWaiters.has(vendorIdQueryId)) {
+                return vendorIdQueryId;
+            }
+
+            if (productId !== undefined) {
+                const productIdQueryId = this.#buildCommissionableQueryIdentifier({ productId });
+                if (productIdQueryId !== undefined && 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.
+     */
+    #buildCommissionableQueryIdentifier(identifier: CommissionableDeviceIdentifiers) {
+        if ("instanceId" in identifier) {
+            // instanceId is not supported in BLE scanning
+            return undefined;
+        } else if ("longDiscriminator" in identifier) {
+            return `D:${identifier.longDiscriminator}`;
+        } else if ("shortDiscriminator" in identifier) {
+            return `SD:${identifier.shortDiscriminator}`;
+        } else if ("vendorId" in identifier && "productId" in identifier) {
+            return `VP:${identifier.vendorId}+${identifier.productId}`;
+        } else if ("vendorId" in identifier) {
+            return `V:${identifier.vendorId}`;
+        } else if ("deviceType" in identifier) {
+            // deviceType is not supported in BLE scanning
+            return undefined;
+        } else if ("productId" in identifier) {
+            // Custom identifier because normally productId is only included in TXT record
+            return `P:${identifier.productId}`;
+        } else return "*";
+    }
+
+    #getCommissionableDevices(identifier: CommissionableDeviceIdentifiers) {
+        const storedRecords = Array.from(this.#discoveredMatterDevices.values());
+
+        const foundRecords = new Array<DiscoveredBleDevice>();
+        if ("instanceId" in identifier || "deviceType" in identifier) {
+            // These identifier types are not supported in BLE scanning
+            return foundRecords;
+        } else 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 && "productId" in identifier) {
+            foundRecords.push(
+                ...storedRecords.filter(
+                    ({ deviceData: { VP } }) => VP === `${identifier.vendorId}+${identifier.productId}`,
+                ),
+            );
+        } 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,
+        timeout = Seconds(10),
+        ignoreExistingRecords = false,
+    ): Promise<CommissionableDevice[]> {
+        const queryKey = this.#buildCommissionableQueryIdentifier(identifier);
+        if (queryKey === undefined) {
+            return [];
+        }
+
+        let storedRecords = this.#getCommissionableDevices(identifier);
+        if (ignoreExistingRecords) {
+            // We want to have a fresh discovery result, so clear out the stored records because they might be outdated
+            for (const record of storedRecords) {
+                this.#discoveredMatterDevices.delete(record.peripheral.address);
+            }
+            storedRecords = [];
+        }
+        if (storedRecords.length === 0) {
+            await this.#client.startScanning();
+            await this.#registerWaiterPromise(queryKey, timeout);
+
+            storedRecords = this.#getCommissionableDevices(identifier);
+            await this.#client.stopScanning();
+        }
+        return storedRecords.map(({ deviceData }) => deviceData);
+    }
+
+    async findCommissionableDevicesContinuously(
+        identifier: CommissionableDeviceIdentifiers,
+        callback: (device: CommissionableDevice) => void,
+        timeout?: Duration,
+        cancelSignal?: Promise<void>,
+    ): Promise<CommissionableDevice[]> {
+        const queryKey = this.#buildCommissionableQueryIdentifier(identifier);
+        if (queryKey === undefined) {
+            return [];
+        }
+
+        const discoveredDevices = new Set<string>();
+
+        const discoveryEndTime = timeout ? Time.nowMs + timeout : undefined;
+        await this.#client.startScanning();
+
+        let queryResolver: ((value: void) => void) | undefined;
+        if (cancelSignal === undefined) {
+            const { promise, resolver } = createPromise<void>();
+            cancelSignal = promise;
+            queryResolver = resolver;
+        }
+
+        let canceled = false;
+        cancelSignal?.then(
+            () => {
+                canceled = true;
+                this.#finishWaiter(queryKey, true);
+            },
+            cause => {
+                logger.error("Unexpected error canceling commissioning", cause);
+            },
+        );
+
+        while (!canceled) {
+            this.#getCommissionableDevices(identifier).forEach(({ deviceData }) => {
+                const { deviceIdentifier } = deviceData;
+                if (!discoveredDevices.has(deviceIdentifier)) {
+                    discoveredDevices.add(deviceIdentifier);
+                    callback(deviceData);
+                }
+            });
+
+            let remainingTime;
+            if (discoveryEndTime !== undefined) {
+                remainingTime = Millis.ceil(Timespan(Time.nowMs, discoveryEndTime).duration);
+                if (remainingTime <= 0) {
+                    break;
+                }
+            }
+
+            await this.#registerWaiterPromise(queryKey, remainingTime, false, queryResolver);
+        }
+        await this.#client.stopScanning();
+        return this.#getCommissionableDevices(identifier).map(({ deviceData }) => deviceData);
+    }
+
+    getDiscoveredCommissionableDevices(identifier: CommissionableDeviceIdentifiers): CommissionableDevice[] {
+        return this.#getCommissionableDevices(identifier).map(({ deviceData }) => deviceData);
+    }
+
+    protected closeClient(): MaybePromise<void> {
+        return this.#client.stopScanning();
+    }
+
+    async close() {
+        await this.closeClient();
+        [...this.#recordWaiters.keys()].forEach(queryId =>
+            this.#finishWaiter(queryId, !!this.#recordWaiters.get(queryId)?.timer),
+        );
+    }
+}

package/src/common/index.ts

@@ -5,6 +5,7 @@
  */
 
 export * from "../peer/PeerAddress.js";
+export * from "./BleScanner.js";
 export * from "./ExpandedPath.js";
 export * from "./FailsafeContext.js";
 export * from "./FailsafeTimer.js";

package/src/peer/ControllerCommissioningFlow.ts

@@ -1501,7 +1501,9 @@ export class ControllerCommissioningFlow {
         );
 
         if (addNetworkingStatus !== NetworkCommissioning.NetworkCommissioningStatus.Success) {
-            throw new ThreadNetworkSetupFailedError(`Commissionee failed to add Thread network: ${addDebugText}`);
+            throw new ThreadNetworkSetupFailedError(
+                `Commissionee failed to add Thread network: status=${NetworkCommissioning.NetworkCommissioningStatus[addNetworkingStatus]} (${addNetworkingStatus})${addDebugText ? ` ${addDebugText}` : ""}`,
+            );
         }
         if (networkIndex === undefined) {
             throw new ThreadNetworkSetupFailedError(`Commissionee did not return network index`);
@@ -1538,7 +1540,7 @@ export class ControllerCommissioningFlow {
 
         await this.#ensureFailsafeTimerFor(Seconds(connectMaxTimeSeconds));
 
-        const connectResult = await this.#invokeCommand(
+        const { networkingStatus, debugText } = await this.#invokeCommand(
             {
                 endpoint: RootEndpointNumber,
                 cluster: NetworkCommissioning.Complete,
@@ -1553,9 +1555,9 @@ export class ControllerCommissioningFlow {
             },
         );
 
-        if (connectResult.networkingStatus !== NetworkCommissioning.NetworkCommissioningStatus.Success) {
+        if (networkingStatus !== NetworkCommissioning.NetworkCommissioningStatus.Success) {
             throw new ThreadNetworkSetupFailedError(
-                `Commissionee failed to connect to Thread network: ${connectResult.debugText}`,
+                `Commissionee failed to connect to Thread network: status=${NetworkCommissioning.NetworkCommissioningStatus[networkingStatus]} (${networkingStatus})${debugText ? ` ${debugText}` : ""}`,
             );
         }
         logger.debug(

package/src/protocol/ExchangeManager.ts

@@ -445,9 +445,8 @@ export class ExchangeManager {
             netInterface.onData((socket, data) => {
                 if (udpInterface && data.byteLength > socket.maxPayloadSize) {
                     logger.warn(
-                        `Ignoring UDP message on channel ${socket.name} with size ${data.byteLength} from ${socket.name}, which is larger than the maximum allowed size of ${socket.maxPayloadSize}.`,
+                        `Received UDP message from ${socket.name} with size ${data.byteLength}, which is larger than the maximum allowed size of ${socket.maxPayloadSize}`,
                     );
-                    return;
                 }
 
                 this.#workers.add(this.#onMessage(socket, data));