@matter/nodejs-shell 0.11.0-alpha.0-20241007-547af42a8

package/src/shell/cmd_cluster-commands.ts

@@ -0,0 +1,174 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "@matter/general";
+import { ClusterModel, CommandModel, MatterModel } from "@matter/model";
+import { ValidationError } from "@project-chip/matter.js/common";
+import { ClusterId } from "@project-chip/matter.js/datatype";
+import type { Argv } from "yargs";
+import { MatterNode } from "../MatterNode";
+import { convertJsonDataWithModel } from "../util/Json";
+import { camelize } from "../util/String";
+
+function generateAllCommandHandlersForCluster(yargs: Argv, theNode: MatterNode) {
+    MatterModel.standard.clusters.forEach(cluster => {
+        yargs = generateClusterCommandHandlers(yargs, cluster, theNode);
+    });
+    return yargs;
+}
+
+function generateClusterCommandHandlers(yargs: Argv, cluster: ClusterModel, theNode: MatterNode) {
+    if (cluster.id === undefined) {
+        return yargs;
+    }
+    yargs = yargs.command(
+        [cluster.name.toLowerCase(), `0x${cluster.id.toString(16)}`],
+        `Invoke ${cluster.name} commands`,
+        yargs => {
+            cluster.commands.forEach(command => {
+                yargs = generateCommandHandler(yargs, cluster.id, cluster.name, command, theNode);
+            });
+            return yargs;
+        },
+        async (argv: any) => {
+            argv.unhandled = true;
+        },
+    );
+
+    return yargs;
+}
+
+function generateCommandHandler(
+    yargs: Argv,
+    clusterId: number,
+    clusterName: string,
+    command: CommandModel,
+    theNode: MatterNode,
+) {
+    //console.log("Generating command handler for ", command.name, JSON.stringify(command));
+    //console.log(command.definingModel);
+
+    if (command.definingModel !== undefined) {
+        // If command has parameters for the call
+        return yargs.command(
+            [`${command.name.toLowerCase()} <value> <nodeId> <endpointId>`, `0x${command.id.toString(16)}`],
+            `Invoke ${clusterName}.${command.name} command`,
+            yargs =>
+                yargs
+                    .positional("value", {
+                        describe: "value to write as JSON value",
+                        type: "string",
+                        demandOption: true,
+                    })
+                    .positional("endpoint-id", {
+                        describe: "endpoint id to write to",
+                        type: "number",
+                        demandOption: true,
+                    })
+                    .positional("node-id", {
+                        describe: "node id to write t.",
+                        type: "string",
+                        demandOption: true,
+                    }),
+            async argv => {
+                const { nodeId, endpointId, value } = argv;
+
+                let parsedValue: any;
+                try {
+                    parsedValue = JSON.parse(value);
+                } catch (error) {
+                    try {
+                        parsedValue = JSON.parse(`"${value}"`);
+                    } catch (innerError) {
+                        console.log(`ERROR: Could not parse value ${value} as JSON.`);
+                        return;
+                    }
+                }
+
+                await executeCommand(theNode, nodeId, endpointId, clusterId, command, parsedValue);
+            },
+        );
+    }
+
+    // Command has no parameters for the call
+    return yargs.command(
+        [`${command.name.toLowerCase()} <nodeId> <endpointId>`, `0x${command.id.toString(16)}`],
+        `Invoke ${clusterName}.${command.name} command`,
+        yargs =>
+            yargs
+                .positional("endpoint-id", {
+                    describe: "endpoint id to write to",
+                    type: "number",
+                    demandOption: true,
+                })
+                .positional("node-id", {
+                    describe: "node id to write t.",
+                    type: "string",
+                    demandOption: true,
+                }),
+        async argv => {
+            const { nodeId, endpointId } = argv;
+            await executeCommand(theNode, nodeId, endpointId, clusterId, command);
+        },
+    );
+}
+
+async function executeCommand(
+    theNode: MatterNode,
+    nodeId: string,
+    endpointId: number,
+    clusterId: number,
+    command: CommandModel,
+    requestData?: any,
+) {
+    const commandName = camelize(command.name);
+
+    const node = (await theNode.connectAndGetNodes(nodeId))[0];
+
+    const clusterClient = node.getDeviceById(endpointId)?.getClusterClientById(ClusterId(clusterId));
+    if (clusterClient === undefined) {
+        console.log(`ERROR: Cluster ${node.nodeId.toString()}/${endpointId}/${clusterId} not found.`);
+        return;
+    }
+    if (clusterClient.commands[commandName] == undefined) {
+        console.log(`ERROR: Command ${node.nodeId.toString()}/${endpointId}/${clusterId}/${command.id} not supported.`);
+        return;
+    }
+    try {
+        if (requestData !== undefined) {
+            requestData = convertJsonDataWithModel(command, requestData);
+        }
+
+        const result = await clusterClient.commands[commandName](requestData);
+        console.log(
+            `Command ${command.name} ${node.nodeId.toString()}/${endpointId}/${clusterId}/${command.id} invoked ${requestData ? `with ${Logger.toJSON(requestData)}` : ""}`,
+        );
+        if (result !== undefined) {
+            console.log(`Result: ${Logger.toJSON(result)}`);
+        }
+    } catch (error) {
+        if (error instanceof ValidationError) {
+            console.log(
+                `ERROR: Could not validate data for command ${command.name} with ${Logger.toJSON(requestData)}: ${error}${error.fieldName !== undefined ? ` in field ${error.fieldName}` : ""}`,
+            );
+        } else {
+            console.log(
+                `ERROR: Could not invoke command ${command.name} ${requestData ? `with ${Logger.toJSON(requestData)}` : ""}: ${error}`,
+            );
+        }
+    }
+}
+
+export default function cmdCommands(theNode: MatterNode) {
+    return {
+        command: ["commands", "c"],
+        describe: "Invoke commands",
+        builder: (yargs: Argv) => generateAllCommandHandlersForCluster(yargs, theNode),
+        handler: async (argv: any) => {
+            argv.unhandled = true;
+        },
+    };
+}

