@matter/protocol 0.13.0-alpha.0-20250318-c1aa38b08 → 0.13.0-alpha.0-20250322-f085fa576

package/src/interaction/EventDataDecoder.ts

@@ -14,9 +14,11 @@ import {
     getClusterById,
     getClusterEventById,
     NodeId,
+    Status,
     TlvAny,
     TlvEventData,
     TlvEventReport,
+    TlvEventStatus,
     TlvStream,
     TypeFromSchema,
 } from "#types";
@@ -33,7 +35,7 @@ export type DecodedEventData<T> = {
     data?: T;
 };
 
-export type DecodedEventReportValue<T> = {
+export type DecodedEventReportEntry = {
     path: {
         nodeId?: NodeId;
         endpointId: EndpointNumber;
@@ -41,16 +43,32 @@ export type DecodedEventReportValue<T> = {
         eventId: EventId;
         eventName: string;
     };
+};
+
+/** Represents a fully qualified and decoded attribute value from a received DataReport */
+export type DecodedEventReportValue<T> = DecodedEventReportEntry & {
     events: DecodedEventData<T>[];
 };
 
-export function normalizeAndDecodeReadEventReport(
-    data: TypeFromSchema<typeof TlvEventReport>[],
-): DecodedEventReportValue<any>[] {
+/** Represents a fully qualified and decoded attribute status from a received DataReport */
+export type DecodedEventReportStatus = DecodedEventReportEntry & {
+    status?: Status;
+    clusterStatus?: number;
+};
+
+// TODO: Convert into a Generator function once we migrate Reading Data for controller to also be streaming
+export function normalizeAndDecodeReadEventReport(data: TypeFromSchema<typeof TlvEventReport>[]): {
+    eventData: DecodedEventReportValue<any>[];
+    eventStatus: DecodedEventReportStatus[];
+} {
     // TODO Decide how to handle the attribute report status field, right now we ignore it
     const dataValues = data.flatMap(({ eventData }) => (eventData !== undefined ? eventData : []));
+    const dataStatus = data.flatMap(({ eventStatus }) => (eventStatus !== undefined ? eventStatus : []));
 
-    return normalizeAndDecodeEventData(dataValues);
+    return {
+        eventData: normalizeAndDecodeEventData(dataValues),
+        eventStatus: normalizeEventStatus(dataStatus),
+    };
 }
 
 export function normalizeEventData(
@@ -121,6 +139,40 @@ export function normalizeAndDecodeEventData(
     return result;
 }
 
+export function normalizeEventStatus(data: TypeFromSchema<typeof TlvEventStatus>[]): DecodedEventReportStatus[] {
+    const result = new Array<DecodedEventReportStatus>();
+    data.forEach(entry => {
+        const {
+            path: { nodeId, endpointId, clusterId, eventId },
+            status,
+        } = entry;
+
+        if (endpointId === undefined || clusterId === undefined || eventId === undefined) {
+            throw new UnexpectedDataError(`Invalid event path ${endpointId}/${clusterId}/${eventId}`);
+        }
+        try {
+            const cluster = getClusterById(clusterId);
+            const eventDetail = getClusterEventById(cluster, eventId);
+            if (eventDetail === undefined) {
+                result.push({
+                    path: { nodeId, endpointId, clusterId, eventId, eventName: `Unknown (${Diagnostic.hex(eventId)})` },
+                    status: status.status,
+                    clusterStatus: status.clusterStatus,
+                });
+                return;
+            }
+            result.push({
+                path: { nodeId, endpointId, clusterId, eventId, eventName: eventDetail.name },
+                status: status.status,
+                clusterStatus: status.clusterStatus,
+            });
+        } catch (error: any) {
+            logger.error(`Error decoding event ${endpointId}/${clusterId}/${eventId}: ${error.message}`);
+        }
+    });
+    return result;
+}
+
 export function decodeUnknownEventValue(data: TlvStream): any {
     const schema = TlvAny;
 

package/src/interaction/InteractionClient.ts

@@ -31,7 +31,9 @@ import {
     Event,
     EventId,
     EventNumber,
+    FabricIndex,
     NodeId,
+    ObjectSchema,
     RequestType,
     ResponseType,
     StatusCode,
@@ -46,10 +48,11 @@ import {
     resolveCommandName,
     resolveEventName,
 } from "#types";
+import { MessageChannel } from "../protocol/ExchangeManager.js";
 import { ExchangeProvider, ReconnectableExchangeProvider } from "../protocol/ExchangeProvider.js";
-import { DecodedAttributeReportValue } from "./AttributeDataDecoder.js";
+import { DecodedAttributeReportStatus, DecodedAttributeReportValue } from "./AttributeDataDecoder.js";
 import { DecodedDataReport } from "./DecodedDataReport.js";
-import { DecodedEventData, DecodedEventReportValue } from "./EventDataDecoder.js";
+import { DecodedEventData, DecodedEventReportStatus, DecodedEventReportValue } from "./EventDataDecoder.js";
 import { DataReport, InteractionClientMessenger, ReadRequest } from "./InteractionMessenger.js";
 import { RegisteredSubscription, SubscriptionClient } from "./SubscriptionClient.js";
 
@@ -103,6 +106,17 @@ export class InteractionClientProvider {
         return this.getInteractionClient(address, discoveryOptions);
     }
 
+    async getInteractionClientForChannel(channel: MessageChannel): Promise<InteractionClient> {
+        const exchangeProvider = await this.#peers.exchangeProviderFor(channel);
+
+        return new InteractionClient(
+            exchangeProvider,
+            this.#peers.subscriptionClient,
+            undefined,
+            this.#peers.interactionQueue,
+        );
+    }
+
     async getInteractionClient(address: PeerAddress, discoveryOptions: DiscoveryOptions) {
         let client = this.#clients.get(address);
         if (client !== undefined) {
@@ -141,11 +155,12 @@ export class InteractionClient {
     readonly #ownSubscriptionIds = new Set<number>();
     readonly #subscriptionClient: SubscriptionClient;
     readonly #queue?: PromiseQueue;
+    readonly #address?: PeerAddress;
 
     constructor(
         exchangeProvider: ExchangeProvider,
         subscriptionClient: SubscriptionClient,
-        readonly address: PeerAddress,
+        address?: PeerAddress,
         queue?: PromiseQueue,
         nodeStore?: PeerDataStore,
     ) {
@@ -153,6 +168,18 @@ export class InteractionClient {
         this.#nodeStore = nodeStore;
         this.#subscriptionClient = subscriptionClient;
         this.#queue = queue;
+        this.#address = address;
+    }
+
+    get address() {
+        if (this.#address === undefined) {
+            throw new ImplementationError("This InteractionClient is not bound to a specific peer.");
+        }
+        return this.#address;
+    }
+
+    get isReconnectable() {
+        return this.#exchangeProvider instanceof ReconnectableExchangeProvider;
     }
 
     get channelUpdated() {
@@ -233,6 +260,22 @@ export class InteractionClient {
         return (await this.getMultipleAttributesAndEvents(options)).attributeReports;
     }
 
+    async getMultipleAttributesAndStatus(
+        options: {
+            attributes?: { endpointId?: EndpointNumber; clusterId?: ClusterId; attributeId?: AttributeId }[];
+            dataVersionFilters?: { endpointId: EndpointNumber; clusterId: ClusterId; dataVersion: number }[];
+            enrichCachedAttributeData?: boolean;
+            isFabricFiltered?: boolean;
+            executeQueued?: boolean;
+        } = {},
+    ): Promise<{
+        attributeData: DecodedAttributeReportValue<any>[];
+        attributeStatus?: DecodedAttributeReportStatus[];
+    }> {
+        const { attributeReports, attributeStatus } = await this.getMultipleAttributesAndEvents(options);
+        return { attributeData: attributeReports, attributeStatus };
+    }
+
     async getMultipleEvents(
         options: {
             events?: { endpointId?: EndpointNumber; clusterId?: ClusterId; eventId?: EventId }[];
@@ -244,6 +287,18 @@ export class InteractionClient {
         return (await this.getMultipleAttributesAndEvents(options)).eventReports;
     }
 
+    async getMultipleEventsAndStatus(
+        options: {
+            events?: { endpointId?: EndpointNumber; clusterId?: ClusterId; eventId?: EventId }[];
+            eventFilters?: TypeFromSchema<typeof TlvEventFilter>[];
+            isFabricFiltered?: boolean;
+            executeQueued?: boolean;
+        } = {},
+    ): Promise<{ eventData: DecodedEventReportValue<any>[]; eventStatus?: DecodedEventReportStatus[] }> {
+        const { eventReports, eventStatus } = await this.getMultipleAttributesAndEvents(options);
+        return { eventData: eventReports, eventStatus };
+    }
+
     async getMultipleAttributesAndEvents(
         options: {
             attributes?: { endpointId?: EndpointNumber; clusterId?: ClusterId; attributeId?: AttributeId }[];
@@ -405,12 +460,23 @@ export class InteractionClient {
 
         // Normalize and decode the response
         const normalizedResult = DecodedDataReport(response);
+        const { attributeReports, attributeStatus, eventReports, eventStatus } = normalizedResult;
+
+        const logData = Array<string>();
+        if (attributeReports.length > 0) {
+            logData.push(`attributes ${attributeReports.map(({ path }) => resolveAttributeName(path)).join(", ")}`);
+        }
+        if (eventReports.length > 0) {
+            logData.push(`events ${eventReports.map(({ path }) => resolveEventName(path)).join(", ")}`);
+        }
+        if (attributeStatus !== undefined && attributeStatus.length > 0) {
+            logData.push(`attributeErrors ${attributeStatus.map(({ path }) => resolveAttributeName(path)).join(", ")}`);
+        }
+        if (eventStatus !== undefined && eventStatus.length > 0) {
+            logData.push(`eventErrors ${eventStatus.map(({ path }) => resolveEventName(path)).join(", ")}`);
+        }
         logger.debug(
-            `Received read response with attributes ${normalizedResult.attributeReports
-                .map(({ path, value }) => `${resolveAttributeName(path)} = ${Logger.toJSON(value)}`)
-                .join(", ")} and events ${normalizedResult.eventReports
-                .map(({ path, events }) => `${resolveEventName(path)} = ${Logger.toJSON(events)}`)
-                .join(", ")}`,
+            logData.length ? `Received read response with ${logData.join(", ")}` : "Received empty read response",
         );
         return normalizedResult;
     }
@@ -893,11 +959,11 @@ export class InteractionClient {
             eventReports?: DecodedEventReportValue<any>[];
             subscriptionId?: number;
         }) => {
-            updateReceived?.();
             if (
                 (!Array.isArray(dataReport.attributeReports) || !dataReport.attributeReports.length) &&
                 (!Array.isArray(dataReport.eventReports) || !dataReport.eventReports.length)
             ) {
+                updateReceived?.();
                 return;
             }
             const { attributeReports, eventReports } = dataReport;
@@ -948,6 +1014,7 @@ export class InteractionClient {
                     attributeListener?.(data, changed, oldValue);
                 }
             }
+            updateReceived?.();
         };
 
         const seedReport = DecodedDataReport(report);
@@ -977,23 +1044,47 @@ export class InteractionClient {
         clusterId: ClusterId;
         request: RequestType<C>;
         command: C;
+
+        /** Send as timed request. If no timedRequestTimeoutMs is provided the default of 10s will be used. */
         asTimedRequest?: boolean;
+
+        /** Use this timeout and send the request as Timed Request. If this is specified the above parameter is implied. */
         timedRequestTimeoutMs?: number;
+
+        /** Use an extended Message Response Timeout as defined for FailSafe cases which is 30s. */
         useExtendedFailSafeMessageResponseTimeout?: boolean;
+
+        /** Execute this request queued - mainly used to execute invokes sequentially for thread devices. */
         executeQueued?: boolean;
+
+        /** Skip request data validation. Use this only when you know that your data is correct and validation would return an error. */
+        skipValidation?: boolean;
     }): Promise<ResponseType<C>> {
         const { executeQueued } = options;
 
         const {
             endpointId,
             clusterId,
-            request,
             command: { requestId, requestSchema, responseId, responseSchema, optional, timed },
             asTimedRequest,
             timedRequestTimeoutMs = DEFAULT_TIMED_REQUEST_TIMEOUT_MS,
             useExtendedFailSafeMessageResponseTimeout = false,
+            skipValidation,
         } = options;
-        const timedRequest = timed || asTimedRequest === true || options.timedRequestTimeoutMs !== undefined;
+        let { request } = options;
+        const timedRequest =
+            (timed && !skipValidation) || asTimedRequest === true || options.timedRequestTimeoutMs !== undefined;
+
+        if (requestSchema instanceof ObjectSchema) {
+            if (request === undefined) {
+                // If developer did not provide a request object, create an empty one if it needs to be an object
+                // This can happen when all object properties are optional
+                request = {} as RequestType<C>;
+            }
+            if (requestSchema.isFabricScoped && request.fabricIndex === undefined) {
+                request.fabricIndex = FabricIndex.NO_FABRIC;
+            }
+        }
 
         logger.debug(
             `Invoking command: ${resolveCommandName({
@@ -1003,7 +1094,9 @@ export class InteractionClient {
             })} with ${Logger.toJSON(request)}`,
         );
 
-        requestSchema.validate(request);
+        if (!skipValidation) {
+            requestSchema.validate(request);
+        }
 
         const commandFields = requestSchema.encodeTlv(request);
 

package/src/interaction/InteractionMessenger.ts

@@ -14,6 +14,7 @@ import {
 } from "#general";
 import { Specification } from "#model";
 import {
+    ReceivedStatusResponseError,
     Status,
     StatusCode,
     StatusResponseError,
@@ -184,7 +185,10 @@ class InteractionMessenger {
         if (messageType !== MessageType.StatusResponse) return;
         const { status } = TlvStatusResponse.decode(payload);
         if (status !== StatusCode.Success)
-            throw new StatusResponseError(`Received error status: ${status}${logHint ? ` (${logHint})` : ""}`, status);
+            throw new ReceivedStatusResponseError(
+                `Received error status: ${status}${logHint ? ` (${logHint})` : ""}`,
+                status,
+            );
     }
 
     getExchangeChannelName() {
@@ -680,7 +684,7 @@ export class IncomingInteractionClientMessenger extends InteractionMessenger {
         if (receivedMessageType !== messageType) {
             if (receivedMessageType === MessageType.StatusResponse) {
                 const statusCode = TlvStatusResponse.decode(message.payload).status;
-                throw new StatusResponseError(`Received status response ${statusCode}`, statusCode);
+                throw new ReceivedStatusResponseError(`Received status response ${statusCode}`, statusCode);
             }
             throw new MatterFlowError(
                 `Received unexpected message type ${receivedMessageType.toString(16)}. Expected ${messageType.toString(

package/src/interaction/InteractionServer.ts

@@ -4,7 +4,16 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
-import { Crypto, Diagnostic, InternalError, Logger, MatterFlowError, Observable, ServerAddressIp } from "#general";
+import {
+    Crypto,
+    Diagnostic,
+    InternalError,
+    Logger,
+    MatterError,
+    MatterFlowError,
+    Observable,
+    ServerAddressIp,
+} from "#general";
 import { AttributeModel, ClusterModel, CommandModel, GLOBAL_IDS, MatterModel, Specification } from "#model";
 import { PeerAddress } from "#peer/PeerAddress.js";
 import { SessionManager } from "#session/SessionManager.js";
@@ -19,6 +28,7 @@ import {
     EventNumber,
     INTERACTION_PROTOCOL_ID,
     NodeId,
+    ReceivedStatusResponseError,
     StatusCode,
     StatusResponseError,
     TlvAny,
@@ -1115,12 +1125,12 @@ export class InteractionServer implements ProtocolHandler, InteractionRecipient
                 exchange,
                 message,
             );
-        } catch (error: any) {
+        } catch (error) {
             logger.error(
                 `Subscription ${subscriptionId} for Session ${session.id}: Error while sending initial data reports`,
-                error,
+                error instanceof MatterError ? error.message : error,
             );
-            if (error instanceof StatusResponseError) {
+            if (error instanceof StatusResponseError && !(error instanceof ReceivedStatusResponseError)) {
                 logger.info(`Sending status response ${error.code} for interaction error: ${error.message}`);
                 await messenger.sendStatus(error.code, {
                     logContext: {

package/src/peer/ControllerCommissioner.ts

@@ -11,6 +11,7 @@ import { Fabric } from "#fabric/Fabric.js";
 import {
     Channel,
     ChannelType,
+    ClassExtends,
     Environment,
     Environmental,
     isIPv6,
@@ -55,6 +56,12 @@ export interface CommissioningOptions extends Partial<ControllerCommissioningFlo
      * not throw, the commissioner considers commissioning complete.
      */
     finalizeCommissioning?: (peerAddress: PeerAddress, discoveryData?: DiscoveryData) => Promise<void>;
+
+    /**
+     * Commissioning Flow Implementation as class that extends the official implementation to use for commissioning.
+     * Defaults to the matter.js default implementation {@link ControllerCommissioningFlow}.
+     */
+    commissioningFlowImpl?: ClassExtends<ControllerCommissioningFlow>;
 }
 
 /**
@@ -169,9 +176,11 @@ export class ControllerCommissioner {
     }
 
     /**
-     * Commission a node with discovery.
+     * Discover and establish a PASE channel with a device.
      */
-    async commissionWithDiscovery(options: DiscoveryAndCommissioningOptions): Promise<PeerAddress> {
+    async discoverAndEstablishPase(
+        options: DiscoveryAndCommissioningOptions,
+    ): Promise<{ paseSecureChannel: MessageChannel; discoveryData?: DiscoveryData }> {
         const {
             discovery: { timeoutSeconds = 30 },
             passcode,
@@ -211,7 +220,7 @@ export class ControllerCommissioner {
         const scannersToUse = this.#context.scanners.select(discoveryCapabilities);
 
         logger.info(
-            `Commissioning device with identifier ${Logger.toJSON(identifierData)} and ${
+            `Connecting to device with identifier ${Logger.toJSON(identifierData)} and ${
                 scannersToUse.length
             } scanners and knownAddress ${Logger.toJSON(knownAddress)}`,
         );
@@ -251,6 +260,17 @@ export class ControllerCommissioner {
             paseSecureChannel = result;
         }
 
+        return { paseSecureChannel, discoveryData };
+    }
+
+    /**
+     * Commission a node with discovery.
+     */
+    async commissionWithDiscovery(options: DiscoveryAndCommissioningOptions): Promise<PeerAddress> {
+        // Establish PASE channel
+        const { paseSecureChannel, discoveryData } = await this.discoverAndEstablishPase(options);
+
+        // Commission the node
         return await this.#commissionConnectedNode(paseSecureChannel, options, discoveryData);
     }
 
@@ -266,7 +286,7 @@ export class ControllerCommissioner {
     ): Promise<MessageChannel> {
         let paseChannel: Channel<Uint8Array>;
         if (device !== undefined) {
-            logger.info(`Commissioning device`, MdnsScanner.discoveryDataDiagnostics(device));
+            logger.info(`Establish PASE to device`, MdnsScanner.discoveryDataDiagnostics(device));
         }
         if (address.type === "udp") {
             const { ip } = address;
@@ -347,7 +367,11 @@ export class ControllerCommissioner {
             ...options,
         };
 
-        const { fabric, finalizeCommissioning: performCaseCommissioning } = commissioningOptions;
+        const {
+            fabric,
+            finalizeCommissioning: performCaseCommissioning,
+            commissioningFlowImpl = ControllerCommissioningFlow,
+        } = commissioningOptions;
 
         // TODO: Create the fabric only when needed before commissioning (to do when refactoring MatterController away)
         // TODO also move certificateManager and other parts into that class to get rid of them here
@@ -381,7 +405,7 @@ export class ControllerCommissioner {
         logger.info(
             `Start commissioning of node ${address.nodeId} into fabric ${fabric.fabricId} (index ${address.fabricIndex})`,
         );
-        const commissioningManager = new ControllerCommissioningFlow(
+        const commissioningManager = new commissioningFlowImpl(
             // Use the created secure session to do the commissioning
             new InteractionClient(
                 new DedicatedChannelExchangeProvider(this.#context.exchanges, paseSecureMessageChannel),