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

package/src/shell/cmd_nodes.ts

@@ -0,0 +1,249 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { capitalize, decamelize, Logger } from "@matter/general";
+import { NodeId } from "@project-chip/matter.js/datatype";
+import { CommissioningControllerNodeOptions, NodeStateInformation } from "@project-chip/matter.js/device";
+import type { Argv } from "yargs";
+import { MatterNode } from "../MatterNode";
+
+export function createDiagnosticCallbacks(): Partial<CommissioningControllerNodeOptions> {
+    return {
+        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 Node ${peerNodeId} connected`);
+                    break;
+                case NodeStateInformation.Disconnected:
+                    console.log(`stateInformationCallback Node ${peerNodeId} disconnected`);
+                    break;
+                case NodeStateInformation.Reconnecting:
+                    console.log(`stateInformationCallback Node ${peerNodeId} reconnecting`);
+                    break;
+                case NodeStateInformation.WaitingForDeviceDiscovery:
+                    console.log(
+                        `stateInformationCallback Node ${peerNodeId} waiting that device gets discovered again`,
+                    );
+                    break;
+                case NodeStateInformation.StructureChanged:
+                    console.log(`stateInformationCallback Node ${peerNodeId} structure changed`);
+                    break;
+                case NodeStateInformation.Decommissioned:
+                    console.log(`stateInformationCallback Node ${peerNodeId} decommissioned`);
+                    break;
+            }
+        },
+    };
+}
+
+export default function commands(theNode: MatterNode) {
+    return {
+        command: ["nodes", "node"],
+        describe: "Manage nodes",
+        builder: (yargs: Argv) =>
+            yargs
+                // Pair
+                .command(
+                    ["*", "list [status]"],
+                    "List all commissioned nodes",
+                    yargs => {
+                        return yargs.positional("status", {
+                            describe: "status",
+                            options: ["commissioned", "connected"] as const,
+                            default: "commissioned",
+                            type: "string",
+                        });
+                    },
+                    async argv => {
+                        const { status } = argv;
+                        await theNode.start();
+                        if (theNode.commissioningController === undefined) {
+                            throw new Error("CommissioningController not initialized");
+                        }
+                        switch (status) {
+                            case "commissioned": {
+                                const details = theNode.commissioningController.getCommissionedNodesDetails();
+                                details
+                                    .map(detail => ({
+                                        ...detail,
+                                        nodeId: detail.nodeId.toString(),
+                                    }))
+                                    .forEach(detail => {
+                                        console.log(detail);
+                                    });
+                                break;
+                            }
+                            case "connected": {
+                                const nodeIds = theNode.commissioningController
+                                    .getCommissionedNodes()
+                                    .filter(nodeId => !!theNode.commissioningController?.getPairedNode(nodeId));
+                                console.log(nodeIds.map(nodeId => nodeId.toString()));
+                                break;
+                            }
+                        }
+                    },
+                )
+                .command(
+                    "log [node-id]",
+                    "Log the Structure of one node",
+                    yargs => {
+                        return yargs.positional("node-id", {
+                            describe: "node id to log - if omitted the first node is logged.",
+                            default: undefined,
+                            type: "string",
+                        });
+                    },
+                    async argv => {
+                        const { nodeId } = argv;
+                        const node = (await theNode.connectAndGetNodes(nodeId))[0];
+
+                        console.log("Logging structure of Node ", node.nodeId.toString());
+                        node.logStructure({});
+                    },
+                )
+                .command(
+                    "connect <node-id> [min-subscription-interval] [max-subscription-interval]",
+                    "Connects to one or all commissioned nodes",
+                    yargs => {
+                        return yargs
+                            .positional("node-id", {
+                                describe: "node id to connect. Use 'all' to connect to all nodes.",
+                                default: undefined,
+                                type: "string",
+                                demandOption: true,
+                            })
+                            .positional("min-subscription-interval", {
+                                describe:
+                                    "Minimum subscription interval in seconds. If set then the node is subscribed to all attributes and events.",
+                                type: "number",
+                            })
+                            .positional("max-subscription-interval", {
+                                describe:
+                                    "Maximum subscription interval in seconds. If minimum interval is set and this not it will be determined automatically.",
+                                type: "number",
+                            });
+                    },
+                    async argv => {
+                        const { nodeId: nodeIdStr, maxSubscriptionInterval, minSubscriptionInterval } = argv;
+                        await theNode.start();
+                        if (theNode.commissioningController === undefined) {
+                            throw new Error("CommissioningController not initialized");
+                        }
+                        let nodeIds = theNode.commissioningController.getCommissionedNodes();
+                        if (nodeIdStr !== "all") {
+                            const cmdNodeId = NodeId(BigInt(nodeIdStr));
+                            nodeIds = nodeIds.filter(nodeId => nodeId === cmdNodeId);
+                            if (!nodeIds.length) {
+                                throw new Error(`Node ${nodeIdStr} not commissioned`);
+                            }
+                        }
+
+                        const autoSubscribe = minSubscriptionInterval !== undefined;
+
+                        for (const nodeIdToProcess of nodeIds) {
+                            await theNode.commissioningController.connectNode(nodeIdToProcess, {
+                                autoSubscribe,
+                                subscribeMinIntervalFloorSeconds: autoSubscribe ? minSubscriptionInterval : undefined,
+                                subscribeMaxIntervalCeilingSeconds: autoSubscribe ? maxSubscriptionInterval : undefined,
+                                ...createDiagnosticCallbacks(),
+                            });
+                        }
+                    },
+                )
+                .command(
+                    "disconnect <node-id>",
+                    "Disconnects from one or all nodes",
+                    yargs => {
+                        return yargs.positional("node-id", {
+                            describe: "node id to disconnect. Use 'all' to disconnect from all nodes.",
+                            default: undefined,
+                            type: "string",
+                            demandOption: true,
+                        });
+                    },
+                    async argv => {
+                        const { nodeId: nodeIdStr } = argv;
+                        if (theNode.commissioningController === undefined) {
+                            console.log("Controller not initialized, nothing to disconnect.");
+                            return;
+                        }
+
+                        let nodeIds = theNode.commissioningController.getCommissionedNodes();
+                        if (nodeIdStr !== "all") {
+                            const cmdNodeId = NodeId(BigInt(nodeIdStr));
+                            nodeIds = nodeIds.filter(nodeId => nodeId === cmdNodeId);
+                            if (!nodeIds.length) {
+                                throw new Error(`Node ${nodeIdStr} not commissioned`);
+                            }
+                        }
+
+                        for (const nodeIdToProcess of nodeIds) {
+                            const node = theNode.commissioningController.getPairedNode(nodeIdToProcess);
+                            if (node === undefined) {
+                                console.log(`Node ${nodeIdToProcess} not connected`);
+                                continue;
+                            }
+                            await node.disconnect();
+                        }
+                    },
+                )
+                .command(
+                    "status <node-ids>",
+                    "Logs the connection status for all or specified nodes",
+                    yargs => {
+                        return yargs.positional("node-ids", {
+                            describe:
+                                "node ids to connect (comma separated list allowed). Use 'all' to log status for all nodes.",
+                            default: undefined,
+                            type: "string",
+                            demandOption: true,
+                        });
+                    },
+                    async argv => {
+                        const { nodeIds: nodeIdStr } = argv;
+                        await theNode.start();
+                        if (theNode.commissioningController === undefined) {
+                            throw new Error("CommissioningController not initialized");
+                        }
+                        let nodeIds = theNode.commissioningController.getCommissionedNodes();
+                        if (nodeIdStr !== "all") {
+                            const nodeIdList = nodeIdStr.split(",").map(nodeId => NodeId(BigInt(nodeId)));
+                            nodeIds = nodeIds.filter(nodeId => nodeIdList.includes(nodeId));
+                            if (!nodeIds.length) {
+                                throw new Error(`Node ${nodeIdStr} not commissioned`);
+                            }
+                        }
+
+                        for (const nodeIdToProcess of nodeIds) {
+                            const node = theNode.commissioningController.getPairedNode(nodeIdToProcess);
+                            if (node === undefined) {
+                                console.log(`Node ${nodeIdToProcess}: Not initialized`);
+                            } else {
+                                const basicInfo = node.basicInformation;
+                                console.log(
+                                    `Node ${nodeIdToProcess}: Node Status: ${capitalize(decamelize(NodeStateInformation[node.nodeState], " "))}${basicInfo !== undefined ? ` (${basicInfo.vendorName} ${basicInfo.productName})` : ""}`,
+                                );
+                            }
+                        }
+                    },
+                ),
+        handler: async (argv: any) => {
+            argv.unhandled = true;
+        },
+    };
+}

package/src/shell/cmd_session.ts

@@ -0,0 +1,23 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { MatterNode } from "../MatterNode";
+
+export default function commands(theNode: MatterNode) {
+    return {
+        command: "session",
+        describe: "Manage session",
+        builder: {},
+        handler: async () => {
+            if (!theNode.commissioningController) {
+                throw new Error("CommissioningController not initialized");
+            }
+
+            const sessions = theNode.commissioningController?.getActiveSessionInformation();
+            console.log(sessions);
+        },
+    };
+}

package/src/shell/cmd_subscribe.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Logger } from "@matter/general";
+import type { Argv } from "yargs";
+import { MatterNode } from "../MatterNode.js";
+
+export default function commands(theNode: MatterNode) {
+    return {
+        command: "subscribe [node-id]",
+        describe: "Subscribe to all events and attributes of a node",
+        builder: (yargs: Argv) => {
+            return yargs.positional("node-id", {
+                describe: "node id",
+                default: undefined,
+                type: "string",
+            });
+        },
+
+        handler: async (argv: any) => {
+            const { nodeId } = argv;
+            const node = (await theNode.connectAndGetNodes(nodeId))[0];
+
+            await node.subscribeAllAttributesAndEvents({
+                attributeChangedCallback: ({ path: { nodeId, clusterId, endpointId, attributeName }, value }) =>
+                    console.log(
+                        `${nodeId}: Attribute ${nodeId}/${endpointId}/${clusterId}/${attributeName} changed to ${Logger.toJSON(
+                            value,
+                        )}`,
+                    ),
+                eventTriggeredCallback: ({ path: { nodeId, clusterId, endpointId, eventName }, events }) =>
+                    console.log(
+                        `${nodeId} Event ${nodeId}/${endpointId}/${clusterId}/${eventName} triggered with ${Logger.toJSON(
+                            events,
+                        )}`,
+                    ),
+            });
+        },
+    };
+}

package/src/shell/cmd_tlv.ts

@@ -0,0 +1,169 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes, Logger, serialize, UnexpectedDataError } from "#general";
+import { TlvAny, TlvArrayReader, TlvElement, TlvStream, TlvType } from "#types";
+import type { Argv } from "yargs";
+
+const logger = Logger.get("tlv");
+
+const TlvTypeNames: { [key: number]: string } = {
+    [TlvType.Null]: "(Null)",
+    [TlvType.Boolean]: "Boolean(",
+    [TlvType.UnsignedInt]: "UnsignedInt(",
+    [TlvType.SignedInt]: "SignedInt(",
+    [TlvType.Float]: "Float(",
+    [TlvType.Utf8String]: "Utf8String(",
+    [TlvType.ByteString]: "ByteString(",
+    [TlvType.Array]: "Array {",
+    [TlvType.List]: "List {",
+    [TlvType.Structure]: "Structure {",
+    [TlvType.EndOfContainer]: "}",
+};
+
+function logAnyTlvStream(encoded: TlvStream) {
+    if (encoded.length === 0) {
+        return undefined;
+    }
+    const reader = new TlvArrayReader(encoded);
+    logGenericElement(reader);
+    const nextElement = reader.readTagType();
+    if (nextElement !== undefined) {
+        throw new UnexpectedDataError(`Unexpected data left after parsing all data: ${Logger.toJSON(nextElement)}`);
+    }
+}
+
+function logGenericElement(reader: TlvArrayReader, preReadElement?: TlvElement<any>, allowTag = false) {
+    const element = preReadElement ?? reader.readTagType();
+    const {
+        tag,
+        typeLength: { type },
+    } = element;
+
+    switch (type) {
+        case TlvType.Null:
+        case TlvType.Boolean:
+        case TlvType.UnsignedInt:
+        case TlvType.SignedInt:
+        case TlvType.Float:
+        case TlvType.Utf8String:
+        case TlvType.ByteString:
+            if (tag !== undefined && !allowTag) {
+                throw new UnexpectedDataError(`Tag detected for a native type: ${Logger.toJSON(element)}`);
+            }
+            const value = reader.readPrimitive(element.typeLength);
+            const logValue = value instanceof Uint8Array ? Bytes.toHex(value) : value;
+            const logNumberHex =
+                typeof value === "number" || typeof value === "bigint" ? value.toString(16) : undefined;
+            logger.info(
+                tag?.id !== undefined ? `${tag.id}/0x${tag?.id?.toString(16)} => ` : "",
+                TlvTypeNames[type],
+                `${logValue}${logNumberHex !== undefined ? `/0x${logNumberHex}` : ""}`,
+                ")",
+            );
+            break;
+        case TlvType.Array:
+        case TlvType.List:
+            tag?.id !== undefined
+                ? logger.info(`${tag.id}/0x${tag.id.toString(16)} => `, TlvTypeNames[type])
+                : logger.info(TlvTypeNames[type]);
+            Logger.nest(() => logGenericArrayOrList(reader, type === TlvType.List));
+            logger.info(TlvTypeNames[TlvType.EndOfContainer]);
+            break;
+        case TlvType.Structure:
+            tag?.id !== undefined
+                ? logger.info(`${tag.id}/0x${tag.id.toString(16)} => `, TlvTypeNames[type])
+                : logger.info(TlvTypeNames[type]);
+            Logger.nest(() => logGenericStructure(reader));
+            logger.info(TlvTypeNames[TlvType.EndOfContainer]);
+            break;
+        default:
+            throw new UnexpectedDataError(`Unknown type: ${type}`);
+    }
+}
+
+function logGenericArrayOrList(reader: TlvArrayReader, allowTag = false) {
+    const result = new Array<any>();
+    while (true) {
+        const element = reader.readTagType();
+        const {
+            tag,
+            typeLength: { type },
+        } = element;
+        if (type === TlvType.EndOfContainer) break;
+        if (tag !== undefined && !allowTag) {
+            throw new UnexpectedDataError(`Tag detected : ${Logger.toJSON(element)}`);
+        }
+        logGenericElement(reader, element, allowTag);
+    }
+    return result;
+}
+
+function logGenericStructure(reader: TlvArrayReader) {
+    const result: { [key: string]: any } = {};
+    while (true) {
+        const element = reader.readTagType();
+        const {
+            tag,
+            typeLength: { type },
+        } = element;
+        if (type === TlvType.EndOfContainer) break;
+        if (tag === undefined || tag.id === undefined) {
+            throw new UnexpectedDataError(`Tag missing for a structure: ${Logger.toJSON(element)}`);
+        }
+        logGenericElement(reader, element, true);
+    }
+    return result;
+}
+
+export default function commands() {
+    return {
+        command: "tlv",
+        describe: "TLV decoding tools",
+        builder: (yargs: Argv) => {
+            return yargs
+                .command(
+                    "decode [value]",
+                    "Decodes a TLV string (hex) into matter.js JavaScript object",
+                    yargs => {
+                        return yargs.positional("value", {
+                            describe: "The TLV value as hex string",
+                            type: "string",
+                            demandOption: true,
+                        });
+                    },
+                    async argv => {
+                        const { value } = argv;
+                        const bytes = Bytes.fromHex(value);
+                        const tlvEncoded = TlvAny.decode(bytes);
+                        const decoded = TlvAny.decodeAnyTlvStream(tlvEncoded);
+
+                        console.log("Decoded:", serialize(decoded));
+                    },
+                )
+                .command(
+                    "log [value]",
+                    "Decodes a TLV string (hex string) and logs it's structure",
+                    yargs => {
+                        return yargs.positional("value", {
+                            describe: "The TLV value as hex string",
+                            type: "string",
+                            demandOption: true,
+                        });
+                    },
+                    async argv => {
+                        const { value } = argv;
+                        const bytes = Bytes.fromHex(value);
+                        const tlvEncoded = TlvAny.decode(bytes);
+                        logAnyTlvStream(tlvEncoded);
+                    },
+                );
+        },
+        handler: async (argv: any) => {
+            argv.unhandled = true;
+        },
+    };
+}

package/src/tsconfig.json

@@ -0,0 +1,22 @@
+{
+    "extends": "../../tools/tsc/tsconfig.app.json",
+    "compilerOptions": {
+        "types": [
+            "node"
+        ]
+    },
+    "references": [
+        {
+            "path": "../../nodejs-ble/src"
+        },
+        {
+            "path": "../../nodejs/src"
+        },
+        {
+            "path": "../../general/src"
+        },
+        {
+            "path": "../../matter.js/src"
+        }
+    ]
+}

package/src/util/CommandlineParser.ts

@@ -0,0 +1,123 @@
+/**
+ * Quote aware Command line parser
+ *
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * This is a Typescript rewrite of https://github.com/cdhowie/shell-parser/
+ *
+ * Copyright 2019 Chris Howie
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
+ * documentation files (the "Software"), to deal in the Software without restriction, including without limitation the
+ * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit
+ * persons to whom the Software is furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all copies or substantial portions of the
+ * Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ * WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS
+ * OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+ * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+
+class StringReader {
+    private pos: number;
+    public current: string | undefined;
+
+    constructor(private readonly str: string) {
+        this.pos = -1;
+    }
+
+    next() {
+        if (this.pos < this.str.length) {
+            this.current = this.str[++this.pos];
+        }
+
+        return this.current;
+    }
+}
+
+function isWhitespace(c: string) {
+    return c === " ";
+}
+
+function consumeWhitespace(r: StringReader) {
+    while (r.current !== undefined && isWhitespace(r.current)) {
+        r.next();
+    }
+}
+
+function escaped(r: StringReader) {
+    const n = r.next();
+    if (n === undefined) {
+        throw new Error("Unterminated escape sequence");
+    }
+
+    return n;
+}
+
+function quoted(r: StringReader) {
+    let s = "";
+
+    const q = r.current;
+    const e = q === '"';
+
+    for (let c = r.next(); c !== q; c = r.next()) {
+        if (c === undefined) {
+            throw new Error(`Unterminated quote: ${q}`);
+        }
+
+        if (e && c === "\\") {
+            s += escaped(r);
+        } else {
+            s += c;
+        }
+    }
+
+    return s;
+}
+
+export function commandlineParser(line: string) {
+    const args = [];
+    let s = "";
+
+    const r = new StringReader(line);
+    r.next();
+    consumeWhitespace(r);
+
+    // Indicates if we saw a quote in the current argument. This is necessary
+    // to allow empty arguments ('' or ""), otherwise we have no way to
+    // distinguish this case from nothing.
+    let sawQuote = false;
+
+    while (r.current !== undefined) {
+        if (isWhitespace(r.current)) {
+            args.push(s);
+            sawQuote = false;
+            s = "";
+
+            consumeWhitespace(r);
+        } else if (r.current == "\\") {
+            s += escaped(r);
+            r.next();
+        } else if (r.current === "'" || r.current === '"') {
+            s += quoted(r);
+            sawQuote = true;
+            r.next();
+        } else {
+            s += r.current;
+            r.next();
+        }
+    }
+
+    if (sawQuote || s.length) {
+        args.push(s);
+    }
+
+    return args;
+}

package/src/util/Json.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2022-2024 Matter.js Authors
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { Bytes } from "@matter/general";
+import { ValueModel } from "@matter/model";
+import { ValidationDatatypeMismatchError } from "@project-chip/matter.js/common";
+import { camelize } from "./String";
+
+export function convertJsonDataWithModel(model: ValueModel, data: any): any {
+    const definingModel = model.definingModel ?? model;
+    switch (definingModel.effectiveMetatype) {
+        case "array":
+            if (!Array.isArray(data)) {
+                throw new ValidationDatatypeMismatchError(`Expected array, got ${typeof data}`);
+            }
+            return data.map(item => convertJsonDataWithModel(definingModel.children[0], item));
+        case "object":
+            if (typeof data !== "object") {
+                throw new ValidationDatatypeMismatchError(`Expected object, got ${typeof data}`);
+            }
+            for (const child of definingModel.children) {
+                const childKeyName = camelize(child.name);
+                data[childKeyName] = convertJsonDataWithModel(child, data[childKeyName]);
+            }
+            return data;
+        case "integer":
+            if (typeof data === "string") {
+                if (definingModel.metabase?.byteSize !== undefined && definingModel.metabase.byteSize > 6) {
+                    // If we have an integer with byteSize > 6 and a string value, we need to convert the string to a
+                    // BigInt also handles 0x prefixed hex strings
+                    return BigInt(data);
+                } else if (data.startsWith("0x")) {
+                    // Else if hex string convert to number
+                    return parseInt(data.substring(2), 16);
+                }
+            }
+            break;
+        case "bytes":
+            if (typeof data === "string") {
+                // ByteArray encoded as hex-String ... so convert to ByteArray
+                return Bytes.fromHex(data);
+            }
+            break;
+    }
+
+    return data;
+}