@matter/create 0.13.0-alpha.0-20250415-475996bb5 → 0.13.0-alpha.0-20250418-8cfc0b832

package/dist/templates/controller/ControllerNode.ts

@@ -28,6 +28,7 @@ if (environment.vars.get("ble")) {
     Ble.get = singleton(
         () =>
             new NodeJsBle({
+                environment,
                 hciId: environment.vars.number("ble.hci.id"),
             }),
     );
@@ -84,11 +85,11 @@ class ControllerNode {
                 environment.vars.number("longDiscriminator") ??
                 (await controllerStorage.get("longDiscriminator", 3840));
             if (longDiscriminator > 4095) throw new Error("Discriminator value must be less than 4096");
-            setupPin = environment.vars.number("pin") ?? (await controllerStorage.get("pin", 20202021));
+            setupPin = environment.vars.number("passcode") ?? (await controllerStorage.get("passcode", 20202021));
         }
         if ((shortDiscriminator === undefined && longDiscriminator === undefined) || setupPin === undefined) {
             throw new Error(
-                "Please specify the longDiscriminator of the device to commission with -longDiscriminator or provide a valid passcode with -passcode",
+                "Please specify the longDiscriminator of the device to commission with -longDiscriminator or provide a valid passcode with --passcode=xxxxxx",
             );
         }
 

package/dist/templates/device-air-quality-sensor/AirQualitySensorDeviceNode.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * This example shows how to create a Air Quality Sensor Matter device with temperature, humidity, PMx and TVOC
+ * measurements.  It just defines initial static values, so it won't change over time.
+ */
+
+import { Endpoint, ServerNode } from "@matter/main";
+import { Pm1ConcentrationMeasurementServer } from "@matter/main/behaviors/pm1-concentration-measurement";
+import { Pm10ConcentrationMeasurementServer } from "@matter/main/behaviors/pm10-concentration-measurement";
+import { Pm25ConcentrationMeasurementServer } from "@matter/main/behaviors/pm25-concentration-measurement";
+import { RelativeHumidityMeasurementServer } from "@matter/main/behaviors/relative-humidity-measurement";
+import { TemperatureMeasurementServer } from "@matter/main/behaviors/temperature-measurement";
+import { TotalVolatileOrganicCompoundsConcentrationMeasurementServer } from "@matter/main/behaviors/total-volatile-organic-compounds-concentration-measurement";
+import { AirQuality } from "@matter/main/clusters/air-quality";
+import { ConcentrationMeasurement } from "@matter/main/clusters/concentration-measurement";
+import { AirQualitySensorDevice } from "@matter/main/devices/air-quality-sensor";
+
+// Define the endpoint for the device.  This is the "thing/device" that will appear on the network.
+const airQualityEndpoint = new Endpoint(
+    AirQualitySensorDevice.with(
+        TemperatureMeasurementServer,
+        RelativeHumidityMeasurementServer,
+        Pm1ConcentrationMeasurementServer.with(ConcentrationMeasurement.Feature.NumericMeasurement),
+        Pm25ConcentrationMeasurementServer.with(ConcentrationMeasurement.Feature.NumericMeasurement),
+        Pm10ConcentrationMeasurementServer.with(ConcentrationMeasurement.Feature.NumericMeasurement),
+        TotalVolatileOrganicCompoundsConcentrationMeasurementServer.with(
+            ConcentrationMeasurement.Feature.NumericMeasurement,
+        ),
+    ),
+    {
+        id: "airQuality",
+        airQuality: {
+            airQuality: AirQuality.AirQualityEnum.Poor,
+        },
+        relativeHumidityMeasurement: {
+            tolerance: 0,
+            minMeasuredValue: 0,
+            maxMeasuredValue: 100,
+        },
+        temperatureMeasurement: {
+            tolerance: 0,
+            minMeasuredValue: 0,
+            maxMeasuredValue: 100,
+        },
+        pm1ConcentrationMeasurement: {
+            measuredValue: 12.34,
+            measurementUnit: ConcentrationMeasurement.MeasurementUnit.Ppm,
+            measurementMedium: ConcentrationMeasurement.MeasurementMedium.Air,
+        },
+        pm10ConcentrationMeasurement: {
+            measuredValue: 12.34,
+            measurementUnit: ConcentrationMeasurement.MeasurementUnit.Ppm,
+            measurementMedium: ConcentrationMeasurement.MeasurementMedium.Air,
+        },
+        pm25ConcentrationMeasurement: {
+            measuredValue: 12.34,
+            measurementUnit: ConcentrationMeasurement.MeasurementUnit.Ppm,
+            measurementMedium: ConcentrationMeasurement.MeasurementMedium.Air,
+        },
+        totalVolatileOrganicCompoundsConcentrationMeasurement: {
+            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(airQualityEndpoint);
+// 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/dist/templates/device-onoff-advanced/DeviceNodeFull.ts

@@ -74,6 +74,7 @@ if (environment.vars.get("ble.enable")) {
     Ble.get = singleton(
         () =>
             new NodeJsBle({
+                environment,
                 hciId: environment.vars.number("ble.hciId"),
             }),
     );
@@ -381,7 +382,7 @@ logEndpoint(EndpointServer.forEndpoint(server));
 /**
  * In order to start the node and announce it into the network we start the node. This method resolves when the Matter
  * node enters his online state. Alternatively, we could also use `await server.run()` which
- * resolves when the node goes offline again, but we want to execute code afterwards, so we use start() here
+ * resolves when the node goes offline again, but we want to execute code afterward, so we use start() here
  */
 await server.start();
 

package/dist/templates/device-robotic-vacuum-cleaner/RoboticVacuumCleanerDevice.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2022-2025 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+// This demonstrates bringing a "Robotic Vacuum Cleaner" device online with matter.js.
+
+import { AreaNamespaceTag, ServerNode } from "@matter/main";
+import { ServiceAreaServer } from "@matter/main/behaviors/service-area";
+import { ModeBase } from "@matter/main/clusters/mode-base";
+import { RvcCleanMode } from "@matter/main/clusters/rvc-clean-mode";
+import { RvcOperationalState } from "@matter/main/clusters/rvc-operational-state";
+import { RvcRunMode } from "@matter/main/clusters/rvc-run-mode";
+import { RoboticVacuumCleanerDevice } from "@matter/main/devices/robotic-vacuum-cleaner";
+import { CleaningAreas, RvcDeviceCleanMode, RvcDeviceLogic, RvcDeviceRunModes } from "./RvcDeviceLogic.js";
+import { CustomRvcCleanModeServer } from "./behaviors/CustomRvcCleanModeServer.js";
+import { CustomRvcOperationalStateServer } from "./behaviors/CustomRvcOperationalStateServer.js";
+import { CustomRvcRunModeServer } from "./behaviors/CustomRvcRunModeServer.js";
+
+// 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 RoboticVacuumCleanerDevice.
+// THe RVC device has some requirements where multiple clusters need to work together.  We are using own Cluster logic
+// for this - please see in the respective Behavior files.
+// The below options also show the available Run Modes, Operational States and Service Areas that the device exposes
+// and their data structures.
+
+await node.add(
+    RoboticVacuumCleanerDevice.with(
+        CustomRvcCleanModeServer,
+        CustomRvcOperationalStateServer,
+        CustomRvcRunModeServer,
+        ServiceAreaServer,
+        RvcDeviceLogic,
+    ),
+    {
+        id: "robotic-vacuum-cleaner",
+        rvcCleanMode: {
+            supportedModes: [
+                {
+                    label: "Vacuuming",
+                    mode: RvcDeviceCleanMode.Vacuuming,
+                    modeTags: [{ value: RvcCleanMode.ModeTag.Vacuum }],
+                },
+                {
+                    label: "Mopping",
+                    mode: RvcDeviceCleanMode.Mopping,
+                    modeTags: [{ value: RvcCleanMode.ModeTag.Mop }],
+                },
+            ],
+            // We start with this mode. It will be persisted
+            currentMode: RvcDeviceCleanMode.Vacuuming,
+        },
+        rvcRunMode: {
+            supportedModes: [
+                {
+                    label: "Auto-Cleaning",
+                    mode: RvcDeviceRunModes.AutoCleaning,
+                    modeTags: [{ value: RvcRunMode.ModeTag.Cleaning }, { value: ModeBase.ModeTag.Auto }],
+                },
+                {
+                    label: "Quick-Cleaning",
+                    mode: RvcDeviceRunModes.QuickCleaning,
+                    modeTags: [{ value: RvcRunMode.ModeTag.Cleaning }, { value: ModeBase.ModeTag.Quick }],
+                },
+                {
+                    label: "Mapping",
+                    mode: RvcDeviceRunModes.Mapping,
+                    modeTags: [{ value: RvcRunMode.ModeTag.Mapping }],
+                },
+                {
+                    label: "Idle",
+                    mode: RvcDeviceRunModes.Idle,
+                    modeTags: [{ value: RvcRunMode.ModeTag.Idle }],
+                },
+            ],
+            // We start with this mode. It will be persisted
+            currentMode: RvcDeviceRunModes.Idle,
+        },
+        rvcOperationalState: {
+            operationalStateList: [
+                { operationalStateId: RvcOperationalState.OperationalState.Running },
+                { operationalStateId: RvcOperationalState.OperationalState.Paused },
+                { operationalStateId: RvcOperationalState.OperationalState.Error },
+                { operationalStateId: RvcOperationalState.OperationalState.SeekingCharger },
+                { operationalStateId: RvcOperationalState.OperationalState.Charging },
+                { operationalStateId: RvcOperationalState.OperationalState.Docked },
+            ],
+            operationalState: RvcOperationalState.OperationalState.Docked,
+        },
+        serviceArea: {
+            supportedAreas: [
+                {
+                    areaId: CleaningAreas.Kitchen,
+                    mapId: null,
+                    areaInfo: {
+                        locationInfo: {
+                            locationName: "Kitchen",
+                            floorNumber: 0,
+                            areaType: AreaNamespaceTag.Kitchen.tag,
+                        },
+                        landmarkInfo: null,
+                    },
+                },
+                {
+                    areaId: CleaningAreas.LivingRoom,
+                    mapId: null,
+                    areaInfo: {
+                        locationInfo: {
+                            locationName: "Living Room",
+                            floorNumber: 0,
+                            areaType: AreaNamespaceTag.LivingRoom.tag,
+                        },
+                        landmarkInfo: null,
+                    },
+                },
+                {
+                    areaId: CleaningAreas.Bathroom,
+                    mapId: null,
+                    areaInfo: {
+                        locationInfo: {
+                            locationName: "Bathroom",
+                            floorNumber: 0,
+                            areaType: AreaNamespaceTag.Bathroom.tag,
+                        },
+                        landmarkInfo: null,
+                    },
+                },
+                {
+                    areaId: CleaningAreas.Bedroom,
+                    mapId: null,
+                    areaInfo: {
+                        locationInfo: {
+                            locationName: "Bedroom",
+                            floorNumber: 0,
+                            areaType: AreaNamespaceTag.Bedroom.tag,
+                        },
+                        landmarkInfo: null,
+                    },
+                },
+            ],
+            currentArea: null,
+        },
+    },
+);
+
+// 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/dist/templates/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/dist/templates/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/dist/templates/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/dist/templates/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/dist/templates/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/dist/templates/index.json

@@ -1,21 +1,29 @@
 {
-    "typescriptVersion": "~5.8.2",
+    "typescriptVersion": "~5.8.3",
     "nodeTypesVersion": "^22.14.1",
     "templates": [
         {
             "name": "controller",
             "dependencies": {
-                "@matter/main": "~0.13.0-alpha.0-20250415-475996bb5",
-                "@matter/nodejs-ble": "~0.13.0-alpha.0-20250415-475996bb5",
-                "@project-chip/matter.js": "~0.13.0-alpha.0-20250415-475996bb5"
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832",
+                "@matter/nodejs-ble": "~0.13.0-alpha.0-20250418-8cfc0b832",
+                "@project-chip/matter.js": "~0.13.0-alpha.0-20250418-8cfc0b832"
             },
             "description": "Controller example to commission and connect devices",
             "entrypoint": "ControllerNode.ts"
         },
+        {
+            "name": "device-air-quality-sensor",
+            "dependencies": {
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
+            },
+            "description": "Air quality sensor example",
+            "entrypoint": "AirQualitySensorDeviceNode.ts"
+        },
         {
             "name": "device-bridge-onoff",
             "dependencies": {
-                "@matter/main": "~0.13.0-alpha.0-20250415-475996bb5"
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
             },
             "description": "Bridge for multiple OnOff light/sockets with a CLI command execution interface",
             "entrypoint": "BridgedDevicesNode.ts"
@@ -23,7 +31,7 @@
         {
             "name": "device-composed-onoff",
             "dependencies": {
-                "@matter/main": "~0.13.0-alpha.0-20250415-475996bb5"
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
             },
             "description": "Composed device for multiple OnOff light/sockets with a CLI command execution interface",
             "entrypoint": "ComposedDeviceNode.ts"
@@ -31,7 +39,7 @@
         {
             "name": "device-composed-wc-light",
             "dependencies": {
-                "@matter/main": "~0.13.0-alpha.0-20250415-475996bb5"
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
             },
             "description": "Composed device with Window covering and a light endpoint that logs changes",
             "entrypoint": "IlluminatedRollerShade.ts"
@@ -39,7 +47,7 @@
         {
             "name": "device-measuring-socket",
             "dependencies": {
-                "@matter/main": "~0.13.0-alpha.0-20250415-475996bb5"
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
             },
             "description": "Socket device that reports random Energy and Power measurements",
             "entrypoint": "MeasuredSocketDevice.ts"
@@ -59,9 +67,9 @@
         {
             "name": "device-onoff-advanced",
             "dependencies": {
-                "@matter/nodejs": "~0.13.0-alpha.0-20250415-475996bb5",
-                "@matter/nodejs-ble": "~0.13.0-alpha.0-20250415-475996bb5",
-                "@matter/main": "~0.13.0-alpha.0-20250415-475996bb5"
+                "@matter/nodejs": "~0.13.0-alpha.0-20250418-8cfc0b832",
+                "@matter/nodejs-ble": "~0.13.0-alpha.0-20250418-8cfc0b832",
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
             },
             "description": "OnOff light/socket device with BLE support and advanced API usage",
             "entrypoint": "DeviceNodeFull.ts"
@@ -69,15 +77,23 @@
         {
             "name": "device-onoff-light",
             "dependencies": {
-                "@matter/main": "~0.13.0-alpha.0-20250415-475996bb5"
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
             },
             "description": "OnOff light example which logs the state changes to the console",
             "entrypoint": "LightDevice.ts"
         },
+        {
+            "name": "device-robotic-vacuum-cleaner",
+            "dependencies": {
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
+            },
+            "description": "Robotic Vacuum Cleaner Example",
+            "entrypoint": "RoboticVacuumCleanerDevice.ts"
+        },
         {
             "name": "device-sensor",
             "dependencies": {
-                "@matter/main": "~0.13.0-alpha.0-20250415-475996bb5"
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
             },
             "description": "Temperature/Humidity sensor with a CLI command interface to get the value",
             "entrypoint": "SensorDeviceNode.ts"
@@ -85,10 +101,18 @@
         {
             "name": "device-simple",
             "dependencies": {
-                "@matter/main": "~0.13.0-alpha.0-20250415-475996bb5"
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
             },
             "description": "A simple on/off device",
             "entrypoint": "main.ts"
+        },
+        {
+            "name": "device-smoke-co-alarm",
+            "dependencies": {
+                "@matter/main": "~0.13.0-alpha.0-20250418-8cfc0b832"
+            },
+            "description": "Smoke CO Alarm Example",
+            "entrypoint": "SmokeCOAlarmDeviceNode.ts"
         }
     ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@matter/create",
-    "version": "0.13.0-alpha.0-20250415-475996bb5",
+    "version": "0.13.0-alpha.0-20250418-8cfc0b832",
     "description": "Matter.js skeleton project generator",
     "type": "module",
     "scripts": {
@@ -32,7 +32,7 @@
     },
     "homepage": "https://github.com/project-chip/matter.js#readme",
     "devDependencies": {
-        "@matter/tools": "0.13.0-alpha.0-20250415-475996bb5",
+        "@matter/tools": "0.13.0-alpha.0-20250418-8cfc0b832",
         "@types/node": "^22.14.1",
         "@types/tar-stream": "^3.1.3"
     },