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

package/src/shell/cmd_config.ts

@@ -0,0 +1,366 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "@matter/general";
+import { Argv } from "yargs";
+import { MatterNode } from "../MatterNode";
+import { setLogLevel } from "../app";
+
+export default function commands(theNode: MatterNode) {
+    return {
+        command: "config",
+        describe: "Manage global configuration",
+        builder: (yargs: Argv) =>
+            yargs
+                // Console LogLevel
+                .command("loglevel", "Manage Console and File LogLevels", yargs => {
+                    return yargs
+                        .command(
+                            ["* [action]", "* [type] [ action]"],
+                            "get/delete console or file log level",
+                            yargs => {
+                                return yargs
+                                    .positional("type", {
+                                        describe: "type to set the loglevel for",
+                                        choices: ["console", "file"] as const,
+                                        default: "console",
+                                        type: "string",
+                                    })
+                                    .positional("action", {
+                                        describe: "get/delete",
+                                        choices: ["get", "delete"] as const,
+                                        default: "get",
+                                        type: "string",
+                                    });
+                            },
+                            async argv => doLogLevel(theNode, argv),
+                        )
+                        .command(
+                            "set <value>",
+                            "set console log level",
+                            yargs => {
+                                return yargs
+                                    .positional("type", {
+                                        describe: "type to set the loglevel for",
+                                        choices: ["console", "file"] as const,
+                                        default: "console",
+                                        type: "string",
+                                    })
+                                    .positional("value", {
+                                        describe: "log level to set",
+                                        type: "string",
+                                        choices: ["fatal", "error", "warn", "info", "debug"] as const,
+                                        demandOption: true,
+                                    });
+                            },
+                            async argv => doLogLevel(theNode, { action: "set", ...argv }),
+                        );
+                })
+
+                // LogFile name
+                .command("logfile", "Manage Logfile path", yargs => {
+                    return yargs
+                        .command(
+                            "* [action]",
+                            "get/delete logfile path",
+                            yargs => {
+                                return yargs.positional("action", {
+                                    describe: "get/delete",
+                                    choices: ["get", "delete"] as const,
+                                    default: "get",
+                                    type: "string",
+                                });
+                            },
+                            async argv => doLogfilePath(theNode, argv),
+                        )
+                        .command(
+                            "set <value>",
+                            "set logfile path",
+                            yargs => {
+                                return yargs.positional("value", {
+                                    describe: "logfile path to set",
+                                    type: "string",
+                                    demandOption: true,
+                                });
+                            },
+                            async argv => doLogfilePath(theNode, { action: "set", ...argv }),
+                        );
+                })
+
+                // BLE HCI number (Linux)
+                .command("ble-hci", "Manage BLE HCI ID (Linux)", yargs => {
+                    return yargs
+                        .command(
+                            "* [action]",
+                            "get/delete BLE HCI ID of the device (Linux only)",
+                            yargs => {
+                                return yargs.positional("action", {
+                                    describe: "get/delete",
+                                    choices: ["get", "delete"] as const,
+                                    default: "get",
+                                    type: "string",
+                                });
+                            },
+                            async argv => doBleHci(theNode, argv),
+                        )
+                        .command(
+                            "set <value>",
+                            "set BLE HCI ID of the device (Linux only)",
+                            yargs => {
+                                return yargs.positional("value", {
+                                    describe: "HCI ID to set",
+                                    type: "number",
+                                    demandOption: true,
+                                });
+                            },
+                            async argv => doBleHci(theNode, { action: "set", ...argv }),
+                        );
+                })
+
+                // Commissioning Wi-Fi credentials
+                .command("wifi-credentials", "Manage Wi-Fi credentials used in commissioning process", yargs => {
+                    return yargs
+                        .command(
+                            "* [action]",
+                            "get/set Wi-Fi credentials",
+                            yargs => {
+                                return yargs.positional("action", {
+                                    describe: "get/delete",
+                                    choices: ["get", "delete"] as const,
+                                    default: "get",
+                                    type: "string",
+                                });
+                            },
+                            async argv => doWifiCredentials(theNode, argv),
+                        )
+                        .command(
+                            "set <wifi-ssid> <wifi-password>",
+                            "set Wi-Fi credentials",
+                            yargs => {
+                                return yargs
+                                    .positional("wifi-ssid", {
+                                        describe: "SSID of the Wifi network to commission",
+                                        type: "string",
+                                        demandOption: true,
+                                    })
+                                    .positional("wifi-password", {
+                                        describe: "Password of the Wifi network to commission",
+                                        type: "string",
+                                        demandOption: true,
+                                    });
+                            },
+                            async argv => doWifiCredentials(theNode, { action: "set", ...argv }),
+                        );
+                })
+
+                // Commissioning Thread credentials
+                .command("thread-credentials", "Manage Thread credentials used in commissioning process", yargs => {
+                    return yargs
+                        .command(
+                            "* [action]",
+                            "get/set thread network credentials",
+                            yargs => {
+                                return yargs.positional("action", {
+                                    describe: "get/delete",
+                                    choices: ["get", "delete"] as const,
+                                    default: "get",
+                                    type: "string",
+                                });
+                            },
+                            async argv => doThreadCredentials(theNode, argv),
+                        )
+                        .command(
+                            "set <thread-name> <thread-operational-dataset>",
+                            "set thread networkcredentials",
+                            yargs => {
+                                return yargs
+                                    .positional("thread-name", {
+                                        describe: "Thread network name to commission",
+                                        type: "string",
+                                        demandOption: true,
+                                    })
+                                    .positional("thread-operational-dataset", {
+                                        describe: "Thread network operational dataset to commission",
+                                        type: "string",
+                                        demandOption: true,
+                                    });
+                            },
+                            argv => doThreadCredentials(theNode, { action: "set", ...argv }),
+                        );
+                }),
+        handler: async (argv: any) => {
+            argv.unhandled = true;
+        },
+    };
+}
+
+async function doLogLevel(
+    theNode: MatterNode,
+    args: {
+        action: string;
+        type: string;
+        value?: string;
+    },
+) {
+    const { action, value } = args;
+    const storageKey = args.type === "console" ? "LogLevel" : "LogLevelFile";
+    const logtype = args.type === "console" ? "Console" : "File";
+    switch (action) {
+        case "get":
+            console.log(`Current Loglevel for ${logtype}: ${await theNode.Store.get<string>(storageKey, "info")}`);
+            break;
+        case "set":
+            if (value === undefined) {
+                console.log(`Cannot change Loglevel for ${logtype}: New Loglevel value not provided`);
+                return;
+            }
+            await theNode.Store.set(storageKey, value);
+            console.log(`New Loglevel for ${logtype}:" ${value}"`);
+            setLogLevel(args.type === "console" ? "default" : "file", value);
+            break;
+        case "delete":
+            await theNode.Store.delete(storageKey);
+            console.log(`Loglevel for ${logtype}: Reset to "info"`);
+            setLogLevel(args.type === "console" ? "default" : "file", "info");
+            break;
+    }
+}
+
+async function doLogfilePath(
+    theNode: MatterNode,
+    args: {
+        action: string;
+        value?: string;
+    },
+) {
+    const { action, value } = args;
+    switch (action) {
+        case "get":
+            console.log(`Current Logfile Path: ${await theNode.Store.get<string>("LogFile", "-")}`);
+            break;
+        case "set":
+            if (value === undefined) {
+                console.log(`Cannot change Logfile path: new path not provided`);
+                return;
+            }
+            await theNode.Store.set("LogFile", value);
+            console.log(`New LogFile path:" ${value}". Please restart the shell for teh changes to take effect.`);
+            break;
+        case "delete":
+            await theNode.Store.delete("LogFile");
+            console.log(`LogFile path removed. Please restart the shell for teh changes to take effect.`);
+            break;
+    }
+}
+
+async function doBleHci(
+    theNode: MatterNode,
+    args: {
+        action: string;
+        value?: number;
+    },
+) {
+    const { action, value } = args;
+    switch (action) {
+        case "get":
+            console.log(`Current BLE HCI ID: ${await theNode.Store.get<number>("BleHciId", 0)}`);
+            break;
+        case "set":
+            if (value === undefined) {
+                console.log(`Cannot change HCI ID: New HCI ID value not provided`);
+                return;
+            }
+            await theNode.Store.set("BleHciId", value);
+            console.log(`New HCI ID:" ${value}". Please restart the shell for teh changes to take effect.`);
+            break;
+        case "delete":
+            await theNode.Store.delete("BleHciId");
+            console.log(`BLE HCI ID reset to default (0). Please restart the shell for teh changes to take effect.`);
+            break;
+    }
+}
+
+async function doWifiCredentials(
+    theNode: MatterNode,
+    args: {
+        action: string;
+        wifiSsid?: string;
+        wifiPassword?: string;
+    },
+) {
+    const { action, wifiSsid, wifiPassword } = args;
+    switch (action) {
+        case "get":
+            console.log(
+                `Current Wifi-Credentials: SSID="${await theNode.Store.get<string>(
+                    "WiFiSsid",
+                    "-",
+                )}", Password="${Logger.maskString(await theNode.Store.get<string>("WiFiPassword", ""))}"`,
+            );
+            break;
+        case "set":
+            if (wifiSsid === undefined || wifiPassword === undefined) {
+                console.log(`Cannot change Wi-Fi credentials: New values not provided`);
+                return;
+            }
+            await theNode.Store.set("WiFiSsid", wifiSsid);
+            await theNode.Store.set("WiFiPassword", wifiPassword);
+            console.log(
+                `New Wifi-Credentials: SSID="${theNode.Store.get<string>(
+                    "WiFiSsid",
+                    "-",
+                )}", Password="${Logger.maskString(await theNode.Store.get<string>("WiFiPassword"))}"`,
+            );
+            break;
+        case "delete":
+            await theNode.Store.delete("WiFiSsid");
+            await theNode.Store.delete("WiFiPassword");
+            console.log(`Wi-Fi credentials were deleted`);
+            break;
+    }
+}
+
+async function doThreadCredentials(
+    theNode: MatterNode,
+    args: {
+        action: string;
+        threadName?: string;
+        threadOperationalDataset?: string;
+    },
+) {
+    const { action, threadName, threadOperationalDataset } = args;
+    switch (action) {
+        case "get":
+            console.log(
+                `Current Thread network credentials: name="${await theNode.Store.get<string>(
+                    "ThreadName",
+                    "-",
+                )}", Operational-Dataset="${Logger.maskString(
+                    await theNode.Store.get<string>("ThreadOperationalDataset", ""),
+                )}"`,
+            );
+            break;
+        case "set":
+            if (threadName === undefined || threadOperationalDataset === undefined) {
+                console.log(`Cannot change Thread network credentials: New values not provided`);
+                return;
+            }
+            await theNode.Store.set("ThreadName", threadName);
+            await theNode.Store.set("ThreadOperationalDataset", threadOperationalDataset);
+            console.log(
+                `New Wifi-Credentials: SSID="${await theNode.Store.get<string>(
+                    "ThreadName",
+                    "-",
+                )}", OperationalDataset="${Logger.maskString(await theNode.Store.get<string>("ThreadOperationalDataset"))}"`,
+            );
+            break;
+        case "delete":
+            await theNode.Store.delete("ThreadName");
+            await theNode.Store.delete("ThreadOperationalDataset");
+            console.log(`Thread network credentials were deleted`);
+            break;
+    }
+}

