@matter/examples 0.11.0-alpha.0-20241005-e3e4e4a7a

package/src/examples/MultiDeviceNode.ts

@@ -0,0 +1,205 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * This example shows how to create a new device node that is composed of multiple devices.
+ * It creates multiple endpoints on the server. For information on how to add a composed device to a bridge please
+ * refer to the bridge example!
+ * It can be used as CLI script and starting point for your own device node implementation.
+ */
+
+import {
+    DeviceTypeId,
+    Endpoint,
+    EndpointServer,
+    Environment,
+    ServerNode,
+    StorageService,
+    Time,
+    VendorId,
+} from "@matter/main";
+import { OnOffLightDevice } from "@matter/main/devices/on-off-light";
+import { OnOffPlugInUnitDevice } from "@matter/main/devices/on-off-plug-in-unit";
+import { logEndpoint } from "@matter/main/protocol";
+import { execSync } from "child_process";
+
+const devices = await getConfiguration();
+for (let idx = 1; idx < devices.length; idx++) {
+    const {
+        isSocket,
+        deviceName,
+        vendorName,
+        passcode,
+        discriminator,
+        vendorId,
+        productName,
+        productId,
+        port,
+        uniqueId,
+    } = devices[idx];
+    const i = idx + 1;
+
+    /**
+     * Create a Matter ServerNode, which contains the Root Endpoint and all relevant data and configuration
+     */
+    const server = await ServerNode.create({
+        // Required: Give the Node a unique ID which is used to store the state of this node
+        id: uniqueId,
+
+        // Provide Network relevant configuration like the port
+        // Optional when operating only one device on a host, Default port is 5540
+        network: {
+            port,
+        },
+
+        // Provide Commissioning relevant settings
+        // Optional for development/testing purposes
+        commissioning: {
+            passcode,
+            discriminator,
+        },
+
+        // Provide Node announcement settings
+        // Optional: If Ommitted some development defaults are used
+        productDescription: {
+            name: deviceName,
+            deviceType: DeviceTypeId(isSocket ? OnOffPlugInUnitDevice.deviceType : OnOffLightDevice.deviceType),
+        },
+
+        // Provide defaults for the BasicInformation cluster on the Root endpoint
+        // Optional: If Omitted some development defaults are used
+        basicInformation: {
+            vendorName,
+            vendorId: VendorId(vendorId),
+            nodeLabel: productName,
+            productName,
+            productLabel: productName,
+            productId,
+            serialNumber: `matterjs-${uniqueId}`,
+            uniqueId,
+        },
+    });
+
+    console.log(
+        `Added device ${i} on port ${port} and unique id ${uniqueId}: Passcode: ${passcode}, Discriminator: ${discriminator}`,
+    );
+
+    const endpoint = new Endpoint(isSocket ? OnOffPlugInUnitDevice : OnOffLightDevice, { id: "onoff" });
+    await server.add(endpoint);
+
+    /**
+     * Register state change handlers of the node for identify and onoff states to react to the commands.
+     * If the code in these change handlers fail then the change is also rolled back and not executed and an error is
+     * reported back to the controller.
+     */
+    endpoint.events.identify.startIdentifying.on(() => {
+        console.log(`Run identify logic for device ${i}, ideally blink a light every 0.5s ...`);
+    });
+
+    endpoint.events.identify.stopIdentifying.on(() => {
+        console.log(`Stop identify logic for device ${i}...`);
+    });
+
+    endpoint.events.onOff.onOff$Changed.on(value => {
+        executeCommand(value ? `on${i}` : `off${i}`);
+        console.log(`OnOff ${i} is now ${value ? "ON" : "OFF"}`);
+    });
+
+    /**
+     * Log the endpoint structure for debugging reasons and to allow to verify anything is correct
+     */
+    logEndpoint(EndpointServer.forEndpoint(server));
+
+    console.log("----------------------------");
+    console.log(`QR Code for Device ${i} on port ${port}:`);
+    console.log("----------------------------");
+
+    /**
+     * In order to start the node and announce it into the network we use the run method which resolves when the node goes
+     * offline again because we do not need anything more here. See the Full example for other starting options.
+     * The QR Code is printed automatically.
+     */
+    await server.start();
+}
+
+/*********************************************************************************************************
+ * Convenience Methods
+ *********************************************************************************************************/
+
+/**
+ * Defines a shell command from an environment variable and execute it and log the response
+ */
+function executeCommand(scriptParamName: string) {
+    const script = Environment.default.vars.string(scriptParamName);
+    if (script === undefined) return undefined;
+    console.log(`${scriptParamName}: ${execSync(script).toString().slice(0, -1)}`);
+}
+
+async function getConfiguration() {
+    const environment = Environment.default;
+
+    const storageService = environment.get(StorageService);
+    console.log(`Storage location: ${storageService.location} (Directory)`);
+    console.log(
+        'Use the parameter "--storage-path=NAME-OR-PATH" to specify a different storage location in this directory, use --storage-clear to start with an empty storage.',
+    );
+    const deviceStorage = (await storageService.open("device")).createContext("data");
+
+    let defaultPasscode = 20202021;
+    let defaultDiscriminator = 3840;
+    let defaultPort = 5550;
+
+    const devices = [];
+    const numDevices = environment.vars.number("num") ?? 2;
+    for (let i = 1; i <= numDevices; i++) {
+        const isSocket = await deviceStorage.get(`isSocket${i}`, environment.vars.string(`type${i}`) === "socket");
+        if (await deviceStorage.has(`isSocket${i}`)) {
+            console.log(`Device type ${isSocket ? "socket" : "light"} found in storage. --type parameter is ignored.`);
+        }
+        const deviceName = `Matter ${environment.vars.string(`type${i}`) ?? "light"} device ${i}`;
+        const vendorName = "matter-node.js";
+        const passcode =
+            environment.vars.number(`passcode${i}`) ?? (await deviceStorage.get(`passcode${i}`, defaultPasscode++));
+        const discriminator =
+            environment.vars.number(`discriminator${i}`) ??
+            (await deviceStorage.get(`discriminator${i}`, defaultDiscriminator++));
+        // product name / id and vendor id should match what is in the device certificate
+        const vendorId = environment.vars.number(`vendorid${i}`) ?? (await deviceStorage.get(`vendorid${i}`, 0xfff1));
+        const productName = `node-matter OnOff-Device ${i}`;
+        const productId =
+            environment.vars.number(`productid${i}`) ?? (await deviceStorage.get(`productid${i}`, 0x8000));
+
+        const port = environment.vars.number(`port${i}`) ?? defaultPort++;
+
+        const uniqueId =
+            environment.vars.string(`uniqueid${i}`) ??
+            (await deviceStorage.get(`uniqueid${i}`, `${i}-${Time.nowMs()}`));
+
+        // Persist basic data to keep them also on restart
+        await deviceStorage.set(`passcode${i}`, passcode);
+        await deviceStorage.set(`discriminator${i}`, discriminator);
+        await deviceStorage.set(`vendorid${i}`, vendorId);
+        await deviceStorage.set(`productid${i}`, productId);
+        await deviceStorage.set(`isSocket${i}`, isSocket);
+        await deviceStorage.set(`uniqueid${i}`, uniqueId);
+
+        devices.push({
+            isSocket,
+            deviceName,
+            vendorName,
+            passcode,
+            discriminator,
+            vendorId,
+            productName,
+            productId,
+            port,
+            uniqueId,
+        });
+    }
+
+    return devices;
+}

