@matter/examples 0.13.0-alpha.0-20250413-d5a27700d → 0.13.0-alpha.0-20250418-8cfc0b832

package/src/device-robotic-vacuum-cleaner/RvcDeviceLogic.ts

@@ -0,0 +1,421 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { Behavior, Logger, Node, Time, Timer } from "@matter/main";
+import { ServiceAreaServer } from "@matter/main/behaviors/service-area";
+import { RvcOperationalState } from "@matter/main/clusters/rvc-operational-state";
+import { CustomRvcCleanModeServer } from "./behaviors/CustomRvcCleanModeServer.js";
+import { CustomRvcOperationalStateServer } from "./behaviors/CustomRvcOperationalStateServer.js";
+import { CustomRvcRunModeServer } from "./behaviors/CustomRvcRunModeServer.js";
+
+const logger = Logger.get("RvcDeviceLogic");
+
+/** Define the effective run modes for our robotic vacuum cleaner */
+export enum RvcDeviceRunModes {
+    /** Do nothing, wait for user action. */
+    Idle = 0,
+
+    /** Cleans every 3h for 3 cycles of 10 minutes with 3 minutes recharging in between. */
+    AutoCleaning = 1,
+
+    /** Cleans once for 10 minutes, recharge afterward, then switch to Idle. */
+    QuickCleaning = 2,
+
+    /** Does one mapping round of 10 minutes and recharges afterward, then switch to AutoCleaning mode. */
+    Mapping = 3,
+}
+
+export enum RvcDeviceCleanMode {
+    Vacuuming = 0,
+    Mopping = 1,
+}
+
+export enum CleaningAreas {
+    Kitchen = 0,
+    LivingRoom = 1,
+    Bedroom = 2,
+    Bathroom = 3,
+}
+
+/**
+ * Defines the desired operational states of the device.
+ */
+enum DesiredOperationalDeviceState {
+    Idle = 0,
+    Paused = 1,
+    Working = 2,
+}
+
+enum DetailOperationalDeviceState {
+    SeekingCharger = 0,
+    Docked = 1,
+    Charging = 2,
+    Cleaning = 3,
+    Mapping = 4,
+}
+
+// We simulate cleaning rounds of 10 minutes
+const CLEANING_MAPPING_ROUND_TIME = 10 * 60_000;
+
+/**
+ * This class implements the Logic of our fictional robotic vacuum cleaner device and should demonstrate how the
+ * different clusters work together and how their data depend on each other.
+ * It is added as a custom Behavior to the device and can so easily access the other behaviors and clusters.
+ */
+export class RvcDeviceLogic extends Behavior {
+    static override readonly id = "rvcDeviceLogic";
+    static override readonly early = true;
+
+    declare internal: RvcDeviceLogic.Internal;
+
+    override async initialize() {
+        // Delay setting up all the listeners to make sure we have a clean state
+        this.reactTo((this.endpoint as Node).lifecycle.partsReady, this.#initializeNode);
+
+        // Timers to simulate a device state machine
+        this.internal.cleaningTimer = Time.getTimer("CleaningTimer", CLEANING_MAPPING_ROUND_TIME, () =>
+            this.#handleCleaningDone(),
+        );
+        this.internal.mappingTimer = Time.getTimer("MappingTimer", CLEANING_MAPPING_ROUND_TIME, () =>
+            this.#handleMappingDone(),
+        );
+        this.internal.rechargingTimer = Time.getTimer("RechargingTimer", 2 * 60_000, () => this.#handleRechargeDone());
+        this.internal.autoWaitTimer = Time.getTimer("AutoWaitTimer", 180 * 60_000, () => this.#handleAutoWaitDone());
+        this.internal.seekingChargerTimer = Time.getTimer("SeekingChargerTimer", 30_000, () => this.#handleDocking());
+    }
+
+    async #initializeNode() {
+        // React to actions from the controller when changing the run mode or triggering a pause, resume or go home commands.
+        // `this.agent.load()` ensures that the behavior is initialized and ready to use.
+        const runMode = await this.agent.load(CustomRvcRunModeServer);
+        this.reactTo(runMode.events.currentMode$Changed, this.#handleRvcModeChange, {
+            offline: true,
+        });
+
+        // React to command calls from the controller when changing the operational state.
+        const operationalState = await this.agent.load(CustomRvcOperationalStateServer);
+        this.reactTo(operationalState.events.pauseTriggered, this.#handlePause);
+        this.reactTo(operationalState.events.resumeTriggered, this.#handleResume);
+        this.reactTo(operationalState.events.goHomeTriggered, this.#handleGoHome);
+
+        // React to the service area changes from the controller.
+        const serviceArea = await this.agent.load(ServiceAreaServer);
+        this.reactTo(serviceArea.events.selectedAreas$Changed, this.#selectedAreasChange);
+    }
+
+    /**
+     * When the run mode is changed, start the relevant timers based on the mode and clean mode
+     */
+    async #handleRvcModeChange(newMode: RvcDeviceRunModes, oldMode: RvcDeviceRunModes) {
+        logger.info(`RVC mode changed from ${RvcDeviceRunModes[oldMode]} to ${RvcDeviceRunModes[newMode]}`);
+        this.internal.runMode = newMode;
+        switch (newMode) {
+            case RvcDeviceRunModes.Idle:
+                await this.#returnToIdleMode();
+                break;
+            case RvcDeviceRunModes.AutoCleaning:
+            case RvcDeviceRunModes.QuickCleaning:
+                await this.#startCleaningMode(newMode);
+                break;
+            case RvcDeviceRunModes.Mapping:
+                await this.#startMappingMode();
+        }
+    }
+
+    /**
+     * Returns the device to idle mode by switching the desired operational state to idle.
+     * This means that also after recharging nothing happens.
+     * This stops all timers and sets the device to seeking charger mode if it is cleaning or mapping.
+     */
+    async #returnToIdleMode() {
+        this.internal.autoWaitTimer.stop();
+        this.internal.mappingTimer.stop();
+        this.internal.cleaningTimer.stop();
+        await this.endpoint.setStateOf(ServiceAreaServer, {
+            currentArea: null,
+        });
+        this.internal.cleaningRoundsLeft = 0;
+        this.internal.desiredOperationalState = DesiredOperationalDeviceState.Idle;
+        if (
+            this.internal.detailOperationalState === DetailOperationalDeviceState.Cleaning ||
+            this.internal.detailOperationalState === DetailOperationalDeviceState.Mapping
+        ) {
+            logger.info(
+                `Switching to Idle mode. Cancelling ${DetailOperationalDeviceState[this.internal.detailOperationalState]} and returning to dock now ...`,
+            );
+            this.internal.detailOperationalState = DetailOperationalDeviceState.SeekingCharger;
+            await this.endpoint.setStateOf(CustomRvcOperationalStateServer, {
+                operationalState: RvcOperationalState.OperationalState.SeekingCharger,
+            });
+            this.internal.seekingChargerTimer.start();
+        } else {
+            logger.info("Switch to Idle mode");
+        }
+    }
+
+    /**
+     * Starts the cleaning mode.
+     * If the device is not docked, it will wait until it is docked to start cleaning.
+     * If the cleaning ist started in AutoCleaning mode, it will do three rounds of cleaning, in QuickCleaning mode
+     * just one round. If action was paused it will continue with the planned rounds.
+     */
+    async #startCleaningMode(mode: RvcDeviceRunModes) {
+        this.internal.desiredOperationalState = DesiredOperationalDeviceState.Working;
+        if (
+            this.internal.detailOperationalState === DetailOperationalDeviceState.Docked ||
+            this.internal.detailOperationalState === DetailOperationalDeviceState.Cleaning ||
+            this.internal.detailOperationalState === DetailOperationalDeviceState.Mapping
+        ) {
+            this.internal.detailOperationalState = DetailOperationalDeviceState.Cleaning;
+            await this.endpoint.setStateOf(CustomRvcOperationalStateServer, {
+                operationalState: RvcOperationalState.OperationalState.Running,
+            });
+            if (this.internal.cleaningRoundsLeft === 0) {
+                this.internal.cleaningRoundsLeft = mode === RvcDeviceRunModes.AutoCleaning ? 3 : 1;
+            }
+            this.internal.cleaningTimer.start();
+            await this.#startServiceAreaChange();
+            const cleanMode = this.endpoint.stateOf(CustomRvcCleanModeServer).currentMode;
+            logger.info(
+                `Starting ${RvcDeviceCleanMode[cleanMode]} ${RvcDeviceRunModes[mode]} (${this.internal.cleaningRoundsLeft} round(s)) ...`,
+            );
+        } else {
+            logger.info(
+                `Delayed start of cleaning with mode ${RvcDeviceRunModes[mode]} until docked (currently ${DetailOperationalDeviceState[this.internal.detailOperationalState]})`,
+            );
+        }
+    }
+
+    /**
+     * Starts the mapping mode.
+     * If the device is not docked, it will wait until it is docked to start mapping.
+     */
+    async #startMappingMode() {
+        this.internal.desiredOperationalState = DesiredOperationalDeviceState.Working;
+        if (this.internal.detailOperationalState === DetailOperationalDeviceState.Docked) {
+            this.internal.detailOperationalState = DetailOperationalDeviceState.Mapping;
+            await this.endpoint.setStateOf(CustomRvcOperationalStateServer, {
+                operationalState: RvcOperationalState.OperationalState.Running,
+            });
+            this.internal.mappingTimer.start();
+            await this.#startServiceAreaChange();
+            logger.info(`Starting mapping ...`);
+        } else {
+            logger.info(
+                `Delayed start of mapping until docked (currently ${DetailOperationalDeviceState[this.internal.detailOperationalState]})`,
+            );
+        }
+    }
+
+    /** Handles a Pause command and pauses the current action, but remembers the current mode. */
+    async #handlePause() {
+        if (this.internal.desiredOperationalState === DesiredOperationalDeviceState.Working) {
+            const cleanMode = this.endpoint.stateOf(CustomRvcCleanModeServer).currentMode;
+            logger.info(
+                `Pausing current action ${RvcDeviceCleanMode[cleanMode]} ${RvcDeviceRunModes[this.internal.runMode]}...`,
+            );
+            this.internal.desiredOperationalState = DesiredOperationalDeviceState.Paused;
+            await this.endpoint.setStateOf(CustomRvcOperationalStateServer, {
+                operationalState: RvcOperationalState.OperationalState.Paused,
+            });
+            this.internal.mappingTimer.stop();
+            this.internal.cleaningTimer.stop();
+        }
+    }
+
+    /** Handles a Resume command and resumes the current action in the previous mode. */
+    async #handleResume() {
+        if (this.internal.desiredOperationalState === DesiredOperationalDeviceState.Paused) {
+            const cleanMode = this.endpoint.stateOf(CustomRvcCleanModeServer).currentMode;
+            logger.info(
+                `Resuming current action ${RvcDeviceCleanMode[cleanMode]} ${RvcDeviceRunModes[this.internal.runMode]}...`,
+            );
+            this.internal.desiredOperationalState = DesiredOperationalDeviceState.Working;
+            await this.endpoint.setStateOf(CustomRvcOperationalStateServer, {
+                operationalState: RvcOperationalState.OperationalState.Running,
+            });
+            switch (this.internal.runMode) {
+                case RvcDeviceRunModes.AutoCleaning:
+                case RvcDeviceRunModes.QuickCleaning:
+                    await this.#startCleaningMode(this.internal.runMode);
+                    break;
+                case RvcDeviceRunModes.Mapping:
+                    await this.#startMappingMode();
+                    break;
+            }
+        }
+    }
+
+    /** Handles a GoHome command and returns the device to the dock and cancels all activities. */
+    async #handleGoHome() {
+        if (this.internal.desiredOperationalState !== DesiredOperationalDeviceState.Idle) {
+            this.internal.cleaningRoundsLeft = 0;
+            this.internal.desiredOperationalState = DesiredOperationalDeviceState.Idle;
+            if (
+                this.internal.detailOperationalState === DetailOperationalDeviceState.Cleaning ||
+                this.internal.detailOperationalState === DetailOperationalDeviceState.Mapping
+            ) {
+                this.internal.cleaningTimer.stop();
+                this.internal.mappingTimer.stop();
+                await this.endpoint.setStateOf(ServiceAreaServer, {
+                    currentArea: null,
+                });
+                const cleanMode = this.endpoint.stateOf(CustomRvcCleanModeServer).currentMode;
+                logger.info(
+                    `Returning to dock from ${RvcDeviceCleanMode[cleanMode]} ${DetailOperationalDeviceState[this.internal.detailOperationalState]} ...`,
+                );
+                await this.endpoint.setStateOf(CustomRvcOperationalStateServer, {
+                    operationalState: RvcOperationalState.OperationalState.SeekingCharger,
+                });
+                this.internal.seekingChargerTimer.start();
+            }
+        }
+    }
+
+    /** Handles the end of one cleaning round and sends the device back to the charging station. */
+    async #handleCleaningDone() {
+        this.internal.cleaningRoundsLeft--;
+        logger.info(
+            `Cleaning run done. ${this.internal.cleaningRoundsLeft} rounds left. Returning to dock for recharge...`,
+        );
+        await this.endpoint.setStateOf(CustomRvcOperationalStateServer, {
+            operationalState: RvcOperationalState.OperationalState.SeekingCharger,
+        });
+        this.internal.seekingChargerTimer.start();
+    }
+
+    /** Handles the end of one mapping round and sends the device back to the charging station. */
+    async #handleMappingDone() {
+        logger.info(
+            `Mapping run done. ${this.internal.cleaningRoundsLeft} rounds left. Returning to dock for recharge...`,
+        );
+        await this.endpoint.setStateOf(CustomRvcOperationalStateServer, {
+            operationalState: RvcOperationalState.OperationalState.SeekingCharger,
+        });
+        this.internal.seekingChargerTimer.start();
+    }
+
+    /** handles the return of the device to the charger and starts the charging cycle. */
+    async #handleDocking() {
+        logger.info(
+            `Docked successfully. Recharging now ... ${this.internal.cleaningRoundsLeft} cleaning rounds left.`,
+        );
+        this.internal.detailOperationalState = DetailOperationalDeviceState.Charging;
+        await this.endpoint.setStateOf(CustomRvcOperationalStateServer, {
+            operationalState: RvcOperationalState.OperationalState.Charging,
+        });
+        this.internal.rechargingTimer.start();
+        if (this.internal.cleaningRoundsLeft === 0) {
+            logger.info("Current actions done, switch to Idle Mode ...");
+            this.internal.desiredOperationalState = DesiredOperationalDeviceState.Idle;
+            await this.endpoint.setStateOf(CustomRvcRunModeServer, {
+                currentMode: RvcDeviceRunModes.Idle,
+            });
+        }
+    }
+
+    /** Handles the end of the recharging cycle and starts the next cleaning round or goes to idle mode. */
+    async #handleRechargeDone() {
+        if (this.internal.desiredOperationalState === DesiredOperationalDeviceState.Working) {
+            if (this.internal.cleaningRoundsLeft > 0) {
+                const cleanMode = this.endpoint.stateOf(CustomRvcCleanModeServer).currentMode;
+                logger.info(
+                    `Recharging done. Executing next ${RvcDeviceCleanMode[cleanMode]} ${DetailOperationalDeviceState[this.internal.detailOperationalState]} round ...`,
+                );
+                await this.#startCleaningMode(this.internal.runMode);
+                return;
+            } else if (this.internal.runMode === RvcDeviceRunModes.AutoCleaning) {
+                this.internal.autoWaitTimer.start();
+                logger.info(`Recharging done. Waiting for next cleaning round in Auto mode ...`);
+            } else {
+                logger.info(`Recharging done. Switching to Idle mode ...`);
+                this.internal.desiredOperationalState = DesiredOperationalDeviceState.Idle;
+                await this.endpoint.setStateOf(CustomRvcRunModeServer, {
+                    currentMode: RvcDeviceRunModes.Idle,
+                });
+            }
+        } else {
+            logger.info(`Recharging done. Switching to Idle mode ...`);
+        }
+        this.internal.detailOperationalState = DetailOperationalDeviceState.Docked;
+        await this.endpoint.setStateOf(CustomRvcOperationalStateServer, {
+            operationalState: RvcOperationalState.OperationalState.Docked,
+        });
+    }
+
+    /** Handles passing the time of the Auto Clean waiting time and starts a new cleaning round. */
+    async #handleAutoWaitDone() {
+        logger.info(`Auto wait done. Starting next cleaning round ...`);
+        await this.#startCleaningMode(this.internal.runMode);
+    }
+
+    /** Logs changed elected areas. */
+    #selectedAreasChange(newAreas: number[]) {
+        logger.info(
+            "Selected areas changed to",
+            newAreas.map(area => CleaningAreas[area]),
+        );
+    }
+
+    /** Initialize the service area change timer to change the current area while cleaning or mapping. */
+    async #startServiceAreaChange() {
+        this.internal.serviceAreaChangeTimer?.stop();
+
+        const selectedAreas = this.endpoint.stateOf(ServiceAreaServer).selectedAreas;
+        const numberOfAreas = selectedAreas.length || this.endpoint.stateOf(ServiceAreaServer).supportedAreas.length;
+
+        this.internal.serviceAreaChangeTimer = Time.getPeriodicTimer(
+            "ServiceAreaChangeTimer",
+            CLEANING_MAPPING_ROUND_TIME / numberOfAreas + 1000, // Two Areas by default
+            () => this.#changeCurrentServiceArea(),
+        ).start();
+        await this.#changeCurrentServiceArea();
+    }
+
+    /**
+     * During Cleaning otr Mapping we simulate that we also work through the selected areas, so we need to change the
+     * current area.
+     */
+    async #changeCurrentServiceArea() {
+        const serviceAreaState = this.endpoint.stateOf(ServiceAreaServer);
+        const selectedAreas = serviceAreaState.selectedAreas.length
+            ? serviceAreaState.selectedAreas
+            : serviceAreaState.supportedAreas;
+        const currentArea = serviceAreaState.currentArea ?? 0;
+        const nextArea = (currentArea + 1) % selectedAreas.length;
+        await this.endpoint.setStateOf(ServiceAreaServer, {
+            currentArea: nextArea,
+        });
+        logger.info(`Changed service area to ${CleaningAreas[nextArea]}`);
+    }
+
+    /** When the Endpoint is closed stop all timer. */
+    override async [Symbol.asyncDispose]() {
+        this.internal.cleaningTimer.stop();
+        this.internal.mappingTimer.stop();
+        this.internal.rechargingTimer.stop();
+        this.internal.autoWaitTimer.stop();
+        this.internal.seekingChargerTimer.stop();
+        this.internal.serviceAreaChangeTimer?.stop();
+
+        await super[Symbol.asyncDispose]?.();
+    }
+}
+
+/** Internal state of the RvcDeviceLogic behavior to store all the timers and such. */
+export namespace RvcDeviceLogic {
+    export class Internal {
+        desiredOperationalState: DesiredOperationalDeviceState = DesiredOperationalDeviceState.Idle;
+        detailOperationalState: DetailOperationalDeviceState = DetailOperationalDeviceState.Docked;
+        runMode: RvcDeviceRunModes = RvcDeviceRunModes.Idle;
+        cleaningTimer!: Timer;
+        mappingTimer!: Timer;
+        serviceAreaChangeTimer!: Timer;
+        rechargingTimer!: Timer;
+        autoWaitTimer!: Timer;
+        seekingChargerTimer!: Timer;
+        cleaningRoundsLeft: number = 0;
+    }
+}