package/src/shell/cmd_discover.ts

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "@matter/general";
+import { CommissionableDeviceIdentifiers } from "@project-chip/matter.js/common";
+import { VendorId } from "@project-chip/matter.js/datatype";
+import { ManualPairingCodeCodec } from "@project-chip/matter.js/schema";
+import type { Argv } from "yargs";
+import { MatterNode } from "../MatterNode";
+
+export default function commands(theNode: MatterNode) {
+    return {
+        command: "discover",
+        describe: "Handle device discovery",
+        builder: (yargs: Argv) =>
+            yargs
+                // Pair
+                .command(
+                    "commissionable [timeout-seconds]",
+                    "Discover commissionable devices",
+                    () => {
+                        return yargs
+                            .positional("timeout-seconds", {
+                                describe: "Discovery timeout in seconds",
+                                default: 900,
+                                type: "number",
+                            })
+                            .options({
+                                pairingCode: {
+                                    describe: "pairing code",
+                                    default: undefined,
+                                    type: "string",
+                                },
+                                discriminator: {
+                                    alias: "d",
+                                    description: "Long discriminator",
+                                    default: undefined,
+                                    type: "number",
+                                },
+                                shortDiscriminator: {
+                                    alias: "s",
+                                    description: "Short discriminator",
+                                    default: undefined,
+                                    type: "number",
+                                },
+                                vendorId: {
+                                    alias: "v",
+                                    description: "Vendor ID",
+                                    default: undefined,
+                                    type: "number",
+                                },
+                                productId: {
+                                    alias: "p",
+                                    description: "Product ID",
+                                    default: undefined,
+                                    type: "number",
+                                },
+                                deviceType: {
+                                    alias: "t",
+                                    description: "Device Type",
+                                    default: undefined,
+                                    type: "number",
+                                },
+                                ble: {
+                                    alias: "b",
+                                    description: "Also discover over BLE",
+                                    default: false,
+                                    type: "boolean",
+                                },
+                            });
+                    },
+                    async argv => {
+                        const { ble = false, pairingCode, vendorId, productId, deviceType, timeoutSeconds } = argv;
+                        let { discriminator, shortDiscriminator } = argv;
+
+                        if (typeof pairingCode === "string") {
+                            const { shortDiscriminator: pairingCodeShortDiscriminator } =
+                                ManualPairingCodeCodec.decode(pairingCode);
+                            shortDiscriminator = pairingCodeShortDiscriminator;
+                            discriminator = undefined;
+                        }
+
+                        await theNode.start();
+                        if (theNode.commissioningController === undefined) {
+                            throw new Error("CommissioningController not initialized");
+                        }
+
+                        const identifierData: CommissionableDeviceIdentifiers =
+                            discriminator !== undefined
+                                ? { longDiscriminator: discriminator }
+                                : shortDiscriminator !== undefined
+                                  ? { shortDiscriminator }
+                                  : vendorId !== undefined
+                                    ? { vendorId: VendorId(vendorId) }
+                                    : productId !== undefined
+                                      ? { productId }
+                                      : deviceType !== undefined
+                                        ? { deviceType }
+                                        : {};
+
+                        console.log(
+                            `Discover devices with identifier ${Logger.toJSON(
+                                identifierData,
+                            )} for ${timeoutSeconds} seconds.`,
+                        );
+
+                        const results = await theNode.commissioningController.discoverCommissionableDevices(
+                            identifierData,
+                            {
+                                ble,
+                                onIpNetwork: true,
+                            },
+                            device => console.log(`Discovered device ${Logger.toJSON(device)}`),
+                            timeoutSeconds,
+                        );
+
+                        console.log(`Discovered ${results.length} devices`, results);
+                    },
+                ),
+        handler: async (argv: any) => {
+            argv.unhandled = true;
+        },
+    };
+}

