zigbee-herdsman 5.0.4 → 6.0.1

package/src/controller/model/endpoint.ts

@@ -1,26 +1,37 @@
 import assert from "node:assert";
-
 import type {Events as AdapterEvents} from "../../adapter";
 import {logger} from "../../utils/logger";
 import * as ZSpec from "../../zspec";
 import {BroadcastAddress} from "../../zspec/enums";
 import type {Eui64} from "../../zspec/tstypes";
 import * as Zcl from "../../zspec/zcl";
+import type {TFoundation} from "../../zspec/zcl/definition/clusters-types";
 import type * as ZclTypes from "../../zspec/zcl/definition/tstype";
 import * as Zdo from "../../zspec/zdo";
 import Request from "../helpers/request";
 import RequestQueue from "../helpers/requestQueue";
 import * as ZclFrameConverter from "../helpers/zclFrameConverter";
 import zclTransactionSequenceNumber from "../helpers/zclTransactionSequenceNumber";
-import type {KeyValue, SendPolicy} from "../tstype";
+import type {
+    ClusterOrRawAttributeKeys,
+    ClusterOrRawAttributes,
+    ClusterOrRawPayload,
+    ClusterOrRawWriteAttributes,
+    FoundationOrRawPayload,
+    KeyValue,
+    PartialClusterOrRawWriteAttributes,
+    SendPolicy,
+    TCustomCluster,
+} from "../tstype";
 import Device from "./device";
 import Entity from "./entity";
 import Group from "./group";
+import {ZigbeeEntity} from "./zigbeeEntity";
 
 const NS = "zh:controller:endpoint";
 