package/src/device-robotic-vacuum-cleaner/behaviors/CustomRvcCleanModeServer.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ModeUtils } from "@matter/main/behaviors/mode-base";
+import { RvcCleanModeServer } from "@matter/main/behaviors/rvc-clean-mode";
+import { ModeBase } from "@matter/main/clusters/mode-base";
+import { RvcOperationalState } from "@matter/main/clusters/rvc-operational-state";
+import { CustomRvcOperationalStateServer } from "./CustomRvcOperationalStateServer.js";
+
+/**
+ * Custom implementation of the RvcCleanModeServer behavior.
+ * This special class only prevents changing the clean mode when the device is in the running state.
+ * That demonstrates how to handle such cases and is completely fiktional.
+ */
+export class CustomRvcCleanModeServer extends RvcCleanModeServer {
+    override initialize() {
+        super.initialize();
+    }
+
+    /** Change more implementation. We do not call super.changeToMode() here because we want to add own validations. */
+    override changeToMode({ newMode }: ModeBase.ChangeToModeRequest): ModeBase.ChangeToModeResponse {
+        const result = ModeUtils.assertModeChange(this.state.supportedModes, this.state.currentMode, newMode);
+        if (result.status !== ModeBase.ModeChangeStatus.Success) {
+            return result;
+        }
+        const state = this.endpoint.stateOf(CustomRvcOperationalStateServer).operationalState;
+        if (state === RvcOperationalState.OperationalState.Running) {
+            return {
+                status: ModeBase.ModeChangeStatus.InvalidInMode,
+                statusText: "Can not switch operative modes while device is operating.",
+            };
+        }
+        this.state.currentMode = newMode; // Update the new mode, needed because we do not use super.changeToMode()
+        return result;
+    }
+}