package/src/shell/cmd_identify.ts

@@ -0,0 +1,51 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { IdentifyCluster } from "@project-chip/matter.js/cluster";
+import type { Argv } from "yargs";
+import { MatterNode } from "../MatterNode.js";
+
+export default function commands(theNode: MatterNode) {
+    return {
+        command: "identify [time] [node-id] [endpoint-id]",
+        describe:
+            "Trigger Identify command with given time (default 10s). Execute on one node or endpoint, else all onoff clusters will be controlled",
+        builder: (yargs: Argv) => {
+            return yargs
+                .positional("time", {
+                    describe: "time in seconds",
+                    default: 10,
+                    type: "number",
+                })
+                .positional("node-id", {
+                    describe: "node id",
+                    default: undefined,
+                    type: "string",
+                })
+                .positional("endpoint-id", {
+                    describe: "endpoint id",
+                    default: undefined,
+                    type: "number",
+                });
+        },
+
+        handler: async (argv: any) => {
+            const { nodeId, time = 10, endpointId } = argv;
+            await theNode.iterateNodeDevices(
+                await theNode.connectAndGetNodes(nodeId),
+                async (device, node) => {
+                    const identifyCluster = device.getClusterClient(IdentifyCluster);
+                    if (identifyCluster === undefined) {
+                        return;
+                    }
+                    console.log("Invoke Identify for", node.nodeId.toString());
+                    await identifyCluster.identify({ identifyTime: time });
+                },
+                endpointId,
+            );
+        },
+    };
+}