@project-chip/matter-node.js-examples 0.7.5-alpha.0-20240222-8696097f → 0.8.0-alpha.0-20240309-64eaef67

package/src/examples/DeviceNode.ts

@@ -1,302 +1,202 @@
-#!/usr/bin/env node
 /**
  * @license
- * Copyright 2022 The node-matter Authors
+ * Copyright 2022-2024 Matter.js Authors
  * SPDX-License-Identifier: Apache-2.0
  */
 
 /**
- * This example shows how to create a simple on-off Matter device.
+ * This example shows how to create a simple on-off Matter device as a light or as a socket.
  * 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 needed modules from @project-chip/matter-node.js
  */
 // Include this first to auto-register Crypto, Network and Time Node.js implementations
-import { CommissioningServer, MatterServer } from "@project-chip/matter-node.js";
+import "@project-chip/matter-node.js";
 
-import { BleNode } from "@project-chip/matter-node-ble.js/ble";
-import { Ble } from "@project-chip/matter-node.js/ble";
-import { OnOffLightDevice, OnOffPluginUnitDevice, logEndpoint } from "@project-chip/matter-node.js/device";
-import { Format, Level, Logger } from "@project-chip/matter-node.js/log";
-import { QrCode } from "@project-chip/matter-node.js/schema";
-import { StorageBackendDisk, StorageManager } from "@project-chip/matter-node.js/storage";
-import { Time } from "@project-chip/matter-node.js/time";
-import {
-    commandExecutor,
-    getIntParameter,
-    getParameter,
-    hasParameter,
-    requireMinNodeVersion,
-    singleton,
-} from "@project-chip/matter-node.js/util";
+import { requireMinNodeVersion } from "@project-chip/matter-node.js/util";
 import { DeviceTypeId, VendorId } from "@project-chip/matter.js/datatype";
-import DummyWifiNetworkCommissioningClusterServer from "./cluster/DummyWifiNetworkCommissioningClusterServer.js";
-
-const logger = Logger.get("Device");
+import { logEndpoint } from "@project-chip/matter.js/device";
+import { OnOffLightDevice } from "@project-chip/matter.js/devices/OnOffLightDevice";
+import { OnOffPlugInUnitDevice } from "@project-chip/matter.js/devices/OnOffPlugInUnitDevice";
+import { Endpoint, EndpointServer } from "@project-chip/matter.js/endpoint";
+import { Environment, StorageService } from "@project-chip/matter.js/environment";
+import { ServerNode } from "@project-chip/matter.js/node";
+import { Time } from "@project-chip/matter.js/time";
+import { execSync } from "child_process";
 
 requireMinNodeVersion(16);
 