package/src/examples/SensorDeviceNode.ts

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * This example shows how to create a simple Sensor Matter device as temperature or humidity device.
+ * It can be used as CLI script and starting point for your own device node implementation.
+ * This example is CJS conform and do not use top level await's.
+ */
+
+import { Endpoint, EndpointServer, Environment, ServerNode, StorageService, Time } from "@matter/main";
+import { HumiditySensorDevice } from "@matter/main/devices/humidity-sensor";
+import { TemperatureSensorDevice } from "@matter/main/devices/temperature-sensor";
+import { logEndpoint } from "@matter/main/protocol";
+import { DeviceTypeId, VendorId } from "@matter/main/types";
+import { execSync } from "child_process";
+
+async function main() {
+    /** Initialize configuration values */
+    const {
+        isTemperature,
+        interval,
+        deviceName,
+        vendorName,
+        passcode,
+        discriminator,
+        vendorId,
+        productName,
+        productId,
+        port,
+        uniqueId,
+    } = await getConfiguration();
+
+    /**
+     * Create a Matter ServerNode, which contains the Root Endpoint and all relevant data and configuration
+     */
+    const server = await ServerNode.create({
+        // Required: Give the Node a unique ID which is used to store the state of this node
+        id: uniqueId,
+
+        // Provide Network relevant configuration like the port
+        // Optional when operating only one device on a host, Default port is 5540
+        network: {
+            port,
+        },
+
+        // Provide Commissioning relevant settings
+        // Optional for development/testing purposes
+        commissioning: {
+            passcode,
+            discriminator,
+        },
+
+        // Provide Node announcement settings
+        // Optional: If Ommitted some development defaults are used
+        productDescription: {
+            name: deviceName,
+            deviceType: DeviceTypeId(
+                isTemperature ? TemperatureSensorDevice.deviceType : HumiditySensorDevice.deviceType,
+            ),
+        },
+
+        // Provide defaults for the BasicInformation cluster on the Root endpoint
+        // Optional: If Omitted some development defaults are used
+        basicInformation: {
+            vendorName,
+            vendorId: VendorId(vendorId),
+            nodeLabel: productName,
+            productName,
+            productLabel: productName,
+            productId,
+            serialNumber: `matterjs-${uniqueId}`,
+            uniqueId,
+        },
+    });
+
+    /**
+     * Matter Nodes are a composition of endpoints. Create and add a single endpoint to the node. This example uses the
+     * OnOffLightDevice or OnOffPlugInUnitDevice depending on the value of the type parameter. It also assigns this Part a
+     * unique ID to store the endpoint number for it in the storage to restore the device on restart.
+     * In this case we directly use the default command implementation from matter.js. Check out the DeviceNodeFull example
+     * to see how to customize the command handlers.
+     */
+    let endpoint: Endpoint<TemperatureSensorDevice | HumiditySensorDevice>;
+    if (isTemperature) {
+        endpoint = new Endpoint(TemperatureSensorDevice, {
+            id: "tempsensor",
+            temperatureMeasurement: {
+                // Use this to initialize the measuredValue with the most uptodate value.
+                // If you do not know the value and also cannot request it, best use "null" (if allowed by the cluster).
+                measuredValue: getIntValueFromCommandOrRandom("value"),
+            },
+        });
+    } else {
+        endpoint = new Endpoint(HumiditySensorDevice, {
+            id: "humsensor",
+            relativeHumidityMeasurement: {
+                // Use this to initialize the measuredValue with the most uptodate value.
+                // If you do not know the value and also cannot request it, best use "null" (if allowed by the cluster).
+                measuredValue: getIntValueFromCommandOrRandom("value", false),
+            },
+        });
+    }
+
+    await server.add(endpoint);
+
+    /**
+     * Log the endpoint structure for debugging reasons and to allow to verify anything is correct
+     */
+    logEndpoint(EndpointServer.forEndpoint(server));
+
+    const updateInterval = setInterval(() => {
+        let setter: Promise<void>;
+        if (isTemperature) {
+            setter = endpoint.set({
+                temperatureMeasurement: {
+                    measuredValue: getIntValueFromCommandOrRandom("value"),
+                },
+            });
+        } else {
+            setter = endpoint.set({
+                relativeHumidityMeasurement: {
+                    measuredValue: getIntValueFromCommandOrRandom("value", false),
+                },
+            });
+        }
+        setter.catch(error => console.error("Error updating measured value:", error));
+    }, interval * 1000);
+
+    // Cleanup our update interval when node goes offline
+    server.lifecycle.offline.on(() => clearTimeout(updateInterval));
+
+    /**
+     * In order to start the node and announce it into the network we use the run method which resolves when the node goes
+     * offline again because we do not need anything more here. See the Full example for other starting options.
+     * The QR Code is printed automatically.
+     */
+    await server.run();
+}
+
+main().catch(error => console.error(error));
+
+/*********************************************************************************************************
+ * Convenience Methods
+ *********************************************************************************************************/
+
+/** Defined a shell command from an environment variable and execute it and log the response. */
+
+function getIntValueFromCommandOrRandom(scriptParamName: string, allowNegativeValues = true) {
+    const script = Environment.default.vars.string(scriptParamName);
+    if (script === undefined) {
+        if (!allowNegativeValues) return Math.round(Math.random() * 100);
+        return (Math.round(Math.random() * 100) - 50) * 100;
+    }
+    let result = execSync(script).toString().trim();
+    if ((result.startsWith("'") && result.endsWith("'")) || (result.startsWith('"') && result.endsWith('"')))
+        result = result.slice(1, -1);
+    console.log(`Command result: ${result}`);
+    let value = Math.round(parseFloat(result));
+    if (!allowNegativeValues && value < 0) value = 0;
+    return value;
+}
+
+async function getConfiguration() {
+    /**
+     * Collect all needed data
+     *
+     * This block collects all needed data from cli, environment or storage. Replace this with where ever your data come from.
+     *
+     * Note: This example uses the matter.js process storage system to store the device parameter data for convenience
+     * and easy reuse. When you also do that be careful to not overlap with Matter-Server own storage contexts
+     * (so maybe better not do it ;-)).
+     */
+    const environment = Environment.default;
+
+    const storageService = environment.get(StorageService);
+    console.log(`Storage location: ${storageService.location} (Directory)`);
+    console.log(
+        'Use the parameter "--storage-path=NAME-OR-PATH" to specify a different storage location in this directory, use --storage-clear to start with an empty storage.',
+    );
+    const deviceStorage = (await storageService.open("device")).createContext("data");
+
+    const isTemperature = await deviceStorage.get("isTemperature", environment.vars.get("type") !== "humidity");
+    if (await deviceStorage.has("isTemperature")) {
+        console.log(
+            `Device type ${isTemperature ? "temperature" : "humidity"} found in storage. --type parameter is ignored.`,
+        );
+    }
+    let interval = environment.vars.number("interval") ?? (await deviceStorage.get("interval", 60));
+    if (interval < 1) {
+        console.log(`Invalid Interval ${interval}, set to 60s`);
+        interval = 60;
+    }
+
+    const deviceName = "Matter test device";
+    const vendorName = "matter-node.js";
+    const passcode = environment.vars.number("passcode") ?? (await deviceStorage.get("passcode", 20202021));
+    const discriminator = environment.vars.number("discriminator") ?? (await deviceStorage.get("discriminator", 3840));
+    // product name / id and vendor id should match what is in the device certificate
+    const vendorId = environment.vars.number("vendorid") ?? (await deviceStorage.get("vendorid", 0xfff1));
+    const productName = `node-matter OnOff ${isTemperature ? "Temperature" : "Humidity"}`;
+    const productId = environment.vars.number("productid") ?? (await deviceStorage.get("productid", 0x8000));
+
+    const port = environment.vars.number("port") ?? 5540;
+
+    const uniqueId =
+        environment.vars.string("uniqueid") ?? (await deviceStorage.get("uniqueid", Time.nowMs().toString()));
+
+    // Persist basic data to keep them also on restart
+    await deviceStorage.set({
+        passcode,
+        discriminator,
+        vendorid: vendorId,
+        productid: productId,
+        interval,
+        isTemperature,
+        uniqueid: uniqueId,
+    });
+
+    return {
+        isTemperature,
+        interval,
+        deviceName,
+        vendorName,
+        passcode,
+        discriminator,
+        vendorId,
+        productName,
+        productId,
+        port,
+        uniqueId,
+    };
+}