package/src/device-robotic-vacuum-cleaner/behaviors/CustomRvcOperationalStateServer.ts

@@ -0,0 +1,79 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+import { AsyncObservable } from "@matter/main";
+import { OperationalStateUtils } from "@matter/main/behaviors/operational-state";
+import { RvcOperationalStateServer } from "@matter/main/behaviors/rvc-operational-state";
+import { OperationalState } from "@matter/main/clusters/operational-state";
+import { RvcOperationalState } from "@matter/main/clusters/rvc-operational-state";
+
+/**
+ * This is a custom implementation of {@link RvcOperationalStateServer} that implements the needed methods goHome,
+ * pause and resume, that are optional and so can not be implemented in the base class.
+ * It also, adds custom events to the server that can be used by the device logic to more easily react on the needed
+ * actions.
+ */
+export class CustomRvcOperationalStateServer extends RvcOperationalStateServer {
+    declare events: CustomRvcOperationalStateServer.Events;
+
+    override async goHome(): Promise<RvcOperationalState.OperationalCommandResponse> {
+        const result = OperationalStateUtils.assertRvcGoHome(this.state.operationalState);
+        if (
+            result.commandResponseState.errorStateId === OperationalState.ErrorState.NoError &&
+            this.state.operationalState !== RvcOperationalState.OperationalState.SeekingCharger
+        ) {
+            await this.events.goHomeTriggered.emit();
+        }
+        return result;
+    }
+
+    override async pause(): Promise<RvcOperationalState.OperationalCommandResponse> {
+        const result = OperationalStateUtils.assertPause(this.state.operationalState);
+        if (
+            result.commandResponseState.errorStateId === OperationalState.ErrorState.NoError &&
+            this.state.operationalState !== RvcOperationalState.OperationalState.Paused
+        ) {
+            if (
+                this.state.operationalState === RvcOperationalState.OperationalState.Charging ||
+                this.state.operationalState === RvcOperationalState.OperationalState.Docked
+            ) {
+                return {
+                    commandResponseState: {
+                        errorStateId: OperationalState.ErrorState.CommandInvalidInState,
+                    },
+                };
+            }
+            await this.events.pauseTriggered.emit();
+        }
+        return result;
+    }
+
+    override async resume(): Promise<RvcOperationalState.OperationalCommandResponse> {
+        const result = OperationalStateUtils.assertResume(this.state.operationalState);
+        if (
+            result.commandResponseState.errorStateId === OperationalState.ErrorState.NoError &&
+            this.state.operationalState !== RvcOperationalState.OperationalState.Paused
+        ) {
+            if (this.state.operationalState === RvcOperationalState.OperationalState.SeekingCharger) {
+                return {
+                    commandResponseState: {
+                        errorStateId: OperationalState.ErrorState.CommandInvalidInState,
+                    },
+                };
+            }
+        } else {
+            await this.events.resumeTriggered.emit();
+        }
+        return result;
+    }
+}
+
+export namespace CustomRvcOperationalStateServer {
+    export class Events extends RvcOperationalStateServer.Events {
+        resumeTriggered = AsyncObservable();
+        pauseTriggered = AsyncObservable();
+        goHomeTriggered = AsyncObservable();
+    }
+}

