@matter/node 0.15.1 → 0.15.2-alpha.0-20250703-2e16aba2b

package/src/behavior/system/commissioning/CommissioningClient.ts

@@ -20,9 +20,11 @@ import {
     LocatedNodeCommissioningOptions,
     PeerAddress,
     SessionParameters,
+    Subscribe,
 } from "#protocol";
 import { DeviceTypeId, DiscoveryCapabilitiesBitmap, NodeId, TypeFromPartialBitSchema, VendorId } from "#types";
 import { ControllerBehavior } from "../controller/ControllerBehavior.js";
+import { NetworkClient } from "../network/NetworkClient.js";
 import { RemoteDescriptor } from "./RemoteDescriptor.js";
 
 /**
@@ -74,7 +76,7 @@ export class CommissioningClient extends Behavior {
         }
 
         // Ensure controller is initialized
-        await this.endpoint.owner?.act(agent => agent.load(ControllerBehavior));
+        await node.owner?.act(agent => agent.load(ControllerBehavior));
 
         // Obtain the fabric we will commission into
         const fabricAuthority = options.fabricAuthority || this.env.get(FabricAuthority);
@@ -98,9 +100,9 @@ export class CommissioningClient extends Behavior {
             throw new ImplementationError(`Cannot commission ${node} because the node has not been located`);
         }
 
-        const commissioner = this.endpoint.env.get(ControllerCommissioner);
+        const commissioner = node.env.get(ControllerCommissioner);
 
-        const identityService = this.endpoint.env.get(IdentityService);
+        const identityService = node.env.get(IdentityService);
         const address = identityService.assignNodeAddress(node, fabric.fabricIndex, options.nodeId);
 
         const commissioningOptions: LocatedNodeCommissioningOptions = {
@@ -118,20 +120,28 @@ export class CommissioningClient extends Behavior {
         try {
             await commissioner.commission(commissioningOptions);
             this.state.peerAddress = address;
-        } finally {
-            if (this.state.peerAddress !== address) {
-                identityService.releaseNodeAddress(address);
-            }
+        } catch (e) {
+            identityService.releaseNodeAddress(address);
+            throw e;
         }
 
+        await this.context.transaction.commit();
+
+        const network = this.agent.get(NetworkClient);
+        network.state.startupSubscription = options.startupSubscription;
+
+        node.lifecycle.commissioned.emit(this.context);
+
+        await node.start();
+
         return node;
     }
 
     /**
      * Override to implement CASE commissioning yourself.
      *
-     * If you override, matter.js commissions to the point where over PASE is complete.  You must then complete
-     * commissioning yourself by connecting to the device and invokeint the "CommissioningComplete" command.
+     * If you override, matter.js commissions to the point where commissioning over PASE is complete.  You must then
+     * complete commissioning yourself by connecting to the device and invokeint the "CommissioningComplete" command.
      */
     protected async finalizeCommissioning(_address: PeerAddress, _discoveryData?: DiscoveryData) {
         throw new NotImplementedError();
@@ -230,7 +240,7 @@ export namespace CommissioningClient {
         /**
          * Time at which the device was discovered.
          */
-        discoveredAt: number = Time.nowMs();
+        discoveredAt?: number;
 
         /**
          * Time at which we discovered the device's current operational addresses.
@@ -322,6 +332,11 @@ export namespace CommissioningClient {
          */
         passcode: number;
 
+        /**
+         * The device's long discriminator.
+         */
+        discriminator?: number;
+
         /**
          * The ID to assign the node during commissioning.  By default the node receives the next available ID.
          */
@@ -344,5 +359,29 @@ export namespace CommissioningClient {
          * is supported for initial commissioning.
          */
         discoveryCapabilities?: TypeFromPartialBitSchema<typeof DiscoveryCapabilitiesBitmap>;
+
+        /**
+         * The initial read used to populate node data.
+         *
+         * By default matter.js reads all attributes on the node.  This allows us to efficiently initialize the complete
+         * node structure.
+         *
+         * If you only require a subset of attributes you can replace this with a more discriminative read.  For
+         * example, if you are only interested in interacting with the root endpoint and the On/Off cluster on other
+         * endpoints, you could do:
+         *
+         * ```js
+         * {
+         *     startupSubscription: Read(
+         *         Read.Attribute({ endpoint: 0 }),
+         *         Read.Attribute({ cluster: OnOffCluster })
+         *     )
+         * }
+         * ```
+         *
+         * Note that certain clusters like Descriptor and Basic Information contain critical operational data. If your
+         * read omits them then the node will only be partially functional once initialized.
+         */
+        startupSubscription?: Subscribe | null;
     }
 }

package/src/behavior/system/commissioning/CommissioningServer.ts

@@ -14,13 +14,24 @@ import {
     Lifecycle,
     Logger,
     MatterFlowError,
+    Mutex,
     Observable,
 } from "#general";
 import { DatatypeModel, FieldElement } from "#model";
 import type { Node } from "#node/Node.js";
 import { NodeLifecycle } from "#node/NodeLifecycle.js";
 import type { ServerNode } from "#node/ServerNode.js";
-import { ExposedFabricInformation, FabricAction, FabricManager, FailsafeContext, PaseClient, Val } from "#protocol";
+import {
+    CommissioningConfigProvider,
+    DeviceAdvertiser,
+    DeviceCommissioner,
+    ExposedFabricInformation,
+    FabricAction,
+    FabricManager,
+    FailsafeContext,
+    PaseClient,
+    Val,
+} from "#protocol";
 import {
     CommissioningFlowType,
     CommissioningOptions,
@@ -35,6 +46,7 @@ import { OperationalCredentialsBehavior } from "../../../behaviors/operational-c
 import { Behavior } from "../../Behavior.js";
 import { ActionContext } from "../../context/ActionContext.js";
 import { NetworkServer } from "../network/NetworkServer.js";
+import { ProductDescriptionServer } from "../product-description/ProductDescriptionServer.js";
 import { SessionsBehavior } from "../sessions/SessionsBehavior.js";
 
 const logger = Logger.get("Commissioning");
@@ -54,6 +66,9 @@ export class CommissioningServer extends Behavior {
     static override early = true;
 
     override initialize() {
+        // This provides a name for the mutex error handler
+        this.internal.name = this.toString();
+
         if (this.state.passcode === -1) {
             this.state.passcode = PaseClient.generateRandomPasscode(this.env.get(Crypto));
         } else if (CommissioningOptions.FORBIDDEN_PASSCODES.includes(this.state.passcode)) {
@@ -64,13 +79,28 @@ export class CommissioningServer extends Behavior {
             this.state.discriminator = PaseClient.generateRandomDiscriminator(this.env.get(Crypto));
         }
 
-        this.reactTo((this.endpoint as Node).lifecycle.online, this.#nodeOnline);
-
         this.reactTo((this.endpoint as Node).lifecycle.partsReady, this.#initializeNode);
+
+        // Ensure the environment conveys commissioning configuration to the DeviceCommissioner
+        if (!this.env.has(CommissioningConfigProvider)) {
+            // Configure the DeviceCommissioner
+            this.env.set(
+                CommissioningConfigProvider,
+                new CommissioningServerConfigProvider(this.endpoint as ServerNode),
+            );
+        }
+
+        this.reactTo((this.endpoint as Node).lifecycle.online, this.#enterOnlineMode);
+
+        this.reactTo((this.endpoint as Node).lifecycle.goingOffline, this.#enterOfflineMode);
     }
 
-    override [Symbol.asyncDispose]() {
-        this.internal.unregisterFailsafeListener?.();
+    override async [Symbol.asyncDispose]() {
+        // Ensure dependencies are cleaned up
+        this.#enterOfflineMode();
+
+        // Wait for cleanup to finish
+        await this.internal.mutex;
     }
 
     handleFabricChange(fabricIndex: FabricIndex, fabricAction: FabricAction) {
@@ -166,15 +196,79 @@ export class CommissioningServer extends Behavior {
         failsafe.construction.change.on(listener);
     }
 
+    #enterOnlineMode() {
+        // If already commissioned, trigger operational announcement
+        if ((this.endpoint.lifecycle as NodeLifecycle).isCommissioned) {
+            this.enterOperationalMode();
+            return;
+        }
+
+        // Skip auto commissioning if disabled
+        if (this.state.enabled === false) {
+            return;
+        }
+
+        // ...or if node is commissioned
+        if (this.env.get(FabricManager).fabrics.length) {
+            return;
+        }
+
+        // ...or the node has no advertisable device type
+        if (!this.#hasAdvertisableDeviceType) {
+            return;
+        }
+
+        // Advertise as commissionable
+        this.enterCommissionableMode();
+    }
+
+    #enterOfflineMode() {
+        this.internal.mutex.run(async () => {
+            await this.env.close(DeviceCommissioner);
+            this.env.delete(CommissioningConfigProvider);
+            this.internal.unregisterFailsafeListener?.();
+            await this.env.close(FailsafeContext);
+        });
+    }
+
     /**
-     * The server invokes this method when the node is active but not yet commissioned unless you set
-     * {@link CommissioningServer.State#enabled} to false.
-     *
      * An uncommissioned node is not yet associated with fabrics.  It cannot be used until commissioned by a controller.
      *
+     * The server normally invokes this method when the node starts and is not yet commissioned.  You can disable by
+     * setting {@link CommissioningServer.State#enabled} to false.  Then you must invoke yourself.
+     */
+    enterCommissionableMode() {
+        if (!this.#hasAdvertisableDeviceType) {
+            throw new ImplementationError(
+                `Node ${this.endpoint} has no endpoints with advertisable device types; you must add an endpoint or set the device type`,
+            );
+        }
+
+        // Ensure a device commissioner is loaded
+        //
+        // TODO - DeviceCommissioner/DeviceAdvertiser API is convoluted; refactor to allow directly moving to the
+        // desired mode
+        this.env.get(DeviceCommissioner);
+
+        this.beginAdvertising();
+
+        this.initiateCommissioning();
+    }
+
+    /**
+     * The server invokes this method when the node starts and is already commissioned, or immediately after
+     * commissioning.
+     */
+    protected enterOperationalMode() {
+        this.beginAdvertising();
+    }
+
+    /**
+     * Display instructions on commissioning the device.
+     *
      * The default implementation logs the QR code and credentials.
      */
-    initiateCommissioning() {
+    protected initiateCommissioning() {
         const { passcode, discriminator } = this.state;
 
         const { qrPairingCode, manualPairingCode } = this.state.pairingCodes;
@@ -236,16 +330,31 @@ export class CommissioningServer extends Behavior {
         ],
     });
 
-    #nodeOnline() {
-        if (this.state.enabled && !this.env.get(FabricManager).fabrics.length) {
-            this.initiateCommissioning();
+    /**
+     * Advertise and continue advertising at regular intervals until timeout per Matter specification.  If already
+     * advertising, the advertisement timeout resets.
+     */
+    beginAdvertising() {
+        if (!(this.endpoint.lifecycle as NodeLifecycle).isOnline) {
+            throw new ImplementationError("Cannot advertise offline server");
         }
+
+        this.env
+            .get(DeviceAdvertiser)
+            .startAdvertising()
+            .catch(error => logger.error("Failed to open advertisement window", error));
     }
 
     #initializeNode() {
         this.state.commissioned = !!this.agent.get(OperationalCredentialsBehavior).state.commissionedFabrics;
         (this.endpoint.lifecycle as NodeLifecycle).initialized.emit(this.state.commissioned);
     }
+
+    get #hasAdvertisableDeviceType() {
+        return (
+            this.agent.get(ProductDescriptionServer).state.deviceType !== ProductDescriptionServer.UNKNOWN_DEVICE_TYPE
+        );
+    }
 }
 
 export namespace CommissioningServer {
@@ -256,6 +365,19 @@ export namespace CommissioningServer {
 
     export class Internal {
         unregisterFailsafeListener?: () => void = undefined;
+
+        /**
+         * We use this to synchronize internal state transitions that would otherwise have race conditions due to the
+         * large number of asynchronous calls.
+         */
+        mutex = new Mutex({
+            toString: () => this.name,
+        });
+
+        /**
+         * Passed to the mutex for error handling purposes
+         */
+        name = "?";
     }
 
     export class State {
@@ -295,3 +417,28 @@ export namespace CommissioningServer {
         enabled$Changed = AsyncObservable<[context: ActionContext]>();
     }
 }
+
+/**
+ * Conveys configuration information to {@link DeviceCommissioner}.
+ */
+class CommissioningServerConfigProvider extends CommissioningConfigProvider {
+    #node: ServerNode;
+
+    constructor(node: ServerNode) {
+        super();
+
+        this.#node = node;
+    }
+
+    override get values() {
+        const { commissioning, productDescription, network } = this.#node.state;
+
+        const config = {
+            ...commissioning,
+            productDescription,
+            ble: !!network.ble,
+        };
+
+        return config as CommissioningOptions.Configuration;
+    }
+}

package/src/behavior/system/controller/ControllerBehavior.ts

@@ -6,24 +6,22 @@
 
 import { Behavior } from "#behavior/Behavior.js";
 import { BasicInformationBehavior } from "#behaviors/basic-information";
-import {
-    ImplementationError,
-    isNetworkInterface,
-    Logger,
-    MatterAggregateError,
-    NetInterfaceSet,
-    TransportInterfaceSet,
-} from "#general";
+import { ImplementationError, isNetworkInterface, NetInterfaceSet, TransportInterfaceSet } from "#general";
 import { Node } from "#node/Node.js";
 import { InteractionServer } from "#node/server/InteractionServer.js";
 import {
     Ble,
+    ClientSubscriptionHandler,
+    ClientSubscriptions,
+    Fabric,
     FabricAuthority,
     FabricAuthorityConfigurationProvider,
     FabricManager,
+    MdnsScanner,
+    MdnsScannerTargetCriteria,
     MdnsService,
+    Scanner,
     ScannerSet,
-    SubscriptionClient,
 } from "#protocol";
 import type { CommissioningClient } from "../commissioning/CommissioningClient.js";
 import { CommissioningServer } from "../commissioning/CommissioningServer.js";
@@ -31,8 +29,6 @@ import { NetworkServer } from "../network/NetworkServer.js";
 import { ActiveDiscoveries } from "./discovery/ActiveDiscoveries.js";
 import type { Discovery } from "./discovery/Discovery.js";
 
-const logger = Logger.get("ControllerBehavior");
-
 /**
  * Node controller functionality.
  *
@@ -44,10 +40,11 @@ const logger = Logger.get("ControllerBehavior");
 export class ControllerBehavior extends Behavior {
     static override readonly id = "controller";
 
+    declare internal: ControllerBehavior.Internal;
     declare state: ControllerBehavior.State;
 
     override async initialize() {
-        if (this.state.adminFabricLabel === undefined) {
+        if (this.state.adminFabricLabel === undefined || this.state.adminFabricLabel === "") {
             throw new ImplementationError("adminFabricLabel must be set for ControllerBehavior.");
         }
         const adminFabricLabel = this.state.adminFabricLabel;
@@ -84,12 +81,15 @@ export class ControllerBehavior extends Behavior {
             );
         }
 
+        // Ensure the fabric authority is fully initialized
+        await this.env.load(FabricAuthority);
+
         // "Automatic" controller mode - disable commissioning if node is not otherwise configured as a commissionable
         // device
         const commissioning = this.agent.get(CommissioningServer);
         if (commissioning.state.enabled === undefined) {
-            const controlledFabrics = this.env.get(FabricAuthority).fabrics.length;
             const totalFabrics = this.env.get(FabricManager).length;
+            const controlledFabrics = this.env.get(FabricAuthority).fabrics.length;
             if (controlledFabrics === totalFabrics) {
                 commissioning.state.enabled = false;
             }
@@ -103,17 +103,7 @@ export class ControllerBehavior extends Behavior {
     }
 
     override async [Symbol.asyncDispose]() {
-        const discoveries = this.env.get(ActiveDiscoveries);
-        while (discoveries.size) {
-            for (const discovery of discoveries) {
-                discovery.cancel();
-            }
-
-            await MatterAggregateError.allSettled([...discoveries], "Error while cancelling discoveries").catch(error =>
-                logger.error(error),
-            );
-        }
-
+        await this.env.close(ActiveDiscoveries);
         this.env.delete(FabricAuthority);
         this.env.delete(ScannerSet);
     }
@@ -131,15 +121,33 @@ export class ControllerBehavior extends Behavior {
             netInterfaces.add(Ble.get().getBleCentralInterface());
         }
 
-        // This is necessary to receive data reports for subscriptions
-        this.env.get(InteractionServer).clientHandler = this.env.get(SubscriptionClient);
+        // Install handler to receive data reports for subscriptions
+        const subscriptions = this.env.get(ClientSubscriptions);
+        const interactionServer = this.env.get(InteractionServer);
+        interactionServer.clientHandler = new ClientSubscriptionHandler(subscriptions);
 
         // Clean up as the node goes offline
         const node = Node.forEndpoint(this.endpoint);
         this.reactTo(node.lifecycle.goingOffline, this.#nodeGoingOffline);
+
+        // Add each pre-existing fabric to discovery criteria
+        const authority = this.env.get(FabricAuthority);
+        for (const fabric of authority.fabrics) {
+            this.#enableScanningForFabric(fabric);
+        }
+        this.reactTo(authority.fabricAdded, this.#enableScanningForFabric);
+
+        // Configure each MDNS scanner with criteria
+        const scanners = this.env.get(ScannerSet);
+        for (const scanner of scanners) {
+            this.#enableScanningForScanner(scanner);
+        }
+        this.reactTo(scanners.added, this.#enableScanningForScanner);
     }
 
     async #nodeGoingOffline() {
+        await this.env.close(ClientSubscriptions);
+
         const netInterfaces = this.env.get(NetInterfaceSet);
         const netTransports = this.env.get(TransportInterfaceSet);
 
@@ -152,9 +160,30 @@ export class ControllerBehavior extends Behavior {
 
         await this.env.close(NetInterfaceSet);
     }
+
+    #enableScanningForFabric(fabric: Fabric) {
+        this.internal.mdnsTargetCriteria.operationalTargets.push({ operationalId: fabric.operationalId });
+    }
+
+    #enableScanningForScanner(scanner: Scanner) {
+        if (!(scanner instanceof MdnsScanner)) {
+            return;
+        }
+        scanner.targetCriteriaProviders.add(this.internal.mdnsTargetCriteria);
+    }
 }
 
 export namespace ControllerBehavior {
+    export class Internal {
+        /**
+         * MDNS scanner criteria for each controlled fabric (keyed by operational ID).
+         */
+        mdnsTargetCriteria: MdnsScannerTargetCriteria = {
+            commissionable: true,
+            operationalTargets: [],
+        };
+    }
+
     export class State {
         /**
          * Set to false to disable scanning on BLE.
@@ -173,6 +202,6 @@ export namespace ControllerBehavior {
         /**
          * Contains the label of the admin fabric which is set for all commissioned devices
          */
-        adminFabricLabel!: string;
+        adminFabricLabel = "matter.js";
     }
 }

package/src/behavior/system/controller/discovery/ActiveDiscoveries.ts

@@ -5,15 +5,64 @@
  */
 
 import { Environment, Environmental } from "#general";
+import { MdnsScanner, MdnsScannerTargetCriteria, Scanner, ScannerSet } from "#protocol";
 import type { Discovery } from "./Discovery.js";
 
 /**
  * Ongoing node discoveries registered with the environment.
  */
 export class ActiveDiscoveries extends Set<Discovery<any>> {
+    #env: Environment;
+    #mdnsTargetCriteria?: MdnsScannerTargetCriteria;
+
+    constructor(env: Environment) {
+        super();
+
+        this.#env = env;
+
+        this.#activateCommissionableScanning();
+        env.get(ScannerSet).added.on(this.#activateCommissionableScanningFor.bind(this));
+    }
+
     static [Environmental.create](env: Environment) {
-        const instance = new ActiveDiscoveries();
+        const instance = new ActiveDiscoveries(env);
         env.set(ActiveDiscoveries, instance);
         return instance;
     }
+
+    async close() {
+        this.#env.delete(ActiveDiscoveries, this);
+
+        this.#deactivateCommissionableScanning();
+    }
+
+    #activateCommissionableScanning() {
+        const scanners = this.#env.get(ScannerSet);
+        for (const scanner of scanners) {
+            this.#activateCommissionableScanningFor(scanner);
+        }
+    }
+
+    #activateCommissionableScanningFor(scanner: Scanner) {
+        if (!(scanner instanceof MdnsScanner)) {
+            return;
+        }
+
+        if (this.#mdnsTargetCriteria === undefined) {
+            this.#mdnsTargetCriteria = { commissionable: true, operationalTargets: [] };
+        }
+        scanner.targetCriteriaProviders.add(this.#mdnsTargetCriteria);
+    }
+
+    #deactivateCommissionableScanning() {
+        if (!this.#mdnsTargetCriteria) {
+            return;
+        }
+        const scanners = this.#env.get(ScannerSet);
+        for (const scanner of scanners) {
+            if (scanner instanceof MdnsScanner) {
+                scanner.targetCriteriaProviders.delete(this.#mdnsTargetCriteria);
+            }
+        }
+    }
 }

package/src/behavior/system/controller/discovery/CommissioningDiscovery.ts

@@ -16,7 +16,13 @@ export class CommissioningDiscovery extends InstanceDiscovery {
     #options: CommissioningDiscovery.Options;
 
     constructor(owner: ServerNode, options: CommissioningDiscovery.Options) {
+        const { discriminator } = options;
+        if (discriminator !== undefined) {
+            options = { ...options, longDiscriminator: discriminator };
+        }
+
         super(owner, options);
+
         this.#options = options;
     }