zigbee-herdsman 3.5.1 → 4.0.0

package/src/zspec/zcl/definition/status.ts

@@ -0,0 +1,69 @@
+export enum Status {
+    /**  Operation was successful. */
+    SUCCESS = 0x00,
+    /**  Operation was not successful. */
+    FAILURE = 0x01,
+    /** The sender of the command does not have authorization to carry out this command. */
+    NOT_AUTHORIZED = 0x7e,
+    RESERVED = 0x7f,
+    /**
+     * The command appears to contain the wrong fields, as detected either by the presence of one or more invalid
+     * field entries or by there being missing fields.
+     * Command not carried out. Implementer has discretion as to whether to return this error or INVALID_FIELD.
+     */
+    MALFORMED_COMMAND = 0x80,
+    // UNSUP_CLUSTER_COMMAND = 0x81, DEPRECATED in favor of UNSUP_COMMAND
+    /** The specified command is not supported on the device. Command not carried out. */
+    UNSUP_COMMAND = 0x81,
+    UNSUP_GENERAL_COMMAND = 0x82, // DEPRECATED in favor of UNSUP_COMMAND
+    UNSUP_MANUF_CLUSTER_COMMAND = 0x83, // DEPRECATED in favor of UNSUP_COMMAND
+    UNSUP_MANUF_GENERAL_COMMAND = 0x84, // DEPRECATED in favor of UNSUP_COMMAND
+    /** At least one field of the command contains an incorrect value, according to the specification the device is implemented to. */
+    INVALID_FIELD = 0x85,
+    /** The specified attribute does not exist on the device. */
+    UNSUPPORTED_ATTRIBUTE = 0x86,
+    /**
+     * Out of range error or set to a reserved value. Attribute keeps its old value.
+     * Note that an attribute value may be out of range if an attribute is related to another,
+     * e.g., with minimum and maximum attributes. See the individual attribute descriptions for specific details.
+     */
+    INVALID_VALUE = 0x87,
+    /** Attempt to write a read-only attribute. */
+    READ_ONLY = 0x88,
+    /** An operation failed due to an insufficient amount of free space available. */
+    INSUFFICIENT_SPACE = 0x89,
+    DUPLICATE_EXISTS = 0x8a, // DEPRECATED in favor of SUCCESS
+    /** The requested information (e.g., table entry) could not be found. */
+    NOT_FOUND = 0x8b,
+    /** Periodic reports cannot be issued for this attribute.*/
+    UNREPORTABLE_ATTRIBUTE = 0x8c,
+    /** The data type given for an attribute is incorrect. Command not carried out.*/
+    INVALID_DATA_TYPE = 0x8d,
+    /** The selector for an attribute is incorrect. */
+    INVALID_SELECTOR = 0x8e,
+    WRITE_ONLY = 0x8f, // DEPRECATED in favor of NOT_AUTHORIZED
+    INCONSISTENT_STARTUP_STATE = 0x90, // DEPRECATED in favor of FAILURE
+    DEFINED_OUT_OF_BAND = 0x91, // DEPRECATED in favor of FAILURE
+    RESERVED14 = 0x92,
+    ACTION_DENIED = 0x93, // DEPRECATED in favor of FAILURE
+    /** The exchange was aborted due to excessive response time. */
+    TIMEOUT = 0x94,
+    /** Failed case when a client or a server decides to abort the upgrade process. */
+    ABORT = 0x95,
+    /** Invalid OTA upgrade image (ex. failed signature validation or signer information check or CRC check). */
+    INVALID_IMAGE = 0x96,
+    /** Server does not have data block available yet. */
+    WAIT_FOR_DATA = 0x97,
+    /** No OTA upgrade image available for the client. */
+    NO_IMAGE_AVAILABLE = 0x98,
+    /** The client still requires more OTA upgrade image files to successfully upgrade. */
+    REQUIRE_MORE_IMAGE = 0x99,
+    /** The command has been received and is being processed. */
+    NOTIFICATION_PENDING = 0x9a,
+    HARDWARE_FAILURE = 0xc0, // DEPRECATED in favor of FAILURE
+    SOFTWARE_FAILURE = 0xc1, // DEPRECATED in favor of FAILURE
+    RESERVED15 = 0xc2,
+    /** The cluster is not supported. */
+    UNSUPPORTED_CLUSTER = 0xc3,
+    LIMIT_REACHED = 0xc4, // DEPRECATED in favor of SUCCESS
+}