package/src/device-robotic-vacuum-cleaner/behaviors/CustomRvcRunModeServer.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { ModeUtils } from "@matter/main/behaviors/mode-base";
+import { RvcRunModeServer } from "@matter/main/behaviors/rvc-run-mode";
+import { ModeBase } from "@matter/main/clusters/mode-base";
+import { RvcDeviceRunModes } from "../RvcDeviceLogic.js";
+
+/**
+ * This is a custom implementation of {@link RvcRunModeServer} that makes sure that the Run Mode can not be changed
+ * when the device is not in the Idle mode. SO a change from Mapping to Cleaning or such is not allowed without being
+ * Idle in between which mainly means that the current operation was stopped.
+ * Additionally, the run mode is set to Idle on start of the device to make sure potentially old states sre reset.
+ */
+export class CustomRvcRunModeServer extends RvcRunModeServer {
+    override initialize() {
+        super.initialize();
+        this.state.currentMode = RvcDeviceRunModes.Idle; // Always start in Idle mode
+    }
+
+    /** Change more implementation. We do not call super.changeToMode() here because we want to add own validations. */
+    override changeToMode({ newMode }: ModeBase.ChangeToModeRequest): ModeBase.ChangeToModeResponse {
+        const result = ModeUtils.assertModeChange(this.state.supportedModes, this.state.currentMode, newMode);
+        if (result.status !== ModeBase.ModeChangeStatus.Success) {
+            return result;
+        }
+        if (newMode !== RvcDeviceRunModes.Idle && this.state.currentMode !== RvcDeviceRunModes.Idle) {
+            return {
+                status: ModeBase.ModeChangeStatus.InvalidInMode,
+                statusText: `Can not switch operative modes while in a non-idle state (${this.state.currentMode})`,
+            };
+        }
+        this.state.currentMode = newMode; // Update the new mode, needed because we do not use super.changeToMode()
+        return result; // Is Success
+    }
+}

