@matter/nodejs-shell 0.17.9 → 0.18.0-alpha.0-20260812-4d7f2790e

package/src/shell/cmd_cluster-attributes.ts

@@ -4,12 +4,17 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Diagnostic } from "@matter/general";
+import { Diagnostic, ImplementationError } from "@matter/general";
 import { AttributeModel, ClusterModel, Matter } from "@matter/model";
-import { AttributeId, ClusterId, EndpointNumber, ValidationError } from "@matter/types";
-import { SupportedAttributeClient } from "@project-chip/matter.js/cluster";
+import { AttributeId, ClusterId, ClusterLookup, EndpointNumber, ValidationError } from "@matter/types";
 import type { Argv } from "yargs";
 import { MatterNode } from "../MatterNode.js";
+import {
+    elementKnownUnsupported,
+    readAttributesRemote,
+    resolveClusterEndpoint,
+    ResolvedClusterEndpoint,
+} from "../util/ClusterEndpoint.js";
 import { convertJsonDataWithModel } from "../util/Json.js";
 
 function generateAllAttributeHandlersForCluster(yargs: Argv, theNode: MatterNode) {
@@ -55,31 +60,32 @@ function generateAllAttributeHandlersForCluster(yargs: Argv, theNode: MatterNode
             const node = (await theNode.connectAndGetNodes(nodeId))[0];
 
             try {
-                const interactionClient = await node.getInteractionClient();
-                const result = await interactionClient.getMultipleAttributes({
-                    attributes: [
+                const values = await readAttributesRemote(
+                    node,
+                    [
                         {
                             endpointId: EndpointNumber(endpointId),
                             clusterId: ClusterId(clusterId),
                             attributeId: attributeId !== undefined ? AttributeId(attributeId) : undefined,
                         },
                     ],
-                    isFabricFiltered: fabricFiltered,
-                });
+                    fabricFiltered,
+                );
                 console.log(
-                    `Attribute values for cluster ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attributeId}:`,
+                    `Attribute values for cluster ${node.peerAddress?.nodeId}/${endpointId}/${clusterId}/${attributeId}:`,
                 );
                 for (const {
-                    path: { attributeId, attributeName },
+                    path: { attributeId: id },
                     value,
-                } of result) {
+                } of values) {
+                    const attributeName = ClusterLookup.attributeName(ClusterId(clusterId), id, node.matter);
                     console.log(
-                        `    ${Diagnostic.hex(attributeId)}${attributeName !== undefined ? ` (${attributeName})` : ""}: ${Diagnostic.json(value)}`,
+                        `    ${Diagnostic.hex(id)}${attributeName !== undefined ? ` (${attributeName})` : ""}: ${Diagnostic.json(value)}`,
                     );
                 }
             } catch (error) {
                 console.log(
-                    `ERROR: Could not get attribute ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attributeId}: ${error}`,
+                    `ERROR: Could not get attribute ${node.peerAddress?.nodeId}/${endpointId}/${clusterId}/${attributeId}: ${error}`,
                 );
             }
         },
@@ -132,35 +138,31 @@ function generateClusterAttributeHandlers(yargs: Argv, cluster: ClusterModel, th
                                 });
                         },
                         async argv => {
-                            const clusterId = cluster.id;
                             const { nodeId, endpointId, remote, fabricFiltered } = 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.`,
-                                );
+                            const resolved = await resolveClusterEndpoint(theNode, nodeId, endpointId, clusterId!);
+                            if (resolved === undefined) {
                                 return;
                             }
+                            const { node, endpoint, behaviorType } = resolved;
+
                             console.log(
-                                `Attribute values for cluster ${cluster.name} (${node.nodeId.toString()}/${endpointId}/${clusterId}):`,
+                                `Attribute values for cluster ${cluster.name} (${node.peerAddress?.nodeId}/${endpointId}/${clusterId}):`,
                             );
                             for (const attribute of cluster.attributes) {
                                 const attributeName = attribute.propertyName;
-                                const attributeClient = clusterClient.attributes[attributeName];
                                 if (
-                                    attributeClient === undefined ||
-                                    (!remote && !(attributeClient instanceof SupportedAttributeClient))
+                                    !remote &&
+                                    elementKnownUnsupported(endpoint, behaviorType, "attributes", attributeName)
                                 ) {
                                     continue;
                                 }
-                                console.log(
-                                    `    ${attributeName} (${attribute.id}): ${Diagnostic.json(await attributeClient.get(requestRemote, fabricFiltered))}`,
-                                );
+                                try {
+                                    console.log(
+                                        `    ${attributeName} (${attribute.id}): ${Diagnostic.json(await getAttributeValue(resolved, clusterId!, attribute, remote, fabricFiltered))}`,
+                                    );
+                                } catch (error) {
+                                    console.log(`    ${attributeName} (${attribute.id}): ERROR: ${error}`);
+                                }
                             }
                         },
                     );
@@ -204,6 +206,35 @@ function generateClusterAttributeHandlers(yargs: Argv, cluster: ClusterModel, th
     return yargs;
 }
 
+/** Fetch a single attribute's value: cached behavior state, or a live interaction read when `requestRemote`. */
+async function getAttributeValue(
+    resolved: ResolvedClusterEndpoint,
+    clusterId: number,
+    attribute: AttributeModel,
+    requestRemote: boolean,
+    fabricFiltered: boolean,
+): Promise<unknown> {
+    const { node, endpoint, behaviorType } = resolved;
+    if (requestRemote) {
+        const values = await readAttributesRemote(
+            node,
+            [
+                {
+                    endpointId: endpoint.number,
+                    clusterId: ClusterId(clusterId),
+                    attributeId: AttributeId(attribute.id),
+                },
+            ],
+            fabricFiltered,
+        );
+        if (values.length === 0) {
+            throw new ImplementationError(`No value returned for attribute ${attribute.propertyName}`);
+        }
+        return values[0].value;
+    }
+    return endpoint.stateOf(behaviorType.id)[attribute.propertyName];
+}
+
 function generateAttributeReadHandler(
     yargs: Argv,
     clusterId: number,
@@ -242,24 +273,21 @@ function generateAttributeReadHandler(
                 }),
         async argv => {
             const { nodeId, endpointId, remote, fabricFiltered } = 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.`);