package/src/shell/cmd_cluster-events.ts

@@ -0,0 +1,99 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "@matter/general";
+import { ClusterModel, EventModel, MatterModel } from "@matter/model";
+import { SupportedEventClient } from "@project-chip/matter.js/cluster";
+import { ClusterId } from "@project-chip/matter.js/datatype";
+import type { Argv } from "yargs";
+import { MatterNode } from "../MatterNode";
+import { camelize } from "../util/String";
+
+function generateAllEventHandlersForCluster(yargs: Argv, theNode: MatterNode) {
+    MatterModel.standard.clusters.forEach(cluster => {
+        yargs = generateClusterEventHandlers(yargs, cluster, theNode);
+    });
+    return yargs;
+}
+
+function generateClusterEventHandlers(yargs: Argv, cluster: ClusterModel, theNode: MatterNode) {
+    if (cluster.id === undefined) {
+        return yargs;
+    }
+    yargs = yargs.command(
+        [cluster.name.toLowerCase(), `0x${cluster.id.toString(16)}`],
+        `Read ${cluster.name} events`,
+        yargs => {
+            cluster.events.forEach(event => {
+                yargs = generateEventHandler(yargs, cluster.id, cluster.name, event, theNode);
+            });
+            return yargs;
+        },
+        async (argv: any) => {
+            argv.unhandled = true;
+        },
+    );
+
+    return yargs;
+}
+
+function generateEventHandler(
+    yargs: Argv,
+    clusterId: number,
+    clusterName: string,
+    event: EventModel,
+    theNode: MatterNode,
+) {
+    //console.log("Generating event handler for ", event.name, JSON.stringify(event));
+    const eventName = camelize(event.name);
+    return yargs.command(
+        [`${event.name.toLowerCase()} <node-id> <endpoint-id>`, `0x${event.id.toString(16)}`],
+        `Read ${clusterName}.${event.name} event`,
+        yargs =>
+            yargs
+                .positional("endpoint-id", {
+                    describe: "endpoint id to read",
+                    type: "number",
+                    demandOption: true,
+                })
+                .positional("node-id", {
+                    describe: "node id to read",
+                    type: "string",
+                    demandOption: true,
+                }),
+        async argv => {
+            const { nodeId, endpointId } = argv;
+            const node = (await theNode.connectAndGetNodes(nodeId))[0];
+
+            const clusterClient = node.getDeviceById(endpointId)?.getClusterClientById(ClusterId(clusterId));
+            if (clusterClient === undefined) {
+                console.log(`ERROR: Cluster ${node.nodeId.toString()}/${endpointId}/${clusterId} not found.`);
+                return;
+            }
+            const eventClient = clusterClient.events[eventName];
+            if (!(eventClient instanceof SupportedEventClient)) {
+                console.log(
+                    `ERROR: Event ${node.nodeId.toString()}/${endpointId}/${clusterId}/${event.id} not supported.`,
+                );
+                return;
+            }
+            console.log(
+                `Event value for ${eventName} ${node.nodeId.toString()}/${endpointId}/${clusterId}/${event.id}: ${Logger.toJSON(await eventClient.get())}`,
+            );
+        },
+    );
+}
+
+export default function cmdEvents(theNode: MatterNode) {
+    return {
+        command: ["events", "e"],
+        describe: "Read events",
+        builder: (yargs: Argv) => generateAllEventHandlersForCluster(yargs, theNode),
+        handler: async (argv: any) => {
+            argv.unhandled = true;
+        },
+    };
+}

