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

package/src/examples/ControllerNode.ts

@@ -0,0 +1,305 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * This example shows how to create a Matter controller to pair with a device and interfact with it.
+ * It can be used as CLI script, but is more thought as a starting point for your own controller implementation
+ * because you need to adjust the code in any way depending on your use case.
+ */
+
+import { Environment, Logger, singleton, StorageService, Time } from "@matter/main";
+import { NodeJsBle } from "@matter/nodejs-ble";
+import { NodeId } from "@matter/types";
+import { CommissioningController, NodeCommissioningOptions } from "@project-chip/matter.js";
+import { Ble } from "@project-chip/matter.js/ble";
+import {
+    BasicInformationCluster,
+    ClusterClientObj,
+    DescriptorCluster,
+    GeneralCommissioning,
+    OnOff,
+} from "@project-chip/matter.js/cluster";
+import { CommissioningOptions } from "@project-chip/matter.js/protocol";
+import { ManualPairingCodeCodec } from "@project-chip/matter.js/schema";
+import { NodeStateInformation } from "../../../matter.js/dist/esm/device/PairedNode.js";
+
+const logger = Logger.get("Controller");
+
+const environment = Environment.default;
+
+if (environment.vars.get("ble")) {
+    // Initialize Ble
+    Ble.get = singleton(
+        () =>
+            new NodeJsBle({
+                hciId: environment.vars.number("ble-hci-id"),
+            }),
+    );
+}
+
+const storageService = environment.get(StorageService);
+
+console.log(`Storage location: ${storageService.location} (Directory)`);
+logger.info(
+    '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.',
+);
+
+class ControllerNode {
+    async start() {
+        logger.info(`node-matter Controller started`);
+
+        /**
+         * 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 controllerStorage = (await storageService.open("controller")).createContext("data");
+        const ip = (await controllerStorage.has("ip"))
+            ? await controllerStorage.get<string>("ip")
+            : environment.vars.string("ip");
+        const port = (await controllerStorage.has("port"))
+            ? await controllerStorage.get<number>("port")
+            : environment.vars.number("port");
+        const uniqueId = (await controllerStorage.has("uniqueid"))
+            ? await controllerStorage.get<string>("uniqueid")
+            : (environment.vars.string("uniqueid") ?? Time.nowMs().toString());
+        await controllerStorage.set("uniqueid", uniqueId);
+
+        const pairingCode = environment.vars.string("pairingcode");
+        let longDiscriminator, setupPin, shortDiscriminator;
+        if (pairingCode !== undefined) {
+            const pairingCodeCodec = ManualPairingCodeCodec.decode(pairingCode);
+            shortDiscriminator = pairingCodeCodec.shortDiscriminator;
+            longDiscriminator = undefined;
+            setupPin = pairingCodeCodec.passcode;
+            logger.debug(`Data extracted from pairing code: ${Logger.toJSON(pairingCodeCodec)}`);
+        } else {
+            longDiscriminator =
+                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));
+        }
+        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",
+            );
+        }
+
+        // Collect commissioning options from commandline parameters
+        const commissioningOptions: CommissioningOptions = {
+            regulatoryLocation: GeneralCommissioning.RegulatoryLocationType.IndoorOutdoor,
+            regulatoryCountryCode: "XX",
+        };
+
+        let ble = false;
+        if (environment.vars.get("ble")) {
+            ble = true;
+            const wifiSsid = environment.vars.string("ble-wifi-ssid");
+            const wifiCredentials = environment.vars.string("ble-wifi-credentials");
+            const threadNetworkName = environment.vars.string("ble-thread-networkname");
+            const threadOperationalDataset = environment.vars.string("ble-thread-operationaldataset");
+            if (wifiSsid !== undefined && wifiCredentials !== undefined) {
+                logger.info(`Registering Commissioning over BLE with WiFi: ${wifiSsid}`);
+                commissioningOptions.wifiNetwork = {
+                    wifiSsid: wifiSsid,
+                    wifiCredentials: wifiCredentials,
+                };
+            }
+            if (threadNetworkName !== undefined && threadOperationalDataset !== undefined) {
+                logger.info(`Registering Commissioning over BLE with Thread: ${threadNetworkName}`);
+                commissioningOptions.threadNetwork = {
+                    networkName: threadNetworkName,
+                    operationalDataset: threadOperationalDataset,
+                };
+            }
+        }
+
+        /**
+         * Create Matter Server and Controller Node
+         *
+         * To allow the device to be announced, found, paired and operated we need a MatterServer instance and add a
+         * CommissioningController to it and add the just created device instance to it.
+         * The Controller 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.
+         */
+
+        const commissioningController = new CommissioningController({
+            environment: {
+                environment,
+                id: uniqueId,
+            },
+            autoConnect: false,
+        });
+
+        /**
+         * 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 commissioningController.start();
+
+        if (!commissioningController.isCommissioned()) {
+            const options = {
+                commissioning: commissioningOptions,
+                discovery: {
+                    knownAddress: ip !== undefined && port !== undefined ? { ip, port, type: "udp" } : undefined,
+                    identifierData:
+                        longDiscriminator !== undefined
+                            ? { longDiscriminator }
+                            : shortDiscriminator !== undefined
+                              ? { shortDiscriminator }
+                              : {},
+                    discoveryCapabilities: {
+                        ble,
+                    },
+                },
+                passcode: setupPin,
+            } as NodeCommissioningOptions;
+            logger.info(`Commissioning ... ${Logger.toJSON(options)}`);
+            const nodeId = await commissioningController.commissionNode(options);
+
+            console.log(`Commissioning successfully done with nodeId ${nodeId}`);
+        }
+
+        /**
+         * TBD
+         */
+        try {
+            const nodes = commissioningController.getCommissionedNodes();
+            console.log("Found commissioned nodes:", Logger.toJSON(nodes));
+
+            const nodeId = NodeId(environment.vars.number("nodeid") ?? nodes[0]);
+            if (!nodes.includes(nodeId)) {
+                throw new Error(`Node ${nodeId} not found in commissioned nodes`);
+            }
+
+            const node = await commissioningController.connectNode(nodeId, {
+                attributeChangedCallback: (
+                    peerNodeId,
+                    { path: { nodeId, clusterId, endpointId, attributeName }, value },
+                ) =>
+                    console.log(
+                        `attributeChangedCallback ${peerNodeId}: Attribute ${nodeId}/${endpointId}/${clusterId}/${attributeName} changed to ${Logger.toJSON(
+                            value,
+                        )}`,
+                    ),
+                eventTriggeredCallback: (peerNodeId, { path: { nodeId, clusterId, endpointId, eventName }, events }) =>
+                    console.log(
+                        `eventTriggeredCallback ${peerNodeId}: Event ${nodeId}/${endpointId}/${clusterId}/${eventName} triggered with ${Logger.toJSON(
+                            events,
+                        )}`,
+                    ),
+                stateInformationCallback: (peerNodeId, info) => {
+                    switch (info) {
+                        case NodeStateInformation.Connected:
+                            console.log(`stateInformationCallback ${peerNodeId}: Node ${nodeId} connected`);
+                            break;
+                        case NodeStateInformation.Disconnected:
+                            console.log(`stateInformationCallback ${peerNodeId}: Node ${nodeId} disconnected`);
+                            break;
+                        case NodeStateInformation.Reconnecting:
+                            console.log(`stateInformationCallback ${peerNodeId}: Node ${nodeId} reconnecting`);
+                            break;
+                        case NodeStateInformation.WaitingForDeviceDiscovery:
+                            console.log(
+                                `stateInformationCallback ${peerNodeId}: Node ${nodeId} waiting for device discovery`,
+                            );
+                            break;
+                        case NodeStateInformation.StructureChanged:
+                            console.log(`stateInformationCallback ${peerNodeId}: Node ${nodeId} structure changed`);
+                            break;
+                        case NodeStateInformation.Decommissioned:
+                            console.log(`stateInformationCallback ${peerNodeId}: Node ${nodeId} decommissioned`);
+                            break;
+                    }
+                },
+            });
+
+            // Important: This is a temporary API to proof the methods working and this will change soon and is NOT stable!
+            // It is provided to proof the concept
+
+            node.logStructure();
+
+            // Example to initialize a ClusterClient and access concrete fields as API methods
+            const descriptor = node.getRootClusterClient(DescriptorCluster);
+            if (descriptor !== undefined) {
+                console.log(await descriptor.attributes.deviceTypeList.get()); // you can call that way
+                console.log(await descriptor.getServerListAttribute()); // or more convenient that way
+            } else {
+                console.log("No Descriptor Cluster found. This should never happen!");
+            }
+
+            // Example to subscribe to a field and get the value
+            const info = node.getRootClusterClient(BasicInformationCluster);
+            if (info !== undefined) {
+                console.log(await info.getProductNameAttribute()); // This call is executed remotely
+                //console.log(await info.subscribeProductNameAttribute(value => console.log("productName", value), 5, 30));
+                //console.log(await info.getProductNameAttribute()); // This call is resolved locally because we have subscribed to the value!
+            } else {
+                console.log("No BasicInformation Cluster found. This should never happen!");
+            }
+
+            // Example to get all Attributes of the commissioned node: */*/*
+            //const attributesAll = await interactionClient.getAllAttributes();
+            //console.log("Attributes-All:", Logger.toJSON(attributesAll));
+
+            // Example to get all Attributes of all Descriptor Clusters of the commissioned node: */DescriptorCluster/*
+            //const attributesAllDescriptor = await interactionClient.getMultipleAttributes([{ clusterId: DescriptorCluster.id} ]);
+            //console.log("Attributes-Descriptor:", JSON.stringify(attributesAllDescriptor, null, 2));
+
+            // Example to get all Attributes of the Basic Information Cluster of endpoint 0 of the commissioned node: 0/BasicInformationCluster/*
+            //const attributesBasicInformation = await interactionClient.getMultipleAttributes([{ endpointId: 0, clusterId: BasicInformationCluster.id} ]);
+            //console.log("Attributes-BasicInformation:", JSON.stringify(attributesBasicInformation, null, 2));
+
+            const devices = node.getDevices();
+            if (devices[0] && devices[0].number === 1) {
+                // Example to subscribe to all Attributes of endpoint 1 of the commissioned node: */*/*
+                //await interactionClient.subscribeMultipleAttributes([{ endpointId: 1, /* subscribe anything from endpoint 1 */ }], 0, 180, data => {
+                //    console.log("Subscribe-All Data:", Logger.toJSON(data));
+                //});
+
+                const onOff: ClusterClientObj<OnOff.Complete> | undefined = devices[0].getClusterClient(OnOff.Complete);
+                if (onOff !== undefined) {
+                    let onOffStatus = await onOff.getOnOffAttribute();
+                    console.log("initial onOffStatus", onOffStatus);
+
+                    onOff.addOnOffAttributeListener(value => {
+                        console.log("subscription onOffStatus", value);
+                        onOffStatus = value;
+                    });
+                    // read data every minute to keep up the connection to show the subscription is working
+                    setInterval(() => {
+                        onOff
+                            .toggle()
+                            .then(() => {
+                                onOffStatus = !onOffStatus;
+                                console.log("onOffStatus", onOffStatus);
+                            })
+                            .catch(error => logger.error(error));
+                    }, 60000);
+                }
+            }
+        } finally {
+            //await matterServer.close(); // Comment out when subscribes are used, else the connection will be closed
+            setTimeout(() => process.exit(0), 1000000);
+        }
+    }
+}
+
+new ControllerNode().start().catch(error => logger.error(error));

package/src/examples/DeviceNode.ts

@@ -0,0 +1,198 @@
+#!/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 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 {
+    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";
+
+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,
+        },
+
+        // 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,
+        },
+    });
+
+    /**
+     * 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 and events 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, ideally blink a light every 0.5s ...`);
+    });
+
+    endpoint.events.identify.stopIdentifying.on(() => {
+        console.log(`Stop identify logic ...`);
+    });
+
+    endpoint.events.onOff.onOff$Changed.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();
+}
+
+main().catch(error => console.error(error));
+
+/*********************************************************************************************************
+ * Convenience Methods
+ *********************************************************************************************************/
+
+/** 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)}`);
+}
+
+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 isSocket = await deviceStorage.get("isSocket", environment.vars.get("type") === "socket");
+    if (await 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") ?? (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 ${isSocket ? "Socket" : "Light"}`;
+    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,
+        isSocket,
+        uniqueid: uniqueId,
+    });
+
+    return {
+        isSocket,
+        deviceName,
+        vendorName,
+        passcode,
+        discriminator,
+        vendorId,
+        productName,
+        productId,
+        port,
+        uniqueId,
+    };
+}