@willieee802/zigbee-herdsman 0.48.3 → 0.49.0

package/src/controller/helpers/request.ts

@@ -0,0 +1,96 @@
+import type * as Zcl from "../../zspec/zcl";
+import type {SendPolicy} from "../tstype";
+
+// biome-ignore lint/suspicious/noExplicitAny: API
+export class Request<Type = any> {
+    static defaultSendPolicy: {[key: number]: SendPolicy} = {
+        0: "keep-payload", // Read Attributes
+        1: "immediate", // Read Attributes Response
+        2: "keep-command", // Write Attributes
+        3: "keep-cmd-undiv", // Write Attributes Undivided
+        4: "immediate", // Write Attributes Response
+        5: "keep-command", // Write Attributes No Response
+        6: "keep-payload", // Configure Reporting
+        7: "immediate", // Configure Reporting Response
+        8: "keep-payload", // Read Reporting Configuration
+        9: "immediate", // Read Reporting Configuration Response
+        10: "keep-payload", // Report attributes
+        11: "immediate", // Default Response
+        12: "keep-payload", // Discover Attributes
+        13: "immediate", // Discover Attributes Response
+        14: "keep-payload", // Read Attributes Structured
+        15: "keep-payload", // Write Attributes Structured
+        16: "immediate", // Write Attributes Structured response
+        17: "keep-payload", // Discover Commands Received
+        18: "immediate", // Discover Commands Received Response
+        19: "keep-payload", // Discover Commands Generated
+        20: "immediate", // Discover Commands Generated Response
+        21: "keep-payload", // Discover Attributes Extended
+        22: "immediate", // Discover Attributes Extended Response
+    };
+
+    private func: () => Promise<Type>;
+    frame: Zcl.Frame;
+    expires: number;
+    sendPolicy: SendPolicy | undefined;
+    private resolveQueue: Array<(value: Type) => void>;
+    private rejectQueue: Array<(error: Error) => void>;
+    private lastError: Error;
+
+    constructor(
+        func: () => Promise<Type>,
+        frame: Zcl.Frame,
+        timeout: number,
+        sendPolicy?: SendPolicy,
+        lastError?: Error,
+        resolve?: (value: Type) => void,
+        reject?: (error: Error) => void,
+    ) {
+        this.func = func;
+        this.frame = frame;
+        this.expires = timeout + Date.now();
+        this.sendPolicy = sendPolicy ?? (!frame.command ? undefined : Request.defaultSendPolicy[frame.command.ID]);
+        this.resolveQueue = resolve === undefined ? ([] as ((value: Type) => void)[]) : new Array<(value: Type) => void>(resolve);
+        this.rejectQueue = reject === undefined ? ([] as ((error: Error) => void)[]) : new Array<(error: Error) => void>(reject);
+        this.lastError = lastError ?? Error("Request rejected before first send");
+    }
+
+    moveCallbacks(from: Request<Type>): void {
+        this.resolveQueue = this.resolveQueue.concat(from.resolveQueue);
+        this.rejectQueue = this.rejectQueue.concat(from.rejectQueue);
+        from.resolveQueue.length = 0;
+        from.rejectQueue.length = 0;
+    }
+
+    addCallbacks(resolve: (value: Type) => void, reject: (error: Error) => void): void {
+        this.resolveQueue.push(resolve);
+        this.rejectQueue.push(reject);
+    }
+
+    reject(error?: Error): void {
+        for (const el of this.rejectQueue) {
+            el(error ?? this.lastError);
+        }
+        this.rejectQueue.length = 0;
+    }
+
+    resolve(value: Type): void {
+        for (const el of this.resolveQueue) {
+            el(value);
+        }
+        this.resolveQueue.length = 0;
+    }
+
+    async send(): Promise<Type> {
+        try {
+            const ret = await this.func();
+
+            return ret;
+        } catch (error) {
+            this.lastError = error as Error;
+            throw error;
+        }
+    }
+}
+
+export default Request;

package/src/controller/helpers/requestQueue.ts

