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

package/src/app.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env node
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { LogFormat, LogLevel, Logger, singleton } from "@matter/general";
+import { createFileLogger } from "@matter/nodejs";
+import { NodeJsBle } from "@matter/nodejs-ble";
+import { Ble } from "@matter/protocol";
+import yargs from "yargs/yargs";
+import { MatterNode } from "./MatterNode.js";
+import { Shell } from "./shell/Shell";
+
+const PROMPT = "matter> ";
+const logger = Logger.get("Shell");
+if (process.stdin?.isTTY) Logger.format = LogFormat.ANSI;
+
+let theNode: MatterNode;
+
+export function setLogLevel(identifier: string, level: string): void {
+    let logLevel = LogLevel.INFO;
+    switch (level) {
+        case "fatal":
+            logLevel = LogLevel.FATAL;
+            break;
+        case "error":
+            logLevel = LogLevel.ERROR;
+            break;
+        case "warn":
+            logLevel = LogLevel.WARN;
+            break;
+        case "debug":
+            logLevel = LogLevel.DEBUG;
+            break;
+    }
+    Logger.setDefaultLoglevelForLogger(identifier, logLevel);
+}
+
+/**
+ * @file Top level application for Matter Node.
+ */
+async function main() {
+    const yargsInstance = yargs(process.argv.slice(2))
+        .command(
+            "* [node-num] [node-type]",
+            "Matter Node Shell",
+            yargs => {
+                return yargs
+                    .positional("node-num", {
+                        describe: "Node number for storage",
+                        default: 0,
+                        type: "number",
+                    })
+                    .positional("node-type", {
+                        describe: "Type of the node",
+                        choices: ["controller"],
+                        default: "controller",
+                        type: "string",
+                    })
+                    .options({
+                        ble: {
+                            description: "Enable BLE support.",
+                            type: "boolean",
+                        },
+                        bleHciId: {
+                            description:
+                                "HCI ID of the BLE adapter to use. The provided value will be persisted for future runs.",
+                            type: "number",
+                            default: 0,
+                        },
+                        factoryReset: {
+                            description: "Factory-Reset storage of this node.",
+                            default: false,
+                            type: "boolean",
+                        },
+                        netInterface: {
+                            description: "Network interface to use for MDNS announcements and scanning.",
+                            type: "string",
+                            default: undefined,
+                        },
+                        logfile: {
+                            description:
+                                "Logfile to use to log to. By Default debug loglevel is logged to the file. The provided value will be persisted for future runs.",
+                            type: "string",
+                            default: undefined,
+                        },
+                    });
+            },
+            async argv => {
+                if (argv.help) return;
+
+                const { nodeNum, ble, bleHciId, nodeType, factoryReset, netInterface, logfile } = argv;
+
+                theNode = new MatterNode(nodeNum, netInterface);
+                await theNode.initialize(factoryReset);
+
+                if (logfile !== undefined) {
+                    await theNode.Store.set("LogFile", logfile);
+                }
+                if (theNode.Store.has("LogFile")) {
+                    const storedLogFileName = await theNode.Store.get<string>("LogFile");
+                    if (storedLogFileName !== undefined) {
+                        Logger.addLogger("file", await createFileLogger(storedLogFileName), {
+                            defaultLogLevel: await theNode.Store.get<LogLevel>("LoglevelFile", LogLevel.DEBUG),
+                            logFormat: LogFormat.PLAIN,
+                        });
+                    }
+                }
+                setLogLevel("default", await theNode.Store.get<string>("LogLevel", "info"));
+
+                const theShell = new Shell(theNode, nodeNum, PROMPT);
+
+                if (bleHciId !== undefined) {
+                    await theNode.Store.set("BleHciId", bleHciId);
+                }
+
+                if (ble) {
+                    const hciId = await theNode.Store.get<number>("BleHciId", 0);
+                    // Initialize Ble
+                    Ble.get = singleton(
+                        () =>
+                            new NodeJsBle({
+                                hciId,
+                            }),
+                    );
+                }
+
+                console.log(`Started Node #${nodeNum} (Type: ${nodeType}) ${ble ? "with" : "without"} BLE`);
+                theShell.start();
+            },
+        )
+        .version(false)
+        .scriptName("shell");
+    await yargsInstance.wrap(yargsInstance.terminalWidth()).parseAsync();
+}
+
+process.on("message", function (message) {
+    console.log(`Message to shell.ts: ${message}`);
+
+    switch (message) {
+        case "exit":
+            exit().catch(error => logger.error(error));
+    }
+});
+
+export async function exit(code = 0) {
+    await theNode?.close();
+    process.exit(code);
+}
+
+process.on("SIGINT", () => {
+    // Pragmatic way to make sure the storage is correctly closed before the process ends.
+    exit().catch(error => logger.error(error));
+});
+
+main().catch(error => logger.error(error));

