@project-chip/matter-node.js-examples 0.11.0-alpha.0-20240909-b3b29745 → 0.11.0-alpha.0-20241006-eccb81ae1

package/src/examples/ControllerNode.ts

@@ -1,318 +0,0 @@
-#!/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 needed modules from @project-chip/matter-node.js
- */
-// Include this first to auto-register Crypto, Network and Time Node.js implementations
-// Include this first to auto-register Crypto, Network and Time Node.js implementations
-import "@project-chip/matter-node.js";
-
-import { BleNode } from "@project-chip/matter-node-ble.js/ble";
-import { requireMinNodeVersion } from "@project-chip/matter-node.js/util";
-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 { NodeId } from "@project-chip/matter.js/datatype";
-import { NodeStateInformation } from "@project-chip/matter.js/device";
-import { Environment, StorageService } from "@project-chip/matter.js/environment";
-import { Logger } from "@project-chip/matter.js/log";
-import { CommissioningOptions } from "@project-chip/matter.js/protocol";
-import { ManualPairingCodeCodec } from "@project-chip/matter.js/schema";
-import { Time } from "@project-chip/matter.js/time";
-import { singleton } from "@project-chip/matter.js/util";
-
-const logger = Logger.get("Controller");
-
-requireMinNodeVersion(16);
-
-const environment = Environment.default;
-
-if (environment.vars.get("ble")) {
-    // Initialize Ble
-    Ble.get = singleton(
-        () =>
-            new BleNode({
-                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

@@ -1,202 +0,0 @@
-#!/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 needed modules from @project-chip/matter-node.js
- */
-// Include this first to auto-register Crypto, Network and Time Node.js implementations
-import "@project-chip/matter-node.js";
-
-import { requireMinNodeVersion } from "@project-chip/matter-node.js/util";
-import { DeviceTypeId, VendorId } from "@project-chip/matter.js/datatype";
-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);
-
-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,
-    };
-}