@matter/node 0.16.0-alpha.0-20251101-70c8d51d7 → 0.16.0-alpha.0-20251103-b47ffa15b

package/src/behaviors/groups/GroupsServer.ts

@@ -6,6 +6,7 @@
 
 import { GroupKeyManagementServer } from "#behaviors/group-key-management";
 import { IdentifyBehavior } from "#behaviors/identify";
+import { ScenesManagementServer } from "#behaviors/scenes-management";
 import { Groups } from "#clusters/groups";
 import { Endpoint } from "#endpoint/Endpoint.js";
 import { RootEndpoint } from "#endpoints/root";
@@ -164,11 +165,17 @@ export class GroupsServer extends GroupsBase {
         }
 
         try {
+            assertRemoteActor(this.context);
             if (
                 await this.#actOnGroupKeyManagement((fabric, gkm) =>
                     gkm.removeEndpoint(fabric, this.endpoint.number, groupId),
                 )
             ) {
+                if (this.agent.has(ScenesManagementServer)) {
+                    this.agent
+                        .get(ScenesManagementServer)
+                        .removeScenesForGroupOnFabric(this.context.session.associatedFabric.fabricIndex, groupId);
+                }
                 return { status: StatusCode.Success, groupId };
             }
             return { status: StatusCode.NotFound, groupId };
@@ -178,10 +185,15 @@ export class GroupsServer extends GroupsBase {
         }
     }
 