@@ -0,0 +1,126 @@
+import equal from "fast-deep-equal/es6";
+import {logger} from "../../utils/logger";
+import type * as Zcl from "../../zspec/zcl";
+import type {Endpoint} from "../model";
+import type Request from "./request";
+
+const NS = "zh:controller:requestqueue";
+
+type Mutable<T> = {-readonly [P in keyof T]: T[P]};
+
+export class RequestQueue extends Set<Request> {
+    private sendInProgress: boolean;
+    private id: number;
+    private deviceIeeeAddress: string;
+
+    constructor(endpoint: Endpoint) {
+        super();
+        this.sendInProgress = false;
+        this.id = endpoint.ID;
+        this.deviceIeeeAddress = endpoint.deviceIeeeAddress;
+    }
+
+    public async send(fastPolling: boolean): Promise<void> {
+        if (this.size === 0) return;
+
+        if (!fastPolling && this.sendInProgress) {
+            logger.debug(`Request Queue (${this.deviceIeeeAddress}/${this.id}): sendPendingRequests already in progress`, NS);
+            return;
+        }
+        this.sendInProgress = true;
+
+        // Remove expired requests first
+        const now = Date.now();
+        for (const request of this) {
+            if (now > request.expires) {
+                logger.debug(`Request Queue (${this.deviceIeeeAddress}/${this.id}): discard after timeout. Size before: ${this.size}`, NS);
+                request.reject();
+                this.delete(request);
+            }
+        }
+
+        logger.debug(`Request Queue (${this.deviceIeeeAddress}/${this.id}): send pending requests (${this.size}, ${fastPolling})`, NS);
+
+        for (const request of this) {
+            if (fastPolling || request.sendPolicy !== "bulk") {
+                try {
+                    const result = await request.send();
+                    logger.debug(`Request Queue (${this.deviceIeeeAddress}/${this.id}): send success`, NS);
+                    request.resolve(result);
+                    this.delete(request);
+                } catch (error) {
+                    logger.debug(
+                        `Request Queue (${this.deviceIeeeAddress}/${this.id}): send failed, expires in ` +
+                            `${(request.expires - now) / 1000} seconds (${(error as Error).message})`,
+                        NS,
+                    );
+                }
+            }
+        }
+        this.sendInProgress = false;
+    }
+
+    public async queue<Type>(request: Request<Type>): Promise<Type> {
+        logger.debug(`Request Queue (${this.deviceIeeeAddress}/${this.id}): Sending when active. Expires: ${request.expires}`, NS);
+        return await new Promise((resolve, reject): void => {
+            request.addCallbacks(resolve, reject);
+            this.add(request);
+        });
+    }
+
+    public filter(newRequest: Request): void {
+        if (this.size === 0 || !newRequest.frame.command) {
+            return;
+        }
+        const clusterID = newRequest.frame.cluster.ID;
+        const payload = newRequest.frame.payload;
+        const commandID = newRequest.frame.command.ID;
+
+        logger.debug(
+            `Request Queue (${this.deviceIeeeAddress}/${this.id}): ZCL ${newRequest.frame.command.name} ` +
+                `command, filter requests. Before: ${this.size}`,
+            NS,
+        );
+
+        for (const request of this) {
+            if (request?.frame?.cluster?.ID === undefined || !request.frame.command) {
+                continue;
+            }
+
+            if (request.sendPolicy === "bulk" || request.sendPolicy === "queue" || request.sendPolicy === "immediate") {
+                continue;
+            }
+
+            if (request.frame.cluster.ID === clusterID && request.frame.command.ID === commandID) {
+                if (newRequest.sendPolicy === "keep-payload" && equal(request.frame.payload, payload)) {
+                    logger.debug(`Request Queue (${this.deviceIeeeAddress}/${this.id}): Merge duplicate request`, NS);
+                    this.delete(request);
+                    newRequest.moveCallbacks(request);
+                } else if (
+                    (newRequest.sendPolicy === "keep-command" || newRequest.sendPolicy === "keep-cmd-undiv") &&
+                    Array.isArray(request.frame.payload)
+                ) {
+                    const filteredPayload = request.frame.payload.filter(
+                        (oldEl: {attrId: number}) => !payload.find((newEl: {attrId: number}) => oldEl.attrId === newEl.attrId),
+                    );
+                    if (filteredPayload.length === 0) {
+                        logger.debug(`Request Queue (${this.deviceIeeeAddress}/${this.id}): Remove & reject request`, NS);
+                        if (equal(request.frame.payload, payload)) {
+                            newRequest.moveCallbacks(request);
+                        } else {
+                            request.reject(new Error("Request superseded"));
+                        }
+                        this.delete(request);
+                    } else if (newRequest.sendPolicy !== "keep-cmd-undiv") {
+                        // remove all duplicate attributes if we shall not write undivided
+                        (request.frame as Mutable<Zcl.Frame>).payload = filteredPayload;
+                        logger.debug(`Request Queue (${this.deviceIeeeAddress}/${this.id}): Remove commands from request`, NS);
+                    }
+                }
+            }
+        }
+        logger.debug(`Request Queue (${this.deviceIeeeAddress}/${this.id}): After: ${this.size}`, NS);
+    }
+}
+
+export default RequestQueue;