package/src/shell/Shell.ts

@@ -0,0 +1,184 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterError } from "@matter/general";
+import { createWriteStream, readFileSync } from "fs";
+import readline from "node:readline";
+import yargs from "yargs/yargs";
+import { MatterNode } from "../MatterNode.js";
+import { exit } from "../app";
+import { commandlineParser } from "../util/CommandlineParser.js";
+import cmdAttributes from "./cmd_cluster-attributes";
+import cmdCommands from "./cmd_cluster-commands";
+import cmdEvents from "./cmd_cluster-events";
+import cmdCommission from "./cmd_commission.js";
+import cmdConfig from "./cmd_config.js";
+import cmdDiscover from "./cmd_discover.js";
+import cmdIdentify from "./cmd_identify.js";
+import cmdNodes from "./cmd_nodes.js";
+import cmdSession from "./cmd_session.js";
+import cmdSubscribe from "./cmd_subscribe.js";
+import cmdTlv from "./cmd_tlv";
+
+const MAX_HISTORY_SIZE = 1000;
+
+function exitCommand() {
+    return {
+        command: "exit",
+        describe: "Exit",
+        builder: {},
+        handler: async () => {
+            console.log("Goodbye.");
+            await exit();
+        },
+    };
+}
+
+/**
+ * Class to process and dispatch shell commands.
+ */
+export class Shell {
+    readline?: readline.Interface;
+    writeStream?: NodeJS.WritableStream;
+
+    /**
+     * Construct a new Shell object.
+     */
+    constructor(
+        public theNode: MatterNode,
+        public nodeNum: number,
+        public prompt: string,
+    ) {}
+
+    start() {
+        const history = new Array<string>();
+        const fileName = `.matter-shell-${this.nodeNum}.history`;
+        try {
+            const historyData = readFileSync(fileName, "utf8");
+            history.push(
+                ...historyData
+                    .split("\n")
+                    .map(line => line.trim())
+                    .filter(line => line.length),
+            );
+            history.splice(0, -MAX_HISTORY_SIZE);
+            console.log(`Loaded ${history.length} history entries from ${fileName}`);
+        } catch (e) {
+            if (e instanceof Error && "code" in e && e.code !== "ENOENT") {
+                process.stderr.write(`Error happened during history file read: ${e}\n`);
+            }
+        }
+        try {
+            this.writeStream = createWriteStream(fileName, { flags: "w" });
+            this.writeStream.write(`${history.join("\n")}\n`);
+        } catch (e) {
+            process.stderr.write(`Error happened during history file write: ${e}\n`);
+        }
+
+        this.readline = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: true,
+            prompt: this.prompt,
+            history: history.reverse(),
+            historySize: MAX_HISTORY_SIZE,
+        });
+        this.readline
+            .on("line", cmd => {
+                cmd = cmd.trim();
+                this.onReadLine(cmd)
+                    .then(result => result && cmd.length && this.writeStream?.write(`${cmd}\n`))
+                    .catch(e => {
+                        process.stderr.write(`Read error: ${e}\n`);
+                        process.exit(1);
+                    });
+            })
+            .on("close", () => {
+                try {
+                    this.writeStream?.end();
+                } catch (e) {
+                    process.stderr.write(`Error happened during history file write: ${e}\n`);
+                }
+                exit()
+                    .then(() => process.exit(0))
+                    .catch(e => {
+                        process.stderr.write(`Close error: ${e}\n`);
+                        process.exit(1);
+                    });
+            });
+
+        this.readline.prompt();
+    }
+
+    /**
+     * Method to process a line of raw cli text input.
+     *
+     * @param {string} line
+     */
+    async onReadLine(line: string) {
+        let result = true;
+        if (line) {
+            let args;
+            try {
+                args = commandlineParser(line);
+            } catch (error) {
+                process.stderr.write(`Error happened during command parsing: ${error}\n`);
+                return false;
+            }
+            const yargsInstance = yargs(args)
+                .command([
+                    cmdCommission(this.theNode),
+                    cmdConfig(this.theNode),
+                    cmdSession(this.theNode),
+                    cmdNodes(this.theNode),
+                    cmdSubscribe(this.theNode),
+                    cmdIdentify(this.theNode),
+                    cmdDiscover(this.theNode),
+                    cmdAttributes(this.theNode),
+                    cmdEvents(this.theNode),
+                    cmdCommands(this.theNode),
+                    cmdTlv(),
+                    exitCommand(),
+                ])
+                .command({
+                    command: "*",
+                    handler: argv => {
+                        argv.unhandled = true;
+                    },
+                })
+                .exitProcess(false)
+                .version(false)
+                .help("help")
+                .scriptName("")
+                .strictCommands(false)
+                .strictOptions(false)
+                .fail(false)
+                .strict(false);
+            try {
+                const argv = await yargsInstance.wrap(yargsInstance.terminalWidth()).parseAsync();
+
+                if (argv.unhandled) {
+                    process.stderr.write(`Unknown command: ${line}\n`);
+                    yargsInstance.showHelp();
+                } else {
+                    console.log("Done.");
+                }
+            } catch (error) {
+                process.stderr.write(`Error happened during command: ${error}\n`);
+                if (error instanceof Error && error.stack) {
+                    process.stderr.write(error.stack.toString());
+                    process.stderr.write("\n");
+                }
+                if (!(error instanceof MatterError)) {
+                    yargsInstance.showHelp();
+                    result = false;
+                }
+            }
+        }
+        this.readline?.prompt();
+        return result;
+    }
+}

