@willieee802/zigbee-herdsman 0.49.4 → 0.50.0

package/src/controller/model/device.ts

@@ -7,9 +7,9 @@ import * as ZSpec from "../../zspec";
 import {BroadcastAddress} from "../../zspec/enums";
 import type {Eui64} from "../../zspec/tstypes";
 import * as Zcl from "../../zspec/zcl";
-import type {TClusterCommandPayload, TClusterPayload, TPartialClusterAttributes} from "../../zspec/zcl/definition/clusters-types";
-import type {ClusterDefinition, CustomClusters} from "../../zspec/zcl/definition/tstype";
-import type {TZclFrame} from "../../zspec/zcl/zclFrame";
+import type {TClusterCommandPayload, TPartialClusterAttributes} from "../../zspec/zcl/definition/clusters-types";
+import type {Cluster, CustomClusters} from "../../zspec/zcl/definition/tstype";
+import type {TFoundationZclFrame, TZclFrame} from "../../zspec/zcl/zclFrame";
 import * as Zdo from "../../zspec/zdo";
 import type {BindingTableEntry, LQITableEntry, RoutingTableEntry} from "../../zspec/zdo/definition/tstypes";
 import type {ControllerEventMap} from "../controller";
@@ -43,6 +43,11 @@ const INTERVIEW_GENBASIC_ATTRIBUTES = [
     "swBuildId",
 ] as const;
 