-/** Configure logging */
-switch (getParameter("loglevel")) {
-    case "fatal":
-        Logger.defaultLogLevel = Level.FATAL;
-        break;
-    case "error":
-        Logger.defaultLogLevel = Level.ERROR;
-        break;
-    case "warn":
-        Logger.defaultLogLevel = Level.WARN;
-        break;
-    case "info":
-        Logger.defaultLogLevel = Level.INFO;
-        break;
-}
-
-switch (getParameter("logformat")) {
-    case "plain":
-        Logger.format = Format.PLAIN;
-        break;
-    case "html":
-        Logger.format = Format.HTML;
-        break;
-    default:
-        if (process.stdin?.isTTY) Logger.format = Format.ANSI;
-}
-
-if (hasParameter("ble")) {
-    // Initialize Ble
-    Ble.get = singleton(
-        () =>
-            new BleNode({
-                hciId: getIntParameter("ble-hci-id"),
-            }),
-    );
-}
-
-const storageLocation = getParameter("store") ?? ".device-node";
-const storage = new StorageBackendDisk(storageLocation, hasParameter("clearstorage"));
-logger.info(`Storage location: ${storageLocation} (Directory)`);
-logger.info(
-    'Use the parameter "-store NAME" to specify a different storage location, use -clearstorage to start with an empty storage.',
-);
-
-class Device {
-    private matterServer: MatterServer | undefined;
-
-    async start() {
-        logger.info(`node-matter`);
-
-        /**
-         * Initialize the storage system.
-         *
-         * The storage manager is then also used by the Matter server, so this code block in general is required,
-         * but you can choose a different storage backend as long as it implements the required API.
-         */
-
-        const storageManager = new StorageManager(storage);
-        await storageManager.initialize();
-
-        /**
-         * Collect all needed data
-         *
-         * This block makes sure to collect all needed data from cli or storage. Replace this with where ever your data
-         * come from.
-         *
-         * Note: This example also uses the initialized 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 contexts
-         * (so maybe better not ;-)).
-         */
-
-        const deviceStorage = storageManager.createContext("Device");
-
-        if (deviceStorage.has("isSocket")) {
-            logger.info("Device type found in storage. -type parameter is ignored.");
-        }
-        const isSocket = deviceStorage.get("isSocket", getParameter("type") === "socket");
-        const deviceName = "Matter test device";
-        const vendorName = "matter-node.js";
-        const passcode = getIntParameter("passcode") ?? deviceStorage.get("passcode", 20202021);
-        const discriminator = getIntParameter("discriminator") ?? deviceStorage.get("discriminator", 3840);
-        // product name / id and vendor id should match what is in the device certificate
-        const vendorId = getIntParameter("vendorid") ?? deviceStorage.get("vendorid", 0xfff1);
-        const productName = `node-matter OnOff ${isSocket ? "Socket" : "Light"}`;
-        const productId = getIntParameter("productid") ?? deviceStorage.get("productid", 0x8000);
-
-        const netInterface = getParameter("netinterface");
-        const port = getIntParameter("port") ?? 5540;
-
-        const uniqueId = getIntParameter("uniqueid") ?? deviceStorage.get("uniqueid", Time.nowMs());
-
-        deviceStorage.set("passcode", passcode);
-        deviceStorage.set("discriminator", discriminator);
-        deviceStorage.set("vendorid", vendorId);
-        deviceStorage.set("productid", productId);
-        deviceStorage.set("isSocket", isSocket);
-        deviceStorage.set("uniqueid", uniqueId);
-
-        /**
-         * Create Device instance and add needed Listener
-         *
-         * Create an instance of the matter device class you want to use.
-         * This example uses the OnOffLightDevice or OnOffPluginUnitDevice depending on the value of the type  parameter.
-         * To execute the on/off scripts defined as parameters a listener for the onOff attribute is registered via the
-         * device specific API.
-         *
-         * The below logic also adds command handlers for commands of clusters that normally are handled device internally
-         * like identify that can be implemented with the logic when these commands are called.
-         */
-
-        const onOffDevice = isSocket ? new OnOffPluginUnitDevice() : new OnOffLightDevice();
-        onOffDevice.addOnOffListener(on => commandExecutor(on ? "on" : "off")?.());
-
-        onOffDevice.addCommandHandler("identify", async ({ request: { identifyTime } }) =>
-            logger.info(`Identify called for OnOffDevice: ${identifyTime}`),
-        );
-
-        /**
-         * Create Matter Server and CommissioningServer Node
-         *
-         * To allow the device to be announced, found, paired and operated we need a MatterServer instance and add a
-         * commissioningServer to it and add the just created device instance to it.
-         * The CommissioningServer node defines the port where the server listens for the UDP packages of the Matter protocol
-         * and initializes deice specific certificates and such.
-         *
-         * The below logic also adds command handlers for commands of clusters that normally are handled internally
-         * like testEventTrigger (General Diagnostic Cluster) that can be implemented with the logic when these commands
-         * are called.
-         */
-
-        this.matterServer = new MatterServer(storageManager, { mdnsInterface: netInterface });
-
-        const commissioningServer = new CommissioningServer({
+async function main() {
+    /** Initialize configuration values */
+    const {
+        isSocket,
+        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,
-            deviceName,
-            deviceType: DeviceTypeId(onOffDevice.deviceType),
+        },
+
+        // Provide Commissioning relevant settings
+        // Optional for development/testing purposes
+        commissioning: {
             passcode,
             discriminator,
-            basicInformation: {
-                vendorName,
-                vendorId: VendorId(vendorId),
-                nodeLabel: productName,
-                productName,
-                productLabel: productName,
-                productId,
-                serialNumber: `node-matter-${uniqueId}`,
-            },
-            delayedAnnouncement: hasParameter("ble"), // Delay announcement when BLE is used to show how limited advertisement works
-            activeSessionsChangedCallback: fabricIndex => {
-                console.log(
-                    `activeSessionsChangedCallback: Active sessions changed on Fabric ${fabricIndex}`,
-                    commissioningServer.getActiveSessionInformation(fabricIndex),
-                );
-            },
-            commissioningChangedCallback: fabricIndex => {
-                console.log(
-                    `commissioningChangedCallback: Commissioning changed on Fabric ${fabricIndex}`,
-                    commissioningServer.getCommissionedFabricInformation(fabricIndex)[0],
-                );
-            },
-        });
-
-        // optionally add a listener for the testEventTrigger command from the GeneralDiagnostics cluster
-        commissioningServer.addCommandHandler("testEventTrigger", async ({ request: { enableKey, eventTrigger } }) =>
-            logger.info(`testEventTrigger called on GeneralDiagnostic cluster: ${enableKey} ${eventTrigger}`),
-        );
-
-        /**
-         * Modify automatically added clusters of the Root endpoint if needed
-         * In this example we change the networkCommissioning cluster into one for "Wifi only" devices when BLE is used
-         * for commissioning, to demonstrate how to do this.
-         * If you want to implement Ethernet only devices that get connected to the network via LAN/Ethernet cable,
-         * then all this is not needed.
-         * The same as shown here for Wi-Fi is also possible theoretical for Thread only or combined devices.
-         */
-
-        if (hasParameter("ble")) {
-            // matter.js will create a Ethernet-only device by default when ut comes to Network Commissioning Features.
-            // To offer e.g. a "Wi-Fi only device" (or any other combination) we need to override the Network Commissioning
-            // cluster and implement all the need handling here. This is a "static implementation" for pure demonstration
-            // purposes and just "simulates" the actions to be done. In a real world implementation this would be done by
-            // the device implementor based on the relevant networking stack.
-            // The NetworkCommissioningCluster and all logics are described in Matter Core Specifications section 11.8
-            commissioningServer.addRootClusterServer(DummyWifiNetworkCommissioningClusterServer);
-        }
-
-        commissioningServer.addDevice(onOffDevice);
-
-        await this.matterServer.addCommissioningServer(commissioningServer);
-
-        /**
-         * Start the Matter Server
-         *
-         * After everything was plugged together we can start the server. When not delayed announcement is set for the
-         * CommissioningServer node then this command also starts the announcement of the device into the network.
-         */
-
-        await this.matterServer.start();
-
-        logEndpoint(commissioningServer.getRootEndpoint());
-
-        // When we want to limit the initial announcement to one medium (e.g. BLE) then we need to delay the
-        // announcement and provide the limiting information.
-        // Without delaying the announcement is directly triggered with the above "start()" call.
-        if (hasParameter("ble")) {
-            // Announce operational in BLE network only if we have ble enabled, else everywhere
-            await commissioningServer.advertise({ ble: true });
+        },
+
+        // 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,
+        },
+    });
+
+    /**
+     * 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.
+     */
+    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.
+     */
+    let isIdentifying = false;
+    endpoint.events.identify.identifyTime$Change.on(value => {
+        // identifyTime is set when an identify command is called and then decreased every second while indentify logic runs.
+        if (value > 0 && !isIdentifying) {
+            isIdentifying = true;
+            console.log(`Run identify logic, ideally blink a light every 0.5s ...`);
+        } else if (value === 0) {
+            isIdentifying = false;
+            console.log(`Stop identify logic ...`);
         }
+    });
+
+    endpoint.events.onOff.onOff$Change.on(value => {
+        executeCommand(value ? "on" : "off");
+        console.log(`OnOff is now ${value ? "ON" : "OFF"}`);
+    });
+
+    /**
+     * Log the endpoint structure for debugging reasons and to allow to verify anything is correct
+     */
+    logEndpoint(EndpointServer.forEndpoint(server));
+
+    /**
+     * 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();
+}
 
-        /**
-         * Print Pairing Information
-         *
-         * If the device is not already commissioned (this info is stored in the storage system) then get and print the
-         * pairing details. This includes the QR code that can be scanned by the Matter app to pair the device.
-         */
+main().catch(error => console.error(error));
 
-        logger.info("Listening");
-        if (!commissioningServer.isCommissioned()) {
-            const pairingData = commissioningServer.getPairingCode({
-                ble: hasParameter("ble"),
-                softAccessPoint: false,
-                onIpNetwork: false,
-            });
+/*********************************************************************************************************
+ * Convenience Methods
+ *********************************************************************************************************/
 
-            const { qrPairingCode, manualPairingCode } = pairingData;
+/** Defined 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)}`);
+}
 
-            console.log(QrCode.get(qrPairingCode));
-            logger.info(
-                `QR Code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=${qrPairingCode}`,
-            );
-            logger.info(`Manual pairing code: ${manualPairingCode}`);
-        } else {
-            logger.info("Device is already commissioned. Waiting for controllers to connect ...");
-        }
-    }
+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");
 
-    async stop() {
-        await this.matterServer?.close();
+    const isSocket = deviceStorage.get("isSocket", environment.vars.get("type") === "socket");
+    if (deviceStorage.has("isSocket")) {
+        console.log(`Device type ${isSocket ? "socket" : "light"} found in storage. --type parameter is ignored.`);
     }
+    const deviceName = "Matter test device";
+    const vendorName = "matter-node.js";
+    const passcode = environment.vars.number("passcode") ?? deviceStorage.get("passcode", 20202021);
+    const discriminator = environment.vars.number("discriminator") ?? deviceStorage.get("discriminator", 3840);
+    // product name / id and vendor id should match what is in the device certificate
+    const vendorId = environment.vars.number("vendorid") ?? deviceStorage.get("vendorid", 0xfff1);
+    const productName = `node-matter OnOff ${isSocket ? "Socket" : "Light"}`;
+    const productId = environment.vars.number("productid") ?? deviceStorage.get("productid", 0x8000);
+
+    const port = environment.vars.number("port") ?? 5540;
+
+    const uniqueId = environment.vars.string("uniqueid") ?? deviceStorage.get("uniqueid", Time.nowMs().toString());
+
+    // Persist basic data to keep them also on restart
+    deviceStorage.set("passcode", passcode);
+    deviceStorage.set("discriminator", discriminator);
+    deviceStorage.set("vendorid", vendorId);
+    deviceStorage.set("productid", productId);
+    deviceStorage.set("isSocket", isSocket);
+    deviceStorage.set("uniqueid", uniqueId);
+
+    return {
+        isSocket,
+        deviceName,
+        vendorName,
+        passcode,
+        discriminator,
+        vendorId,
+        productName,
+        productId,
+        port,
+        uniqueId,
+    };
 }
-
-const device = new Device();
-device
-    .start()
-    .then(() => {
-        /* done */
-    })
-    .catch(err => console.error(err));
-
-process.on("SIGINT", () => {
-    // Clean up on CTRL-C
-    device
-        .stop()
-        .then(() => {
-            // Pragmatic way to make sure the storage is correctly closed before the process ends.
-            storage
-                .close()
-                .then(() => process.exit(0))
-                .catch(err => console.error(err));
-        })
-        .catch(err => console.error(err));
-});