-export interface ConfigureReportingItem {
-    attribute: string | number | {ID: number; type: number};
+export interface ConfigureReportingItem<Cl extends string | number, Custom extends TCustomCluster | undefined = undefined> {
+    attribute: ClusterOrRawAttributeKeys<Cl, Custom>[number] | {ID: number; type: number};
     minimumReportInterval: number;
     maximumReportInterval: number;
     reportableChange: number;
@@ -86,7 +97,7 @@ interface ConfiguredReporting {
     reportableChange: number;
 }
 
-export class Endpoint extends Entity {
+export class Endpoint extends ZigbeeEntity {
     public deviceID?: number;
     public inputClusters: number[];
     public outputClusters: number[];
@@ -372,16 +383,22 @@ export class Endpoint extends Entity {
         if (invalid) throw new Zcl.StatusError(invalid);
     }
 
-    public async report(clusterKey: number | string, attributes: KeyValue, options?: Options): Promise<void> {
+    public async report<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        attributes: PartialClusterOrRawWriteAttributes<Cl, Custom>,
+        options?: Options,
+    ): Promise<void> {
         const cluster = this.getCluster(clusterKey, undefined, options?.manufacturerCode);
-        const payload: {attrId: number; dataType: number; attrData: number | string | boolean}[] = [];
+        const payload: TFoundation["report"] = [];
 
-        for (const [nameOrID, value] of Object.entries(attributes)) {
+        for (const nameOrID in attributes) {
             const attribute = cluster.getAttribute(nameOrID);
 
             if (attribute) {
-                payload.push({attrId: attribute.ID, attrData: value, dataType: attribute.type});
+                payload.push({attrId: attribute.ID, attrData: attributes[nameOrID], dataType: attribute.type});
             } else if (!Number.isNaN(Number(nameOrID))) {
+                const value = attributes[nameOrID];
+
                 payload.push({attrId: Number(nameOrID), attrData: value.value, dataType: value.type});
             } else {
                 throw new Error(`Unknown attribute '${nameOrID}', specify either an existing attribute or a number`);
@@ -391,23 +408,29 @@ export class Endpoint extends Entity {
         await this.zclCommand(cluster, "report", payload, options, attributes);
     }
 
-    public async write(clusterKey: number | string, attributes: KeyValue, options?: Options): Promise<void> {
+    public async write<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        attributes: PartialClusterOrRawWriteAttributes<Cl, Custom>,
+        options?: Options,
+    ): Promise<void> {
         const cluster = this.getCluster(clusterKey, undefined, options?.manufacturerCode);
         const optionsWithDefaults = this.getOptionsWithDefaults(options, true, Zcl.Direction.CLIENT_TO_SERVER, cluster.manufacturerCode);
-        optionsWithDefaults.manufacturerCode = this.ensureManufacturerCodeIsUniqueAndGet(
+        optionsWithDefaults.manufacturerCode = this.ensureManufacturerCodeIsUniqueAndGet<Cl, Custom>(
             cluster,
             Object.keys(attributes),
             optionsWithDefaults.manufacturerCode,
             "write",
         );
+        const payload: TFoundation["write"] = [];
 
-        const payload: {attrId: number; dataType: number; attrData: number | string | boolean}[] = [];
-        for (const [nameOrID, value] of Object.entries(attributes)) {
+        for (const nameOrID in attributes) {
             const attribute = cluster.getAttribute(nameOrID);
 
             if (attribute) {
-                payload.push({attrId: attribute.ID, attrData: value, dataType: attribute.type});
+                payload.push({attrId: attribute.ID, attrData: attributes[nameOrID], dataType: attribute.type});
             } else if (!Number.isNaN(Number(nameOrID))) {
+                const value = attributes[nameOrID];
+
                 payload.push({attrId: Number(nameOrID), attrData: value.value, dataType: value.type});
             } else {
                 throw new Error(`Unknown attribute '${nameOrID}', specify either an existing attribute or a number`);
@@ -417,17 +440,21 @@ export class Endpoint extends Entity {
         await this.zclCommand(cluster, optionsWithDefaults.writeUndiv ? "writeUndiv" : "write", payload, optionsWithDefaults, attributes, true);
     }
 
-    public async writeResponse(
-        clusterKey: number | string,
+    public async writeResponse<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
         transactionSequenceNumber: number,
-        attributes: KeyValue,
+        attributes: Partial<Record<ClusterOrRawAttributeKeys<Cl, Custom>[number], TFoundation["writeRsp"][number]>> &
+            Record<number, TFoundation["writeRsp"][number]>,
         options?: Options,
     ): Promise<void> {
         assert(options?.transactionSequenceNumber === undefined, "Use parameter");
         const cluster = this.getCluster(clusterKey, undefined, options?.manufacturerCode);
-        const payload: {status: number; attrId: number}[] = [];
+        const payload: TFoundation["writeRsp"] = [];
+
+        for (const nameOrID in attributes) {
+            // biome-ignore lint/style/noNonNullAssertion: from loop
+            const value = attributes[nameOrID]!;
 
-        for (const [nameOrID, value] of Object.entries(attributes)) {
             if (value.status !== undefined) {
                 const attribute = cluster.getAttribute(nameOrID);
 
@@ -452,17 +479,22 @@ export class Endpoint extends Entity {
         );
     }
 
-    public async read(clusterKey: number | string, attributes: (string | number)[], options?: Options): Promise<KeyValue> {
+    // XXX: ideally, the return type should limit to the contents of the `attributes` param
+    public async read<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        attributes: ClusterOrRawAttributeKeys<Cl, Custom>,
+        options?: Options,
+    ): Promise<ClusterOrRawAttributes<Cl, Custom>> {
         const device = this.getDevice();
         const cluster = this.getCluster(clusterKey, device, options?.manufacturerCode);
         const optionsWithDefaults = this.getOptionsWithDefaults(options, true, Zcl.Direction.CLIENT_TO_SERVER, cluster.manufacturerCode);
-        optionsWithDefaults.manufacturerCode = this.ensureManufacturerCodeIsUniqueAndGet(
+        optionsWithDefaults.manufacturerCode = this.ensureManufacturerCodeIsUniqueAndGet<Cl, Custom>(
             cluster,
             attributes,
             optionsWithDefaults.manufacturerCode,
             "read",
         );
-        const payload: {attrId: number}[] = [];
+        const payload: TFoundation["read"] = [];
 
         for (const attribute of attributes) {
             if (typeof attribute === "number") {
@@ -480,29 +512,30 @@ export class Endpoint extends Entity {
 
         const resultFrame = await this.zclCommand(cluster, "read", payload, optionsWithDefaults, attributes, true);
 
-        if (resultFrame) {
-            return ZclFrameConverter.attributeKeyValue(resultFrame, device.manufacturerID, device.customClusters);
-        }
-
-        return {};
+        return resultFrame
+            ? ZclFrameConverter.attributeKeyValue<Cl, Custom>(resultFrame, device.manufacturerID, device.customClusters)
+            : ({} as ClusterOrRawWriteAttributes<Cl, Custom>);
     }
 
-    public async readResponse(
-        clusterKey: number | string,
+    public async readResponse<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
         transactionSequenceNumber: number,
-        attributes: KeyValue,
+        attributes: PartialClusterOrRawWriteAttributes<Cl, Custom>,
         options?: Options,
     ): Promise<void> {
         assert(options?.transactionSequenceNumber === undefined, "Use parameter");
 
         const cluster = this.getCluster(clusterKey, undefined, options?.manufacturerCode);
-        const payload: {attrId: number; status: number; dataType: number; attrData: number | string}[] = [];
-        for (const [nameOrID, value] of Object.entries(attributes)) {
+        const payload: TFoundation["readRsp"] = [];
+
+        for (const nameOrID in attributes) {
             const attribute = cluster.getAttribute(nameOrID);
 
             if (attribute) {
-                payload.push({attrId: attribute.ID, attrData: value, dataType: attribute.type, status: 0});
+                payload.push({attrId: attribute.ID, attrData: attributes[nameOrID], dataType: attribute.type, status: 0});
             } else if (!Number.isNaN(Number(nameOrID))) {
+                const value = attributes[nameOrID];
+
                 payload.push({attrId: Number(nameOrID), attrData: value.value, dataType: value.type, status: 0});
             } else {
                 throw new Error(`Unknown attribute '${nameOrID}', specify either an existing attribute or a number`);
@@ -688,19 +721,23 @@ export class Endpoint extends Entity {
         await this.zclCommand(clusterID, "defaultRsp", payload, {direction: Zcl.Direction.SERVER_TO_CLIENT, ...options, transactionSequenceNumber});
     }
 
-    public async configureReporting(clusterKey: number | string, items: ConfigureReportingItem[], options?: Options): Promise<void> {
+    public async configureReporting<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        items: ConfigureReportingItem<Cl, Custom>[],
+        options?: Options,
+    ): Promise<void> {
         const cluster = this.getCluster(clusterKey, undefined, options?.manufacturerCode);
         const optionsWithDefaults = this.getOptionsWithDefaults(options, true, Zcl.Direction.CLIENT_TO_SERVER, cluster.manufacturerCode);
-        optionsWithDefaults.manufacturerCode = this.ensureManufacturerCodeIsUniqueAndGet(
+        optionsWithDefaults.manufacturerCode = this.ensureManufacturerCodeIsUniqueAndGet<Cl, Custom>(
             cluster,
             items,
             optionsWithDefaults.manufacturerCode,
             "configureReporting",
         );
 
-        const payload = items.map((item): KeyValue => {
-            let dataType: number | undefined;
-            let attrId: number | undefined;
+        const payload = items.map((item): TFoundation["configReport"][number] => {
+            let dataType: number;
+            let attrId: number;
 
             if (typeof item.attribute === "object") {
                 dataType = item.attribute.type;
@@ -711,13 +748,15 @@ export class Endpoint extends Entity {
                 if (attribute) {
                     dataType = attribute.type;
                     attrId = attribute.ID;
+                } else {
+                    throw new Error(`Invalid attribute '${item.attribute}' for cluster '${clusterKey}'`);
                 }
             }
 
             return {
                 direction: Zcl.Direction.CLIENT_TO_SERVER,
-                attrId, // TODO: biome migration - can be undefined?
-                dataType, // TODO: biome migration - can be undefined?
+                attrId,
+                dataType,
                 minRepIntval: item.minimumReportInterval,
                 maxRepIntval: item.maximumReportInterval,
                 repChange: item.reportableChange,
@@ -742,9 +781,10 @@ export class Endpoint extends Entity {
                 this._configuredReportings.push({
                     cluster: cluster.ID,
                     attrId: entry.attrId,
-                    minRepIntval: entry.minRepIntval,
-                    maxRepIntval: entry.maxRepIntval,
-                    repChange: entry.repChange,
+                    minRepIntval: entry.minRepIntval as number,
+                    maxRepIntval: entry.maxRepIntval as number,
+                    // expects items[].attribute to always point to a number DataType
+                    repChange: entry.repChange as number,
                     manufacturerCode: optionsWithDefaults.manufacturerCode,
                 });
             }
@@ -753,15 +793,19 @@ export class Endpoint extends Entity {
         this.save();
     }
 
-    public async writeStructured(clusterKey: number | string, payload: KeyValue, options?: Options): Promise<void> {
+    public async writeStructured<Cl extends number | string>(
+        clusterKey: Cl,
+        payload: TFoundation["writeStructured"],
+        options?: Options,
+    ): Promise<void> {
         await this.zclCommand(clusterKey, "writeStructured", payload, options);
         // TODO: support `writeStructuredResponse`
     }
 
-    public async command(
-        clusterKey: number | string,
-        commandKey: number | string,
-        payload: KeyValue,
+    public async command<Cl extends number | string, Co extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        commandKey: Co,
+        payload: ClusterOrRawPayload<Cl, Co, Custom>,
         options?: Options,
     ): Promise<undefined | KeyValue> {
         const frame = await this.zclCommand(clusterKey, commandKey, payload, options, undefined, false, Zcl.FrameType.SPECIFIC);
@@ -770,10 +814,10 @@ export class Endpoint extends Entity {
         }
     }
 
-    public async commandResponse(
-        clusterKey: number | string,
-        commandKey: number | string,
-        payload: KeyValue,
+    public async commandResponse<Cl extends number | string, Co extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        commandKey: Co,
+        payload: ClusterOrRawPayload<Cl, Co, Custom>,
         options?: Options,
         transactionSequenceNumber?: number,
     ): Promise<void> {
@@ -844,8 +888,12 @@ export class Endpoint extends Entity {
         const promise = new Promise<{header: Zcl.Header; payload: KeyValue}>((resolve, reject) => {
             waiter.promise.then(
                 (payload) => {
-                    const frame = Zcl.Frame.fromBuffer(payload.clusterID, payload.header, payload.data, device.customClusters);
-                    resolve({header: frame.header, payload: frame.payload});
+                    try {
+                        const frame = Zcl.Frame.fromBuffer(payload.clusterID, payload.header, payload.data, device.customClusters);
+                        resolve({header: frame.header, payload: frame.payload});
+                    } catch (error) {
+                        reject(error);
+                    }
                 },
                 (error) => reject(error),
             );
@@ -875,9 +923,9 @@ export class Endpoint extends Entity {
         };
     }
 
-    private ensureManufacturerCodeIsUniqueAndGet(
+    private ensureManufacturerCodeIsUniqueAndGet<Cl extends string | number, Custom extends TCustomCluster | undefined = undefined>(
         cluster: ZclTypes.Cluster,
-        attributes: (string | number)[] | ConfigureReportingItem[],
+        attributes: (string | number)[] | ConfigureReportingItem<Cl, Custom>[],
         fallbackManufacturerCode: number | undefined, // XXX: problematic undefined for a "fallback"?
         caller: string,
     ): number | undefined {
@@ -958,10 +1006,10 @@ export class Endpoint extends Entity {
         }
     }
 
-    public async zclCommand(
-        clusterKey: number | string | ZclTypes.Cluster,
-        commandKey: number | string | ZclTypes.Command,
-        payload: KeyValue,
+    public async zclCommand<Cl extends number | string, Co extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl | ZclTypes.Cluster,
+        commandKey: Co | ZclTypes.Command,
+        payload: ClusterOrRawPayload<Cl, Co, Custom> | FoundationOrRawPayload<Co>,
         options?: Options,
         logPayload?: KeyValue,
         checkStatus = false,
@@ -1015,12 +1063,12 @@ export class Endpoint extends Entity {
         }
     }
 
-    public async zclCommandBroadcast(
+    public async zclCommandBroadcast<Cl extends number | string, Co extends number | string, Custom extends TCustomCluster | undefined = undefined>(
         endpoint: number,
         destination: BroadcastAddress,
-        clusterKey: number | string,
-        commandKey: number | string,
-        payload: unknown,
+        clusterKey: Cl,
+        commandKey: Co,
+        payload: ClusterOrRawPayload<Cl, Co, Custom> | FoundationOrRawPayload<Co>,
         options?: Options,
     ): Promise<void> {
         const device = this.getDevice();

package/src/controller/model/group.ts

@@ -1,12 +1,21 @@
 import assert from "node:assert";
 import {logger} from "../../utils/logger";
 import * as Zcl from "../../zspec/zcl";
+import type {TFoundation} from "../../zspec/zcl/definition/clusters-types";
 import type {CustomClusters} from "../../zspec/zcl/definition/tstype";
 import zclTransactionSequenceNumber from "../helpers/zclTransactionSequenceNumber";
-import type {DatabaseEntry, KeyValue} from "../tstype";
+import type {
+    ClusterOrRawAttributeKeys,
+    ClusterOrRawPayload,
+    DatabaseEntry,
+    KeyValue,
+    PartialClusterOrRawWriteAttributes,
+    TCustomCluster,
+} from "../tstype";
 import Device from "./device";
 import type Endpoint from "./endpoint";
 import Entity from "./entity";
+import {ZigbeeEntity} from "./zigbeeEntity";
 
 const NS = "zh:controller:group";
 
@@ -23,7 +32,7 @@ interface OptionsWithDefaults extends Options {
     reservedBits: number;
 }
 
-export class Group extends Entity {
+export class Group extends ZigbeeEntity {
     private databaseID: number;
     public readonly groupID: number;
     private readonly _members: Endpoint[];
@@ -248,18 +257,24 @@ export class Group extends Entity {
      * Zigbee functions
      */
 
-    public async write(clusterKey: number | string, attributes: KeyValue, options?: Options): Promise<void> {
+    public async write<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        attributes: PartialClusterOrRawWriteAttributes<Cl, Custom>,
+        options?: Options,
+    ): Promise<void> {
         const customClusters = this.#customClusters[options?.direction === Zcl.Direction.SERVER_TO_CLIENT ? 1 : 0 /* default to CLIENT_TO_SERVER */];
         const cluster = Zcl.Utils.getCluster(clusterKey, options?.manufacturerCode, customClusters);
         const optionsWithDefaults = this.getOptionsWithDefaults(options, Zcl.Direction.CLIENT_TO_SERVER, cluster.manufacturerCode);
-        const payload: {attrId: number; dataType: number; attrData: number | string | boolean}[] = [];
+        const payload: TFoundation["write"] = [];
 
-        for (const [nameOrID, value] of Object.entries(attributes)) {
+        for (const nameOrID in attributes) {
             const attribute = cluster.getAttribute(nameOrID);
 
             if (attribute) {
-                payload.push({attrId: attribute.ID, attrData: value, dataType: attribute.type});
+                payload.push({attrId: attribute.ID, attrData: attributes[nameOrID], dataType: attribute.type});
             } else if (!Number.isNaN(Number(nameOrID))) {
+                const value = attributes[nameOrID];
+
                 payload.push({attrId: Number(nameOrID), attrData: value.value, dataType: value.type});
             } else {
                 throw new Error(`Unknown attribute '${nameOrID}', specify either an existing attribute or a number`);
@@ -295,11 +310,15 @@ export class Group extends Entity {
         }
     }
 
-    public async read(clusterKey: number | string, attributes: (string | number)[], options?: Options): Promise<void> {
+    public async read<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        attributes: ClusterOrRawAttributeKeys<Cl, Custom>,
+        options?: Options,
+    ): Promise<undefined> {
         const customClusters = this.#customClusters[options?.direction === Zcl.Direction.SERVER_TO_CLIENT ? 1 : 0 /* default to CLIENT_TO_SERVER */];
         const cluster = Zcl.Utils.getCluster(clusterKey, options?.manufacturerCode, customClusters);
         const optionsWithDefaults = this.getOptionsWithDefaults(options, Zcl.Direction.CLIENT_TO_SERVER, cluster.manufacturerCode);
-        const payload: {attrId: number}[] = [];
+        const payload: TFoundation["read"] = [];
 
         for (const attribute of attributes) {
             if (typeof attribute === "number") {
@@ -344,7 +363,12 @@ export class Group extends Entity {
         }
     }
 
-    public async command(clusterKey: number | string, commandKey: number | string, payload: KeyValue, options?: Options): Promise<void> {
+    public async command<Cl extends number | string, Co extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        commandKey: Co,
+        payload: ClusterOrRawPayload<Cl, Co, Custom>,
+        options?: Options,
+    ): Promise<undefined> {
         const customClusters = this.#customClusters[options?.direction === Zcl.Direction.SERVER_TO_CLIENT ? 1 : 0 /* default to CLIENT_TO_SERVER */];
         const cluster = Zcl.Utils.getCluster(clusterKey, options?.manufacturerCode, customClusters);
         const optionsWithDefaults = this.getOptionsWithDefaults(options, Zcl.Direction.CLIENT_TO_SERVER, cluster.manufacturerCode);

package/src/controller/model/index.ts

@@ -2,3 +2,4 @@ export {Device} from "./device";
 export {Endpoint} from "./endpoint";
 export {Entity} from "./entity";
 export {Group} from "./group";
+export {ZigbeeEntity} from "./zigbeeEntity";

package/src/controller/model/zigbeeEntity.ts

@@ -0,0 +1,30 @@
+import type {
+    ClusterOrRawAttributeKeys,
+    ClusterOrRawAttributes,
+    ClusterOrRawPayload,
+    KeyValue,
+    PartialClusterOrRawWriteAttributes,
+    TCustomCluster,
+} from "../tstype";
+import Entity from "./entity";
+
+export abstract class ZigbeeEntity extends Entity {
+    public abstract read<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        attributes: ClusterOrRawAttributeKeys<Cl, Custom>,
+        options?: KeyValue,
+    ): Promise<ClusterOrRawAttributes<Cl, Custom> | undefined>;
+
+    public abstract write<Cl extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        attributes: PartialClusterOrRawWriteAttributes<Cl, Custom>,
+        options?: KeyValue,
+    ): Promise<void>;
+
+    public abstract command<Cl extends number | string, Co extends number | string, Custom extends TCustomCluster | undefined = undefined>(
+        clusterKey: Cl,
+        commandKey: Co,
+        payload: ClusterOrRawPayload<Cl, Co, Custom>,
+        options?: KeyValue,
+    ): Promise<undefined | KeyValue>;
+}