+const GEN_BASIC_CLUSTER_ID = Zcl.Clusters.genBasic.ID;
+const GEN_TIME_CLUSTER_ID = Zcl.Clusters.genTime.ID;
+const GEN_POLL_CTRL_CLUSTER_ID = Zcl.Clusters.genPollCtrl.ID;
+const GEN_OTA_CLUSTER_ID = Zcl.Clusters.genOta.ID;
+
 type CustomReadResponse = (frame: Zcl.Frame, endpoint: Endpoint) => boolean;
 
 export enum InterviewState {
@@ -74,6 +79,7 @@ export class Device extends Entity<ControllerEventMap> {
     private _gpSecurityKey?: number[];
     #scheduledOta: OtaSource | undefined;
     #otaInProgress = false;
+    #otaAbortController: AbortController | undefined;
 
     // Getters/setters
     get ieeeAddr(): string {
@@ -197,6 +203,7 @@ export class Device extends Entity<ControllerEventMap> {
     get customReadResponse(): CustomReadResponse | undefined {
         return this._customReadResponse;
     }
+    /** If the set function returns true, the default read response behavior is skipped */
     set customReadResponse(customReadResponse: CustomReadResponse | undefined) {
         this._customReadResponse = customReadResponse;
     }
@@ -290,6 +297,21 @@ export class Device extends Entity<ControllerEventMap> {
         this.#scheduledOta = scheduledOta;
     }
 
+    /**
+     * Reset transient data about the device.
+     * @param cache If true, reset some previously cached data.
+     *   Should be set to true when device potentially changed its internal data to prevent mismatching state/config.
+     */
+    resetTransient(cache: boolean): void {
+        this._lastDefaultResponseSequenceNumber = undefined;
+
+        if (cache) {
+            // force retrieving this data again
+            this._checkinInterval = undefined;
+            this._pendingRequestTimeout = 0;
+        }
+    }
+
     public createEndpoint(id: number): Endpoint {
         if (this.getEndpoint(id)) {
             throw new Error(`Device '${this.ieeeAddr}' already has an endpoint '${id}'`);
@@ -348,72 +370,141 @@ export class Device extends Entity<ControllerEventMap> {
         return this.endpoints.find((e) => e.hasPendingRequests()) !== undefined;
     }
 
-    public async onZclData(dataPayload: AdapterEvents.ZclPayload, frame: Zcl.Frame, endpoint: Endpoint): Promise<void> {
+    public async onZclData(
+        dataPayload: AdapterEvents.ZclPayload,
+        frame: Zcl.Frame,
+        endpoint: Endpoint,
+        defaultResponse: Zcl.Status | undefined,
+    ): Promise<void> {
         if (!Device.devices.get(this.databaseID)?.has(this.ieeeAddr)) {
             // prevent race conditions where device gets deleted during processing
             return;
         }
 
-        if (frame.header.isGlobal) {
-            // Response to read requests
-            if (frame.command.name === "read" && !this._customReadResponse?.(frame, endpoint)) {
-                const attributes: {[s: string]: KeyValue} = {
-                    ...endpoint.clusters,
-                };
+        if (this.type === "GreenPower") {
+            // nothing below applies
+            return;
+        }
 
-                const isTimeReadRequest = dataPayload.clusterID === Zcl.Clusters.genTime.ID;
-                if (isTimeReadRequest) {
-                    attributes.genTime = {
-                        attributes: timeService.getTimeClusterAttributes(),
-                    };
-                }
+        const {header, command, cluster} = frame;
+        let sendDefaultResponse = !dataPayload.wasBroadcast && command.response === undefined;
+        let defaultResponseStatus = defaultResponse ?? Zcl.Status.SUCCESS;
+
+        if (header.isGlobal) {
+            // Response to read requests from device to coordinator
+            switch (command.name) {
+                case "read": {
+                    // NOTE: `sendDefaultResponse` always false from `command.response === 0x01`
+
+                    if (this._customReadResponse?.(frame, endpoint)) {
+                        break;
+                    }
 
-                if (frame.cluster.name in attributes) {
                     const response: KeyValue = {};
 
-                    for (const entry of frame.payload) {
-                        const name = frame.cluster.getAttribute(entry.attrId)?.name;
+                    switch (dataPayload.clusterID) {
+                        case GEN_TIME_CLUSTER_ID: {
+                            // relax type to index by attr name, undefined results in non-success attr record
+                            const timeAttrs = timeService.getTimeClusterAttributes() as Record<string, unknown>;
+
+                            for (const entry of frame.payload) {
+                                // TODO: this.manufacturerID or frame.header.manufacturerCode
+                                const name = Zcl.Utils.getClusterAttribute(cluster, entry.attrId, this.manufacturerID)?.name;
 
-                        if (name && name in attributes[frame.cluster.name].attributes) {
-                            response[name] = attributes[frame.cluster.name].attributes[name];
+                                if (name === undefined) {
+                                    // UNSUPPORTED_ATTRIBUTE
+                                    response[entry.attrId] = {value: undefined, type: Zcl.DataType.NO_DATA};
+                                } else {
+                                    response[name] = timeAttrs[name];
+                                }
+                            }
+                            break;
+                        }
+                        // NOTE: can add more clusters here to use defaults from spec as needed
+                        case GEN_BASIC_CLUSTER_ID: {
+                            for (const entry of frame.payload) {
+                                // TODO: this.manufacturerID or frame.header.manufacturerCode
+                                const attr = Zcl.Utils.getClusterAttribute(cluster, entry.attrId, this.manufacturerID);
+
+                                if (attr?.default === undefined) {
+                                    // UNSUPPORTED_ATTRIBUTE
+                                    response[entry.attrId] = {value: undefined, type: Zcl.DataType.NO_DATA};
+                                } else {
+                                    response[attr.name] = attr.default;
+                                }
+                            }
+
+                            break;
+                        }
+                        default: {
+                            for (const entry of frame.payload) {
+                                // UNSUPPORTED_ATTRIBUTE
+                                response[entry.attrId] = {value: undefined, type: Zcl.DataType.NO_DATA};
+                            }
+
+                            break;
                         }
                     }
 
                     try {
-                        await endpoint.readResponse(frame.cluster.ID, frame.header.transactionSequenceNumber, response, {
+                        await endpoint.readResponse(cluster.ID, header.transactionSequenceNumber, response, {
                             srcEndpoint: dataPayload.destinationEndpoint,
                         });
                     } catch (error) {
                         logger.error(`Read response to ${this.ieeeAddr} failed (${(error as Error).message})`, NS);
+                        // XXX: technically, if `readResponse` fails before reaching the network (internal to ZH), we should send a default response
+                        //      currently not possible due to implementation (no distinction as to "where" it failed)
                     }
+
+                    break;
+                }
+                case "defaultRsp": {
+                    sendDefaultResponse = false; // per spec
+                    break;
                 }
             }
-        } else if (frame.header.isSpecific) {
-            switch (frame.cluster.name) {
+        } else if (header.isSpecific) {
+            switch (cluster.name) {
                 case "ssIasZone": {
-                    if (frame.command.name === "enrollReq") {
+                    if (command.name === "enrollReq") {
                         // Respond to enroll requests
                         logger.debug(`IAS - '${this.ieeeAddr}' responding to enroll response`, NS);
 
-                        await endpoint.command("ssIasZone", "enrollRsp", {enrollrspcode: 0, zoneid: 23}, {disableDefaultResponse: true});
+                        try {
+                            await endpoint.command(
+                                "ssIasZone",
+                                "enrollRsp",
+                                {enrollrspcode: 0, zoneid: 23},
+                                {transactionSequenceNumber: header.transactionSequenceNumber, disableDefaultResponse: true},
+                            );
+
+                            sendDefaultResponse = false; // per spec, sending a specific response TODO: no "Effect on receipt" in spec, is this correct?
+                        } catch (error) {
+                            logger.error(`Handling of IAS zone enroll for ${this.ieeeAddr} failed (${(error as Error).message})`, NS);
+                            defaultResponseStatus = Zcl.Status.FAILURE;
+                        }
                     }
                     break;
                 }
                 case "genPollCtrl": {
-                    if (frame.command.name === "checkin") {
+                    if (command.name === "checkin") {
+                        let startedFastPolling = false;
+
                         // Handle check-in from sleeping end devices
                         try {
                             if (this.hasPendingRequests() || this._checkinInterval === undefined) {
                                 logger.debug(`check-in from ${this.ieeeAddr}: accepting fast-poll`, NS);
                                 await endpoint.command(
-                                    frame.cluster.name as "genPollCtrl",
+                                    cluster.name as "genPollCtrl",
                                     "checkinRsp",
+                                    {startFastPolling: 1, fastPollTimeout: 0},
                                     {
-                                        startFastPolling: 1,
-                                        fastPollTimeout: 0,
+                                        transactionSequenceNumber: header.transactionSequenceNumber,
+                                        disableDefaultResponse: true,
+                                        sendPolicy: "immediate",
                                     },
-                                    {sendPolicy: "immediate"},
                                 );
+                                startedFastPolling = true;
 
                                 // This is a good time to read the checkin interval if we haven't stored it previously
                                 if (this._checkinInterval === undefined) {
@@ -427,24 +518,35 @@ export class Device extends Entity<ControllerEventMap> {
                                 }
 
                                 await Promise.all(this.endpoints.map(async (e) => await e.sendPendingRequests(true)));
-                                // We *must* end fast-poll when we're done sending things. Otherwise
-                                // we cause undue power-drain.
-                                logger.debug(`check-in from ${this.ieeeAddr}: stopping fast-poll`, NS);
-                                await endpoint.command(frame.cluster.name as "genPollCtrl", "fastPollStop", {}, {sendPolicy: "immediate"});
                             } else {
                                 logger.debug(`check-in from ${this.ieeeAddr}: declining fast-poll`, NS);
                                 await endpoint.command(
-                                    frame.cluster.name as "genPollCtrl",
+                                    cluster.name as "genPollCtrl",
                                     "checkinRsp",
+                                    {startFastPolling: 0, fastPollTimeout: 0},
                                     {
-                                        startFastPolling: 0,
-                                        fastPollTimeout: 0,
+                                        transactionSequenceNumber: header.transactionSequenceNumber,
+                                        disableDefaultResponse: true,
+                                        sendPolicy: "immediate",
                                     },
-                                    {sendPolicy: "immediate"},
                                 );
                             }
+
+                            sendDefaultResponse = false; // per spec, sending a specific response
                         } catch (error) {
                             logger.error(`Handling of poll check-in from ${this.ieeeAddr} failed (${(error as Error).message})`, NS);
+                            defaultResponseStatus = Zcl.Status.FAILURE;
+                        } finally {
+                            if (startedFastPolling) {
+                                // We *must* end fast-poll when we're done sending things. Otherwise we cause undue power-drain.
+                                logger.debug(`check-in from ${this.ieeeAddr}: stopping fast-poll`, NS);
+
+                                try {
+                                    await endpoint.command(cluster.name as "genPollCtrl", "fastPollStop", {}, {sendPolicy: "immediate"});
+                                } catch (error) {
+                                    logger.error(`Failed to stop fast poll for ${this.ieeeAddr} (${(error as Error).message})`, NS);
+                                }
+                            }
                         }
                     }
                     break;
@@ -453,38 +555,28 @@ export class Device extends Entity<ControllerEventMap> {
         }
 
         // Send a default response if necessary.
-        const isDefaultResponse = frame.header.isGlobal && frame.command.name === "defaultRsp";
-        const commandHasResponse = frame.command.response !== undefined;
-        const disableDefaultResponse = frame.header.frameControl.disableDefaultResponse;
         /* v8 ignore next */
         const disableTuyaDefaultResponse = this.manufacturerName?.startsWith("_TZ") && process.env.DISABLE_TUYA_DEFAULT_RESPONSE;
         // Sometimes messages are received twice, prevent responding twice
-        const alreadyResponded = this._lastDefaultResponseSequenceNumber === frame.header.transactionSequenceNumber;
+        const alreadyResponded = this._lastDefaultResponseSequenceNumber === header.transactionSequenceNumber;
 
         if (
-            this.type !== "GreenPower" &&
-            !dataPayload.wasBroadcast &&
-            !disableDefaultResponse &&
-            !isDefaultResponse &&
-            !commandHasResponse &&
             !this._skipDefaultResponse &&
+            sendDefaultResponse &&
+            (!header.frameControl.disableDefaultResponse || defaultResponseStatus !== Zcl.Status.SUCCESS) &&
             !alreadyResponded &&
             !disableTuyaDefaultResponse
         ) {
             try {
-                this._lastDefaultResponseSequenceNumber = frame.header.transactionSequenceNumber;
-                // In the ZCL it is not documented what the direction of the default response should be
-                // In https://github.com/Koenkk/zigbee2mqtt/issues/18096 a commandResponse (SERVER_TO_CLIENT)
-                // is send and the device expects a CLIENT_TO_SERVER back.
-                // Previously SERVER_TO_CLIENT was always used.
-                // Therefore for non-global commands we inverse the direction.
-                const direction = frame.header.isGlobal
-                    ? Zcl.Direction.SERVER_TO_CLIENT
-                    : frame.header.frameControl.direction === Zcl.Direction.CLIENT_TO_SERVER
-                      ? Zcl.Direction.SERVER_TO_CLIENT
-                      : Zcl.Direction.CLIENT_TO_SERVER;
-
-                await endpoint.defaultResponse(frame.command.ID, 0, frame.cluster.ID, frame.header.transactionSequenceNumber, {direction});
+                this._lastDefaultResponseSequenceNumber = header.transactionSequenceNumber;
+                const direction =
+                    header.frameControl.direction === Zcl.Direction.CLIENT_TO_SERVER
+                        ? Zcl.Direction.SERVER_TO_CLIENT
+                        : Zcl.Direction.CLIENT_TO_SERVER;
+
+                await endpoint.defaultResponse(command.ID, defaultResponseStatus, cluster.ID, header.transactionSequenceNumber, {
+                    direction,
+                });
             } catch (error) {
                 logger.debug(`Default response to ${this.ieeeAddr} failed (${error})`, NS);
             }
@@ -521,7 +613,7 @@ export class Device extends Entity<ControllerEventMap> {
 
         // default: no timeout (messages expire immediately after first send attempt)
         let pendingRequestTimeout = 0;
-        if (endpoints.filter((e): boolean => e.inputClusters.includes(Zcl.Clusters.genPollCtrl.ID)).length > 0) {
+        if (endpoints.filter((e): boolean => e.inputClusters.includes(GEN_POLL_CTRL_CLUSTER_ID)).length > 0) {
             // default for devices that support genPollCtrl cluster (RX off when idle): 1 day
             pendingRequestTimeout = 86400000;
         }
@@ -1361,37 +1453,42 @@ export class Device extends Entity<ControllerEventMap> {
         // Zigbee does not have an official pinging mechanism. Use a read request
         // of a mandatory basic cluster attribute to keep it as lightweight as
         // possible.
-        const endpoint = this.endpoints.find((ep) => ep.inputClusters.includes(0)) ?? this.endpoints[0];
+        const endpoint = this.endpoints.find((ep) => ep.inputClusters.includes(GEN_BASIC_CLUSTER_ID)) ?? this.endpoints[0];
         await endpoint.read("genBasic", ["zclVersion"], {disableRecovery, sendPolicy: "immediate"});
     }
 
-    public addCustomCluster(name: string, cluster: ClusterDefinition): void {
+    public addCustomCluster(name: string, cluster: Cluster): void {
         assert(
-            ![Zcl.Clusters.touchlink.ID, Zcl.Clusters.greenPower.ID].includes(cluster.ID),
+            cluster.ID !== Zcl.Clusters.touchlink.ID && cluster.ID !== Zcl.Clusters.greenPower.ID,
             "Overriding of greenPower or touchlink cluster is not supported",
         );
-        if (Zcl.Utils.isClusterName(name)) {
-            const existingCluster = this._customClusters[name] ?? Zcl.Clusters[name];
 
+        if (Zcl.Utils.isClusterName(name)) {
             // Extend existing cluster
+            const existingCluster = this._customClusters[name] ?? Zcl.Clusters[name];
             assert(existingCluster.ID === cluster.ID, `Custom cluster ID (${cluster.ID}) should match existing cluster ID (${existingCluster.ID})`);
-            cluster = {
+
+            const extendedCluster: Cluster = {
+                name: cluster.name,
                 ID: cluster.ID,
                 manufacturerCode: cluster.manufacturerCode,
                 attributes: {...existingCluster.attributes, ...cluster.attributes},
                 commands: {...existingCluster.commands, ...cluster.commands},
                 commandsResponse: {...existingCluster.commandsResponse, ...cluster.commandsResponse},
             };
+
+            this._customClusters[name] = extendedCluster;
+        } else {
+            this._customClusters[name] = cluster;
         }
-        this._customClusters[name] = cluster;
     }
 
     #waitForOtaCommand<Co extends string>(
         endpointId: number,
         commandId: number,
-        transactionSequenceNumber: number | undefined,
+        defaultRspCommandId: number | undefined,
         timeout: number,
-    ): {promise: Promise<TZclFrame<"genOta", Co>>; cancel: () => void} {
+    ): {promise: Promise<TZclFrame<"genOta", Co> | TFoundationZclFrame<"defaultRsp">>; cancel: () => void} {
         const adapter = Entity.getAdapterByID(this.databaseID);
         if (!adapter) {
             throw new Error(`No adapter found for database ID ${this.databaseID}`);
@@ -1401,18 +1498,19 @@ export class Device extends Entity<ControllerEventMap> {
             endpointId,
             Zcl.FrameType.SPECIFIC,
             Zcl.Direction.CLIENT_TO_SERVER,
-            transactionSequenceNumber,
-            Zcl.Clusters.genOta.ID,
+            undefined,
+            GEN_OTA_CLUSTER_ID,
             commandId,
+            defaultRspCommandId,
             timeout,
         );
-        const promise = new Promise<Zcl.Frame & {payload: TClusterPayload<"genOta", Co>}>((resolve, reject) => {
+        const promise = new Promise<TZclFrame<"genOta", Co> | TFoundationZclFrame<"defaultRsp">>((resolve, reject) => {
             waiter.promise.then(
                 (payload) => {
                     try {
                         const frame = Zcl.Frame.fromBuffer(payload.clusterID, payload.header, payload.data, this.customClusters);
 
-                        resolve(frame);
+                        resolve(frame as TZclFrame<"genOta", Co> | TFoundationZclFrame<"defaultRsp">);
                     } catch (error) {
                         reject(error);
                     }
@@ -1464,7 +1562,7 @@ export class Device extends Entity<ControllerEventMap> {
         const queryNextImageRequest = this.#waitForOtaCommand<"queryNextImageRequest">(
             endpoint.ID,
             Zcl.Clusters.genOta.commands.queryNextImageRequest.ID,
-            undefined,
+            Zcl.Clusters.genOta.commandsResponse.imageNotify.ID,
             60000,
         );
 
@@ -1473,7 +1571,9 @@ export class Device extends Entity<ControllerEventMap> {
 
             const response = await queryNextImageRequest.promise;
 
-            return [response.payload, response.header.transactionSequenceNumber];
+            assert(response.header.isSpecific);
+
+            return [(response as TZclFrame<"genOta", "queryNextImageRequest">).payload, response.header.transactionSequenceNumber];
         } catch {
             queryNextImageRequest.cancel();
 
@@ -1666,9 +1766,15 @@ export class Device extends Entity<ControllerEventMap> {
         let endResult: TZclFrame<"genOta", "upgradeEndRequest">;
 
         try {
-            endResult = await session.run();
+            this.#otaAbortController = new AbortController();
+            const runEnd = await session.run(this.#otaAbortController.signal);
+
+            assert(runEnd.header.isSpecific);
+
+            endResult = runEnd as TZclFrame<"genOta", "upgradeEndRequest">;
         } finally {
             this.#otaInProgress = false;
+            this.#otaAbortController = undefined;
         }
 
         logger.debug(() => `Received upgrade end request for ${this.ieeeAddr}: ${JSON.stringify(endResult.payload)}`, NS);
@@ -1745,7 +1851,7 @@ export class Device extends Entity<ControllerEventMap> {
                 await endpoint.defaultResponse(
                     Zcl.Clusters.genOta.commands.upgradeEndRequest.ID,
                     Zcl.Status.SUCCESS,
-                    Zcl.Clusters.genOta.ID,
+                    GEN_OTA_CLUSTER_ID,
                     endResult.header.transactionSequenceNumber,
                 );
             } catch (error) {
@@ -1758,6 +1864,13 @@ export class Device extends Entity<ControllerEventMap> {
         }
     }
 
+    /**
+     * Abort running OTA if any. Send `ABORT` with next block response to device.
+     */
+    abortOta(): void {
+        this.#otaAbortController?.abort();
+    }
+
     scheduleOta(source: OtaSource): void {
         assert(
             this.endpoints.some((e) => e.supportsOutputCluster("genOta")),