package/src/examples/cluster/DummyThreadNetworkCommissioningServer.ts

@@ -0,0 +1,162 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, Logger } from "@matter/main";
+import { GeneralCommissioningBehavior } from "@matter/main/behaviors/general-commissioning";
+import { NetworkCommissioningBehavior } from "@matter/main/behaviors/network-commissioning";
+import { DeviceAdvertiser, DeviceCommissioner } from "@matter/main/protocol";
+import { NetworkCommissioning } from "@matter/types/clusters";
+
+const firstNetworkId = new Uint8Array(32);
+
+/**
+ * This represents a Dummy version of a Thread Network Commissioning Cluster Server without real thread related logic, beside
+ * returning some values provided as CLI parameters. This dummy implementation is only there for tests/as showcase for BLE
+ * commissioning of a device.
+ */
+export class DummyThreadNetworkCommissioningServer extends NetworkCommissioningBehavior.with(
+    NetworkCommissioning.Feature.ThreadNetworkInterface,
+) {
+    override scanNetworks({
+        breadcrumb,
+    }: NetworkCommissioning.ScanNetworksRequest): NetworkCommissioning.ScanNetworksResponse {
+        console.log(`---> scanNetworks called on NetworkCommissioning cluster: ${breadcrumb}`);
+
+        // Simulate successful scan
+        if (breadcrumb !== undefined) {
+            const generalCommissioningCluster = this.agent.get(GeneralCommissioningBehavior);
+            generalCommissioningCluster.state.breadcrumb = breadcrumb;
+        }
+
+        const networkingStatus = NetworkCommissioning.NetworkCommissioningStatus.Success;
+        this.state.lastNetworkingStatus = networkingStatus;
+
+        const threadScanResults = [
+            {
+                panId: this.env.vars.number("ble.thread.panId"),
+                extendedPanId: BigInt(this.env.vars.string("ble.thread.extendedPanId")),
+                networkName: this.env.vars.string("ble.thread.networkName"),
+                channel: this.env.vars.number("ble.thread.channel"),
+                version: 130,
+                extendedAddress: Bytes.fromString(
+                    (this.env.vars.string("ble.thread.address") ?? "000000000000").toLowerCase(),
+                ),
+                rssi: -50,
+                lqi: 50,
+            },
+        ];
+        console.log(Logger.toJSON(threadScanResults));
+
+        return {
+            networkingStatus,
+            threadScanResults,
+        };
+    }
+
+    override addOrUpdateThreadNetwork({
+        operationalDataset,
+        breadcrumb,
+    }: NetworkCommissioning.AddOrUpdateThreadNetworkRequest) {
+        console.log(
+            `---> addOrUpdateThreadNetwork called on NetworkCommissioning cluster: ${Bytes.toHex(operationalDataset)} ${breadcrumb}`,
+        );
+
+        this.env
+            .get(DeviceCommissioner)
+            .assertFailsafeArmed("Failsafe timer needs to be armed to add or update networks.");
+
+        // Simulate successful add or update
+        if (breadcrumb !== undefined) {
+            const generalCommissioningCluster = this.agent.get(GeneralCommissioningBehavior);
+            generalCommissioningCluster.state.breadcrumb = breadcrumb;
+        }
+
+        const networkingStatus = NetworkCommissioning.NetworkCommissioningStatus.Success;
+        this.state.lastNetworkingStatus = networkingStatus;
+        this.state.lastNetworkId = firstNetworkId;
+
+        return {
+            networkingStatus,
+            networkIndex: 0,
+        };
+    }
+
+    override removeNetwork({ networkId, breadcrumb }: NetworkCommissioning.RemoveNetworkRequest) {
+        console.log(
+            `---> removeNetwork called on NetworkCommissioning cluster: ${Bytes.toHex(networkId)} ${breadcrumb}`,
+        );
+
+        this.env
+            .get(DeviceCommissioner)
+            .assertFailsafeArmed("Failsafe timer needs to be armed to add or update networks.");
+
+        // Simulate successful add or update
+        if (breadcrumb !== undefined) {
+            const generalCommissioningCluster = this.agent.get(GeneralCommissioningBehavior);
+            generalCommissioningCluster.state.breadcrumb = breadcrumb;
+        }
+
+        const networkingStatus = NetworkCommissioning.NetworkCommissioningStatus.Success;
+        this.state.lastNetworkingStatus = networkingStatus;
+        this.state.lastNetworkId = firstNetworkId;
+
+        return {
+            networkingStatus,
+            networkIndex: 0,
+        };
+    }
+
+    override async connectNetwork({ networkId, breadcrumb }: NetworkCommissioning.ConnectNetworkRequest) {
+        console.log(
+            `---> connectNetwork called on NetworkCommissioning cluster: ${Bytes.toHex(networkId)} ${breadcrumb}`,
+        );
+
+        this.env
+            .get(DeviceCommissioner)
+            .assertFailsafeArmed("Failsafe timer needs to be armed to add or update networks.");
+
+        // Simulate successful connection
+        if (breadcrumb !== undefined) {
+            const generalCommissioningCluster = this.agent.get(GeneralCommissioningBehavior);
+            generalCommissioningCluster.state.breadcrumb = breadcrumb;
+        }
+
+        this.state.networks[0].connected = true;
+
+        const networkingStatus = NetworkCommissioning.NetworkCommissioningStatus.Success;
+        this.state.lastNetworkingStatus = networkingStatus;
+        this.state.lastNetworkId = firstNetworkId;
+        this.state.lastConnectErrorValue = null;
+
+        // Announce operational in IP network
+        await this.env.get(DeviceAdvertiser).startAdvertising();
+
+        return {
+            networkingStatus,
+            errorValue: null,
+        };
+    }
+
+    override reorderNetwork({ networkId, networkIndex, breadcrumb }: NetworkCommissioning.ReorderNetworkRequest) {
+        console.log(
+            `---> reorderNetwork called on NetworkCommissioning cluster: ${Bytes.toHex(networkId)} ${networkIndex} ${breadcrumb}`,
+        );
+
+        // Simulate successful connection
+        if (breadcrumb !== undefined) {
+            const generalCommissioningCluster = this.agent.get(GeneralCommissioningBehavior);
+            generalCommissioningCluster.state.breadcrumb = breadcrumb;
+        }
+
+        const networkingStatus = NetworkCommissioning.NetworkCommissioningStatus.Success;
+        this.state.lastNetworkingStatus = networkingStatus;
+
+        return {
+            networkingStatus,
+            networkIndex: 0,
+        };
+    }
+}