zigbee-clusters 2.9.0 → 2.10.0

package/AGENTS.md

@@ -303,6 +303,7 @@ attr3: { ... },
 | `id` | Yes | Always 4-digit hex format (0x0000); add decimal comment if > 9 |
 | `args` | If has params | Object with typed fields |
 | `response` | If expects response | Has own `id` and `args` |
+| `encodeMissingFieldsBehavior` | Controls the behavior of missing fields when encoding the struct | Set to `skip` if some fields are optional, omit if all fields are mandatory |
 | `direction` | For server→client | `Cluster.DIRECTION_SERVER_TO_CLIENT` |
 
 #### Command Sections
@@ -333,11 +334,54 @@ lockDoor: {
 },
 ```
 
-**Server→client commands** (events/notifications) should be evaluated per case:
-- Implement if commonly needed (e.g., `operationEventNotification` for door locks)
-- Skip obscure or rarely-used notifications unless specifically requested
+**Server→client commands** should only be added as standalone commands when they can be sent **unsolicited** (not just as a response to a request). Examples:
+- Unsolicited notifications (e.g., `operationEventNotification` for door locks) — add as standalone
+- Responses that the server can also send unsolicited (e.g., `upgradeEndResponse` for synchronized upgrades) — add as standalone
+- Responses that are **only** sent in reply to a request (e.g., `queryNextImageResponse`) — do **NOT** add as standalone; they are already covered by the inline `response:` on the request command
 - These require `direction: Cluster.DIRECTION_SERVER_TO_CLIENT`
 
+#### Optional fields
+Some commands contain optional fields. If this is the case add `encodeMissingFieldsBehavior: 'skip'` to the command definition.
+
+```javascript
+lockDoor: {
+  id: 0x0000,
+  encodeMissingFieldsBehavior: 'skip',
+  args: { pinCode: ZCLDataTypes.octstr },
+  response: {
+    id: 0x0000,
+    args: { status: ZCLDataTypes.uint8 },
+  },
+}
+```
+
+#### Command variants
+Some commands might change their structure based on a status field. If this is the case, add `encodeMissingFieldsBehavior: 'skip'`. And add a comment above each field
+when the field should be present.
+
+**IMPORTANT**: This applies to `response:` structs too, not just the top-level command. If a response has variant fields (e.g., different fields depending on a status value), add `encodeMissingFieldsBehavior: 'skip'` to the response and include all variant fields with comments indicating when each group is present.
+
+```javascript
+imageBlockRequest: {
+  id: 0x0003,
+  args: { ... },
+  response: {
+    id: 0x0005,
+    encodeMissingFieldsBehavior: 'skip',
+    args: {
+      status: ZCLDataTypes.enum8Status,
+      // When status is SUCCESS
+      manufacturerCode: ZCLDataTypes.uint16,
+      fileOffset: ZCLDataTypes.uint32,
+      imageData: ZCLDataTypes.buffer,
+      // When status is WAIT_FOR_DATA
+      currentTime: ZCLDataTypes.uint32,
+      requestTime: ZCLDataTypes.uint32,
+    },
+  },
+}
+```
+
 ---
 
 ### ZCLDataTypes Reference

package/index.d.ts

@@ -31,6 +31,8 @@ type ZCLNodeConstructorInput = {
   ) => Promise<void>;
 };
 
+type ZCLEnum8Status = 'SUCCESS' | 'FAILURE' | 'NOT_AUTHORIZED' | 'RESERVED_FIELD_NOT_ZERO' | 'MALFORMED_COMMAND' | 'UNSUP_CLUSTER_COMMAND' | 'UNSUP_GENERAL_COMMAND' | 'UNSUP_MANUF_CLUSTER_COMMAND' | 'UNSUP_MANUF_GENERAL_COMMAND' | 'INVALID_FIELD' | 'UNSUPPORTED_ATTRIBUTE' | 'INVALID_VALUE' | 'READ_ONLY' | 'INSUFFICIENT_SPACE' | 'DUPLICATE_EXISTS' | 'NOT_FOUND' | 'UNREPORTABLE_ATTRIBUTE' | 'INVALID_DATA_TYPE' | 'INVALID_SELECTOR' | 'WRITE_ONLY' | 'INCONSISTENT_STARTUP_STATE' | 'DEFINED_OUT_OF_BAND' | 'INCONSISTENT' | 'ACTION_DENIED' | 'TIMEOUT' | 'ABORT' | 'INVALID_IMAGE' | 'WAIT_FOR_DATA' | 'NO_IMAGE_AVAILABLE' | 'REQUIRE_MORE_IMAGE' | 'NOTIFICATION_PENDING' | 'HARDWARE_FAILURE' | 'SOFTWARE_FAILURE' | 'CALIBRATION_ERROR' | 'UNSUPPORTED_CLUSTER';
+
 export interface ZCLNodeCluster extends EventEmitter {
   discoverCommandsGenerated(params?: {
     startValue?: number;
@@ -449,10 +451,10 @@ export interface GroupsCluster extends ZCLNodeCluster {
   writeAttributes(attributes: Partial<GroupsClusterAttributes>, opts?: { timeout?: number }): Promise<unknown>;
   on<K extends keyof GroupsClusterAttributes & string>(eventName: `attr.${K}`, listener: (value: GroupsClusterAttributes[K]) => void): this;
   once<K extends keyof GroupsClusterAttributes & string>(eventName: `attr.${K}`, listener: (value: GroupsClusterAttributes[K]) => void): this;
-  addGroup(args: { groupId: number; groupName: string }, opts?: ClusterCommandOptions): Promise<{ status: 'SUCCESS' | 'FAILURE' | 'NOT_AUTHORIZED' | 'RESERVED_FIELD_NOT_ZERO' | 'MALFORMED_COMMAND' | 'UNSUP_CLUSTER_COMMAND' | 'UNSUP_GENERAL_COMMAND' | 'UNSUP_MANUF_CLUSTER_COMMAND' | 'UNSUP_MANUF_GENERAL_COMMAND' | 'INVALID_FIELD' | 'UNSUPPORTED_ATTRIBUTE' | 'INVALID_VALUE' | 'READ_ONLY' | 'INSUFFICIENT_SPACE' | 'DUPLICATE_EXISTS' | 'NOT_FOUND' | 'UNREPORTABLE_ATTRIBUTE' | 'INVALID_DATA_TYPE' | 'INVALID_SELECTOR' | 'WRITE_ONLY' | 'INCONSISTENT_STARTUP_STATE' | 'DEFINED_OUT_OF_BAND' | 'INCONSISTENT' | 'ACTION_DENIED' | 'TIMEOUT' | 'ABORT' | 'INVALID_IMAGE' | 'WAIT_FOR_DATA' | 'NO_IMAGE_AVAILABLE' | 'REQUIRE_MORE_IMAGE' | 'NOTIFICATION_PENDING' | 'HARDWARE_FAILURE' | 'SOFTWARE_FAILURE' | 'CALIBRATION_ERROR' | 'UNSUPPORTED_CLUSTER'; groupId: number }>;
-  viewGroup(args: { groupId: number }, opts?: ClusterCommandOptions): Promise<{ status: 'SUCCESS' | 'FAILURE' | 'NOT_AUTHORIZED' | 'RESERVED_FIELD_NOT_ZERO' | 'MALFORMED_COMMAND' | 'UNSUP_CLUSTER_COMMAND' | 'UNSUP_GENERAL_COMMAND' | 'UNSUP_MANUF_CLUSTER_COMMAND' | 'UNSUP_MANUF_GENERAL_COMMAND' | 'INVALID_FIELD' | 'UNSUPPORTED_ATTRIBUTE' | 'INVALID_VALUE' | 'READ_ONLY' | 'INSUFFICIENT_SPACE' | 'DUPLICATE_EXISTS' | 'NOT_FOUND' | 'UNREPORTABLE_ATTRIBUTE' | 'INVALID_DATA_TYPE' | 'INVALID_SELECTOR' | 'WRITE_ONLY' | 'INCONSISTENT_STARTUP_STATE' | 'DEFINED_OUT_OF_BAND' | 'INCONSISTENT' | 'ACTION_DENIED' | 'TIMEOUT' | 'ABORT' | 'INVALID_IMAGE' | 'WAIT_FOR_DATA' | 'NO_IMAGE_AVAILABLE' | 'REQUIRE_MORE_IMAGE' | 'NOTIFICATION_PENDING' | 'HARDWARE_FAILURE' | 'SOFTWARE_FAILURE' | 'CALIBRATION_ERROR' | 'UNSUPPORTED_CLUSTER'; groupId: number; groupNames: string }>;
+  addGroup(args: { groupId: number; groupName: string }, opts?: ClusterCommandOptions): Promise<{ status: ZCLEnum8Status; groupId: number }>;
+  viewGroup(args: { groupId: number }, opts?: ClusterCommandOptions): Promise<{ status: ZCLEnum8Status; groupId: number; groupNames: string }>;
   getGroupMembership(args: { groupIds: number[] }, opts?: ClusterCommandOptions): Promise<{ capacity: number; groups: number[] }>;
-  removeGroup(args: { groupId: number }, opts?: ClusterCommandOptions): Promise<{ status: 'SUCCESS' | 'FAILURE' | 'NOT_AUTHORIZED' | 'RESERVED_FIELD_NOT_ZERO' | 'MALFORMED_COMMAND' | 'UNSUP_CLUSTER_COMMAND' | 'UNSUP_GENERAL_COMMAND' | 'UNSUP_MANUF_CLUSTER_COMMAND' | 'UNSUP_MANUF_GENERAL_COMMAND' | 'INVALID_FIELD' | 'UNSUPPORTED_ATTRIBUTE' | 'INVALID_VALUE' | 'READ_ONLY' | 'INSUFFICIENT_SPACE' | 'DUPLICATE_EXISTS' | 'NOT_FOUND' | 'UNREPORTABLE_ATTRIBUTE' | 'INVALID_DATA_TYPE' | 'INVALID_SELECTOR' | 'WRITE_ONLY' | 'INCONSISTENT_STARTUP_STATE' | 'DEFINED_OUT_OF_BAND' | 'INCONSISTENT' | 'ACTION_DENIED' | 'TIMEOUT' | 'ABORT' | 'INVALID_IMAGE' | 'WAIT_FOR_DATA' | 'NO_IMAGE_AVAILABLE' | 'REQUIRE_MORE_IMAGE' | 'NOTIFICATION_PENDING' | 'HARDWARE_FAILURE' | 'SOFTWARE_FAILURE' | 'CALIBRATION_ERROR' | 'UNSUPPORTED_CLUSTER'; groupId: number }>;
+  removeGroup(args: { groupId: number }, opts?: ClusterCommandOptions): Promise<{ status: ZCLEnum8Status; groupId: number }>;
   removeAllGroups(opts?: ClusterCommandOptions): Promise<void>;
   addGroupIfIdentify(args: { groupId: number; groupName: string }, opts?: ClusterCommandOptions): Promise<void>;
 }
@@ -579,32 +581,22 @@ export interface MeteringClusterAttributes {
   currentTier3SummationReceived?: number;
   currentTier4SummationDelivered?: number;
   currentTier4SummationReceived?: number;
-  status?: unknown;
+  status?: Partial<{ checkMeter: boolean; lowBattery: boolean; tamperDetect: boolean; powerFailure: boolean; powerQuality: boolean; leakDetect: boolean; serviceDisconnect: boolean }>;
   remainingBatteryLife?: number;
   hoursInOperation?: number;
   hoursInFault?: number;
-  extendedStatus?: unknown;
   unitOfMeasure?: unknown;
   multiplier?: number;
   divisor?: number;
-  summationFormatting?: unknown;
-  demandFormatting?: unknown;
-  historicalConsumptionFormatting?: unknown;
-  meteringDeviceType?: unknown;
   siteId?: Buffer;
   meterSerialNumber?: Buffer;
   energyCarrierUnitOfMeasure?: unknown;
-  energyCarrierSummationFormatting?: unknown;
-  energyCarrierDemandFormatting?: unknown;
   temperatureUnitOfMeasure?: unknown;
-  temperatureFormatting?: unknown;
   moduleSerialNumber?: Buffer;
   operatingTariffLabelDelivered?: Buffer;
   operatingTariffLabelReceived?: Buffer;
   customerIdNumber?: Buffer;
   alternativeUnitOfMeasure?: unknown;
-  alternativeDemandFormatting?: unknown;
-  alternativeConsumptionFormatting?: unknown;
   instantaneousDemand?: number;
   currentDayConsumptionDelivered?: number;
   currentDayConsumptionReceived?: number;
@@ -714,14 +706,6 @@ export interface MeteringClusterAttributes {
   currentTier4Block14SummationDelivered?: number;
   currentTier4Block15SummationDelivered?: number;
   currentTier4Block16SummationDelivered?: number;
-  genericAlarmMask?: unknown;
-  electricityAlarmMask?: unknown;
-  genericFlowPressureAlarmMask?: unknown;
-  waterSpecificAlarmMask?: unknown;
-  heatAndCoolingSpecificAlarmMask?: unknown;
-  gasSpecificAlarmMask?: unknown;
-  extendedGenericAlarmMask?: unknown;
-  manufacturerAlarmMask?: unknown;
   currentNoTierBlock1SummationReceived?: number;
   currentNoTierBlock2SummationReceived?: number;
   currentNoTierBlock3SummationReceived?: number;
@@ -742,12 +726,10 @@ export interface MeteringClusterAttributes {
   billToDateTimeStampDelivered?: number;
   projectedBillDelivered?: number;
   projectedBillTimeStampDelivered?: number;
-  billDeliveredTrailingDigit?: unknown;
   billToDateReceived?: number;
   billToDateTimeStampReceived?: number;
   projectedBillReceived?: number;
   projectedBillTimeStampReceived?: number;
-  billReceivedTrailingDigit?: unknown;
   proposedChangeSupplyImplementationTime?: number;
   proposedChangeSupplyStatus?: unknown;
   uncontrolledFlowThreshold?: number;
@@ -759,7 +741,7 @@ export interface MeteringClusterAttributes {
 }
 
 export interface MeteringCluster extends ZCLNodeCluster {
-  readAttributes<K extends 'currentSummationDelivered' | 'currentSummationReceived' | 'currentMaxDemandDelivered' | 'currentMaxDemandReceived' | 'dftSummation' | 'dailyFreezeTime' | 'powerFactor' | 'readingSnapShotTime' | 'currentMaxDemandDeliveredTime' | 'currentMaxDemandReceivedTime' | 'defaultUpdatePeriod' | 'fastPollUpdatePeriod' | 'currentBlockPeriodConsumptionDelivered' | 'dailyConsumptionTarget' | 'currentBlock' | 'profileIntervalPeriod' | 'currentTier1SummationDelivered' | 'currentTier1SummationReceived' | 'currentTier2SummationDelivered' | 'currentTier2SummationReceived' | 'currentTier3SummationDelivered' | 'currentTier3SummationReceived' | 'currentTier4SummationDelivered' | 'currentTier4SummationReceived' | 'status' | 'remainingBatteryLife' | 'hoursInOperation' | 'hoursInFault' | 'extendedStatus' | 'unitOfMeasure' | 'multiplier' | 'divisor' | 'summationFormatting' | 'demandFormatting' | 'historicalConsumptionFormatting' | 'meteringDeviceType' | 'siteId' | 'meterSerialNumber' | 'energyCarrierUnitOfMeasure' | 'energyCarrierSummationFormatting' | 'energyCarrierDemandFormatting' | 'temperatureUnitOfMeasure' | 'temperatureFormatting' | 'moduleSerialNumber' | 'operatingTariffLabelDelivered' | 'operatingTariffLabelReceived' | 'customerIdNumber' | 'alternativeUnitOfMeasure' | 'alternativeDemandFormatting' | 'alternativeConsumptionFormatting' | 'instantaneousDemand' | 'currentDayConsumptionDelivered' | 'currentDayConsumptionReceived' | 'previousDayConsumptionDelivered' | 'previousDayConsumptionReceived' | 'currentPartialProfileIntervalStartTimeDelivered' | 'currentPartialProfileIntervalStartTimeReceived' | 'currentPartialProfileIntervalValueDelivered' | 'currentPartialProfileIntervalValueReceived' | 'currentDayMaxPressure' | 'currentDayMinPressure' | 'previousDayMaxPressure' | 'previousDayMinPressure' | 'currentDayMaxDemand' | 'previousDayMaxDemand' | 'currentMonthMaxDemand' | 'currentYearMaxDemand' | 'currentDayMaxEnergyCarrierDemand' | 'previousDayMaxEnergyCarrierDemand' | 'currentMonthMaxEnergyCarrierDemand' | 'currentMonthMinEnergyCarrierDemand' | 'currentYearMaxEnergyCarrierDemand' | 'currentYearMinEnergyCarrierDemand' | 'maxNumberOfPeriodsDelivered' | 'currentDemandDelivered' | 'demandLimit' | 'demandIntegrationPeriod' | 'numberOfDemandSubintervals' | 'demandLimitArmDuration' | 'currentNoTierBlock1SummationDelivered' | 'currentNoTierBlock2SummationDelivered' | 'currentNoTierBlock3SummationDelivered' | 'currentNoTierBlock4SummationDelivered' | 'currentNoTierBlock5SummationDelivered' | 'currentNoTierBlock6SummationDelivered' | 'currentNoTierBlock7SummationDelivered' | 'currentNoTierBlock8SummationDelivered' | 'currentNoTierBlock9SummationDelivered' | 'currentNoTierBlock10SummationDelivered' | 'currentNoTierBlock11SummationDelivered' | 'currentNoTierBlock12SummationDelivered' | 'currentNoTierBlock13SummationDelivered' | 'currentNoTierBlock14SummationDelivered' | 'currentNoTierBlock15SummationDelivered' | 'currentNoTierBlock16SummationDelivered' | 'currentTier1Block1SummationDelivered' | 'currentTier1Block2SummationDelivered' | 'currentTier1Block3SummationDelivered' | 'currentTier1Block4SummationDelivered' | 'currentTier1Block5SummationDelivered' | 'currentTier1Block6SummationDelivered' | 'currentTier1Block7SummationDelivered' | 'currentTier1Block8SummationDelivered' | 'currentTier1Block9SummationDelivered' | 'currentTier1Block10SummationDelivered' | 'currentTier1Block11SummationDelivered' | 'currentTier1Block12SummationDelivered' | 'currentTier1Block13SummationDelivered' | 'currentTier1Block14SummationDelivered' | 'currentTier1Block15SummationDelivered' | 'currentTier1Block16SummationDelivered' | 'currentTier2Block1SummationDelivered' | 'currentTier2Block2SummationDelivered' | 'currentTier2Block3SummationDelivered' | 'currentTier2Block4SummationDelivered' | 'currentTier2Block5SummationDelivered' | 'currentTier2Block6SummationDelivered' | 'currentTier2Block7SummationDelivered' | 'currentTier2Block8SummationDelivered' | 'currentTier2Block9SummationDelivered' | 'currentTier2Block10SummationDelivered' | 'currentTier2Block11SummationDelivered' | 'currentTier2Block12SummationDelivered' | 'currentTier2Block13SummationDelivered' | 'currentTier2Block14SummationDelivered' | 'currentTier2Block15SummationDelivered' | 'currentTier2Block16SummationDelivered' | 'currentTier3Block1SummationDelivered' | 'currentTier3Block2SummationDelivered' | 'currentTier3Block3SummationDelivered' | 'currentTier3Block4SummationDelivered' | 'currentTier3Block5SummationDelivered' | 'currentTier3Block6SummationDelivered' | 'currentTier3Block7SummationDelivered' | 'currentTier3Block8SummationDelivered' | 'currentTier3Block9SummationDelivered' | 'currentTier3Block10SummationDelivered' | 'currentTier3Block11SummationDelivered' | 'currentTier3Block12SummationDelivered' | 'currentTier3Block13SummationDelivered' | 'currentTier3Block14SummationDelivered' | 'currentTier3Block15SummationDelivered' | 'currentTier3Block16SummationDelivered' | 'currentTier4Block1SummationDelivered' | 'currentTier4Block2SummationDelivered' | 'currentTier4Block3SummationDelivered' | 'currentTier4Block4SummationDelivered' | 'currentTier4Block5SummationDelivered' | 'currentTier4Block6SummationDelivered' | 'currentTier4Block7SummationDelivered' | 'currentTier4Block8SummationDelivered' | 'currentTier4Block9SummationDelivered' | 'currentTier4Block10SummationDelivered' | 'currentTier4Block11SummationDelivered' | 'currentTier4Block12SummationDelivered' | 'currentTier4Block13SummationDelivered' | 'currentTier4Block14SummationDelivered' | 'currentTier4Block15SummationDelivered' | 'currentTier4Block16SummationDelivered' | 'genericAlarmMask' | 'electricityAlarmMask' | 'genericFlowPressureAlarmMask' | 'waterSpecificAlarmMask' | 'heatAndCoolingSpecificAlarmMask' | 'gasSpecificAlarmMask' | 'extendedGenericAlarmMask' | 'manufacturerAlarmMask' | 'currentNoTierBlock1SummationReceived' | 'currentNoTierBlock2SummationReceived' | 'currentNoTierBlock3SummationReceived' | 'currentNoTierBlock4SummationReceived' | 'currentNoTierBlock5SummationReceived' | 'currentNoTierBlock6SummationReceived' | 'currentNoTierBlock7SummationReceived' | 'currentNoTierBlock8SummationReceived' | 'currentNoTierBlock9SummationReceived' | 'currentNoTierBlock10SummationReceived' | 'currentNoTierBlock11SummationReceived' | 'currentNoTierBlock12SummationReceived' | 'currentNoTierBlock13SummationReceived' | 'currentNoTierBlock14SummationReceived' | 'currentNoTierBlock15SummationReceived' | 'currentNoTierBlock16SummationReceived' | 'billToDateDelivered' | 'billToDateTimeStampDelivered' | 'projectedBillDelivered' | 'projectedBillTimeStampDelivered' | 'billDeliveredTrailingDigit' | 'billToDateReceived' | 'billToDateTimeStampReceived' | 'projectedBillReceived' | 'projectedBillTimeStampReceived' | 'billReceivedTrailingDigit' | 'proposedChangeSupplyImplementationTime' | 'proposedChangeSupplyStatus' | 'uncontrolledFlowThreshold' | 'uncontrolledFlowThresholdUnitOfMeasure' | 'uncontrolledFlowMultiplier' | 'uncontrolledFlowDivisor' | 'flowStabilisationPeriod' | 'flowMeasurementPeriod'>(attributeNames: K[], opts?: { timeout?: number }): Promise<Pick<MeteringClusterAttributes, K>>;
+  readAttributes<K extends 'currentSummationDelivered' | 'currentSummationReceived' | 'currentMaxDemandDelivered' | 'currentMaxDemandReceived' | 'dftSummation' | 'dailyFreezeTime' | 'powerFactor' | 'readingSnapShotTime' | 'currentMaxDemandDeliveredTime' | 'currentMaxDemandReceivedTime' | 'defaultUpdatePeriod' | 'fastPollUpdatePeriod' | 'currentBlockPeriodConsumptionDelivered' | 'dailyConsumptionTarget' | 'currentBlock' | 'profileIntervalPeriod' | 'currentTier1SummationDelivered' | 'currentTier1SummationReceived' | 'currentTier2SummationDelivered' | 'currentTier2SummationReceived' | 'currentTier3SummationDelivered' | 'currentTier3SummationReceived' | 'currentTier4SummationDelivered' | 'currentTier4SummationReceived' | 'status' | 'remainingBatteryLife' | 'hoursInOperation' | 'hoursInFault' | 'unitOfMeasure' | 'multiplier' | 'divisor' | 'siteId' | 'meterSerialNumber' | 'energyCarrierUnitOfMeasure' | 'temperatureUnitOfMeasure' | 'moduleSerialNumber' | 'operatingTariffLabelDelivered' | 'operatingTariffLabelReceived' | 'customerIdNumber' | 'alternativeUnitOfMeasure' | 'instantaneousDemand' | 'currentDayConsumptionDelivered' | 'currentDayConsumptionReceived' | 'previousDayConsumptionDelivered' | 'previousDayConsumptionReceived' | 'currentPartialProfileIntervalStartTimeDelivered' | 'currentPartialProfileIntervalStartTimeReceived' | 'currentPartialProfileIntervalValueDelivered' | 'currentPartialProfileIntervalValueReceived' | 'currentDayMaxPressure' | 'currentDayMinPressure' | 'previousDayMaxPressure' | 'previousDayMinPressure' | 'currentDayMaxDemand' | 'previousDayMaxDemand' | 'currentMonthMaxDemand' | 'currentYearMaxDemand' | 'currentDayMaxEnergyCarrierDemand' | 'previousDayMaxEnergyCarrierDemand' | 'currentMonthMaxEnergyCarrierDemand' | 'currentMonthMinEnergyCarrierDemand' | 'currentYearMaxEnergyCarrierDemand' | 'currentYearMinEnergyCarrierDemand' | 'maxNumberOfPeriodsDelivered' | 'currentDemandDelivered' | 'demandLimit' | 'demandIntegrationPeriod' | 'numberOfDemandSubintervals' | 'demandLimitArmDuration' | 'currentNoTierBlock1SummationDelivered' | 'currentNoTierBlock2SummationDelivered' | 'currentNoTierBlock3SummationDelivered' | 'currentNoTierBlock4SummationDelivered' | 'currentNoTierBlock5SummationDelivered' | 'currentNoTierBlock6SummationDelivered' | 'currentNoTierBlock7SummationDelivered' | 'currentNoTierBlock8SummationDelivered' | 'currentNoTierBlock9SummationDelivered' | 'currentNoTierBlock10SummationDelivered' | 'currentNoTierBlock11SummationDelivered' | 'currentNoTierBlock12SummationDelivered' | 'currentNoTierBlock13SummationDelivered' | 'currentNoTierBlock14SummationDelivered' | 'currentNoTierBlock15SummationDelivered' | 'currentNoTierBlock16SummationDelivered' | 'currentTier1Block1SummationDelivered' | 'currentTier1Block2SummationDelivered' | 'currentTier1Block3SummationDelivered' | 'currentTier1Block4SummationDelivered' | 'currentTier1Block5SummationDelivered' | 'currentTier1Block6SummationDelivered' | 'currentTier1Block7SummationDelivered' | 'currentTier1Block8SummationDelivered' | 'currentTier1Block9SummationDelivered' | 'currentTier1Block10SummationDelivered' | 'currentTier1Block11SummationDelivered' | 'currentTier1Block12SummationDelivered' | 'currentTier1Block13SummationDelivered' | 'currentTier1Block14SummationDelivered' | 'currentTier1Block15SummationDelivered' | 'currentTier1Block16SummationDelivered' | 'currentTier2Block1SummationDelivered' | 'currentTier2Block2SummationDelivered' | 'currentTier2Block3SummationDelivered' | 'currentTier2Block4SummationDelivered' | 'currentTier2Block5SummationDelivered' | 'currentTier2Block6SummationDelivered' | 'currentTier2Block7SummationDelivered' | 'currentTier2Block8SummationDelivered' | 'currentTier2Block9SummationDelivered' | 'currentTier2Block10SummationDelivered' | 'currentTier2Block11SummationDelivered' | 'currentTier2Block12SummationDelivered' | 'currentTier2Block13SummationDelivered' | 'currentTier2Block14SummationDelivered' | 'currentTier2Block15SummationDelivered' | 'currentTier2Block16SummationDelivered' | 'currentTier3Block1SummationDelivered' | 'currentTier3Block2SummationDelivered' | 'currentTier3Block3SummationDelivered' | 'currentTier3Block4SummationDelivered' | 'currentTier3Block5SummationDelivered' | 'currentTier3Block6SummationDelivered' | 'currentTier3Block7SummationDelivered' | 'currentTier3Block8SummationDelivered' | 'currentTier3Block9SummationDelivered' | 'currentTier3Block10SummationDelivered' | 'currentTier3Block11SummationDelivered' | 'currentTier3Block12SummationDelivered' | 'currentTier3Block13SummationDelivered' | 'currentTier3Block14SummationDelivered' | 'currentTier3Block15SummationDelivered' | 'currentTier3Block16SummationDelivered' | 'currentTier4Block1SummationDelivered' | 'currentTier4Block2SummationDelivered' | 'currentTier4Block3SummationDelivered' | 'currentTier4Block4SummationDelivered' | 'currentTier4Block5SummationDelivered' | 'currentTier4Block6SummationDelivered' | 'currentTier4Block7SummationDelivered' | 'currentTier4Block8SummationDelivered' | 'currentTier4Block9SummationDelivered' | 'currentTier4Block10SummationDelivered' | 'currentTier4Block11SummationDelivered' | 'currentTier4Block12SummationDelivered' | 'currentTier4Block13SummationDelivered' | 'currentTier4Block14SummationDelivered' | 'currentTier4Block15SummationDelivered' | 'currentTier4Block16SummationDelivered' | 'currentNoTierBlock1SummationReceived' | 'currentNoTierBlock2SummationReceived' | 'currentNoTierBlock3SummationReceived' | 'currentNoTierBlock4SummationReceived' | 'currentNoTierBlock5SummationReceived' | 'currentNoTierBlock6SummationReceived' | 'currentNoTierBlock7SummationReceived' | 'currentNoTierBlock8SummationReceived' | 'currentNoTierBlock9SummationReceived' | 'currentNoTierBlock10SummationReceived' | 'currentNoTierBlock11SummationReceived' | 'currentNoTierBlock12SummationReceived' | 'currentNoTierBlock13SummationReceived' | 'currentNoTierBlock14SummationReceived' | 'currentNoTierBlock15SummationReceived' | 'currentNoTierBlock16SummationReceived' | 'billToDateDelivered' | 'billToDateTimeStampDelivered' | 'projectedBillDelivered' | 'projectedBillTimeStampDelivered' | 'billToDateReceived' | 'billToDateTimeStampReceived' | 'projectedBillReceived' | 'projectedBillTimeStampReceived' | 'proposedChangeSupplyImplementationTime' | 'proposedChangeSupplyStatus' | 'uncontrolledFlowThreshold' | 'uncontrolledFlowThresholdUnitOfMeasure' | 'uncontrolledFlowMultiplier' | 'uncontrolledFlowDivisor' | 'flowStabilisationPeriod' | 'flowMeasurementPeriod'>(attributeNames: K[], opts?: { timeout?: number }): Promise<Pick<MeteringClusterAttributes, K>>;
   readAttributes(attributeNames: Array<keyof MeteringClusterAttributes | number>, opts?: { timeout?: number }): Promise<Partial<MeteringClusterAttributes> & Record<number, unknown>>;
   writeAttributes(attributes: Partial<MeteringClusterAttributes>, opts?: { timeout?: number }): Promise<unknown>;
   on<K extends keyof MeteringClusterAttributes & string>(eventName: `attr.${K}`, listener: (value: MeteringClusterAttributes[K]) => void): this;
@@ -868,7 +850,36 @@ export interface OnOffCluster extends ZCLNodeCluster {
 export interface OnOffSwitchCluster extends ZCLNodeCluster {
 }
 
+export interface OTAClusterAttributes {
+  upgradeServerID?: string;
+  fileOffset?: number;
+  currentFileVersion?: number;
+  currentZigBeeStackVersion?: number;
+  downloadedFileVersion?: number;
+  downloadedZigBeeStackVersion?: number;
+  imageUpgradeStatus?: 'normal' | 'downloadInProgress' | 'downloadComplete' | 'waitingToUpgrade' | 'countDown' | 'waitForMore' | 'waitingToUpgradeViaExternalEvent';
+  manufacturerID?: number;
+  imageTypeID?: number;
+  minimumBlockPeriod?: number;
+  imageStamp?: number;
+  upgradeActivationPolicy?: 'otaServerActivationAllowed' | 'outOfBandActivationOnly';
+  upgradeTimeoutPolicy?: 'applyUpgradeAfterTimeout' | 'doNotApplyUpgradeAfterTimeout';
+}
+
 export interface OTACluster extends ZCLNodeCluster {
+  readAttributes<K extends 'upgradeServerID' | 'fileOffset' | 'currentFileVersion' | 'currentZigBeeStackVersion' | 'downloadedFileVersion' | 'downloadedZigBeeStackVersion' | 'imageUpgradeStatus' | 'manufacturerID' | 'imageTypeID' | 'minimumBlockPeriod' | 'imageStamp' | 'upgradeActivationPolicy' | 'upgradeTimeoutPolicy'>(attributeNames: K[], opts?: { timeout?: number }): Promise<Pick<OTAClusterAttributes, K>>;
+  readAttributes(attributeNames: Array<keyof OTAClusterAttributes | number>, opts?: { timeout?: number }): Promise<Partial<OTAClusterAttributes> & Record<number, unknown>>;
+  writeAttributes(attributes: Partial<OTAClusterAttributes>, opts?: { timeout?: number }): Promise<unknown>;
+  on<K extends keyof OTAClusterAttributes & string>(eventName: `attr.${K}`, listener: (value: OTAClusterAttributes[K]) => void): this;
+  once<K extends keyof OTAClusterAttributes & string>(eventName: `attr.${K}`, listener: (value: OTAClusterAttributes[K]) => void): this;
+  imageNotify(args?: { payloadType?: 'queryJitter' | 'queryJitterAndManufacturerCode' | 'queryJitterAndManufacturerCodeAndImageType' | 'queryJitterAndManufacturerCodeAndImageTypeAndNewFileVersion'; queryJitter?: number; manufacturerCode?: number; imageType?: number; newFileVersion?: number }, opts?: ClusterCommandOptions): Promise<void>;
+  queryNextImageRequest(args?: { fieldControl?: Partial<{ hardwareVersionPresent: boolean }>; manufacturerCode?: number; imageType?: number; fileVersion?: number; hardwareVersion?: number }, opts?: ClusterCommandOptions): Promise<{ status?: ZCLEnum8Status; manufacturerCode?: number; imageType?: number; fileVersion?: number; imageSize?: number }>;
+  imageBlockRequest(args?: { fieldControl?: Partial<{ requestNodeAddressPresent: boolean; minimumBlockPeriodPresent: boolean }>; manufacturerCode?: number; imageType?: number; fileVersion?: number; fileOffset?: number; maximumDataSize?: number; requestNodeAddress?: string; minimumBlockPeriod?: number }, opts?: ClusterCommandOptions): Promise<{ status?: ZCLEnum8Status; manufacturerCode?: number; imageType?: number; fileVersion?: number; fileOffset?: number; dataSize?: number; imageData?: Buffer; currentTime?: number; requestTime?: number; minimumBlockPeriod?: number }>;
+  imagePageRequest(args?: { fieldControl?: Partial<{ requestNodeAddressPresent: boolean }>; manufacturerCode?: number; imageType?: number; fileVersion?: number; fileOffset?: number; maximumDataSize?: number; pageSize?: number; responseSpacing?: number; requestNodeAddress?: string }, opts?: ClusterCommandOptions): Promise<{ status?: ZCLEnum8Status; manufacturerCode?: number; imageType?: number; fileVersion?: number; fileOffset?: number; dataSize?: number; imageData?: Buffer; currentTime?: number; requestTime?: number; minimumBlockPeriod?: number }>;
+  imageBlockResponse(args?: { status?: ZCLEnum8Status; manufacturerCode?: number; imageType?: number; fileVersion?: number; fileOffset?: number; dataSize?: number; imageData?: Buffer; currentTime?: number; requestTime?: number; minimumBlockPeriod?: number }, opts?: ClusterCommandOptions): Promise<void>;
+  upgradeEndRequest(args: { status: ZCLEnum8Status; manufacturerCode: number; imageType: number; fileVersion: number }, opts?: ClusterCommandOptions): Promise<{ manufacturerCode: number; imageType: number; fileVersion: number; currentTime: number; upgradeTime: number }>;
+  upgradeEndResponse(args: { manufacturerCode: number; imageType: number; fileVersion: number; currentTime: number; upgradeTime: number }, opts?: ClusterCommandOptions): Promise<void>;
+  queryDeviceSpecificFileRequest(args: { requestNodeAddress: string; manufacturerCode: number; imageType: number; fileVersion: number; zigBeeStackVersion: number }, opts?: ClusterCommandOptions): Promise<{ status?: ZCLEnum8Status; manufacturerCode?: number; imageType?: number; fileVersion?: number; imageSize?: number }>;
 }
 
 export interface PollControlClusterAttributes {
@@ -1185,7 +1196,7 @@ export interface ClusterAttributesByName {
   occupancySensing: OccupancySensingClusterAttributes;
   onOff: OnOffClusterAttributes;
   onOffSwitch: Record<string, unknown>;
-  ota: Record<string, unknown>;
+  ota: OTAClusterAttributes;
   pollControl: PollControlClusterAttributes;
   powerConfiguration: PowerConfigurationClusterAttributes;
   powerProfile: Record<string, unknown>;
@@ -1217,6 +1228,7 @@ export type ZCLNodeEndpoint = {
   clusters: ClusterRegistry & {
     [clusterName: string]: ZCLNodeCluster | undefined;
   };
+  bind(clusterName: string, impl: BoundCluster): void;
 };
 
 export interface ZCLNode {
@@ -1506,6 +1518,14 @@ export const CLUSTER: {
     COMMANDS: unknown;
   };
 };
+export class BoundCluster {
+
+}
+
+export class ZCLError extends Error {
+  zclStatus: ZCLEnum8Status;
+  constructor(zclStatus?: ZCLEnum8Status);
+}
 export const AlarmsCluster: {
   new (...args: any[]): AlarmsCluster;
   ID: 9;

package/index.js

@@ -8,6 +8,7 @@ const Clusters = require('./lib/clusters');
 const BoundCluster = require('./lib/BoundCluster');
 const zclTypes = require('./lib/zclTypes');
 const zclFrames = require('./lib/zclFrames');
+const { ZCLError } = require('./lib/util');
 
 /**
  * Enables or disables debug logging.
@@ -55,6 +56,7 @@ module.exports = {
   ZCLDataTypes,
   ZCLDataType,
   ZCLStruct,
+  ZCLError,
   ...Clusters,
   debug,
   ZIGBEE_PROFILE_ID,

package/lib/BoundCluster.js

@@ -317,7 +317,7 @@ class BoundCluster {
         const result = await this[command.name](args, meta, frame, rawFrame);
         if (command.response && command.response.args) {
           // eslint-disable-next-line new-cap
-          return [command.response.id, new command.response.args(result)];
+          return [command.response.id, new command.response.args(result), command.response];
         }
         // eslint-disable-next-line consistent-return
         return;

package/lib/Cluster.js

@@ -789,7 +789,7 @@ class Cluster extends EventEmitter {
         const response = await handler.call(this, args, meta, frame, rawFrame);
         if (command.response && command.response.args) {
           // eslint-disable-next-line new-cap
-          return [command.response.id, new command.response.args(response)];
+          return [command.response.id, new command.response.args(response), command.response];
         }
         // eslint-disable-next-line consistent-return
         return;
@@ -1027,7 +1027,9 @@ class Cluster extends EventEmitter {
     clusterClass.commandsById = Object.entries(clusterClass.commands).reduce((r, [name, _cmd]) => {
       const cmd = { ..._cmd, name };
       if (cmd.args) {
-        cmd.args = ZCLStruct(`${clusterClass.NAME}.${name}`, cmd.args);
+        cmd.args = ZCLStruct(`${clusterClass.NAME}.${name}`, cmd.args, {
+          encodeMissingFieldsBehavior: cmd.encodeMissingFieldsBehavior,
+        });
         if (_cmd === GLOBAL_COMMANDS.defaultResponse) {
           clusterClass.defaultResponseArgsType = cmd.args;
         }
@@ -1045,7 +1047,9 @@ class Cluster extends EventEmitter {
           res.id = cmd.id;
         }
         if (res.args) {
-          res.args = ZCLStruct(`${clusterClass.NAME}.${res.name}`, res.args);
+          res.args = ZCLStruct(`${clusterClass.NAME}.${res.name}`, res.args, {
+            encodeMissingFieldsBehavior: res.encodeMissingFieldsBehavior,
+          });
         }
         if (cmd.global) res.global = true;
         if (cmd.manufacturerSpecific) res.manufacturerSpecific = true;
@@ -1096,7 +1100,9 @@ class Cluster extends EventEmitter {
             }
 
             if (cmd.args) {
-              const CommandArgs = ZCLStruct(`${this.name}.${cmdName}`, cmd.args);
+              const CommandArgs = ZCLStruct(`${this.name}.${cmdName}`, cmd.args, {
+                encodeMissingFieldsBehavior: cmd.encodeMissingFieldsBehavior,
+              });
               payload.data = new CommandArgs(args);
             }
 

package/lib/Endpoint.js

@@ -7,7 +7,8 @@ const BoundCluster = require('./BoundCluster');
 const { ZCLStandardHeader, ZCLMfgSpecificHeader } = require('./zclFrames');
 
 let { debug } = require('./util');
-const { getLogId } = require('./util');
+const { getLogId, ZCLError } = require('./util');
+const { ZCLDataTypes } = require('./zclTypes');
 
 debug = debug.extend('endpoint');
 
@@ -120,7 +121,10 @@ class Endpoint extends EventEmitter {
 
     // If cluster specific error, respond with a default response error frame
     if (clusterSpecificError) {
-      const defaultResponseErrorFrame = this.makeDefaultResponseFrame(frame, false);
+      const status = clusterSpecificError instanceof ZCLError
+        ? clusterSpecificError.zclStatus : undefined;
+
+      const defaultResponseErrorFrame = this.makeDefaultResponseFrame(frame, false, status);
       this.sendFrame(clusterId, defaultResponseErrorFrame.toBuffer()).catch(err => {
         debug(`${this.getLogId(clusterId)}, error while sending default error response`, err, { response: defaultResponseErrorFrame });
       });
@@ -135,7 +139,10 @@ class Endpoint extends EventEmitter {
     // If a cluster specific response was generated, set the response data
     // and cmdId in the response frame.
     if (clusterSpecificResponse) {
-      const [cmdId, data] = clusterSpecificResponse;
+      const [cmdId, data, cmd] = clusterSpecificResponse;
+      if (!cmd.global) {
+        responseFrame.frameControl.clusterSpecific = true;
+      }
       responseFrame.data = data.toBuffer();
       responseFrame.cmdId = cmdId;
     }
@@ -185,9 +192,10 @@ class Endpoint extends EventEmitter {
    * Returns a default response frame with an error status code.
    * @param {*} receivedFrame
    * @param {boolean} success
+   * @param {string} [status] - Optional ZCL status code to use in the response
    * @returns {ZCLStandardHeader|ZCLMfgSpecificHeader}
    */
-  makeDefaultResponseFrame(receivedFrame, success) {
+  makeDefaultResponseFrame(receivedFrame, success, status) {
     let responseFrame;
     if (receivedFrame instanceof ZCLStandardHeader) {
       responseFrame = new ZCLStandardHeader();
@@ -205,6 +213,19 @@ class Endpoint extends EventEmitter {
     responseFrame.trxSequenceNumber = receivedFrame.trxSequenceNumber;
     responseFrame.cmdId = 0x0B;
     responseFrame.data = Buffer.from([receivedFrame.cmdId, success ? 0 : 1]);
+
+    // If not successful, set the status code in the response frame data
+    // Note that if the status code is invalid, enum8Status.toBuffer will throw an error,
+    // and the default error status will be FAILURE. This also allows overriding the status code
+    // with SUCCESS, which is intentional. The OTA Cluster requires this in some cases.
+    if (!success && typeof status === 'string') {
+      try {
+        ZCLDataTypes.enum8Status.toBuffer(responseFrame.data, status, 1);
+      } catch (err) {
+        // Ignore invalid status codes and keep the default FAILURE status.
+      }
+    }
+
     return responseFrame;
   }
 

package/lib/clusters/metering.js

@@ -33,34 +33,51 @@ const ATTRIBUTES = {
   currentTier4SummationReceived: { id: 0x0107, type: ZCLDataTypes.uint48 }, // 263, Optional
 
   // Meter Status (0x0200 - 0x02FF)
-  status: { id: 0x0200, type: ZCLDataTypes.map8 }, // 512, Optional
+  status: { // 512, Optional
+    id: 0x0200,
+    type: ZCLDataTypes.map8(
+      'checkMeter',
+      'lowBattery',
+      'tamperDetect',
+      'powerFailure',
+      'powerQuality',
+      'leakDetect',
+      'serviceDisconnect',
+    ),
+  },
   remainingBatteryLife: { id: 0x0201, type: ZCLDataTypes.uint8 }, // 513, Optional
   hoursInOperation: { id: 0x0202, type: ZCLDataTypes.uint24 }, // 514, Optional
   hoursInFault: { id: 0x0203, type: ZCLDataTypes.uint24 }, // 515, Optional
-  extendedStatus: { id: 0x0204, type: ZCLDataTypes.map64 }, // 516, Optional
+  // TODO: map64 bitmap with general flags (bits 0-13) and meter-type-specific flags (bits 24+)
+  // extendedStatus: { id: 0x0204, type: ZCLDataTypes.map64() }, // 516, Optional
 
   // Formatting Set (0x0300 - 0x03FF)
   unitOfMeasure: { id: 0x0300, type: ZCLDataTypes.enum8 }, // 768, Mandatory
   multiplier: { id: 0x0301, type: ZCLDataTypes.uint24 }, // 769, Optional
   divisor: { id: 0x0302, type: ZCLDataTypes.uint24 }, // 770, Optional
-  summationFormatting: { id: 0x0303, type: ZCLDataTypes.map8 }, // 771, Mandatory
-  demandFormatting: { id: 0x0304, type: ZCLDataTypes.map8 }, // 772, Optional
-  historicalConsumptionFormatting: { id: 0x0305, type: ZCLDataTypes.map8 }, // 773, Optional
-  meteringDeviceType: { id: 0x0306, type: ZCLDataTypes.map8 }, // 774, Mandatory
+  // TODO: map8 packed fields — bits 0-2: right digits, 3-6: left digits, 7: suppress zeros
+  // summationFormatting: { id: 0x0303, type: ZCLDataTypes.map8() }, // 771, Mandatory
+  // demandFormatting: { id: 0x0304, type: ZCLDataTypes.map8() }, // 772, Optional
+  // historicalConsumptionFormatting: { id: 0x0305, type: ZCLDataTypes.map8() }, // 773, Optional
+  // TODO: ZCL spec says enum values, but wire type is map8 for backwards compat
+  // meteringDeviceType: { id: 0x0306, type: ZCLDataTypes.map8() }, // 774, Mandatory
   siteId: { id: 0x0307, type: ZCLDataTypes.octstr }, // 775, Optional
   meterSerialNumber: { id: 0x0308, type: ZCLDataTypes.octstr }, // 776, Optional
   energyCarrierUnitOfMeasure: { id: 0x0309, type: ZCLDataTypes.enum8 }, // 777, Optional
-  energyCarrierSummationFormatting: { id: 0x030A, type: ZCLDataTypes.map8 }, // 778, Optional
-  energyCarrierDemandFormatting: { id: 0x030B, type: ZCLDataTypes.map8 }, // 779, Optional
+  // TODO: map8 packed fields — bits 0-2: right digits, 3-6: left digits, 7: suppress zeros
+  // energyCarrierSummationFormatting: { id: 0x030A, type: ZCLDataTypes.map8() }, // 778, Optional
+  // energyCarrierDemandFormatting: { id: 0x030B, type: ZCLDataTypes.map8() }, // 779, Optional
   temperatureUnitOfMeasure: { id: 0x030C, type: ZCLDataTypes.enum8 }, // 780, Optional
-  temperatureFormatting: { id: 0x030D, type: ZCLDataTypes.map8 }, // 781, Optional
+  // TODO: map8 packed fields — bits 0-2: right digits, 3-6: left digits, 7: suppress zeros
+  // temperatureFormatting: { id: 0x030D, type: ZCLDataTypes.map8() }, // 781, Optional
   moduleSerialNumber: { id: 0x030E, type: ZCLDataTypes.octstr }, // 782, Optional
   operatingTariffLabelDelivered: { id: 0x030F, type: ZCLDataTypes.octstr }, // 783, Optional
   operatingTariffLabelReceived: { id: 0x0310, type: ZCLDataTypes.octstr }, // 784, Optional
   customerIdNumber: { id: 0x0311, type: ZCLDataTypes.octstr }, // 785, Optional
   alternativeUnitOfMeasure: { id: 0x0312, type: ZCLDataTypes.enum8 }, // 786, Optional
-  alternativeDemandFormatting: { id: 0x0313, type: ZCLDataTypes.map8 }, // 787, Optional
-  alternativeConsumptionFormatting: { id: 0x0314, type: ZCLDataTypes.map8 }, // 788, Optional
+  // TODO: map8 packed fields — bits 0-2: right digits, 3-6: left digits, 7: suppress zeros
+  // alternativeDemandFormatting: { id: 0x0313, type: ZCLDataTypes.map8() }, // 787, Optional
+  // alternativeConsumptionFormatting: { id: 0x0314, type: ZCLDataTypes.map8() }, // 788, Optional
 
   // Historical Consumption (0x0400 - 0x04FF)
   instantaneousDemand: { id: 0x0400, type: ZCLDataTypes.int24 }, // 1024, Optional
@@ -193,14 +210,15 @@ const ATTRIBUTES = {
   currentTier4Block16SummationDelivered: { id: 0x074F, type: ZCLDataTypes.uint48 },
 
   // Alarms (0x0800 - 0x08FF)
-  genericAlarmMask: { id: 0x0800, type: ZCLDataTypes.map16 }, // 2048, Optional
-  electricityAlarmMask: { id: 0x0801, type: ZCLDataTypes.map32 }, // 2049, Optional
-  genericFlowPressureAlarmMask: { id: 0x0802, type: ZCLDataTypes.map16 }, // 2050, Optional
-  waterSpecificAlarmMask: { id: 0x0803, type: ZCLDataTypes.map16 }, // 2051, Optional
-  heatAndCoolingSpecificAlarmMask: { id: 0x0804, type: ZCLDataTypes.map16 }, // 2052, Optional
-  gasSpecificAlarmMask: { id: 0x0805, type: ZCLDataTypes.map16 }, // 2053, Optional
-  extendedGenericAlarmMask: { id: 0x0806, type: ZCLDataTypes.map48 }, // 2054, Optional
-  manufacturerAlarmMask: { id: 0x0807, type: ZCLDataTypes.map16 }, // 2055, Optional
+  // TODO: map16/32/48 alarm masks — bits map to alarm codes in their group (spec 10.4.2.2.9.1)
+  // genericAlarmMask: { id: 0x0800, type: ZCLDataTypes.map16() }, // 2048, Optional
+  // electricityAlarmMask: { id: 0x0801, type: ZCLDataTypes.map32() }, // 2049, Optional
+  // genericFlowPressureAlarmMask: { id: 0x0802, type: ZCLDataTypes.map16() }, // 2050, Optional
+  // waterSpecificAlarmMask: { id: 0x0803, type: ZCLDataTypes.map16() }, // 2051, Optional
+  // heatAndCoolingSpecificAlarmMask: { id: 0x0804, type: ZCLDataTypes.map16() }, // 2052, Optional
+  // gasSpecificAlarmMask: { id: 0x0805, type: ZCLDataTypes.map16() }, // 2053, Optional
+  // extendedGenericAlarmMask: { id: 0x0806, type: ZCLDataTypes.map48() }, // 2054, Optional
+  // manufacturerAlarmMask: { id: 0x0807, type: ZCLDataTypes.map16() }, // 2055, Optional
 
   // Block Information Received (0x0900 - 0x09FF)
   // All attributes in this section are Optional
@@ -226,12 +244,14 @@ const ATTRIBUTES = {
   billToDateTimeStampDelivered: { id: 0x0A01, type: ZCLDataTypes.uint32 }, // 2561, Optional
   projectedBillDelivered: { id: 0x0A02, type: ZCLDataTypes.uint32 }, // 2562, Optional
   projectedBillTimeStampDelivered: { id: 0x0A03, type: ZCLDataTypes.uint32 }, // 2563, Optional
-  billDeliveredTrailingDigit: { id: 0x0A04, type: ZCLDataTypes.map8 }, // 2564, Optional
+  // TODO: map8 packed field — most significant nibble = digits right of decimal
+  // billDeliveredTrailingDigit: { id: 0x0A04, type: ZCLDataTypes.map8() }, // 2564, Optional
   billToDateReceived: { id: 0x0A10, type: ZCLDataTypes.uint32 }, // 2576, Optional
   billToDateTimeStampReceived: { id: 0x0A11, type: ZCLDataTypes.uint32 }, // 2577, Optional
   projectedBillReceived: { id: 0x0A12, type: ZCLDataTypes.uint32 }, // 2578, Optional
   projectedBillTimeStampReceived: { id: 0x0A13, type: ZCLDataTypes.uint32 }, // 2579, Optional
-  billReceivedTrailingDigit: { id: 0x0A14, type: ZCLDataTypes.map8 }, // 2580, Optional
+  // TODO: map8 packed field — most significant nibble = digits right of decimal
+  // billReceivedTrailingDigit: { id: 0x0A14, type: ZCLDataTypes.map8() }, // 2580, Optional
 
   // Supply Control (0x0B00 - 0x0BFF)
   proposedChangeSupplyImplementationTime: { // Optional

package/lib/clusters/ota.js

@@ -1,15 +1,286 @@
 'use strict';
 
 const Cluster = require('../Cluster');
+const { ZCLDataTypes } = require('../zclTypes');
 
-const ATTRIBUTES = {};
+// ============================================================================
+// Server Attributes
+// ============================================================================
+const ATTRIBUTES = {
+  // OTA Upgrade Cluster Attributes (0x0000 - 0x000C)
 
-const COMMANDS = {};
+  // The IEEE address of the upgrade server resulted from the discovery of the
+  // upgrade server's identity. If the value is set to a non-zero value and
+  // corresponds to an IEEE address of a device that is no longer accessible, a
+  // device MAY choose to discover a new Upgrade Server depending on its own
+  // security policies.
+  upgradeServerID: { id: 0x0000, type: ZCLDataTypes.EUI64 }, // Mandatory
+
+  // The parameter indicates the current location in the OTA upgrade image. It is
+  // essentially the (start of the) address of the image data that is being
+  // transferred from the OTA server to the client.
+  fileOffset: { id: 0x0001, type: ZCLDataTypes.uint32 }, // Optional
+
+  // The file version of the running firmware image on the device.
+  currentFileVersion: { id: 0x0002, type: ZCLDataTypes.uint32 }, // Optional
+
+  // The ZigBee stack version of the running image on the device.
+  currentZigBeeStackVersion: { id: 0x0003, type: ZCLDataTypes.uint16 }, // Optional
+
+  // The file version of the downloaded image on additional memory space on the
+  // device.
+  downloadedFileVersion: { id: 0x0004, type: ZCLDataTypes.uint32 }, // Optional
+
+  // The ZigBee stack version of the downloaded image on additional memory space
+  // on the device.
+  downloadedZigBeeStackVersion: { id: 0x0005, type: ZCLDataTypes.uint16 }, // Optional
+
+  // The upgrade status of the client device. The status indicates where the client
+  // device is at in terms of the download and upgrade process.
+  imageUpgradeStatus: { // Mandatory
+    id: 0x0006,
+    type: ZCLDataTypes.enum8({
+      normal: 0x00,
+      downloadInProgress: 0x01,
+      downloadComplete: 0x02,
+      waitingToUpgrade: 0x03,
+      countDown: 0x04,
+      waitForMore: 0x05,
+      waitingToUpgradeViaExternalEvent: 0x06,
+    }),
+  },
+
+  // The ZigBee assigned value for the manufacturer of the device.
+  manufacturerID: { id: 0x0007, type: ZCLDataTypes.uint16 }, // Optional
+
+  // The image type identifier of the file that the client is currently downloading,
+  // or a file that has been completely downloaded but not upgraded to yet.
+  imageTypeID: { id: 0x0008, type: ZCLDataTypes.uint16 }, // Optional
+
+  // This attribute acts as a rate limiting feature for the server to slow down the
+  // client download and prevent saturating the network with block requests. The
+  // value is in milliseconds.
+  minimumBlockPeriod: { id: 0x0009, type: ZCLDataTypes.uint16 }, // Optional
+
+  // A 32 bit value used as a second verification to identify the image. The value
+  // must be consistent during the lifetime of the same image and unique for each
+  // different build of the image.
+  imageStamp: { id: 0x000A, type: ZCLDataTypes.uint32 }, // 10, Optional
+
+  // Indicates what behavior the client device supports for activating a fully
+  // downloaded but not installed upgrade image.
+  upgradeActivationPolicy: { // Optional
+    id: 0x000B, // 11
+    type: ZCLDataTypes.enum8({
+      otaServerActivationAllowed: 0x00,
+      outOfBandActivationOnly: 0x01,
+    }),
+  },
+
+  // Dictates the behavior of the device in situations where an explicit activation
+  // command cannot be retrieved.
+  upgradeTimeoutPolicy: { // Optional
+    id: 0x000C, // 12
+    type: ZCLDataTypes.enum8({
+      applyUpgradeAfterTimeout: 0x00,
+      doNotApplyUpgradeAfterTimeout: 0x01,
+    }),
+  },
+};
+
+// Response to the Image Block Request or Image Page Request. The payload varies
+// based on the status field.
+const IMAGE_BLOCK_RESPONSE = {
+  id: 0x0005,
+  encodeMissingFieldsBehavior: 'skip',
+  args: {
+    status: ZCLDataTypes.enum8Status,
+    // When status is SUCCESS
+    manufacturerCode: ZCLDataTypes.uint16,
+    imageType: ZCLDataTypes.uint16,
+    fileVersion: ZCLDataTypes.uint32,
+    fileOffset: ZCLDataTypes.uint32,
+    dataSize: ZCLDataTypes.uint8,
+    imageData: ZCLDataTypes.buffer,
+    // When status is WAIT_FOR_DATA
+    currentTime: ZCLDataTypes.uint32,
+    requestTime: ZCLDataTypes.uint32,
+    minimumBlockPeriod: ZCLDataTypes.uint16,
+  },
+};
+
+const UPGRADE_END_RESPONSE = {
+  id: 0x0007,
+  args: {
+    manufacturerCode: ZCLDataTypes.uint16,
+    imageType: ZCLDataTypes.uint16,
+    fileVersion: ZCLDataTypes.uint32,
+    currentTime: ZCLDataTypes.uint32,
+    upgradeTime: ZCLDataTypes.uint32,
+  },
+};
+
+// ============================================================================
+// Commands
+// ============================================================================
+const COMMANDS = {
+  // --- Server to Client Commands ---
+
+  // The purpose of sending Image Notify command is so the server has a way to
+  // notify client devices of when the OTA upgrade images are available for them.
+  imageNotify: { // Optional
+    id: 0x0000,
+    direction: Cluster.DIRECTION_SERVER_TO_CLIENT,
+    encodeMissingFieldsBehavior: 'skip',
+    frameControl: ['directionToClient', 'clusterSpecific', 'disableDefaultResponse'],
+    args: {
+      payloadType: ZCLDataTypes.enum8({
+        queryJitter: 0x00,
+        queryJitterAndManufacturerCode: 0x01,
+        queryJitterAndManufacturerCodeAndImageType: 0x02,
+        queryJitterAndManufacturerCodeAndImageTypeAndNewFileVersion: 0x03,
+      }),
+      queryJitter: ZCLDataTypes.uint8,
+      // Present when payloadType >= 0x01
+      manufacturerCode: ZCLDataTypes.uint16,
+      // Present when payloadType >= 0x02
+      imageType: ZCLDataTypes.uint16,
+      // Present when payloadType >= 0x03
+      newFileVersion: ZCLDataTypes.uint32,
+    },
+  },
+
+  // --- Client to Server Commands ---
+
+  // Client queries the server if new OTA upgrade image is available.
+  queryNextImageRequest: { // Mandatory
+    id: 0x0001,
+    encodeMissingFieldsBehavior: 'skip',
+    args: {
+      fieldControl: ZCLDataTypes.map8('hardwareVersionPresent'),
+      manufacturerCode: ZCLDataTypes.uint16,
+      imageType: ZCLDataTypes.uint16,
+      fileVersion: ZCLDataTypes.uint32,
+      // Present when fieldControl bit 0 is set
+      hardwareVersion: ZCLDataTypes.uint16,
+    },
+    response: {
+      id: 0x0002,
+      encodeMissingFieldsBehavior: 'skip',
+      args: {
+        status: ZCLDataTypes.enum8Status,
+        // Remaining fields only present when status is SUCCESS
+        manufacturerCode: ZCLDataTypes.uint16,
+        imageType: ZCLDataTypes.uint16,
+        fileVersion: ZCLDataTypes.uint32,
+        imageSize: ZCLDataTypes.uint32,
+      },
+    },
+  },
+
+  // Client requests a block of data from the OTA upgrade image.
+  imageBlockRequest: { // Mandatory
+    id: 0x0003,
+    encodeMissingFieldsBehavior: 'skip',
+    args: {
+      fieldControl: ZCLDataTypes.map8(
+        'requestNodeAddressPresent',
+        'minimumBlockPeriodPresent',
+      ),
+      manufacturerCode: ZCLDataTypes.uint16,
+      imageType: ZCLDataTypes.uint16,
+      fileVersion: ZCLDataTypes.uint32,
+      fileOffset: ZCLDataTypes.uint32,
+      maximumDataSize: ZCLDataTypes.uint8,
+      // Present when fieldControl bit 0 is set
+      requestNodeAddress: ZCLDataTypes.EUI64,
+      // Present when fieldControl bit 1 is set
+      minimumBlockPeriod: ZCLDataTypes.uint16,
+    },
+    response: IMAGE_BLOCK_RESPONSE,
+  },
+
+  // Client requests pages of data from the OTA upgrade image. Using Image Page
+  // Request reduces the number of requests sent from the client to the upgrade
+  // server, compared to using Image Block Request command.
+  imagePageRequest: { // Optional
+    id: 0x0004,
+    encodeMissingFieldsBehavior: 'skip',
+    args: {
+      fieldControl: ZCLDataTypes.map8('requestNodeAddressPresent'),
+      manufacturerCode: ZCLDataTypes.uint16,
+      imageType: ZCLDataTypes.uint16,
+      fileVersion: ZCLDataTypes.uint32,
+      fileOffset: ZCLDataTypes.uint32,
+      maximumDataSize: ZCLDataTypes.uint8,
+      pageSize: ZCLDataTypes.uint16,
+      responseSpacing: ZCLDataTypes.uint16,
+      // Present when fieldControl bit 0 is set
+      requestNodeAddress: ZCLDataTypes.EUI64,
+    },
+    response: IMAGE_BLOCK_RESPONSE,
+  },
+
+  imageBlockResponse: { // Mandatory
+    ...IMAGE_BLOCK_RESPONSE,
+    direction: Cluster.DIRECTION_SERVER_TO_CLIENT,
+    frameControl: ['directionToClient', 'clusterSpecific', 'disableDefaultResponse'],
+  },
+
+  // Sent by the client when it has completed downloading an image. The status
+  // value SHALL be SUCCESS, INVALID_IMAGE, REQUIRE_MORE_IMAGE, or ABORT.
+  upgradeEndRequest: { // Mandatory
+    id: 0x0006,
+    args: {
+      status: ZCLDataTypes.enum8Status,
+      manufacturerCode: ZCLDataTypes.uint16,
+      imageType: ZCLDataTypes.uint16,
+      fileVersion: ZCLDataTypes.uint32,
+    },
+    response: UPGRADE_END_RESPONSE,
+  },
+
+  // --- Server to Client Commands ---
+
+  // Response to the Upgrade End Request, indicating when the client should upgrade
+  // to the new image.
+  upgradeEndResponse: { // Mandatory
+    ...UPGRADE_END_RESPONSE,
+    direction: Cluster.DIRECTION_SERVER_TO_CLIENT,
+    frameControl: ['directionToClient', 'clusterSpecific', 'disableDefaultResponse'],
+  },
+
+  // Client requests a device specific file such as security credential,
+  // configuration or log.
+  queryDeviceSpecificFileRequest: { // Optional
+    id: 0x0008,
+    args: {
+      requestNodeAddress: ZCLDataTypes.EUI64,
+      manufacturerCode: ZCLDataTypes.uint16,
+      imageType: ZCLDataTypes.uint16,
+      fileVersion: ZCLDataTypes.uint32,
+      zigBeeStackVersion: ZCLDataTypes.uint16,
+    },
+    response: {
+      id: 0x0009,
+      encodeMissingFieldsBehavior: 'skip',
+      args: {
+        status: ZCLDataTypes.enum8Status,
+        // Remaining fields only present when status is SUCCESS
+        manufacturerCode: ZCLDataTypes.uint16,
+        imageType: ZCLDataTypes.uint16,
+        fileVersion: ZCLDataTypes.uint32,
+        imageSize: ZCLDataTypes.uint32,
+      },
+    },
+  },
+
+};
 
 class OTACluster extends Cluster {
 
   static get ID() {
-    return 25; // 0x19
+    return 0x0019; // 25
   }
 
   static get NAME() {

package/lib/util/index.js

@@ -21,8 +21,18 @@ function getLogId(endpointId, clusterName, clusterId) {
   return `ep: ${endpointId}, cl: ${clusterName} (${clusterId})`;
 }
 
+class ZCLError extends Error {
+
+  constructor(zclStatus = 'FAILURE') {
+    super(`ZCL Error: ${zclStatus}`);
+    this.zclStatus = zclStatus;
+  }
+
+}
+
 module.exports = {
   debug,
   getLogId,
   getPropertyDescriptor,
+  ZCLError,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zigbee-clusters",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "description": "Zigbee Cluster Library for Node.js",
   "main": "index.js",
   "types": "index.d.ts",
@@ -47,7 +47,7 @@
     "watch": "^1.0.2"
   },
   "dependencies": {
-    "@athombv/data-types": "^1.1.3",
+    "@athombv/data-types": "^1.2.0",
     "debug": "^4.1.1"
   }
 }

package/scripts/generate-types.js

@@ -9,6 +9,7 @@
 
 const fs = require('fs');
 const path = require('path');
+const { ZCLDataTypes } = require('../lib/zclTypes');
 
 const OUTPUT_FILE = path.join(__dirname, '../index.d.ts');
 
@@ -17,7 +18,7 @@ const OUTPUT_FILE = path.join(__dirname, '../index.d.ts');
  * @param {object} dataType - ZCLDataType object with shortName and args
  * @returns {string} TypeScript type string
  */
-function zclTypeToTS(dataType) {
+function zclTypeToTS(dataType, useEnum8StatusType = true) {
   if (!dataType || !dataType.shortName) return 'unknown';
 
   const { shortName, args } = dataType;
@@ -49,6 +50,10 @@ function zclTypeToTS(dataType) {
     return 'Buffer';
   }
 
+  if (dataType === ZCLDataTypes.enum8Status && useEnum8StatusType) {
+    return 'ZCLEnum8Status';
+  }
+
   // Enum types - extract keys from args[0]
   if (/^enum(4|8|16|32)$/.test(shortName)) {
     if (args && args[0] && typeof args[0] === 'object') {
@@ -111,6 +116,8 @@ function parseCluster(ClusterClass, exportName) {
   for (const [name, def] of Object.entries(cmds)) {
     const cmdArgs = [];
     const responseArgs = [];
+    const cmdArgsOptional = def && def.encodeMissingFieldsBehavior === 'skip';
+    const responseArgsOptional = def && def.response && def.response.encodeMissingFieldsBehavior === 'skip';
     if (def && def.args) {
       for (const [argName, argType] of Object.entries(def.args)) {
         cmdArgs.push({
@@ -128,7 +135,9 @@ function parseCluster(ClusterClass, exportName) {
         });
       }
     }
-    commands.push({ name, args: cmdArgs, responseArgs });
+    commands.push({
+      name, args: cmdArgs, responseArgs, cmdArgsOptional, responseArgsOptional,
+    });
   }
 
   return {
@@ -188,13 +197,14 @@ function generateClusterInterface(cluster) {
     // Determine return type based on response args
     let returnType = 'void';
     if (cmd.responseArgs && cmd.responseArgs.length > 0) {
-      returnType = `{ ${cmd.responseArgs.map(a => `${a.name}: ${a.tsType}`).join('; ')} }`;
+      const sep = cmd.responseArgsOptional ? '?: ' : ': ';
+      returnType = `{ ${cmd.responseArgs.map(a => `${a.name}${sep}${a.tsType}`).join('; ')} }`;
     }
 
     if (cmd.args.length > 0) {
-      // Buffer arguments are optional - ZCL allows empty octet strings
-      const allArgsOptional = cmd.args.every(a => a.tsType === 'Buffer');
-      const argsType = `{ ${cmd.args.map(a => `${a.name}${a.tsType === 'Buffer' ? '?' : ''}: ${a.tsType}`).join('; ')} }`;
+      // Args are optional when encodeMissingFieldsBehavior is 'skip', or when all args are Buffers
+      const allArgsOptional = cmd.cmdArgsOptional || cmd.args.every(a => a.tsType === 'Buffer');
+      const argsType = `{ ${cmd.args.map(a => `${a.name}${(cmd.cmdArgsOptional || a.tsType === 'Buffer') ? '?' : ''}: ${a.tsType}`).join('; ')} }`;
       // If all args are optional, make the entire args object optional
       lines.push(`  ${cmd.name}(args${allArgsOptional ? '?' : ''}: ${argsType}, opts?: ClusterCommandOptions): Promise<${returnType}>;`);
     } else {
@@ -270,6 +280,8 @@ type ZCLNodeConstructorInput = {
     meta?: unknown
   ) => Promise<void>;
 };
+
+type ZCLEnum8Status = ${zclTypeToTS(ZCLDataTypes.enum8Status, false)};
 `);
 
   // Base ZCLNodeCluster interface
@@ -372,6 +384,7 @@ type ZCLNodeConstructorInput = {
   clusters: ClusterRegistry & {
     [clusterName: string]: ZCLNodeCluster | undefined;
   };
+  bind(clusterName: string, impl: BoundCluster): void;
 };
 
 export interface ZCLNode {
@@ -402,6 +415,15 @@ export const CLUSTER: {
   }
   lines.push('};');
 
+  lines.push(`export class BoundCluster {
+
+}
+
+export class ZCLError extends Error {
+  zclStatus: ZCLEnum8Status;
+  constructor(zclStatus?: ZCLEnum8Status);
+}`);
+
   // Export all cluster classes
   for (const cluster of clusters) {
     const interfaceName = toInterfaceName(cluster);