@matter/node 0.15.1 → 0.15.2-alpha.0-20250704-2715344f0

package/src/behavior/state/managed/values/StructManager.ts

@@ -191,14 +191,22 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
             access.authorizeWrite(this[Internal.session], this[Internal.reference].location);
 
             // We allow attribute/field name or id as key.  If name is present id is ignored
-            let storedKey =
-                name in this[Internal.reference].value
-                    ? name
-                    : id !== undefined && id in this[Internal.reference]
-                      ? id
-                      : name;
+            const pk = this[Internal.reference].primaryKey;
+            let key = pk === "id" ? (id ?? name) : name;
+            let storedKey: undefined | number | string;
+            if (key in this[Internal.reference].value) {
+                storedKey = key;
+            } else if (pk === "id") {
+                if (name in this[Internal.reference].value) {
+                    storedKey = name;
+                }
+            } else if (id !== undefined) {
+                if (id in this[Internal.reference].value) {
+                    storedKey = id;
+                }
+            }
 
-            const oldValue = this[Internal.reference].value[storedKey];
+            const oldValue = storedKey === undefined ? undefined : this[Internal.reference].value[storedKey];
 
             const self = this;
 
@@ -213,7 +221,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                         this[Internal.session],
                     );
                     if (name in properties) {
-                        storedKey = name;
+                        key = storedKey = name;
                         target = properties;
                     } else {
                         target = struct;
@@ -228,7 +236,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                 }
 
                 // Modify the value
-                if (fabricScopedList && Array.isArray(value) && Array.isArray(target[storedKey])) {
+                if (fabricScopedList && Array.isArray(value) && Array.isArray(oldValue)) {
                     // In the case of fabric-scoped write to established list we use the managed proxy to perform update
                     // as it will sort through values and only modify those with correct fabricIndex
                     const proxy = self[name] as Val.List;
@@ -238,7 +246,10 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                     proxy.length = value.length;
                 } else {
                     // Direct assignment
-                    target[storedKey] = value;
+                    target[key] = value;
+                    if (storedKey !== undefined && storedKey !== key) {
+                        delete target[storedKey];
+                    }
                 }
 
                 if (!this[Internal.session].acceptInvalid && validate) {
@@ -258,7 +269,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                     } catch (e) {
                         // Undo our change on error.  Rollback will take care of this when transactional but this
                         // handles the cases of 1.) no transaction, and 2.) error is caught within transaction
-                        target[storedKey] = oldValue;
+                        target[key] = oldValue;
 
                         throw e;
                     }
@@ -285,12 +296,17 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                     }
                 }
 