package/src/zspec/zcl/definition/tstype.ts

@@ -0,0 +1,236 @@
+import type {BuffaloZclDataType, DataType, DataTypeClass, Direction, FrameType, ParameterCondition, StructuredIndicatorType} from "./enums";
+import type {Status} from "./status";
+
+export interface BuffaloZclOptions {
+    length?: number;
+    payload?: {
+        mode?: number; // used to read ListThermoTransitions
+        numoftrans?: number; // used to read ListThermoTransitions
+        commandID?: number; // used to read GpdFrame
+        payloadSize?: number; // used to read GpdFrame
+    } & {[key: string]: unknown};
+    dataType?: DataType | BuffaloZclDataType;
+    attrId?: number;
+}
+
+export interface ZclArray {
+    elementType: DataType | keyof typeof DataType;
+    elements: unknown[];
+}
+
+export interface StructuredSelector {
+    indexes?: number[];
+    indicatorType?: StructuredIndicatorType;
+}
+
+export interface FrameControl {
+    reservedBits: number;
+    frameType: FrameType;
+    manufacturerSpecific: boolean;
+    direction: Direction;
+    disableDefaultResponse: boolean;
+}
+
+export interface Attribute {
+    ID: number;
+    name: string;
+    type: DataType;
+    manufacturerCode?: number;
+}
+
+export interface Parameter {
+    name: string;
+    type: DataType | BuffaloZclDataType;
+}
+
+export interface Command {
+    ID: number;
+    name: string;
+    parameters: readonly Parameter[];
+    response?: number;
+}
+
+export interface AttributeDefinition {
+    ID: number;
+    type: DataType;
+    manufacturerCode?: number;
+}
+
+export interface ParameterDefinition extends Parameter {
+    conditions?: (
+        | {type: ParameterCondition.STATUS_EQUAL; value: Status}
+        | {type: ParameterCondition.STATUS_NOT_EQUAL; value: Status}
+        | {type: ParameterCondition.MINIMUM_REMAINING_BUFFER_BYTES; value: number}
+        | {type: ParameterCondition.DIRECTION_EQUAL; value: Direction}
+        | {type: ParameterCondition.BITMASK_SET; param: string; mask: number /* not set */; reversed?: boolean}
+        | {type: ParameterCondition.BITFIELD_ENUM; param: string; offset: number; size: number; value: number}
+        | {type: ParameterCondition.DATA_TYPE_CLASS_EQUAL; value: DataTypeClass}
+        | {type: ParameterCondition.FIELD_EQUAL; field: string; value: unknown}
+    )[];
+}
+
+export interface CommandDefinition {
+    ID: number;
+    parameters: readonly ParameterDefinition[];
+    response?: number;
+}
+
+export interface Cluster {
+    ID: number;
+    name: string;
+    manufacturerCode?: number;
+    attributes: {[s: string]: Attribute};
+    commands: {
+        [s: string]: Command;
+    };
+    commandsResponse: {
+        [s: string]: Command;
+    };
+    getAttribute: (key: number | string) => Attribute;
+    hasAttribute: (key: number | string) => boolean;
+    getCommand: (key: number | string) => Command;
+    getCommandResponse: (key: number | string) => Command;
+}
+
+export interface ClusterDefinition {
+    ID: number;
+    manufacturerCode?: number;
+    attributes: Readonly<Record<string, Readonly<AttributeDefinition>>>;
+    commands: Readonly<Record<string, Readonly<CommandDefinition>>>;
+    commandsResponse: Readonly<Record<string, Readonly<CommandDefinition>>>;
+}
+
+export interface CustomClusters {
+    [k: string]: ClusterDefinition;
+}
+
+export type ClusterName =
+    | "genBasic"
+    | "genPowerCfg"
+    | "genDeviceTempCfg"
+    | "genIdentify"
+    | "genGroups"
+    | "genScenes"
+    | "genOnOff"
+    | "genOnOffSwitchCfg"
+    | "genLevelCtrl"
+    | "genAlarms"
+    | "genTime"
+    | "genRssiLocation"
+    | "genAnalogInput"
+    | "genAnalogOutput"
+    | "genAnalogValue"
+    | "genBinaryInput"
+    | "genBinaryOutput"
+    | "genBinaryValue"
+    | "genMultistateInput"
+    | "genMultistateOutput"
+    | "genMultistateValue"
+    | "genCommissioning"
+    | "genOta"
+    | "genPollCtrl"
+    | "greenPower"
+    | "mobileDeviceCfg"
+    | "neighborCleaning"
+    | "nearestGateway"
+    | "closuresShadeCfg"
+    | "closuresDoorLock"
+    | "closuresWindowCovering"
+    | "barrierControl"
+    | "hvacPumpCfgCtrl"
+    | "hvacThermostat"
+    | "hvacFanCtrl"
+    | "hvacDehumidificationCtrl"
+    | "hvacUserInterfaceCfg"
+    | "lightingColorCtrl"
+    | "lightingBallastCfg"
+    | "msIlluminanceMeasurement"
+    | "msIlluminanceLevelSensing"
+    | "msTemperatureMeasurement"
+    | "msPressureMeasurement"
+    | "msFlowMeasurement"
+    | "msRelativeHumidity"
+    | "msOccupancySensing"
+    | "msSoilMoisture"
+    | "pHMeasurement"
+    | "msCO2"
+    | "pm1Measurement"
+    | "msFormaldehyde"
+    | "pm10Measurement"
+    | "pm25Measurement"
+    | "ssIasZone"
+    | "ssIasAce"
+    | "ssIasWd"
+    | "piGenericTunnel"
+    | "piBacnetProtocolTunnel"
+    | "piAnalogInputReg"
+    | "piAnalogInputExt"
+    | "piAnalogOutputReg"
+    | "piAnalogOutputExt"
+    | "piAnalogValueReg"
+    | "piAnalogValueExt"
+    | "piBinaryInputReg"
+    | "piBinaryInputExt"
+    | "piBinaryOutputReg"
+    | "piBinaryOutputExt"
+    | "piBinaryValueReg"
+    | "piBinaryValueExt"
+    | "piMultistateInputReg"
+    | "piMultistateInputExt"
+    | "piMultistateOutputReg"
+    | "piMultistateOutputExt"
+    | "piMultistateValueReg"
+    | "piMultistateValueExt"
+    | "pi11073ProtocolTunnel"
+    | "piIso7818ProtocolTunnel"
+    | "piRetailTunnel"
+    | "seMetering"
+    | "tunneling"
+    | "telecommunicationsInformation"
+    | "telecommunicationsVoiceOverZigbee"
+    | "telecommunicationsChatting"
+    | "haApplianceIdentification"
+    | "haMeterIdentification"
+    | "haApplianceEventsAlerts"
+    | "haApplianceStatistics"
+    | "haElectricalMeasurement"
+    | "haDiagnostic"
+    | "touchlink"
+    | "manuSpecificClusterAduroSmart"
+    | "manuSpecificOsram"
+    | "manuSpecificPhilips"
+    | "manuSpecificPhilips2"
+    | "manuSpecificSinope"
+    | "manuSpecificLegrandDevices"
+    | "manuSpecificLegrandDevices2"
+    | "manuSpecificLegrandDevices3"
+    | "wiserDeviceInfo"
+    | "manuSpecificTuya"
+    | "manuSpecificLumi"
+    | "liXeePrivate"
+    | "manuSpecificTuya_2"
+    | "manuSpecificTuya_3"
+    | "manuSpecificCentraliteHumidity"
+    | "manuSpecificSmartThingsArrivalSensor"
+    | "manuSpecificSamsungAccelerometer"
+    | "heimanSpecificAirQuality"
+    | "heimanSpecificScenes"
+    | "tradfriButton"
+    | "heimanSpecificInfraRedRemote"
+    | "schneiderSpecificPilotMode"
+    | "elkoOccupancySettingClusterServer"
+    | "elkoSwitchConfigurationClusterServer"
+    | "manuSpecificSchneiderLightSwitchConfiguration"
+    | "manuSpecificSchneiderFanSwitchConfiguration"
+    | "sprutDevice"
+    | "sprutVoc"
+    | "sprutNoise"
+    | "sprutIrBlaster"
+    | "manuSpecificSiglisZigfred"
+    | "owonClearMetering"
+    | "zosungIRTransmit"
+    | "zosungIRControl"
+    | "manuSpecificAssaDoorLock"
+    | "manuSpecificDoorman"
+    | "manuSpecificProfalux1"
+    | "manuSpecificAmazonWWAH";