package/src/device-smoke-co-alarm/README.md

@@ -0,0 +1,14 @@
+# Smoke CO Alarm Example
+
+This example shows how to build a simple Smoke&CO Alarm Sensor Matter device.  It just defines initial static values,
+so it won't change over time.
+
+## Usage
+
+For general documentation about the CLI parameters or environment variables that can be used for matter.js please refer to the [Examples README](../../../examples/README.md#cli-usage).
+
+Execute the following command in the examples root directory
+
+```bash
+npm run matter-smoke-co-alarm
+```

package/src/device-smoke-co-alarm/SmokeCOAlarmDeviceNode.ts

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * This example shows how to create a simple Smoke&CO Sensor Matter device.  It just defines initial static values,
+ * so it won't change over time.
+ */
+
+import { Endpoint, ServerNode } from "@matter/main";
+import { CarbonDioxideConcentrationMeasurementServer } from "@matter/main/behaviors/carbon-dioxide-concentration-measurement";
+import { SmokeCoAlarmServer } from "@matter/main/behaviors/smoke-co-alarm";
+import { ConcentrationMeasurement } from "@matter/main/clusters/concentration-measurement";
+import { SmokeCoAlarmDevice } from "@matter/main/devices/smoke-co-alarm";
+
+// Define the endpoint for the device.  This is the "thing/device" that will appear on the network.
+const smokeCoAlarmEndpoint = new Endpoint(
+    SmokeCoAlarmDevice.with(
+        CarbonDioxideConcentrationMeasurementServer.with("NumericMeasurement", "PeakMeasurement", "AverageMeasurement"),
+        SmokeCoAlarmServer.with("SmokeAlarm", "CoAlarm"),
+    ),
+    {
+        id: "smokeCoAlarm",
+        smokeCoAlarm: {
+            /*
+            The following values are set as defaults by the SmokeCoAlarmServer class.  You can override them here.
+            expressedState: SmokeCoAlarm.ExpressedState.Normal,
+            smokeState: SmokeCoAlarm.AlarmState.Normal,
+            coState: SmokeCoAlarm.AlarmState.Normal,
+            batteryAlert: SmokeCoAlarm.AlarmState.Normal,
+            testInProgress: false,
+            hardwareFaultAlert: false,
+            endOfServiceAlert: SmokeCoAlarm.EndOfService.Normal,
+             */
+        },
+        carbonDioxideConcentrationMeasurement: {
+            measuredValue: 12.34,
+            measurementUnit: ConcentrationMeasurement.MeasurementUnit.Ppm,
+            measurementMedium: ConcentrationMeasurement.MeasurementMedium.Air,
+        },
+    },
+);
+
+// Physical devices appear as "nodes" on a Matter network.  As a device implementer you use a NodeServer to bring a
+// device online.
+//
+// Note there are a large number of options to NodeServer that we are allowing to take default values here.  See
+// IlluminatedRollerShade.ts for a more detailed example.
+const node = await ServerNode.create();
+
+// Nodes are a composition of endpoints.  Add a single endpoint to the node, our example socket device.
+await node.add(smokeCoAlarmEndpoint);
+// Our device is now built, so we can bring the node online.
+//
+// Note that you may serve multiple nodes from a single process.  We only have one, however, so we can use the run()
+// method of the node.
+await node.run();

package/src/tsconfig.json

@@ -9,6 +9,9 @@
         {
             "path": "../../main/src"
         },
+        {
+            "path": "../../matter.js/src"
+        },
         {
             "path": "../../nodejs-ble/src"
         },