package/src/controller/helpers/zclFrameConverter.ts

@@ -0,0 +1,64 @@
+import {logger} from "../../utils/logger";
+import * as Zcl from "../../zspec/zcl";
+import type {TFoundation} from "../../zspec/zcl/definition/clusters-types";
+import type {Cluster, CustomClusters} from "../../zspec/zcl/definition/tstype";
+import type {ClusterOrRawWriteAttributes, TCustomCluster} from "../tstype";
+
+const NS = "zh:controller:zcl";
+
+// Legrand devices (e.g. 4129) fail to set the manufacturerSpecific flag and
+// manufacturerCode in the frame header, despite using specific attributes.
+// This leads to incorrect reported attribute names.
+// Remap the attributes using the target device's manufacturer ID
+// if the header is lacking the information.
+function getCluster(frame: Zcl.Frame, deviceManufacturerID: number | undefined, customClusters: CustomClusters): Cluster {
+    let cluster = frame.cluster;
+    if (!frame?.header?.manufacturerCode && frame?.cluster && deviceManufacturerID === Zcl.ManufacturerCode.LEGRAND_GROUP) {
+        cluster = Zcl.Utils.getCluster(frame.cluster.ID, deviceManufacturerID, customClusters);
+    }
+    return cluster;
+}
+
+function attributeKeyValue<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+    frame: Zcl.Frame,
+    deviceManufacturerID: number | undefined,
+    customClusters: CustomClusters,
+): ClusterOrRawWriteAttributes<Cl, Custom> {
+    const payload: Record<string | number, unknown> = {};
+    const cluster = getCluster(frame, deviceManufacturerID, customClusters);
+
+    // TODO: remove this type once Zcl.Frame is typed
+    for (const item of frame.payload as TFoundation["report" | "write" | "readRsp"]) {
+        const attribute = cluster.getAttribute(item.attrId);
+
+        if (attribute) {
+            try {
+                const attrData = Zcl.Utils.processAttributePostRead(attribute, item.attrData);
+
+                payload[attribute.name] = attrData;
+            } catch (error) {
+                logger.debug(`Ignoring attribute ${attribute.name} from response: ${error}`, NS);
+            }
+        } else {
+            payload[item.attrId] = item.attrData;
+        }
+    }
+
+    return payload as ClusterOrRawWriteAttributes<Cl, Custom>;
+}
+
+function attributeList(frame: Zcl.Frame, deviceManufacturerID: number | undefined, customClusters: CustomClusters): Array<string | number> {
+    const payload: Array<string | number> = [];
+    const cluster = getCluster(frame, deviceManufacturerID, customClusters);
+
+    // TODO: remove this type once Zcl.Frame is typed
+    for (const item of frame.payload as TFoundation["read"]) {
+        const attribute = cluster.getAttribute(item.attrId);
+
+        payload.push(attribute?.name ?? item.attrId);
+    }
+
+    return payload;
+}
+
+export {attributeKeyValue, attributeList};

package/src/controller/helpers/zclTransactionSequenceNumber.ts

@@ -0,0 +1,15 @@
+class ZclTransactionSequenceNumber {
+    private sequence = -1;
+
+    get current() {
+        return this.sequence;
+    }
+
+    public next(): number {
+        this.sequence = (this.sequence + 1) % 256;
+
+        return this.sequence;
+    }
+}
+
+export default new ZclTransactionSequenceNumber();

package/src/controller/index.ts

@@ -0,0 +1,6 @@
+import Controller from "./controller";
+
+/**
+ * @internal
+ */
+export {Controller};