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

package/dist/esm/shell/cmd_identify.js

@@ -3,7 +3,8 @@
  * Copyright 2022-2026 Matter.js Authors
  * SPDX-License-Identifier: Apache-2.0
  */
-import { Identify } from "@matter/types/clusters";
+import { IdentifyClient } from "@matter/node/behaviors/identify";
+import { awaitSeeded } from "../util/awaitSeeded.js";
 function commands(theNode) {
   return {
     command: "identify [time] [node-id] [endpoint-id]",
@@ -25,17 +26,20 @@ function commands(theNode) {
     },
     handler: async (argv) => {
       const { nodeId, time = 10, endpointId } = argv;
+      const nodes = await theNode.connectAndGetNodes(nodeId);
+      for (const node of nodes) {
+        await awaitSeeded(node);
+      }
       await theNode.iterateNodeDevices(
-        await theNode.connectAndGetNodes(nodeId),
+        nodes,
         async (device, node) => {
-          const identifyCluster = device.getClusterClient(Identify);
-          if (identifyCluster === void 0) {
+          if (device.number === 0 || !device.behaviors.has(IdentifyClient)) {
             return;
           }
-          console.log("Invoke Identify for", node.nodeId.toString());
-          await identifyCluster.identify({ identifyTime: time });
+          console.log("Invoke Identify for", node.peerAddress?.nodeId.toString());
+          await device.act((agent) => agent.get(IdentifyClient).identify({ identifyTime: time }));
         },
-        endpointId
+        endpointId !== void 0 ? [endpointId] : void 0
       );
     }
   };

package/dist/esm/shell/cmd_identify.js.map

@@ -1,6 +1,6 @@
 {
   "version": 3,
   "sources": ["../../../src/shell/cmd_identify.ts"],
-  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,gBAAgB;AAIV,SAAR,SAA0B,SAAqB;AAClD,SAAO;AAAA,IACH,SAAS;AAAA,IACT,UACI;AAAA,IACJ,SAAS,CAAC,UAAgB;AACtB,aAAO,MACF,WAAW,QAAQ;AAAA,QAChB,UAAU;AAAA,QACV,SAAS;AAAA,QACT,MAAM;AAAA,MACV,CAAC,EACA,WAAW,WAAW;AAAA,QACnB,UAAU;AAAA,QACV,SAAS;AAAA,QACT,MAAM;AAAA,MACV,CAAC,EACA,WAAW,eAAe;AAAA,QACvB,UAAU;AAAA,QACV,SAAS;AAAA,QACT,MAAM;AAAA,MACV,CAAC;AAAA,IACT;AAAA,IAEA,SAAS,OAAO,SAAc;AAC1B,YAAM,EAAE,QAAQ,OAAO,IAAI,WAAW,IAAI;AAC1C,YAAM,QAAQ;AAAA,QACV,MAAM,QAAQ,mBAAmB,MAAM;AAAA,QACvC,OAAO,QAAQ,SAAS;AACpB,gBAAM,kBAAkB,OAAO,iBAAiB,QAAQ;AACxD,cAAI,oBAAoB,QAAW;AAC/B;AAAA,UACJ;AACA,kBAAQ,IAAI,uBAAuB,KAAK,OAAO,SAAS,CAAC;AACzD,gBAAM,gBAAgB,SAAS,EAAE,cAAc,KAAK,CAAC;AAAA,QACzD;AAAA,QACA;AAAA,MACJ;AAAA,IACJ;AAAA,EACJ;AACJ;",
+  "mappings": "AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,SAAS,sBAAsB;AAG/B,SAAS,mBAAmB;AAEb,SAAR,SAA0B,SAAqB;AAClD,SAAO;AAAA,IACH,SAAS;AAAA,IACT,UACI;AAAA,IACJ,SAAS,CAAC,UAAgB;AACtB,aAAO,MACF,WAAW,QAAQ;AAAA,QAChB,UAAU;AAAA,QACV,SAAS;AAAA,QACT,MAAM;AAAA,MACV,CAAC,EACA,WAAW,WAAW;AAAA,QACnB,UAAU;AAAA,QACV,SAAS;AAAA,QACT,MAAM;AAAA,MACV,CAAC,EACA,WAAW,eAAe;AAAA,QACvB,UAAU;AAAA,QACV,SAAS;AAAA,QACT,MAAM;AAAA,MACV,CAAC;AAAA,IACT;AAAA,IAEA,SAAS,OAAO,SAAc;AAC1B,YAAM,EAAE,QAAQ,OAAO,IAAI,WAAW,IAAI;AAC1C,YAAM,QAAQ,MAAM,QAAQ,mBAAmB,MAAM;AACrD,iBAAW,QAAQ,OAAO;AACtB,cAAM,YAAY,IAAI;AAAA,MAC1B;AACA,YAAM,QAAQ;AAAA,QACV;AAAA,QACA,OAAO,QAAQ,SAAS;AACpB,cAAI,OAAO,WAAW,KAAK,CAAC,OAAO,UAAU,IAAI,cAAc,GAAG;AAC9D;AAAA,UACJ;AACA,kBAAQ,IAAI,uBAAuB,KAAK,aAAa,OAAO,SAAS,CAAC;AACtE,gBAAM,OAAO,IAAI,WAAS,MAAM,IAAI,cAAc,EAAE,SAAS,EAAE,cAAc,KAAK,CAAC,CAAC;AAAA,QACxF;AAAA,QACA,eAAe,SAAY,CAAC,UAAU,IAAI;AAAA,MAC9C;AAAA,IACJ;AAAA,EACJ;AACJ;",
   "names": []
 }

package/dist/esm/shell/cmd_nodes.js

@@ -3,17 +3,38 @@
  * Copyright 2022-2026 Matter.js Authors
  * SPDX-License-Identifier: Apache-2.0
  */
-import { capitalize, ChannelType, decamelize, Diagnostic, ServerAddress } from "@matter/general";
-import { CommissioningClient, NetworkClient, SoftwareUpdateManager } from "@matter/node";
-import { PeerAddress, PeerSet } from "@matter/protocol";
+import {
+  capitalize,
+  ChannelType,
+  decamelize,
+  Diagnostic,
+  ImplementationError,
+  InternalError,
+  Logger,
+  Millis,
+  ServerAddress
+} from "@matter/general";
+import {
+  CommissioningClient,
+  NetworkClient,
+  NodeConnectionState,
+  SoftwareUpdateManager
+} from "@matter/node";
+import { BasicInformationClient } from "@matter/node/behaviors/basic-information";
+import { FabricAuthority, PeerAddress, PeerSet } from "@matter/protocol";
 import { FabricIndex, NodeId } from "@matter/types";
-import { NodeStateInformation } from "@project-chip/matter.js/device";
-import { createDiagnosticCallbacks } from "../MatterNode.js";
+import { awaitSeeded } from "../util/awaitSeeded.js";
 import { resolveDclMode, withDclModeOption } from "./ota-dcl-mode.js";
+const logger = Logger.get("cmd_nodes");
+function findCommissionedNode(theNode, nodeId) {
+  return theNode.node.peers.commissioned.find((peer) => peer.peerAddress?.nodeId === nodeId);
+}
 function parseFallbackAddress(input) {
   const match = /^(udp|tcp):\/\/(.+)$/i.exec(input);
   if (!match) {
-    throw new Error(`Invalid address "${input}". Expected udp://<host>:<port> or tcp://<host>:<port>`);
+    throw new ImplementationError(
+      `Invalid address "${input}". Expected udp://<host>:<port> or tcp://<host>:<port>`
+    );
   }
   const type = match[1].toLowerCase() === "tcp" ? "tcp" : "udp";
   const rest = match[2];
@@ -22,21 +43,23 @@ function parseFallbackAddress(input) {
   if (rest.startsWith("[")) {
     const end = rest.indexOf("]");
     if (end === -1 || rest[end + 1] !== ":") {
-      throw new Error(`Invalid IPv6 address "${input}". Expected ${type}://[<ipv6>]:<port>`);
+      throw new ImplementationError(`Invalid IPv6 address "${input}". Expected ${type}://[<ipv6>]:<port>`);
     }
     ip = rest.slice(1, end);
     portStr = rest.slice(end + 2);
   } else {
     const idx = rest.lastIndexOf(":");
     if (idx === -1) {
-      throw new Error(`Missing port in "${input}". Expected ${type}://<host>:<port>`);
+      throw new ImplementationError(`Missing port in "${input}". Expected ${type}://<host>:<port>`);
     }
     ip = rest.slice(0, idx);
     portStr = rest.slice(idx + 1);
   }
   const port = Number(portStr);
   if (!ip.length || !Number.isInteger(port) || port < 1 || port > 65535) {
-    throw new Error(`Invalid host/port in "${input}". Expected ${type}://<host>:<port> with port 1-65535`);
+    throw new ImplementationError(
+      `Invalid host/port in "${input}". Expected ${type}://<host>:<port> with port 1-65535`
+    );
   }
   return { ip, port, type };
 }
@@ -58,23 +81,23 @@ function commands(theNode) {
       async (argv) => {
         const { status } = argv;
         await theNode.start();
-        if (theNode.commissioningController === void 0) {
-          throw new Error("CommissioningController not initialized");
-        }
+        const peers = theNode.node.peers.commissioned;
         switch (status) {
           case "commissioned": {
-            const details = theNode.commissioningController.getCommissionedNodesDetails();
-            details.map((detail) => ({
-              ...detail,
-              nodeId: detail.nodeId.toString()
-            })).forEach((detail) => {
-              console.log(detail);
-            });
+            for (const peer of peers) {
+              const { addresses, deviceName } = peer.state.commissioning;
+              console.log({
+                nodeId: peer.peerAddress?.nodeId.toString(),
+                operationalAddress: addresses?.length ? ServerAddress.urlFor(addresses[0]) : void 0,
+                advertisedName: deviceName,
+                basicInformation: peer.maybeStateOf(BasicInformationClient)
+              });
+            }
             break;
           }
           case "connected": {
-            const nodeIds = theNode.commissioningController.getCommissionedNodes().filter((nodeId) => !!theNode.commissioningController?.getPairedNode(nodeId));
-            console.log(nodeIds.map((nodeId) => nodeId.toString()));
+            const nodeIds = peers.filter((peer) => peer.lifecycle.isConnected).map((peer) => peer.peerAddress?.nodeId);
+            console.log(nodeIds.map((nodeId) => nodeId?.toString()));
             break;
           }
         }
@@ -92,8 +115,11 @@ function commands(theNode) {
       async (argv) => {
         const { nodeId } = argv;
         const node = (await theNode.connectAndGetNodes(nodeId))[0];
-        console.log("Logging structure of Node ", node.nodeId.toString());
-        node.logStructure();
+        if (!await awaitSeeded(node)) {
+          return;
+        }
+        console.log("Logging structure of Node ", node.peerAddress?.nodeId.toString());
+        logger.info(node);
       }
     ).command(
       "descriptor <node-id>",
@@ -108,11 +134,12 @@ function commands(theNode) {
       async (argv) => {
         const { nodeId: nodeIdStr } = argv;
         await theNode.start();
-        if (theNode.commissioningController === void 0) {
-          throw new Error("CommissioningController not initialized");
-        }
         const nodeId = NodeId(BigInt(nodeIdStr));
-        const peerAddress = theNode.commissioningController.fabric.addressOf(nodeId);
+        const peerAddress = findCommissionedNode(theNode, nodeId)?.peerAddress;
+        if (peerAddress === void 0) {
+          console.log(`Node ${nodeIdStr} not commissioned`);
+          return;
+        }
         const peerSet = theNode.node.env.get(PeerSet);
         const peer = peerSet.for(peerAddress);
         if (!peer) {
@@ -181,28 +208,12 @@ Peer Descriptor for node ${nodeIdStr}:`);
       },
       async (argv) => {
         const { nodeId: nodeIdStr, maxSubscriptionInterval, minSubscriptionInterval } = argv;
-        await theNode.start();
-        if (theNode.commissioningController === void 0) {
-          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 !== void 0;
-        for (const nodeIdToProcess of nodeIds) {
-          const node = await theNode.commissioningController.getNode(nodeIdToProcess);
-          node.connect({
-            autoSubscribe,
-            subscribeMinIntervalFloorSeconds: autoSubscribe ? minSubscriptionInterval : void 0,
-            subscribeMaxIntervalCeilingSeconds: autoSubscribe ? maxSubscriptionInterval : void 0,
-            ...createDiagnosticCallbacks()
-          });
-        }
+        await theNode.connectAndGetNodes(nodeIdStr !== "all" ? nodeIdStr : void 0, {
+          autoSubscribe,
+          subscribeMinIntervalFloorSeconds: autoSubscribe ? minSubscriptionInterval : void 0,
+          subscribeMaxIntervalCeilingSeconds: autoSubscribe ? maxSubscriptionInterval : void 0
+        });
       }
     ).command(
       "disconnect [node-id]",
@@ -216,25 +227,17 @@ Peer Descriptor for node ${nodeIdStr}:`);
       },
       async (argv) => {
         const { nodeId: nodeIdStr } = argv;
-        if (theNode.commissioningController === void 0) {
-          console.log("Controller not initialized, nothing to disconnect.");
-          return;
-        }
-        let nodeIds = theNode.commissioningController.getCommissionedNodes();
+        await theNode.start();
+        let nodes = theNode.node.peers.commissioned;
         if (nodeIdStr !== "all") {
           const cmdNodeId = NodeId(BigInt(nodeIdStr));
-          nodeIds = nodeIds.filter((nodeId) => nodeId === cmdNodeId);
-          if (!nodeIds.length) {
-            throw new Error(`Node ${nodeIdStr} not commissioned`);
+          nodes = nodes.filter((node) => node.peerAddress?.nodeId === cmdNodeId);
+          if (!nodes.length) {
+            throw new ImplementationError(`Node ${nodeIdStr} not commissioned`);
           }
         }
-        for (const nodeIdToProcess of nodeIds) {
-          const node = theNode.commissioningController.getPairedNode(nodeIdToProcess);
-          if (node === void 0) {
-            console.log(`Node ${nodeIdToProcess} not connected`);
-            continue;
-          }
-          await node.disconnect();
+        for (const node of nodes) {
+          await node.stop();
         }
       }
     ).command(
@@ -250,31 +253,24 @@ Peer Descriptor for node ${nodeIdStr}:`);
       async (argv) => {
         const { nodeIds: nodeIdStr } = argv;
         await theNode.start();
-        if (theNode.commissioningController === void 0) {
-          throw new Error("CommissioningController not initialized");
-        }
-        let nodeIds = theNode.commissioningController.getCommissionedNodes();
+        let nodes = theNode.node.peers.commissioned;
         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`);
+          nodes = nodes.filter(
+            (node) => node.peerAddress !== void 0 && nodeIdList.includes(node.peerAddress.nodeId)
+          );
+          if (!nodes.length) {
+            throw new ImplementationError(`Node ${nodeIdStr} not commissioned`);
           }
         }
-        const nodeDetails = theNode.commissioningController.getCommissionedNodesDetails();
-        for (const nodeIdToProcess of nodeIds) {
-          const node = theNode.commissioningController.getPairedNode(nodeIdToProcess);
-          if (node === void 0) {
-            const details = nodeDetails.find((nd) => nd.nodeId === nodeIdToProcess);
-            console.log(
-              `Node ${nodeIdToProcess}: Not initialized${details?.deviceData?.basicInformation !== void 0 ? ` (${details.deviceData.basicInformation.vendorName} ${details.deviceData.basicInformation.productName})` : ""}`
-            );
-          } else {
-            const basicInfo = node.basicInformation;
-            console.log(
-              `Node ${nodeIdToProcess}: Node Status: ${capitalize(decamelize(NodeStateInformation[node.connectionState], " "))}${basicInfo !== void 0 ? ` (${basicInfo.vendorName} ${basicInfo.productName})` : ""}`
-            );
-          }
+        for (const node of nodes) {
+          const basicInfo = node.maybeStateOf(BasicInformationClient);
+          const status = capitalize(
+            decamelize(NodeConnectionState[node.lifecycle.connectionState], " ")
+          );
+          console.log(
+            `Node ${node.peerAddress?.nodeId}: Node Status: ${status}${basicInfo !== void 0 ? ` (${basicInfo.vendorName} ${basicInfo.productName})` : ""}`
+          );
         }
       }
     ).command(
@@ -295,14 +291,18 @@ Peer Descriptor for node ${nodeIdStr}:`);
       async (argv) => {
         const { nodeId: nodeIdStr, preference } = argv;
         await theNode.start();
-        if (theNode.commissioningController === void 0) {
-          throw new Error("CommissioningController not initialized");
-        }
         const nodeId = NodeId(BigInt(nodeIdStr));
-        const node = await theNode.commissioningController.getNode(nodeId);
+        const node = findCommissionedNode(theNode, nodeId);
+        if (node === void 0) {
+          throw new ImplementationError(`Node ${nodeIdStr} not commissioned`);
+        }
+        const peerAddress = node.peerAddress;
+        if (peerAddress === void 0) {
+          throw new ImplementationError(`Node ${nodeIdStr} has no peer address`);
+        }
         const pref = preference === "on" ? "tcp" : preference === "off" ? "udp" : void 0;
-        await node.node.setStateOf(NetworkClient, { transportPreference: pref });
-        const peer = theNode.node.env.get(PeerSet).for(theNode.commissioningController.fabric.addressOf(nodeId));
+        await node.setStateOf(NetworkClient, { transportPreference: pref });
+        const peer = theNode.node.env.get(PeerSet).for(peerAddress);
         if (peer) {
           peer.transportPreference = pref === "tcp" ? ChannelType.TCP : void 0;
         }
@@ -326,12 +326,12 @@ Peer Descriptor for node ${nodeIdStr}:`);
         async (argv) => {
           const { nodeId: nodeIdStr } = argv;
           await theNode.start();
-          if (theNode.commissioningController === void 0) {
-            throw new Error("CommissioningController not initialized");
-          }
           const nodeId = NodeId(BigInt(nodeIdStr));
-          const node = await theNode.commissioningController.getNode(nodeId);
-          const addresses = node.node.state.commissioning.addresses;
+          const node = findCommissionedNode(theNode, nodeId);
+          if (node === void 0) {
+            throw new ImplementationError(`Node ${nodeIdStr} not commissioned`);
+          }
+          const addresses = node.state.commissioning.addresses;
           if (!addresses?.length) {
             console.log(`Node ${nodeIdStr} has no fallback addresses stored`);
             return;
@@ -358,18 +358,18 @@ Peer Descriptor for node ${nodeIdStr}:`);
         async (argv) => {
           const { nodeId: nodeIdStr, address: addressStr } = argv;
           await theNode.start();
-          if (theNode.commissioningController === void 0) {
-            throw new Error("CommissioningController not initialized");
-          }
           const nodeId = NodeId(BigInt(nodeIdStr));
-          const node = await theNode.commissioningController.getNode(nodeId);
+          const node = findCommissionedNode(theNode, nodeId);
+          if (node === void 0) {
+            throw new ImplementationError(`Node ${nodeIdStr} not commissioned`);
+          }
           if (addressStr === "drop") {
-            await node.node.setStateOf(CommissioningClient, { addresses: void 0 });
+            await node.setStateOf(CommissioningClient, { addresses: void 0 });
             console.log(`Fallback address for node ${nodeIdStr} dropped`);
             return;
           }
           const address = parseFallbackAddress(addressStr);
-          await node.node.setStateOf(CommissioningClient, { addresses: [address] });
+          await node.setStateOf(CommissioningClient, { addresses: [address] });
           console.log(
             `Fallback address for node ${nodeIdStr} set to ${ServerAddress.urlFor(address)}`
           );
@@ -398,25 +398,20 @@ Peer Descriptor for node ${nodeIdStr}:`);
       async (argv) => {
         const { nodeId: nodeIdStr, maxSubscriptionInterval, minSubscriptionInterval } = argv;
         await theNode.start();
-        if (theNode.commissioningController === void 0) {
-          throw new Error("CommissioningController not initialized");
-        }
-        let nodeIds = theNode.commissioningController.getCommissionedNodes();
         const cmdNodeId = NodeId(BigInt(nodeIdStr));
-        nodeIds = nodeIds.filter((nodeId) => nodeId === cmdNodeId);
-        if (nodeIds.length) {
-          throw new Error(`Node ${nodeIdStr} already known`);
+        if (findCommissionedNode(theNode, cmdNodeId) !== void 0) {
+          throw new ImplementationError(`Node ${nodeIdStr} already known`);
         }
-        await theNode.commissioningController.node.peers.forAddress(
-          theNode.commissioningController.fabric.addressOf(cmdNodeId)
-        );
+        const fabric = theNode.node.env.get(FabricAuthority).fabrics[0];
+        if (fabric === void 0) {
+          throw new InternalError("No controller fabric present after start");
+        }
+        await theNode.node.peers.forAddress(fabric.addressOf(cmdNodeId));
         const autoSubscribe = minSubscriptionInterval !== void 0;
-        const node = await theNode.commissioningController.getNode(cmdNodeId);
-        node.connect({
+        await theNode.connectAndGetNodes(nodeIdStr, {
           autoSubscribe,
           subscribeMinIntervalFloorSeconds: autoSubscribe ? minSubscriptionInterval : void 0,
-          subscribeMaxIntervalCeilingSeconds: autoSubscribe ? maxSubscriptionInterval : void 0,
-          ...createDiagnosticCallbacks()
+          subscribeMaxIntervalCeilingSeconds: autoSubscribe ? maxSubscriptionInterval : void 0
         });
       }
     ).command(
@@ -439,15 +434,15 @@ Peer Descriptor for node ${nodeIdStr}:`);
         async (argv) => {
           const { nodeId: nodeIdStr, local } = argv;
           await theNode.start();
-          if (theNode.commissioningController === void 0) {
-            throw new Error("CommissioningController not initialized");
-          }
           let peerToCheck = void 0;
           if (nodeIdStr !== void 0) {
             const nodeId = NodeId(BigInt(nodeIdStr));
-            peerToCheck = (await theNode.commissioningController.getNode(nodeId))?.node;
+            peerToCheck = findCommissionedNode(theNode, nodeId);
+            if (peerToCheck === void 0) {
+              throw new ImplementationError(`Node ${nodeIdStr} not commissioned`);
+            }
           }
-          const updatesAvailable = await theNode.commissioningController.otaProvider.act(
+          const updatesAvailable = await theNode.otaProviderEndpoint.act(
             (agent) => agent.get(SoftwareUpdateManager).queryUpdates({ peerToCheck, includeStoredUpdates: local })
           );
           if (updatesAvailable.length) {
@@ -482,24 +477,24 @@ Peer Descriptor for node ${nodeIdStr}:`);
           const { nodeId: nodeIdStr, mode, local } = argv;
           const { label: dclMode, isProduction } = resolveDclMode(theNode, mode);
           await theNode.start();
-          if (theNode.commissioningController === void 0) {
-            throw new Error("CommissioningController not initialized");
-          }
           const nodeId = NodeId(BigInt(nodeIdStr));
-          const nodeDetails = theNode.commissioningController.getCommissionedNodesDetails().find((nd) => nd.nodeId === nodeId);
-          const basicInfo = nodeDetails?.deviceData?.basicInformation;
-          if (!basicInfo) {
-            throw new Error(`Node ${nodeIdStr} has no basic information available`);
+          const node = findCommissionedNode(theNode, nodeId);
+          if (node === void 0) {
+            throw new ImplementationError(`Node ${nodeIdStr} not commissioned`);
+          }
+          const basicInfo = node.maybeStateOf(BasicInformationClient);
+          if (basicInfo === void 0) {
+            throw new ImplementationError(
+              `Node ${nodeIdStr} has no basic information available`
+            );
           }
           if (basicInfo.vendorId === void 0 || basicInfo.productId === void 0 || basicInfo.softwareVersion === void 0) {
-            throw new Error(
-              `Node ${nodeIdStr} is missing required basic information for OTA check`
+            throw new ImplementationError(
+              `Node ${nodeIdStr} BasicInformation is incomplete; connect the node first`
             );
           }
           console.log(`Checking for OTA updates for node ${nodeIdStr}...`);
-          console.log(
-            `  Vendor ID: ${Diagnostic.hex(basicInfo.vendorId, 4).toUpperCase()}`
-          );
+          console.log(`  Vendor ID: ${Diagnostic.hex(basicInfo.vendorId, 4).toUpperCase()}`);
           console.log(
             `  Product ID: ${Diagnostic.hex(basicInfo.productId, 4).toUpperCase()}`
           );
@@ -561,24 +556,24 @@ Run "nodes ota download ${nodeIdStr}${mode === "auto" ? "" : ` --mode ${mode}`}"
           const { label: dclMode, isProduction } = resolveDclMode(theNode, mode);
           const forceDownload = force === true;
           await theNode.start();
-          if (theNode.commissioningController === void 0) {
-            throw new Error("CommissioningController not initialized");
-          }
           const nodeId = NodeId(BigInt(nodeIdStr));
-          const nodeDetails = theNode.commissioningController.getCommissionedNodesDetails().find((nd) => nd.nodeId === nodeId);
-          const basicInfo = nodeDetails?.deviceData?.basicInformation;
-          if (!basicInfo) {
-            throw new Error(`Node ${nodeIdStr} has no basic information available`);
+          const node = findCommissionedNode(theNode, nodeId);
+          if (node === void 0) {
+            throw new ImplementationError(`Node ${nodeIdStr} not commissioned`);
+          }
+          const basicInfo = node.maybeStateOf(BasicInformationClient);
+          if (basicInfo === void 0) {
+            throw new ImplementationError(
+              `Node ${nodeIdStr} has no basic information available`
+            );
           }
           if (basicInfo.vendorId === void 0 || basicInfo.productId === void 0 || basicInfo.softwareVersion === void 0) {
-            throw new Error(
-              `Node ${nodeIdStr} is missing required basic information for OTA check`
+            throw new ImplementationError(
+              `Node ${nodeIdStr} BasicInformation is incomplete; connect the node first`
             );
           }
           console.log(`Checking for OTA updates for node ${nodeIdStr}...`);
-          console.log(
-            `  Vendor ID: ${Diagnostic.hex(basicInfo.vendorId, 4).toUpperCase()}`
-          );
+          console.log(`  Vendor ID: ${Diagnostic.hex(basicInfo.vendorId, 4).toUpperCase()}`);
           console.log(
             `  Product ID: ${Diagnostic.hex(basicInfo.productId, 4).toUpperCase()}`
           );
@@ -634,31 +629,47 @@ You can now apply this update to the device using your device's OTA mechanism.`
             describe: "Apply update from local file",
             type: "boolean",
             default: false
+          }).option("max-block-size", {
+            describe: "Cap the BDX block size for this transfer, in bytes (default: whatever the device requests)",
+            type: "number"
+          }).option("mrp-margin", {
+            describe: "Additive MRP retransmission margin for this transfer, in milliseconds (default: derived from the device's medium)",
+            type: "number"
+          }).check((argv) => {
+            const blockSize = argv.maxBlockSize;
+            const margin = argv.mrpMargin;
+            if (blockSize !== void 0 && (!Number.isInteger(blockSize) || blockSize <= 0)) {
+              throw new Error("--max-block-size must be a positive integer");
+            }
+            if (margin !== void 0 && (!Number.isFinite(margin) || margin < 0)) {
+              throw new Error("--mrp-margin must be a non-negative number of ms");
+            }
+            return true;
           });
         },
         async (argv) => {
-          const { nodeId: nodeIdStr, mode, force, local } = argv;
+          const { nodeId: nodeIdStr, mode, force, local, maxBlockSize, mrpMargin } = argv;
           const { label: dclMode, isProduction } = resolveDclMode(theNode, mode);
           const forceDownload = force === true;
           await theNode.start();
-          if (theNode.commissioningController === void 0) {
-            throw new Error("CommissioningController not initialized");
-          }
           const nodeId = NodeId(BigInt(nodeIdStr));
-          const nodeDetails = theNode.commissioningController.getCommissionedNodesDetails().find((nd) => nd.nodeId === nodeId);
-          const basicInfo = nodeDetails?.deviceData?.basicInformation;
-          if (!basicInfo) {
-            throw new Error(`Node ${nodeIdStr} has no basic information available`);
+          const node = findCommissionedNode(theNode, nodeId);
+          if (node === void 0) {
+            throw new ImplementationError(`Node ${nodeIdStr} not commissioned`);
+          }
+          const basicInfo = node.maybeStateOf(BasicInformationClient);
+          if (basicInfo === void 0) {
+            throw new ImplementationError(
+              `Node ${nodeIdStr} has no basic information available`
+            );
           }
           if (basicInfo.vendorId === void 0 || basicInfo.productId === void 0 || basicInfo.softwareVersion === void 0) {
-            throw new Error(
-              `Node ${nodeIdStr} is missing required basic information for OTA check`
+            throw new ImplementationError(
+              `Node ${nodeIdStr} BasicInformation is incomplete; connect the node first`
             );
           }
           console.log(`Checking for OTA updates for node ${nodeIdStr}...`);
-          console.log(
-            `  Vendor ID: ${Diagnostic.hex(basicInfo.vendorId, 4).toUpperCase()}`
-          );
+          console.log(`  Vendor ID: ${Diagnostic.hex(basicInfo.vendorId, 4).toUpperCase()}`);
           console.log(
             `  Product ID: ${Diagnostic.hex(basicInfo.productId, 4).toUpperCase()}`
           );
@@ -709,17 +720,27 @@ You can now apply this update to the device using your device's OTA mechanism.`
               `Update to version ${updateVersion} (${localUpdates[0].softwareVersionString}) found in local storage: ${localUpdates[0].filename}`
             );
           }
-          const node = theNode.commissioningController.getPairedNode(nodeId);
-          if (node === void 0) {
-            throw new Error(`Node ${nodeIdStr} not connected`);
-          }
-          await theNode.commissioningController.otaProvider.act((agent) => {
-            return agent.get(SoftwareUpdateManager).forceUpdate(
-              PeerAddress({ nodeId, fabricIndex: FabricIndex(1) }),
-              basicInfo.vendorId,
-              basicInfo.productId,
-              updateVersion
-            );
+          if (!node.lifecycle.isConnected) {
+            throw new ImplementationError(`Node ${nodeIdStr} not connected`);
+          }
+          const peerAddress = node.peerAddress;
+          if (peerAddress === void 0) {
+            throw new ImplementationError(`Node ${nodeIdStr} has no peer address`);
+          }
+          if (maxBlockSize !== void 0) {
+            console.log(`Capping BDX block size to ${maxBlockSize} bytes`);
+          }
+          if (mrpMargin !== void 0) {
+            console.log(`Using an MRP retransmission margin of ${mrpMargin}ms`);
+          }
+          await theNode.otaProviderEndpoint.act((agent) => {
+            return agent.get(SoftwareUpdateManager).forceUpdate(PeerAddress({ nodeId, fabricIndex: FabricIndex(1) }), {
+              vendorId: basicInfo.vendorId,
+              productId: basicInfo.productId,
+              targetSoftwareVersion: updateVersion,
+              maxBdxBlockSize: maxBlockSize,
+              bdxAdditionalMrpDelay: mrpMargin === void 0 ? void 0 : Millis(mrpMargin)
+            });
           });
         }
       ).demandCommand(1, "Please specify an OTA subcommand"),