-    // TODO ScenesManagement cluster is also affected by this command
     override async removeAllGroups() {
         try {
+            assertRemoteActor(this.context);
             await this.#actOnGroupKeyManagement((fabric, gkm) => gkm.removeEndpoint(fabric, this.endpoint.number));
+            if (this.agent.has(ScenesManagementServer)) {
+                this.agent
+                    .get(ScenesManagementServer)
+                    .removeScenesForAllGroupsForFabric(this.context.session.associatedFabric.fabricIndex);
+            }
         } catch (error) {
             StatusResponseError.accept(error);
             throw error;

package/src/behaviors/level-control/LevelControlServer.ts

@@ -10,10 +10,11 @@ import { Transitions } from "#behavior/Transitions.js";
 import { ColorControlServer } from "#behaviors/color-control";
 import { GeneralDiagnosticsBehavior } from "#behaviors/general-diagnostics";
 import { OnOffServer } from "#behaviors/on-off";
+import { ScenesManagementServer } from "#behaviors/scenes-management";
 import { GeneralDiagnostics } from "#clusters/general-diagnostics";
 import { LevelControl } from "#clusters/level-control";
 import { Endpoint } from "#endpoint/Endpoint.js";
-import { AsyncObservable, Identity, Logger, MaybePromise, Millis } from "#general";
+import { AsyncObservable, cropValueRange, Identity, Logger, MaybePromise, Millis } from "#general";
 import { ServerNode } from "#node/ServerNode.js";
 import { Val } from "#protocol";
 import { ClusterType, StatusCode, StatusResponseError, TypeFromPartialBitSchema } from "#types";
@@ -105,6 +106,8 @@ export class LevelControlBaseServer extends LevelControlBase {
         if (this.features.onOff && this.agent.has(OnOffServer)) {
             this.initializeOnOff();
         }
+
+        this.agent.maybeGet(ScenesManagementServer)?.implementScenes(this, this.#applySceneValues);
     }
 
     /**
@@ -230,8 +233,9 @@ export class LevelControlBaseServer extends LevelControlBase {
             return;
         }
 
-        this.#assertLevelValue(level);
+        level = cropValueRange(level, this.minLevel, this.maxLevel);
 
+        this.#invalidateScenes();
         return this.moveToLevelLogic(level, transitionTime, false, effectiveOptions);
     }
 
@@ -241,8 +245,9 @@ export class LevelControlBaseServer extends LevelControlBase {
      * To replace this logic, override {@link moveToLevelLogic} whicih also implements {@link moveToLevel}.
      */
     override moveToLevelWithOnOff({ level, transitionTime }: LevelControl.MoveToLevelRequest): MaybePromise {
-        this.#assertLevelValue(level);
+        level = cropValueRange(level, this.minLevel, this.maxLevel);
 
+        this.#invalidateScenes();
         return this.moveToLevelLogic(level, transitionTime, true);
     }
 
@@ -280,9 +285,11 @@ export class LevelControlBaseServer extends LevelControlBase {
 
         let effectiveRate;
         if (effectiveTransitionTime) {
-            effectiveRate = ((level - this.currentLevel) / effectiveTransitionTime) * 10;
+            // Delay the calculation of the effective rate because the coupling to OnOff might change the currentLevel
+            effectiveRate = (currentLevel: number) => ((level - currentLevel) / effectiveTransitionTime) * 10;
         }
 
+        this.#invalidateScenes();
         return this.transition(level, effectiveRate, withOnOff, options);
     }
 
@@ -301,6 +308,7 @@ export class LevelControlBaseServer extends LevelControlBase {
             return;
         }
 
+        this.#invalidateScenes();
         return this.moveLogic(moveMode, rate, false, effectiveOptions);
     }
 
@@ -314,6 +322,7 @@ export class LevelControlBaseServer extends LevelControlBase {
     override moveWithOnOff({ moveMode, rate }: LevelControl.MoveRequest): MaybePromise {
         rate = this.#assertRateValue(rate);
 
+        this.#invalidateScenes();
         return this.moveLogic(moveMode, rate, true);
     }
 
@@ -365,6 +374,8 @@ export class LevelControlBaseServer extends LevelControlBase {
         if (!this.#optionsAllowExecution(effectiveOptions)) {
             return;
         }
+
+        this.#invalidateScenes();
         return this.stepLogic(stepMode, stepSize, transitionTime, false, effectiveOptions);
     }
 
@@ -374,6 +385,7 @@ export class LevelControlBaseServer extends LevelControlBase {
      * To replace default beahavior, override {@link stepLogic} which also implements {@link step}.
      */
     override stepWithOnOff({ stepMode, stepSize, transitionTime }: LevelControl.StepRequest): MaybePromise {
+        this.#invalidateScenes();
         return this.stepLogic(stepMode, stepSize, transitionTime, true);
     }
 
@@ -412,6 +424,7 @@ export class LevelControlBaseServer extends LevelControlBase {
             return;
         }
 
+        this.#invalidateScenes();
         return this.stopLogic(effectiveOptions);
     }
 
@@ -430,17 +443,20 @@ export class LevelControlBaseServer extends LevelControlBase {
      * Change to a designated level.
      *
      * @param targetLevel the new level once transition completes; if omitted transition will stop at min or max value
-     * @param changePerS the move rate; 0 or nullish means transition instantly
+     * @param changePerS the move rate; 0 or nullish means transition instantly; use function to calculate rate based on current level after coupling logics
      * @param withOnOff if true follows rules for On/Off command variants
      * @param options additional options supplied by the client
      */
     protected transition(
         targetLevel?: number,
-        changePerS?: number | null,
+        changePerS?: number | null | ((currentLevel: number) => number),
         withOnOff = false,
         options: TypeFromPartialBitSchema<typeof LevelControl.Options> = {},
     ): MaybePromise {
-        return MaybePromise.then(this.couple(withOnOff, options, targetLevel), () =>
+        return MaybePromise.then(this.couple(withOnOff, options, targetLevel), () => {
+            if (typeof changePerS === "function") {
+                changePerS = changePerS(this.currentLevel);
+            }
             this.internal.transitions?.start({
                 name: "currentLevel",
                 owner: this,
@@ -450,8 +466,8 @@ export class LevelControlBaseServer extends LevelControlBase {
                 onStep() {
                     this.couple(withOnOff, options, targetLevel);
                 },
-            }),
-        );
+            });
+        });
     }
 
     /**
@@ -464,6 +480,8 @@ export class LevelControlBaseServer extends LevelControlBase {
         options: TypeFromPartialBitSchema<typeof LevelControl.Options> = {},
         targetLevel?: number,
     ): MaybePromise {
+        let result: MaybePromise = undefined;
+
         // Couple with On/Off state
         if (this.features.onOff && withOnOff && this.agent.has(OnOffServer)) {
             if (targetLevel === undefined) {
@@ -491,8 +509,18 @@ export class LevelControlBaseServer extends LevelControlBase {
                 if (!onOff.state.onOff) {
                     onOff.state.onOff = true;
 
-                    // Ensure we move to "on" level before initiating any transition
-                    this.handleOnOffChange(true);
+                    if (this.state.onLevel !== null) {
+                        // Ensure we move to "on" level before initiating any transition
+                        result = this.handleOnOffChange(true);
+                        this.internal.blockOnOffCouplingOnce = true; // But block the second call by listener
+                        this.context.transaction.addParticipants({
+                            postCommit: () => {
+                                if (this.internal.blockOnOffCouplingOnce) {
+                                    this.internal.blockOnOffCouplingOnce = false;
+                                }
+                            },
+                        });
+                    }
                 }
             }
         }
@@ -513,6 +541,8 @@ export class LevelControlBaseServer extends LevelControlBase {
                 },
             });
         }
+
+        return result;
     }
 
     /**
@@ -526,9 +556,16 @@ export class LevelControlBaseServer extends LevelControlBase {
      * @param onOff The new onOff state
      */
     protected handleOnOffChange(onOff: boolean): MaybePromise {
+        if (this.internal.blockOnOffCouplingOnce) {
+            this.internal.blockOnOffCouplingOnce = false;
+            return;
+        }
+
         if (!onOff || this.state.onLevel === null) {
             return;
         }
+
+        logger.debug(`OnOff changed to ON, setting level to onLevel value of ${this.state.onLevel}`);
         this.state.currentLevel = this.state.onLevel;
     }
 
@@ -556,21 +593,6 @@ export class LevelControlBaseServer extends LevelControlBase {
         );
     }
 
-    #assertLevelValue(level: number) {
-        if (level < this.minLevel) {
-            throw new StatusResponseError(
-                `The level value of ${level} is invalid. It must be greater or equal to ${this.minLevel}.`,
-                StatusCode.ConstraintError,
-            );
-        }
-        if (level > this.maxLevel) {
-            throw new StatusResponseError(
-                `The level value of ${level} is invalid. It must be less or equal to ${this.maxLevel}.`,
-                StatusCode.ConstraintError,
-            );
-        }
-    }
-
     #getBootReason() {
         const rootEndpoint = this.env.get(ServerNode);
         if (rootEndpoint.behaviors.has(GeneralDiagnosticsBehavior)) {
@@ -578,6 +600,26 @@ export class LevelControlBaseServer extends LevelControlBase {
         }
     }
 
+    /** Apply Scene values when requested from ScenesManagement cluster */
+    #applySceneValues(values: Val.Struct, transitionTime: number): MaybePromise {
+        const level = values.currentLevel;
+        // If no number (including null), or already current level or outside our range, ignore
+        // This is the only supported sceneable attribute in Level Control, so ignore all others for now
+        if (
+            typeof level !== "number" ||
+            this.state.currentLevel === level ||
+            cropValueRange(level, this.minLevel, this.maxLevel) !== level
+        ) {
+            return;
+        }
+        return this.moveToLevelLogic(level, transitionTime / 100, false, { executeIfOff: true });
+    }
+
+    /** Invalidate all stored scenes manually for this endpoint in the Scenesmanagement cluster because SDK behavior. */
+    #invalidateScenes() {
+        this.agent.maybeGet(ScenesManagementServer)?.makeAllFabricSceneInfoEntriesInvalid();
+    }
+
     override async [Symbol.asyncDispose]() {
         if (this.internal.transitions) {
             await this.internal.transitions.close();
@@ -589,10 +631,11 @@ export class LevelControlBaseServer extends LevelControlBase {
 
 export namespace LevelControlBaseServer {
     export class Internal {
-        /**
-         * Transition management.
-         */
+        /** Transition management. */
         transitions?: Transitions<LevelControlBaseServer>;
+
+        /** Internal flag to avoid on/off coupling during transitions */
+        blockOnOffCouplingOnce = false;
     }
 
     export class State extends LevelControlBase.State {

package/src/behaviors/on-off/OnOffServer.ts

@@ -5,10 +5,12 @@
  */
 
 import { GeneralDiagnosticsBehavior } from "#behaviors/general-diagnostics";
+import { ScenesManagementServer } from "#behaviors/scenes-management";
 import { GeneralDiagnostics } from "#clusters/general-diagnostics";
 import { OnOff } from "#clusters/on-off";
 import { MaybePromise, Millis, Time, Timer } from "#general";
 import { ServerNode } from "#node/ServerNode.js";
+import { hasRemoteActor, Val } from "#protocol";
 import { OnOffBehavior } from "./OnOffBehavior.js";
 
 const OnOffLogicBase = OnOffBehavior.with(OnOff.Feature.Lighting);
@@ -41,6 +43,11 @@ export class OnOffBaseServer extends OnOffLogicBase {
                 }
             }
         }
+
+        if (this.agent.has(ScenesManagementServer)) {
+            this.agent.get(ScenesManagementServer).implementScenes(this, this.#applySceneValues);
+            this.reactTo(this.events.onOff$Changed, this.#clearDelayedSceneApplyData);
+        }
     }
 
     override async [Symbol.asyncDispose]() {
@@ -50,6 +57,9 @@ export class OnOffBaseServer extends OnOffLogicBase {
     }
 
     override on(): MaybePromise {
+        if (!this.state.onOff) {
+            this.#invalidateScenes();
+        }
         this.state.onOff = true;
         if (this.features.lighting) {
             this.state.globalSceneControl = true;
@@ -62,7 +72,15 @@ export class OnOffBaseServer extends OnOffLogicBase {
         }
     }
 
+    /** Invalidate all stored scenes manually for this endpoint in the Scenesmanagement cluster because SDK behavior. */
+    #invalidateScenes() {
+        this.agent.maybeGet(ScenesManagementServer)?.makeAllFabricSceneInfoEntriesInvalid();
+    }
+
     override off(): MaybePromise {
+        if (this.state.onOff) {
+            this.#invalidateScenes();
+        }
         this.state.onOff = false;
         if (this.features.lighting) {
             if (this.timedOnTimer.isRunning) {
@@ -91,30 +109,40 @@ export class OnOffBaseServer extends OnOffLogicBase {
     /**
      * Default implementation notes:
      * * This implementation ignores the effect and just calls off().
-     * * Global Scene Control is not supported yet.
      */
     override offWithEffect(): MaybePromise {
         if (this.state.globalSceneControl) {
-            // TODO Store state in global scene
+            if (hasRemoteActor(this.context) && this.context.session.fabric !== undefined) {
+                this.endpoint
+                    .agentFor(this.context)
+                    .maybeGet(ScenesManagementServer)
+                    ?.storeGlobalScene(this.context.session.fabric.fabricIndex);
+            }
             this.state.globalSceneControl = false;
         }
         return this.off();
     }
 
-    /**
-     * Default implementation notes:
-     * * Global Scene Control is not supported yet, so the device is just turned on.
-     */
-    override onWithRecallGlobalScene(): MaybePromise {
+    override async onWithRecallGlobalScene() {
         if (this.state.globalSceneControl) {
             return;
         }
-        // TODO Recall global scene to set onOff accordingly
+        if (
+            hasRemoteActor(this.context) &&
+            this.context.session.fabric !== undefined &&
+            this.agent.has(ScenesManagementServer)
+        ) {
+            await this.endpoint
+                .agentFor(this.context)
+                .maybeGet(ScenesManagementServer)
+                ?.recallGlobalScene(this.context.session.fabric.fabricIndex);
+        }
+
         this.state.globalSceneControl = true;
         if (this.state.onTime === 0) {
             this.state.offWaitTime = 0;
         }
-        return this.on();
+        await this.on();
     }
 
     /**
@@ -177,6 +205,45 @@ export class OnOffBaseServer extends OnOffLogicBase {
         return timer;
     }
 
+    /** Apply Scene values when requested from ScenesManagement cluster */
+    #applySceneValues(values: Val.Struct, transitionTime: number): MaybePromise {
+        this.#clearDelayedSceneApplyData();
+
+        const onOff = values.onOff;
+        // If no number (including null) or outside our range, ignore
+        if (typeof onOff !== "boolean" || this.state.onOff === onOff) {
+            return;
+        }
+
+        if (transitionTime === 0) {
+            this.state.onOff = onOff;
+        } else {
+            this.internal.applyScenePendingOnOff = onOff;
+            this.internal.applySceneDelayTimer = Time.getPeriodicTimer(
+                "delayed scene apply",
+                Millis(transitionTime),
+                this.callback(this.#applyDelayedSceneOnOffValue),
+            ).start();
+        }
+    }
+
+    #clearDelayedSceneApplyData() {
+        if (this.internal.applySceneDelayTimer?.isRunning) {
+            this.internal.applySceneDelayTimer.stop();
+        }
+        this.internal.applySceneDelayTimer = undefined;
+        this.internal.applyScenePendingOnOff = undefined;
+    }
+
+    #applyDelayedSceneOnOffValue() {
+        const onOff = this.internal.applyScenePendingOnOff;
+        this.#clearDelayedSceneApplyData();
+        if (onOff === undefined) {
+            return;
+        }
+        this.state.onOff = onOff;
+    }
+
     #delayedOffTick() {
         let time = (this.state.offWaitTime ?? 0) - 1;
         if (time <= 0) {
@@ -198,6 +265,8 @@ export namespace OnOffBaseServer {
     export class Internal {
         timedOnTimer?: Timer;
         delayedOffTimer?: Timer;
+        applySceneDelayTimer?: Timer;
+        applyScenePendingOnOff?: boolean;
     }
 }