+            const resolved = await resolveClusterEndpoint(theNode, nodeId, endpointId, clusterId);
+            if (resolved === undefined) {
                 return;
             }
-            const attributeClient = clusterClient.attributes[attributeName];
-            if (attributeClient === undefined || (!remote && !(attributeClient instanceof SupportedAttributeClient))) {
+            const { node, endpoint, behaviorType } = resolved;
+
+            if (!remote && elementKnownUnsupported(endpoint, behaviorType, "attributes", attributeName)) {
                 console.log(
-                    `ERROR: Attribute ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attribute.id} not supported by the device.`,
+                    `ERROR: Attribute ${node.peerAddress?.nodeId}/${endpointId}/${clusterId}/${attribute.id} not supported by the device.`,
                 );
                 return;
             }
             try {
                 console.log(
-                    `Attribute value for ${attributeName} ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attribute.id}: ${Diagnostic.json(await attributeClient.get(requestRemote, fabricFiltered))}`,
+                    `Attribute value for ${attributeName} ${node.peerAddress?.nodeId}/${endpointId}/${clusterId}/${attribute.id}: ${Diagnostic.json(await getAttributeValue(resolved, clusterId, attribute, remote, fabricFiltered))}`,
                 );
             } catch (error) {
                 console.log(`ERROR: Could not get attribute ${attribute.name}: ${error}`);
@@ -275,8 +303,6 @@ function generateAttributeWriteHandler(
     attribute: AttributeModel,
     theNode: MatterNode,
 ) {
-    //console.log("Generating attribute handler for ", attribute.name, attribute);
-    //console.log(attribute.definingModel);
     const attributeName = attribute.propertyName;
     const typeHint = `${attribute.type}${attribute.definingModel === undefined ? "" : " as JSON string"}`;
     return yargs.command(
@@ -321,17 +347,15 @@ function generateAttributeWriteHandler(
                 }
             }
 
-            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.`);
+            const resolved = await resolveClusterEndpoint(theNode, nodeId, endpointId, clusterId);
+            if (resolved === undefined) {
                 return;
             }
-            const attributeClient = clusterClient.attributes[attributeName];
-            if (!force && !(attributeClient instanceof SupportedAttributeClient)) {
+            const { node, endpoint, behaviorType } = resolved;
+
+            if (!force && elementKnownUnsupported(endpoint, behaviorType, "attributes", attributeName)) {
                 console.log(
-                    `ERROR: Attribute ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attribute.id} not supported by the device.`,
+                    `ERROR: Attribute ${node.peerAddress?.nodeId}/${endpointId}/${clusterId}/${attribute.id} not supported by the device.`,
                 );
                 return;
             }
@@ -339,9 +363,9 @@ function generateAttributeWriteHandler(
             try {
                 parsedValue = convertJsonDataWithModel(attribute, parsedValue);
 
-                await attributeClient.set(parsedValue);
+                await endpoint.setStateOf(behaviorType.id, { [attributeName]: parsedValue });
                 console.log(
-                    `Attribute ${attributeName} ${node.nodeId.toString()}/${endpointId}/${clusterId}/${attribute.id} set to ${Diagnostic.json(value)}`,
+                    `Attribute ${attributeName} ${node.peerAddress?.nodeId}/${endpointId}/${clusterId}/${attribute.id} set to ${Diagnostic.json(value)}`,
                 );
             } catch (error) {
                 if (error instanceof ValidationError) {

package/src/shell/cmd_cluster-commands.ts

@@ -6,9 +6,10 @@
 
 import { Diagnostic } from "@matter/general";
 import { ClusterModel, CommandModel, Matter } from "@matter/model";
-import { ClusterId, ValidationError } from "@matter/types";
+import { ValidationError } from "@matter/types";
 import type { Argv } from "yargs";
 import { MatterNode } from "../MatterNode.js";
+import { elementKnownUnsupported, resolveClusterEndpoint } from "../util/ClusterEndpoint.js";
 import { convertJsonDataWithModel } from "../util/Json.js";
 
 function generateAllCommandHandlersForCluster(yargs: Argv, theNode: MatterNode) {
@@ -48,9 +49,6 @@ function generateCommandHandler(
     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(
@@ -126,15 +124,16 @@ async function executeCommand(
 ) {
     const commandName = command.propertyName;
 
-    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.`);
+    const resolved = await resolveClusterEndpoint(theNode, nodeId, endpointId, clusterId);
+    if (resolved === undefined) {
         return;
     }
-    if (clusterClient.commands[commandName] === undefined) {
-        console.log(`ERROR: Command ${node.nodeId.toString()}/${endpointId}/${clusterId}/${command.id} not supported.`);
+    const { node, endpoint, behaviorType } = resolved;
+
+    if (elementKnownUnsupported(endpoint, behaviorType, "commands", commandName)) {
+        console.log(
+            `ERROR: Command ${node.peerAddress?.nodeId}/${endpointId}/${clusterId}/${command.id} not supported.`,
+        );
         return;
     }
     try {
@@ -142,9 +141,9 @@ async function executeCommand(
             requestData = convertJsonDataWithModel(command, requestData);
         }
 
-        const result = await clusterClient.commands[commandName](requestData);
+        const result = await endpoint.commandsOf(behaviorType.id)[commandName](requestData);
         console.log(
-            `Command ${command.name} ${node.nodeId.toString()}/${endpointId}/${clusterId}/${command.id} invoked ${requestData ? `with ${Diagnostic.json(requestData)}` : ""}`,
+            `Command ${command.name} ${node.peerAddress?.nodeId}/${endpointId}/${clusterId}/${command.id} invoked ${requestData ? `with ${Diagnostic.json(requestData)}` : ""}`,
         );
         if (result !== undefined) {
             console.log(`Result: ${Diagnostic.json(result)}`);

package/src/shell/cmd_cluster-events.ts

@@ -6,9 +6,10 @@
 
 import { Diagnostic } from "@matter/general";
 import { ClusterModel, EventModel, Matter } from "@matter/model";
-import { ClusterId } from "@matter/types";
+import { ClusterId, EventId } from "@matter/types";
 import type { Argv } from "yargs";
 import { MatterNode } from "../MatterNode.js";
+import { readEventsRemote, resolveClusterEndpoint } from "../util/ClusterEndpoint.js";
 
 function generateAllEventHandlersForCluster(yargs: Argv, theNode: MatterNode) {
     Matter.clusters.forEach(cluster => {
@@ -47,7 +48,6 @@ function generateEventHandler(
     event: EventModel,
     theNode: MatterNode,
 ) {
-    //console.log("Generating event handler for ", event.name, JSON.stringify(event));
     const eventName = event.propertyName;
     return yargs.command(
         [`${event.name.toLowerCase()} <node-id> <endpoint-id>`, `0x${event.id.toString(16)}`],
@@ -66,17 +66,44 @@ function generateEventHandler(
                 }),
         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.`);
+            const resolved = await resolveClusterEndpoint(theNode, nodeId, endpointId, clusterId);
+            if (resolved === undefined) {
                 return;
             }
-            const eventClient = clusterClient.events[eventName];
-            console.log(
-                `Event value for ${eventName} ${node.nodeId.toString()}/${endpointId}/${clusterId}/${event.id}: ${Diagnostic.json(await eventClient.get())}`,
-            );
+            const { node, endpoint } = resolved;
+
+            try {
+                // No local event cache; every read is a live interaction round trip, same as the legacy EventClient.
+                const reports = await readEventsRemote(
+                    node,
+                    [{ endpointId: endpoint.number, clusterId: ClusterId(clusterId), eventId: EventId(event.id) }],
+                    true,
+                );
+                const events = reports.map(
+                    ({
+                        number,
+                        priority,
+                        epochTimestamp,
+                        systemTimestamp,
+                        deltaEpochTimestamp,
+                        deltaSystemTimestamp,
+                        value,
+                    }) => ({
+                        eventNumber: number,
+                        priority,
+                        epochTimestamp,
+                        systemTimestamp,
+                        deltaEpochTimestamp,
+                        deltaSystemTimestamp,
+                        data: value,
+                    }),
+                );
+                console.log(
+                    `Event value for ${eventName} ${node.peerAddress?.nodeId}/${endpointId}/${clusterId}/${event.id}: ${Diagnostic.json(events)}`,
+                );
+            } catch (error) {
+                console.log(`ERROR: Could not get event ${event.name}: ${error}`);
+            }
         },
     );
 }