package/src/shell/cmd_commission.ts

@@ -0,0 +1,273 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger, MatterError } from "@matter/general";
+import { NodeCommissioningOptions } from "@project-chip/matter.js";
+import { BasicInformationCluster, DescriptorCluster, GeneralCommissioning } from "@project-chip/matter.js/cluster";
+import { NodeId } from "@project-chip/matter.js/datatype";
+import { ManualPairingCodeCodec, QrCode } from "@project-chip/matter.js/schema";
+import type { Argv } from "yargs";
+import { MatterNode } from "../MatterNode";
+import { createDiagnosticCallbacks } from "./cmd_nodes";
+
+export default function commands(theNode: MatterNode) {
+    return {
+        command: "commission",
+        describe: "Handle device commissioning",
+        builder: (yargs: Argv) =>
+            yargs
+                // Pair
+                .command("pair", "Pair with a matter device", yargs => {
+                    return (
+                        yargs
+                            // Pair
+                            .command(
+                                "* [node-id] [ip:[port]]",
+                                "Commission a matter device",
+                                yargs => {
+                                    return yargs
+                                        .positional("node-id", {
+                                            describe: "node id",
+                                            default: undefined,
+                                            type: "string",
+                                        })
+                                        .positional("ip", {
+                                            describe: "ip address",
+                                            default: undefined,
+                                            type: "string",
+                                        })
+                                        .positional("port", {
+                                            describe: "ip port",
+                                            default: undefined,
+                                            type: "number",
+                                        });
+                                },
+                                async argv => {
+                                    const {
+                                        pairingCode,
+                                        nodeId: nodeIdStr,
+                                        ipPort,
+                                        ip,
+                                        ble = false,
+                                        instanceId,
+                                    } = argv;
+                                    let { setupPinCode, discriminator, shortDiscriminator } = argv;
+
+                                    if (typeof pairingCode === "string") {
+                                        const { shortDiscriminator: pairingCodeShortDiscriminator, passcode } =
+                                            ManualPairingCodeCodec.decode(pairingCode);
+                                        shortDiscriminator = pairingCodeShortDiscriminator;
+                                        setupPinCode = passcode;
+                                        discriminator = undefined;
+                                    } else if (discriminator === undefined && shortDiscriminator === undefined) {
+                                        discriminator = 3840;
+                                    }
+
+                                    const nodeId = nodeIdStr !== undefined ? NodeId(BigInt(nodeIdStr)) : undefined;
+                                    await theNode.start();
+                                    if (theNode.commissioningController === undefined) {
+                                        throw new Error("CommissioningController not initialized");
+                                    }
+
+                                    const options = {
+                                        discovery: {
+                                            knownAddress:
+                                                ip !== undefined && ipPort !== undefined
+                                                    ? { ip, port: ipPort, type: "udp" }
+                                                    : undefined,
+                                            identifierData:
+                                                instanceId !== undefined
+                                                    ? { instanceId }
+                                                    : discriminator !== undefined
+                                                      ? { longDiscriminator: discriminator }
+                                                      : shortDiscriminator !== undefined
+                                                        ? { shortDiscriminator }
+                                                        : {},
+                                            discoveryCapabilities: {
+                                                ble,
+                                                onIpNetwork: true,
+                                            },
+                                        },
+                                        passcode: setupPinCode,
+                                        ...createDiagnosticCallbacks(),
+                                    } as NodeCommissioningOptions;
+
+                                    options.commissioning = {
+                                        nodeId: nodeId !== undefined ? NodeId(nodeId) : undefined,
+                                        regulatoryLocation: GeneralCommissioning.RegulatoryLocationType.Outdoor, // Set to the most restrictive if relevant
+                                        regulatoryCountryCode: "XX",
+                                    };
+
+                                    console.log(Logger.toJSON(options));
+
+                                    if (theNode.Store.has("WiFiSsid") && theNode.Store.has("WiFiPassword")) {
+                                        options.commissioning.wifiNetwork = {
+                                            wifiSsid: await theNode.Store.get<string>("WiFiSsid", ""),
+                                            wifiCredentials: await theNode.Store.get<string>("WiFiPassword", ""),
+                                        };
+                                    }
+                                    if (
+                                        theNode.Store.has("ThreadName") &&
+                                        theNode.Store.has("ThreadOperationalDataset")
+                                    ) {
+                                        options.commissioning.threadNetwork = {
+                                            networkName: await theNode.Store.get<string>("ThreadName", ""),
+                                            operationalDataset: await theNode.Store.get<string>(
+                                                "ThreadOperationalDataset",
+                                                "",
+                                            ),
+                                        };
+                                    }
+
+                                    const commissionedNodeId =
+                                        await theNode.commissioningController.commissionNode(options);
+
+                                    console.log("Commissioned Node:", commissionedNodeId);
+
+                                    const node = theNode.commissioningController.getPairedNode(commissionedNodeId);
+                                    if (node === undefined) {
+                                        // Should not happen
+                                        throw new MatterError("Node not found after commissioning.");
+                                    }
+
+                                    // 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
+
+                                    // 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!");
+                                    }
+                                },
+                            )
+                            .options({
+                                pairingCode: {
+                                    describe: "pairing code",
+                                    default: undefined,
+                                    type: "string",
+                                },
+                                setupPinCode: {
+                                    describe: "setup pin code",
+                                    default: 20202021,
+                                    type: "number",
+                                },
+                                instanceId: {
+                                    alias: "i",
+                                    describe: "instance id",
+                                    type: "string",
+                                },
+                                discriminator: {
+                                    alias: "d",
+                                    description: "Long discriminator",
+                                    type: "number",
+                                },
+                                shortDiscriminator: {
+                                    alias: "s",
+                                    description: "Short discriminator",
+                                    type: "number",
+                                },
+                                ble: {
+                                    alias: "b",
+                                    description: "Also discover over BLE",
+                                    type: "boolean",
+                                    default: false,
+                                },
+                            })
+                    );
+                })
+                .command(
+                    "open-basic-window <node-id> [timeout]",
+                    "Open a basic commissioning window",
+                    yargs => {
+                        return yargs
+                            .positional("node-id", {
+                                describe: "node id",
+                                type: "string",
+                                demandOption: true,
+                            })
+                            .positional("timeout", {
+                                describe: "timeout in seconds",
+                                type: "number",
+                                default: 900,
+                            });
+                    },
+                    async argv => {
+                        const { nodeId, timeout = 900 } = argv;
+                        await theNode.start();
+                        const node = (await theNode.connectAndGetNodes(nodeId, { autoSubscribe: false }))[0];
+
+                        await node.openBasicCommissioningWindow(timeout);
+
+                        console.log(`Basic Commissioning Window for node ${nodeId} opened`);
+                    },
+                )
+                .command(
+                    "open-enhanced-window <node-id> [timeout]",
+                    "Open a enhanced commissioning window",
+                    yargs => {
+                        return yargs
+                            .positional("node-id", {
+                                describe: "node id",
+                                type: "string",
+                                demandOption: true,
+                            })
+                            .positional("timeout", {
+                                describe: "timeout in seconds",
+                                type: "number",
+                                default: 900,
+                            });
+                    },
+                    async argv => {
+                        await theNode.start();
+                        const { nodeId, timeout = 900 } = argv;
+                        const node = (await theNode.connectAndGetNodes(nodeId, { autoSubscribe: false }))[0];
+                        const data = await node.openEnhancedCommissioningWindow(timeout);
+
+                        console.log(`Enhanced Commissioning Window for node ${nodeId} opened`);
+                        const { qrPairingCode, manualPairingCode } = data;
+
+                        console.log(QrCode.get(qrPairingCode));
+                        console.log(
+                            `QR Code URL: https://project-chip.github.io/connectedhomeip/qrcode.html?data=${qrPairingCode}`,
+                        );
+                        console.log(`Manual pairing code: ${manualPairingCode}`);
+                    },
+                )
+                .command(
+                    "unpair <node-id>",
+                    "Unpair/Decommission a node",
+                    yargs => {
+                        return yargs.positional("node-id", {
+                            describe: "node id",
+                            type: "string",
+                            demandOption: true,
+                        });
+                    },
+                    async argv => {
+                        await theNode.start();
+                        const { nodeId } = argv;
+                        const node = (await theNode.connectAndGetNodes(nodeId, { autoSubscribe: false }))[0];
+                        await node.decommission();
+                    },
+                ),
+        handler: async (argv: any) => {
+            argv.unhandled = true;
+        },
+    };
+}