package/src/shell/cmd_cluster-attributes.ts

@@ -0,0 +1,340 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Diagnostic, Logger } from "@matter/general";
+import { AttributeModel, ClusterModel, MatterModel } from "@matter/model";
+import { SupportedAttributeClient } from "@project-chip/matter.js/cluster";
+import { ValidationError } from "@project-chip/matter.js/common";
+import { AttributeId, ClusterId, EndpointNumber } 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 generateAllAttributeHandlersForCluster(yargs: Argv, theNode: MatterNode) {
+    MatterModel.standard.clusters.forEach(cluster => {
+        yargs = generateClusterAttributeHandlers(yargs, cluster, theNode);
+    });
+
+    yargs = yargs.command(
+        "by-id <cluster-id> read <attribute-id> <node-id> <endpoint-id>",
+        `Read attributes by id`,
+        yargs =>
+            yargs
+                .positional("cluster-id", {
+                    describe: "cluster id to read from",
+                    type: "number",
+                    demandOption: true,
+                })
+                .positional("attribute-id", {
+                    describe: "attribute id to read, use * to read all attributes of the given cluster",
+                    type: "string",
+                    demandOption: true,
+                })
+                .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, clusterId, attributeId: rawAttributeId } = argv;
+            const attributeId = rawAttributeId === "*" ? undefined : parseInt(rawAttributeId);
+            const node = (await theNode.connectAndGetNodes(nodeId))[0];
+
+            try {
+                const interactionClient = await node.getInteractionClient();
+                const result = await interactionClient.getMultipleAttributes({
+                    attributes: [
+                        {
+                            endpointId: EndpointNumber(endpointId),
+                            clusterId: ClusterId(clusterId),
+                            attributeId: attributeId !== undefined ? AttributeId(attributeId) : undefined,
+                        },
+                    ],
+                });
+                console.log(
+                    `Attribute values for cluster ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attributeId}:`,
+                );
+                for (const {
+                    path: { attributeId, attributeName },
+                    value,
+                } of result) {
+                    console.log(
+                        `    ${Diagnostic.hex(attributeId)}${attributeName !== undefined ? ` (${attributeName})` : ""}: ${Logger.toJSON(value)}`,
+                    );
+                }
+            } catch (error) {
+                console.log(
+                    `ERROR: Could not get attribute ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attributeId}: ${error}`,
+                );
+            }
+        },
+    );
+    return yargs;
+}
+
+function generateClusterAttributeHandlers(yargs: Argv, cluster: ClusterModel, theNode: MatterNode) {
+    if (cluster.id === undefined) {
+        return yargs;
+    }
+    yargs = yargs.command(
+        [cluster.name.toLowerCase(), `0x${cluster.id.toString(16)}`],
+        `Read/Write ${cluster.name} attributes`,
+        yargs => {
+            yargs = yargs.command(
+                "read",
+                `Reads attributes of ${cluster.name}`,
+                yargs => {
+                    yargs = yargs.command(
+                        ["* <node-id> <endpoint-id>", "all"],
+                        `Read all attributes of ${cluster.name}`,
+                        yargs => {
+                            return 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,
+                                })
+                                .options({
+                                    remote: {
+                                        describe: "request value always remote",
+                                        default: false,
+                                        type: "boolean",
+                                    },
+                                });
+                        },
+                        async argv => {
+                            const clusterId = cluster.id;
+                            const { nodeId, endpointId, remote } = argv;
+                            const requestRemote = remote ? true : undefined;
+                            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;
+                            }
+                            console.log(
+                                `Attribute values for cluster ${cluster.name} (${node.nodeId.toString()}/${endpointId}/${clusterId}):`,
+                            );
+                            for (const attribute of cluster.attributes) {
+                                const attributeName = camelize(attribute.name);
+                                const attributeClient = clusterClient.attributes[attributeName];
+                                if (!(attributeClient instanceof SupportedAttributeClient)) {
+                                    continue;
+                                }
+                                console.log(
+                                    `    ${attributeName} (${attribute.id}): ${Logger.toJSON(await attributeClient.get(requestRemote))}`,
+                                );
+                            }
+                        },
+                    );
+
+                    cluster.attributes.forEach(attribute => {
+                        yargs = generateAttributeReadHandler(yargs, cluster.id, cluster.name, attribute, theNode);
+                    });
+                    return yargs;
+                },
+                async (argv: any) => {
+                    argv.unhandled = true;
+                },
+            );
+
+            if (cluster.attributes.some(attribute => attribute.writable)) {
+                yargs = yargs.command(
+                    "write",
+                    `Writes attributes of ${cluster.name}`,
+                    yargs => {
+                        cluster.attributes.forEach(attribute => {
+                            if (!attribute.writable) {
+                                return;
+                            }
+                            yargs = generateAttributeWriteHandler(yargs, cluster.id, cluster.name, attribute, theNode);
+                        });
+                        return yargs;
+                    },
+                    async (argv: any) => {
+                        argv.unhandled = true;
+                    },
+                );
+            }
+
+            return yargs;
+        },
+        async (argv: any) => {
+            argv.unhandled = true;
+        },
+    );
+
+    return yargs;
+}
+
+function generateAttributeReadHandler(
+    yargs: Argv,
+    clusterId: number,
+    clusterName: string,
+    attribute: AttributeModel,
+    theNode: MatterNode,
+) {
+    const attributeName = camelize(attribute.name);
+    return yargs.command(
+        [`${attribute.name.toLowerCase()} <node-id> <endpoint-id>`, `0x${attribute.id.toString(16)}`],
+        `Read ${clusterName}.${attribute.name} attribute`,
+        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,
+                })
+                .options({
+                    remote: {
+                        describe: "request value always remote",
+                        default: false,
+                        type: "boolean",
+                    },
+                }),
+        async argv => {
+            const { nodeId, endpointId, remote } = argv;
+            const requestRemote = remote ? true : undefined;
+            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 attributeClient = clusterClient.attributes[attributeName];
+            if (!(attributeClient instanceof SupportedAttributeClient)) {
+                console.log(
+                    `ERROR: Attribute ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attribute.id} not supported.`,
+                );
+                return;
+            }
+            try {
+                console.log(
+                    `Attribute value for ${attributeName} ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attribute.id}: ${Logger.toJSON(await attributeClient.get(requestRemote))}`,
+                );
+            } catch (error) {
+                console.log(`ERROR: Could not get attribute ${attribute.name}: ${error}`);
+            }
+        },
+    );
+}
+
+function generateAttributeWriteHandler(
+    yargs: Argv,
+    clusterId: number,
+    clusterName: string,
+    attribute: AttributeModel,
+    theNode: MatterNode,
+) {
+    //console.log("Generating attribute handler for ", attribute.name, attribute);
+    //console.log(attribute.definingModel);
+    const attributeName = camelize(attribute.name);
+    const typeHint = `${attribute.type}${attribute.definingModel === undefined ? "" : " as JSON string"}`;
+    return yargs.command(
+        [`${attribute.name.toLowerCase()} <value> <nodeId> <endpointId>`, `0x${attribute.id.toString(16)}`],
+        `Write ${clusterName}.${attribute.name} attribute`,
+        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,
+                })
+                .positional("value", {
+                    describe: `value to write (${typeHint})`,
+                    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;
+                }
+            }
+
+            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 attributeClient = clusterClient.attributes[attributeName];
+            if (!(attributeClient instanceof SupportedAttributeClient)) {
+                console.log(
+                    `ERROR: Attribute ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attribute.id} not supported.`,
+                );
+                return;
+            }
+
+            try {
+                parsedValue = convertJsonDataWithModel(attribute, parsedValue);
+
+                await attributeClient.set(parsedValue);
+                console.log(
+                    `Attribute ${attributeName} ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attribute.id} set to ${Logger.toJSON(value)}`,
+                );
+            } catch (error) {
+                if (error instanceof ValidationError) {
+                    console.log(
+                        `ERROR: Could not validate data for attribute ${attribute.name} to ${Logger.toJSON(parsedValue)}: ${error}${error.fieldName !== undefined ? ` in field ${error.fieldName}` : ""}`,
+                    );
+                } else {
+                    console.log(
+                        `ERROR: Could not set attribute ${attribute.name} to ${Logger.toJSON(parsedValue)}: ${error}`,
+                    );
+                }
+            }
+        },
+    );
+}
+
+export default function cmdAttributes(theNode: MatterNode) {
+    return {
+        command: ["attributes", "a"],
+        describe: "Read and Write attributes",
+        builder: (yargs: Argv) => generateAllAttributeHandlersForCluster(yargs, theNode),
+        handler: async (argv: any) => {
+            argv.unhandled = true;
+        },
+    };
+}