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

package/src/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/src/controller/README.md

@@ -28,12 +28,12 @@ This will commission a MatterServer device (for debugging/capability showing pur
 The following parameters are available and used to initially commission a device (they can be omitted after this):
 * --fabriclabel: the fabric label to use for commissioning (default: "matter.js Controller")
 * If the IP and Port of the device is known (should be only the case in testing cases) you can use the following parameters:
-    * --ip: the IP address of the device to commission (can be used but discovery via pairingcode or discriminator or also just pin (passcode) is most likely better)
+    * --ip: the IP address of the device to commission (can be used but discovery via pairingcode or discriminator or also just passcode is most likely better)
     * --port the port of the device to commission (default: 5540)
 * Device identification options:
-    * --pairingcode: code to use for pairing (-longDiscriminator and -pin will be ignored) - usually the code below the QR Code on the device or displayed in the app!
+    * --pairingcode: code to use for pairing (-longDiscriminator and -passcode will be ignored) - usually the code below the QR Code on the device or displayed in the app!
     * --longDiscriminator: the discriminator to use for pairing (default: 3840, value between 0 and 4095)
-    * --pin: the pin to use for pairing (default: 20202021)
+    * --passcode: the passcode to use for pairing (default: 20202021)
 * When the device to commission is not already in the IP network and also not an Ethernet device commission can be done via ble. In this case the following parameters are used:
     * --ble: enable BLE support (default: false) If this is enabled the controller will try to connect via BLE first (15s timeout) and then via IP if not commissioned yet!
     * --ble-hci-id: Optionally, HCI ID to use (Linux only, default 0)

package/src/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/src/device-air-quality-sensor/README.md

@@ -0,0 +1,14 @@
+# Air quality sensor example
+
+This example shows how to build a simple Air quality Sensor device with temperature, humidity, PMx and TVOC measurements.
+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-air-quality-sensor
+```

package/src/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/src/device-robotic-vacuum-cleaner/README.md

@@ -0,0 +1,22 @@
+# Robotic Vacuum Cleaner Example
+
+This example shows how to run a Robot Vacuum Cleaning device. This is a bit more complex and implements the following 
+(fictional) features and state engine:
+* Supports Run Modes: Idle, Quick-Clean (one cleaning round), Auto-Clean (3 rounds for one cycle and does cleaning again after 3h)
+* Supports Cleaning Modes: Vacuuming and Mopping
+* Supports Cleaning Areas: Living Room, Kitchen, Bedroom, Bathroom
+* State Engine:
+  * One cleaning/mapping round takes 10 minutes
+  * Returning to the charger (after Cleaning/Mapping) takes 30s
+  * Recharging takes 2 Minutes (always happening when device reached charger)
+  * In Auto Mode the RVC is repeating the cleaning after 3h
+
+## 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-rvc
+```

package/src/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();