package/src/zspec/zcl/index.ts

@@ -0,0 +1,10 @@
+export * from "./definition/consts";
+export * from "./definition/enums";
+export {Clusters} from "./definition/cluster";
+export {Status} from "./definition/status";
+export {Foundation} from "./definition/foundation";
+export {ManufacturerCode} from "./definition/manufacturerCode";
+export {ZclFrame as Frame} from "./zclFrame";
+export {ZclHeader as Header} from "./zclHeader";
+export {ZclStatusError as StatusError} from "./zclStatusError";
+export * as Utils from "./utils";

package/src/zspec/zcl/utils.ts

@@ -0,0 +1,342 @@
+import {Clusters} from "./definition/cluster";
+import {DataType, DataTypeClass} from "./definition/enums";
+import {Foundation, type FoundationCommandName, type FoundationDefinition} from "./definition/foundation";
+import type {Attribute, Cluster, ClusterDefinition, ClusterName, Command, CustomClusters} from "./definition/tstype";
+
+const DATA_TYPE_CLASS_DISCRETE = [
+    DataType.DATA8,
+    DataType.DATA16,
+    DataType.DATA24,
+    DataType.DATA32,
+    DataType.DATA40,
+    DataType.DATA48,
+    DataType.DATA56,
+    DataType.DATA64,
+    DataType.BOOLEAN,
+    DataType.BITMAP8,
+    DataType.BITMAP16,
+    DataType.BITMAP24,
+    DataType.BITMAP32,
+    DataType.BITMAP40,
+    DataType.BITMAP48,
+    DataType.BITMAP56,
+    DataType.BITMAP64,
+    DataType.ENUM8,
+    DataType.ENUM16,
+    DataType.OCTET_STR,
+    DataType.CHAR_STR,
+    DataType.LONG_OCTET_STR,
+    DataType.LONG_CHAR_STR,
+    DataType.ARRAY,
+    DataType.STRUCT,
+    DataType.SET,
+    DataType.BAG,
+    DataType.CLUSTER_ID,
+    DataType.ATTR_ID,
+    DataType.BAC_OID,
+    DataType.IEEE_ADDR,
+    DataType.SEC_KEY,
+];
+const DATA_TYPE_CLASS_ANALOG = [
+    DataType.UINT8,
+    DataType.UINT16,
+    DataType.UINT24,
+    DataType.UINT32,
+    DataType.UINT40,
+    DataType.UINT48,
+    DataType.UINT56,
+    DataType.INT8,
+    DataType.INT16,
+    DataType.INT24,
+    DataType.INT32,
+    DataType.INT40,
+    DataType.INT48,
+    DataType.INT56,
+    DataType.SEMI_PREC,
+    DataType.SINGLE_PREC,
+    DataType.DOUBLE_PREC,
+    DataType.TOD,
+    DataType.DATE,
+    DataType.UTC,
+];
+
+const FOUNDATION_DISCOVER_RSP_IDS = [
+    Foundation.discoverRsp.ID,
+    Foundation.discoverCommandsRsp.ID,
+    Foundation.discoverCommandsGenRsp.ID,
+    Foundation.discoverExtRsp.ID,
+];
+
+export function getDataTypeClass(dataType: DataType): DataTypeClass {
+    if (DATA_TYPE_CLASS_DISCRETE.includes(dataType)) {
+        return DataTypeClass.DISCRETE;
+    }
+
+    if (DATA_TYPE_CLASS_ANALOG.includes(dataType)) {
+        return DataTypeClass.ANALOG;
+    }
+
+    throw new Error(`Don't know value type for '${DataType[dataType]}'`);
+}
+
+function hasCustomClusters(customClusters: CustomClusters): boolean {
+    // XXX: was there a good reason to not set the parameter `customClusters` optional? it would allow simple undefined check
+    // below is twice faster than checking `Object.keys(customClusters).length`
+    // biome-ignore lint/style/useNamingConvention: not working properly
+    for (const _k in customClusters) return true;
+    return false;
+}
+
+function findClusterNameByID(
+    id: number,
+    manufacturerCode: number | undefined,
+    clusters: CustomClusters,
+): [name: string | undefined, partialMatch: boolean] {
+    let name: string | undefined;
+    // if manufacturer code is given, consider partial match if didn't match against manufacturer code
+    let partialMatch = Boolean(manufacturerCode);
+
+    for (const clusterName in clusters) {
+        const cluster = clusters[clusterName as ClusterName];
+
+        if (cluster.ID === id) {
+            // priority on first match when matching only ID
+            if (name === undefined) {
+                name = clusterName;
+            }
+
+            if (manufacturerCode && cluster.manufacturerCode === manufacturerCode) {
+                name = clusterName;
+                partialMatch = false;
+                break;
+            }
+
+            if (!cluster.manufacturerCode) {
+                name = clusterName;
+                break;
+            }
+        }
+    }
+
+    return [name, partialMatch];
+}
+
+function getClusterDefinition(
+    key: string | number,
+    manufacturerCode: number | undefined,
+    customClusters: CustomClusters,
+): {name: string; cluster: ClusterDefinition} {
+    let name: string | undefined;
+
+    if (typeof key === "number") {
+        let partialMatch: boolean;
+
+        // custom clusters have priority over Zcl clusters, except in case of better match (see below)
+        [name, partialMatch] = findClusterNameByID(key, manufacturerCode, customClusters);
+
+        if (!name) {
+            [name, partialMatch] = findClusterNameByID(key, manufacturerCode, Clusters);
+        } else if (partialMatch) {
+            let zclName: string | undefined;
+            [zclName, partialMatch] = findClusterNameByID(key, manufacturerCode, Clusters);
+
+            // Zcl clusters contain a better match, use that one
+            if (zclName !== undefined && !partialMatch) {
+                name = zclName;
+            }
+        }
+    } else {
+        name = key;
+    }
+
+    let cluster =
+        name !== undefined && hasCustomClusters(customClusters)
+            ? {
+                  ...Clusters[name as ClusterName],
+                  ...customClusters[name], // should override Zcl clusters
+              }
+            : Clusters[name as ClusterName];
+
+    if (!cluster) {
+        if (typeof key === "number") {
+            name = key.toString();
+            cluster = {attributes: {}, commands: {}, commandsResponse: {}, manufacturerCode: undefined, ID: key};
+        } else {
+            name = undefined;
+        }
+    }
+
+    if (!name) {
+        throw new Error(`Cluster with name '${key}' does not exist`);
+    }
+
+    return {name, cluster};
+}
+
+function createCluster(name: string, cluster: ClusterDefinition, manufacturerCode?: number): Cluster {
+    const attributes: {[s: string]: Attribute} = Object.assign({}, ...Object.entries(cluster.attributes).map(([k, v]) => ({[k]: {...v, name: k}})));
+    const commands: {[s: string]: Command} = Object.assign({}, ...Object.entries(cluster.commands).map(([k, v]) => ({[k]: {...v, name: k}})));
+    const commandsResponse: {[s: string]: Command} = Object.assign(
+        {},
+        ...Object.entries(cluster.commandsResponse).map(([k, v]) => ({[k]: {...v, name: k}})),
+    );
+
+    const getAttributeInternal = (key: number | string): Attribute | undefined => {
+        if (typeof key === "number") {
+            let partialMatchAttr: Attribute | undefined;
+
+            for (const attrKey in attributes) {
+                const attr = attributes[attrKey];
+
+                if (attr.ID === key) {
+                    if (manufacturerCode && attr.manufacturerCode === manufacturerCode) {
+                        return attr;
+                    }
+
+                    if (attr.manufacturerCode === undefined) {
+                        partialMatchAttr = attr;
+                    }
+                }
+            }
+
+            return partialMatchAttr;
+        }
+
+        for (const attrKey in attributes) {
+            const attr = attributes[attrKey];
+
+            if (attr.name === key) {
+                return attr;
+            }
+        }
+
+        return undefined;
+    };
+
+    const getAttribute = (key: number | string): Attribute => {
+        const result = getAttributeInternal(key);
+        if (!result) {
+            throw new Error(`Cluster '${name}' has no attribute '${key}'`);
+        }
+
+        return result;
+    };
+
+    const hasAttribute = (key: number | string): boolean => {
+        const result = getAttributeInternal(key);
+        return !!result;
+    };
+
+    const getCommand = (key: number | string): Command => {
+        if (typeof key === "number") {
+            for (const cmdKey in commands) {
+                const cmd = commands[cmdKey];
+
+                if (cmd.ID === key) {
+                    return cmd;
+                }
+            }
+        } else {
+            for (const cmdKey in commands) {
+                const cmd = commands[cmdKey];
+
+                if (cmd.name === key) {
+                    return cmd;
+                }
+            }
+        }
+
+        throw new Error(`Cluster '${name}' has no command '${key}'`);
+    };
+
+    const getCommandResponse = (key: number | string): Command => {
+        if (typeof key === "number") {
+            for (const cmdKey in commandsResponse) {
+                const cmd = commandsResponse[cmdKey];
+
+                if (cmd.ID === key) {
+                    return cmd;
+                }
+            }
+        } else {
+            for (const cmdKey in commandsResponse) {
+                const cmd = commandsResponse[cmdKey];
+
+                if (cmd.name === key) {
+                    return cmd;
+                }
+            }
+        }
+
+        throw new Error(`Cluster '${name}' has no command response '${key}'`);
+    };
+
+    return {
+        ID: cluster.ID,
+        attributes,
+        manufacturerCode: cluster.manufacturerCode,
+        name,
+        commands,
+        commandsResponse,
+        getAttribute,
+        hasAttribute,
+        getCommand,
+        getCommandResponse,
+    };
+}
+
+export function getCluster(key: string | number, manufacturerCode: number | undefined, customClusters: CustomClusters): Cluster {
+    const {name, cluster} = getClusterDefinition(key, manufacturerCode, customClusters);
+    return createCluster(name, cluster, manufacturerCode);
+}
+
+function getGlobalCommandNameById(id: number): FoundationCommandName {
+    for (const commandName in Foundation) {
+        if (Foundation[commandName as FoundationCommandName].ID === id) {
+            return commandName as FoundationCommandName;
+        }
+    }
+
+    throw new Error(`Global command with id '${id}' does not exist.`);
+}
+
+export function getGlobalCommand(key: number | string): Command {
+    const name = typeof key === "number" ? getGlobalCommandNameById(key) : (key as FoundationCommandName);
+    const command = Foundation[name];
+
+    if (!command) {
+        throw new Error(`Global command with key '${key}' does not exist`);
+    }
+
+    const result: Command = {
+        ID: command.ID,
+        name,
+        parameters: command.parameters,
+    };
+
+    if (command.response !== undefined) {
+        result.response = command.response;
+    }
+
+    return result;
+}
+
+export function isClusterName(name: string): name is ClusterName {
+    return name in Clusters;
+}
+
+export function getFoundationCommand(id: number): FoundationDefinition {
+    for (const commandName in Foundation) {
+        const command = Foundation[commandName as FoundationCommandName];
+
+        if (command.ID === id) {
+            return command;
+        }
+    }
+
+    throw new Error(`Foundation command '${id}' does not exist.`);
+}
+
+export function isFoundationDiscoverRsp(id: number): boolean {
+    return FOUNDATION_DISCOVER_RSP_IDS.includes(id);
+}