/** * @license * Copyright 2022-2026 Matter.js Authors * SPDX-License-Identifier: Apache-2.0 */ import { Diagnostic, Logger, UnexpectedDataError } from "@matter/general"; import { Matter } from "@matter/model"; import { ClusterId, EndpointNumber, EventId, EventNumber, NodeId, Priority, Status, TlvAny, TlvEventData, TlvEventReport, TlvEventStatus, TlvOfModel, TlvStream, TypeFromSchema, } from "@matter/types"; const logger = Logger.get("EventDataDecoder"); /** @deprecated since 0.17 — will be removed in 0.19. Import from `@project-chip/matter.js/cluster` instead. */ export type DecodedEventData = { eventNumber: EventNumber; priority: Priority; epochTimestamp?: number | bigint; systemTimestamp?: number | bigint; deltaEpochTimestamp?: number | bigint; deltaSystemTimestamp?: number | bigint; data?: T; }; /** @deprecated since 0.17 — will be removed in 0.19. Import from `@project-chip/matter.js/cluster` instead. */ export type DecodedEventReportEntry = { path: { nodeId?: NodeId; endpointId: EndpointNumber; clusterId: ClusterId; eventId: EventId; eventName: string; }; }; /** * Represents a fully qualified and decoded event value from a received DataReport. * * @deprecated since 0.17 — will be removed in 0.19. Import from `@project-chip/matter.js/cluster` instead. */ export type DecodedEventReportValue = DecodedEventReportEntry & { events: DecodedEventData[]; }; /** * Represents a fully qualified and decoded event status from a received DataReport. * * @deprecated since 0.17 — will be removed in 0.19. Import from `@project-chip/matter.js/cluster` instead. */ export type DecodedEventReportStatus = DecodedEventReportEntry & { status?: Status; clusterStatus?: number; }; /** * @deprecated since 0.17 — will be removed in 0.19. Use the streaming `InputChunk` API or `decodeDataReport` from `@project-chip/matter.js/cluster`. */ export function normalizeAndDecodeReadEventReport(data: TypeFromSchema[]): { eventData: DecodedEventReportValue[]; 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 { eventData: normalizeAndDecodeEventData(dataValues), eventStatus: normalizeEventStatus(dataStatus), }; } /** * @deprecated since 0.17 — will be removed in 0.19. Use the streaming `InputChunk` API instead. */ export function normalizeEventData( data: TypeFromSchema[], ): TypeFromSchema[][] { // Put all returned values into a map to group by path const responseList = new Map[]>(); // TODO CHECK data.forEach(value => { if (!value) return; const { path: { nodeId, endpointId, clusterId, eventId }, } = value; const mapId = `${nodeId}-${endpointId}-${clusterId}-${eventId}`; const list = responseList.get(mapId) || []; list.push(value); responseList.set(mapId, list); }); return Array.from(responseList.values()); } /** * @deprecated since 0.17 — will be removed in 0.19. Use the streaming `InputChunk` API or `decodeDataReport` from `@project-chip/matter.js/cluster`. */ export function normalizeAndDecodeEventData( data: TypeFromSchema[], ): DecodedEventReportValue[] { const responseList = normalizeEventData(data); const result = new Array>(); responseList.forEach(values => { const { path: { nodeId, endpointId, clusterId, eventId }, } = values[0]; if (endpointId === undefined || clusterId === undefined || eventId === undefined) { throw new UnexpectedDataError(`Invalid event path ${endpointId}/${clusterId}/${eventId}`); } try { const clusterModel = Matter.clusters(clusterId); const eventModel = clusterModel?.events(eventId); if (eventModel === undefined) { logger.debug( `Decode unknown event ${Diagnostic.hex(clusterId)}/${Diagnostic.hex(eventId)} via the AnySchema.`, ); const eventName = `Unknown (${Diagnostic.hex(eventId)})`; const events = values.map(eventData => ({ ...eventData, data: eventData.data === undefined ? undefined : decodeUnknownEventValue(eventData.data), path: undefined, })); result.push({ path: { nodeId, endpointId, clusterId, eventId, eventName }, events }); return; } const schema = TlvOfModel(eventModel); const events = values.map(eventData => ({ ...eventData, data: eventData.data === undefined ? undefined : schema.decodeTlv(eventData.data), path: undefined, })); result.push({ path: { nodeId, endpointId, clusterId, eventId, eventName: eventModel.propertyName }, events, }); } catch (error: any) { logger.warn(`Error decoding event ${endpointId}/${clusterId}/${eventId}: ${error.message}`); } }); return result; } /** * @deprecated since 0.17 — will be removed in 0.19. Use the streaming `InputChunk` API or `decodeDataReport` from `@project-chip/matter.js/cluster`. */ export function normalizeEventStatus(data: TypeFromSchema[]): DecodedEventReportStatus[] { const result = new Array(); 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 clusterModel = Matter.clusters(clusterId); const eventModel = clusterModel?.events(eventId); if (eventModel === 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: eventModel.propertyName }, status: status.status, clusterStatus: status.clusterStatus, }); } catch (error: any) { logger.warn(`Error decoding event ${endpointId}/${clusterId}/${eventId}: ${error.message}`); } }); return result; } export function decodeUnknownEventValue(data: TlvStream): any { const schema = TlvAny; if (data.length === 0) { return undefined; } const tlvEncoded = schema.decodeTlv(data); return schema.decodeAnyTlvStream(tlvEncoded); }