-                const value = struct[name];
-                if (value !== undefined || id === undefined) {
-                    return value;
+                const key = this[Internal.reference].primaryKey === "id" ? (id ?? name) : name;
+                if (key in struct) {
+                    return struct[key];
                 }
 
-                return struct[id];
+                const key2 = this[Internal.reference].primaryKey === "id" ? name : id;
+                if (key2 !== undefined && key2 in struct) {
+                    return struct[key2];
+                }
+
+                return undefined;
             }
         };
     } else {
@@ -321,8 +337,10 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
         descriptor.get = function (this: Struct) {
             let value;
 
-            // Obtain the value.  Normally just struct[name] except in the case of Val.Dynamic
+            // Obtain the value.  Normally just struct[key] except in the case of Val.Dynamic
+            const pk = this[Internal.reference].primaryKey;
             const struct = this[Internal.reference].value;
+            const key = pk === "id" ? (id ?? name) : name;
             if ((struct as Val.Dynamic)[Val.properties]) {
                 const properties = (struct as Val.Dynamic)[Val.properties](
                     this[Internal.reference].rootOwner,
@@ -334,9 +352,13 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
                     value = struct[name];
                 }
             } else {
-                value = struct[name];
-                if (value === undefined && id !== undefined) {
-                    value = struct[id];
+                if (key in struct) {
+                    value = struct[key];
+                } else {
+                    const key2 = pk === "id" ? id : name;
+                    if (key2 !== undefined && key2 in struct) {
+                        value = struct[key2];
+                    }
                 }
             }
 
@@ -372,7 +394,7 @@ function configureProperty(supervisor: RootSupervisor, schema: ValueModel) {
             };
 
             // Clone the container before write
-            const ref = ManagedReference(this[Internal.reference], name, assertWriteOk, cloneContainer);
+            const ref = ManagedReference(this[Internal.reference], pk, name, id, assertWriteOk, cloneContainer);
 
             ref.owner = manage(ref, this[Internal.session]);
 

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

@@ -5,7 +5,9 @@
  */
 
 import { Behavior } from "#behavior/Behavior.js";
-import { ImplementationError, NotImplementedError, ServerAddress, Time } from "#general";
+import { Events as BaseEvents } from "#behavior/Events.js";
+import { OperationalCredentialsClient } from "#behaviors/operational-credentials";
+import { ImplementationError, NotImplementedError, Observable, ServerAddress, Time } from "#general";
 import { DatatypeModel, FieldElement } from "#model";
 import type { ClientNode } from "#node/ClientNode.js";
 import type { Node } from "#node/Node.js";
@@ -20,9 +22,18 @@ import {
     LocatedNodeCommissioningOptions,
     PeerAddress,
     SessionParameters,
+    Subscribe,
 } from "#protocol";
-import { DeviceTypeId, DiscoveryCapabilitiesBitmap, NodeId, TypeFromPartialBitSchema, VendorId } from "#types";
+import {
+    DeviceTypeId,
+    DiscoveryCapabilitiesBitmap,
+    ManualPairingCodeCodec,
+    NodeId,
+    TypeFromPartialBitSchema,
+    VendorId,
+} from "#types";
 import { ControllerBehavior } from "../controller/ControllerBehavior.js";
+import { NetworkClient } from "../network/NetworkClient.js";
 import { RemoteDescriptor } from "./RemoteDescriptor.js";
 
 /**
@@ -32,6 +43,7 @@ import { RemoteDescriptor } from "./RemoteDescriptor.js";
  */
 export class CommissioningClient extends Behavior {
     declare state: CommissioningClient.State;
+    declare events: CommissioningClient.Events;
 
     static override readonly early = true;
 
@@ -47,19 +59,29 @@ export class CommissioningClient extends Behavior {
         }
 
         this.reactTo((this.endpoint as Node).lifecycle.partsReady, this.#initializeNode);
+        this.reactTo(this.events.peerAddress$Changed, this.#peerAddressChanged);
     }
 
     commission(passcode: number): Promise<ClientNode>;
 
     commission(options: CommissioningClient.CommissioningOptions): Promise<ClientNode>;
 
-    async commission(options: number | CommissioningClient.CommissioningOptions) {
-        if (typeof options !== "object") {
+    async commission(options: number | string | CommissioningClient.CommissioningOptions) {
+        // Commissioning can only happen once
+        const node = this.endpoint as ClientNode;
+        if (this.state.peerAddress !== undefined) {
+            throw new ImplementationError(`${node} is already commissioned`);
+        }
+
+        if (typeof options === "number") {
             options = { passcode: options };
+        } else if (typeof options === "string") {
+            options = { pairingCode: options };
         }
+        const opts = CommissioningClient.PasscodeOptions(options) as CommissioningClient.PasscodeOptions;
 
         // Validate passcode
-        let { passcode } = options;
+        let { passcode } = opts;
         if (typeof passcode !== "number" || Number.isNaN(passcode)) {
             passcode = Number.parseInt(passcode as unknown as string);
             if (Number.isNaN(passcode)) {
@@ -67,18 +89,12 @@ export class CommissioningClient extends Behavior {
             }
         }
 
-        // Commissioning can only happen once
-        const node = this.endpoint as ClientNode;
-        if (this.state.peerAddress !== undefined) {
-            throw new ImplementationError(`${node} is already commissioned`);
-        }
-
         // 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);
-        let { fabric } = options;
+        const fabricAuthority = opts.fabricAuthority || this.env.get(FabricAuthority);
+        let { fabric } = opts;
         if (fabric === undefined) {
             if (this.context.fabric === undefined) {
                 fabric = await fabricAuthority.defaultFabric();
@@ -98,10 +114,10 @@ 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 address = identityService.assignNodeAddress(node, fabric.fabricIndex, options.nodeId);
+        const identityService = node.env.get(IdentityService);
+        const address = identityService.assignNodeAddress(node, fabric.fabricIndex, opts.nodeId);
 
         const commissioningOptions: LocatedNodeCommissioningOptions = {
             addresses,
@@ -118,20 +134,50 @@ 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 = opts.startupSubscription;
+
+        node.lifecycle.commissioned.emit(this.context);
+
+        await node.start();
+
         return node;
     }
 
+    /**
+     * Remove this node from the fabric.
+     *
+     * After removal the {@link ClientNode} remains intact.  You can use {@link ClientNode#delete} to remove the node
+     * permanently.
+     *
+     * Only legal if this node controls the peer's fabric.
+     */
+    async decommission() {
+        const { peerAddress } = this.state;
+
+        if (peerAddress === undefined) {
+            throw new ImplementationError("Cannot decommission node that is not commissioned");
+        }
+
+        const opcreds = this.agent.get(OperationalCredentialsClient);
+
+        await opcreds.removeFabric({ fabricIndex: opcreds.state.currentFabricIndex });
+
+        this.state.peerAddress = undefined;
+    }
+
     /**
      * 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();
@@ -150,6 +196,16 @@ export class CommissioningClient extends Behavior {
         endpoint.lifecycle.initialized.emit(this.state.peerAddress !== undefined);
     }
 
+    #peerAddressChanged(addr?: PeerAddress) {
+        const node = this.endpoint as ClientNode;
+
+        if (addr) {
+            node.lifecycle.commissioned.emit(this.context);
+        } else {
+            node.lifecycle.decommissioned.emit(this.context);
+        }
+    }
+
     /**
      * Define logical schema.  This enables runtime validation, make fields persistent and makes subfields editable.
      */
@@ -230,7 +286,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.
@@ -313,22 +369,21 @@ export namespace CommissioningClient {
         longIdleTimeOperatingMode?: boolean;
     }
 
+    export class Events extends BaseEvents {
+        peerAddress$Changed = new Observable<[value: PeerAddress | undefined, oldValue: PeerAddress | undefined]>();
+    }
+
     /**
      * Options that control commissioning.
      */
-    export interface CommissioningOptions {
-        /**
-         * The device's passcode.
-         */
-        passcode: number;
-
+    export interface BaseCommissioningOptions {
         /**
          * The ID to assign the node during commissioning.  By default the node receives the next available ID.
          */
         nodeId?: NodeId;
 
         /**
-         * The fabric the joins upon commissioning.  Defaults to the default fabric of the assigned
+         * The fabric the node joins upon commissioning.  Defaults to the default fabric of the assigned
          * {@link FabricAuthority}.
          */
         fabric?: Fabric;
@@ -344,5 +399,74 @@ 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;
+    }
+
+    export interface PasscodeOptions extends BaseCommissioningOptions {
+        /**
+         * The device's passcode.
+         */
+        passcode: number;
+
+        /**
+         * The device's long discriminator.
+         */
+        discriminator?: number;
+    }
+
+    export interface PairingCodeOptions extends BaseCommissioningOptions {
+        /**
+         * The device's pairing code.
+         */
+        pairingCode: string;
+    }
+
+    export type CommissioningOptions = PasscodeOptions | PairingCodeOptions;
+
+    export function PasscodeOptions<T extends CommissioningOptions>(options: T) {
+        let opts: T & PasscodeOptions;
+
+        if ("pairingCode" in options) {
+            const decoded = ManualPairingCodeCodec.decode(options.pairingCode);
+            opts = {
+                ...options,
+                ...decoded,
+            };
+        } else {
+            opts = options as T & PasscodeOptions;
+        }
+
+        let { passcode } = opts;
+        if (typeof passcode !== "number" || Number.isNaN(passcode)) {
+            passcode = Number.parseInt(passcode as unknown as string);
+            if (Number.isNaN(passcode)) {
+                throw new ImplementationError("You must provide a pairing code or passcode to pair a node");
+            }
+        }
+
+        return opts;
     }
 }

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;
+    }
+}