zigbee-clusters 1.6.0 → 1.7.0

package/README.md

@@ -17,7 +17,7 @@ Make sure to take a look at the API documentation: [https://athombv.github.io/no
 
 A Zigbee cluster is an abstraction on top of the Zigbee protocol which allows implementing functionality for many types of devices. A list of all available clusters can be found in the Zigbee Cluster Library Specification [section 2.2.](https://etc.athom.com/zigbee_cluster_specification.pdf). If you are familiar with Z-Wave Command Classes, Zigbee clusters are very similar.
 
-### Cluster hierachy
+### Cluster hierarchy
 
 It is important to understand the structure of a Zigbee node:
 [![](https://mermaid.ink/img/eyJjb2RlIjoiZ3JhcGggVERcbiAgQVtOb2RlXSAtLT4gQihFbmRwb2ludCAxKVxuICBBIC0tPiBEKEVuZHBvaW50IC4uLilcbiAgQiAtLT4gRShDbHVzdGVyIE9uT2ZmKVxuICBCIC0tPiBGKENsdXN0ZXIgTGV2ZWxDb250cm9sKVxuICBCIC0tPiBHKENsdXN0ZXIgLi4uKVxuICBFIC0tPiBIKENvbW1hbmQgJ3RvZ2dsZScpXG4gIEUgLS0-IEkoQ29tbWFuZCAnc2V0T24nKVxuICBFIC0tPiBKKEF0dHJpYnV0ZSAnb25PZmYnKSIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)](https://mermaid-js.github.io/mermaid-live-editor/#/edit/eyJjb2RlIjoiZ3JhcGggVERcbiAgQVtOb2RlXSAtLT4gQihFbmRwb2ludCAxKVxuICBBIC0tPiBEKEVuZHBvaW50IC4uLilcbiAgQiAtLT4gRShDbHVzdGVyIE9uT2ZmKVxuICBCIC0tPiBGKENsdXN0ZXIgTGV2ZWxDb250cm9sKVxuICBCIC0tPiBHKENsdXN0ZXIgLi4uKVxuICBFIC0tPiBIKENvbW1hbmQgJ3RvZ2dsZScpXG4gIEUgLS0-IEkoQ29tbWFuZCAnc2V0T24nKVxuICBFIC0tPiBKKEF0dHJpYnV0ZSAnb25PZmYnKSIsIm1lcm1haWQiOnsidGhlbWUiOiJkZWZhdWx0In0sInVwZGF0ZUVkaXRvciI6ZmFsc2V9)
@@ -30,7 +30,7 @@ A cluster can be implemented in two ways:
 From the Zigbee Cluster Library Specification "Typically, the entity that stores the attributes of a cluster is referred to as the server of that cluster and an entity that affects or manipulates those attributes is referred to as the client of that cluster." More information on this can be found in the Zigbee Cluster Library Specification [section 2.2.2.](https://etc.athom.com/zigbee_cluster_specification.pdf).
 
 ### Bindings and bound clusters
-The concept of server/client is important for the following reason. Nodes can be receivers of commands (i.e. servers), or senders of commands (i.e. clients), and sometimes both. An example on how to send a command to a node can be found [below](#basic-communication-with-node). Receiving commands from a node requires a binding to be made from the controller to the cluster on the node, and the implementation of a `BoundCluster` to receive and handle the incoming commands. For an example on implementing a `BoundCluster` see [below](#implementing-a-bound-cluster).
+The concept of server/client is important for the following reason. Nodes can be receivers of commands (i.e. servers), or senders of commands (i.e. clients), and sometimes both. An example on how to send a command to a node can be found [below](#basic-communication-with-node). Receiving commands from a node requires a binding to be made from the controller to the cluster on the node, and the implementation of a `BoundCluster` (i.e. server cluster) to receive and handle the incoming commands. For an example on implementing a `BoundCluster` see [below](#implementing-a-bound-cluster).
 
 ## Usage
 
@@ -124,8 +124,10 @@ const COMMANDS = {
   toggle: { id: 2 },
   onWithTimedOff: {
     id: 66,
+    // Optional property that can be used to implement two commands with the same id but different directions. Both commands must have a direction property in that case. See lib/clusters/iasZone.js as example.
+    // direction: Cluster.DIRECTION_SERVER_TO_CLIENT
     args: {
-      onOffControl: ZCLDataTypes.uint8, // Use the `ZCLDataTypes` object to specifiy types
+      onOffControl: ZCLDataTypes.uint8, // Use the `ZCLDataTypes` object to specify types
       onTime: ZCLDataTypes.uint16,
       offWaitTime: ZCLDataTypes.uint16,
     },

package/index.d.ts

@@ -1,30 +1,35 @@
 type EndpointDescriptor = {
-    endpointId: number;
-    inputClusters: number[];
-    outputClusters: number[];
+  endpointId: number;
+  inputClusters: number[];
+  outputClusters: number[];
 };
 
 type ConstructorOptions = {
-    endpointDescriptors: EndpointDescriptor[];
-    sendFrame: (endpointId: number, clusterId: number, frame: Buffer) => Promise<void>;
+  endpointDescriptors: EndpointDescriptor[];
+  sendFrame: (endpointId: number, clusterId: number, frame: Buffer) => Promise<void>;
 };
 type ZCLNodeCluster = {
-    readAttributes: (...args: string[]) => Promise<void>;
+  readAttributes: (...args: string[]) => Promise<void>;
 };
 type ZCLNodeEndpoint = {
-    clusters: { [clusterName: string]: ZCLNodeCluster };
+  clusters: { [clusterName: string]: ZCLNodeCluster };
 };
 
+interface ZCLNode {
+  endpoints: { [endpointId: number]: ZCLNodeEndpoint };
+  handleFrame: (
+    endpointId: number,
+    clusterId: number,
+    frame: Buffer,
+    meta?: unknown
+  ) => Promise<void>;
+}
+
 declare module "zigbee-clusters" {
-    export class ZCLNode {
-        constructor(options: ConstructorOptions);
-        endpoints: { [endpointId: number]: ZCLNodeEndpoint };
-        handleFrame: (
-        endpointId: number,
-        clusterId: number,
-        frame: Buffer,
-        meta?: unknown
-        ) => Promise<void>;
-    }
-    export const CLUSTER: { [key: string]: {ID: number, NAME: string, ATTRIBUTES: any, COMMANDS: any} };
-}
+  export var ZCLNode: {
+    new (options: ConstructorOptions): ZCLNode;
+  };
+  export const CLUSTER: {
+    [key: string]: { ID: number; NAME: string; ATTRIBUTES: any; COMMANDS: any };
+  };
+}

package/lib/BoundCluster.js

@@ -3,6 +3,7 @@
 let { debug } = require('./util');
 const { ZCLDataType } = require('./zclTypes');
 const { getLogId, getPropertyDescriptor } = require('./util');
+const Cluster = require('./Cluster');
 
 debug = debug.extend('bound-cluster');
 
@@ -277,11 +278,32 @@ class BoundCluster {
   async handleFrame(frame, meta, rawFrame) {
     const commands = this.cluster.commandsById[frame.cmdId] || [];
 
-    const command = commands
+    let filteredCommands = commands
       .filter(cmd => frame.frameControl.clusterSpecific === !cmd.global
         && (cmd.global || frame.frameControl.manufacturerSpecific === !!cmd.manufacturerId)
         && (cmd.global || !frame.frameControl.manufacturerSpecific
-          || frame.manufacturerId === cmd.manufacturerId))
+          || frame.manufacturerId === cmd.manufacturerId));
+
+    // Try to filter based on frame direction, note: this is optional as a cluster command
+    // does not always have a 'direction' property. The filter ensure that multiple commands
+    // can share the same command id. If so, it is required to add the direction property
+    // to both command definitions (see iasZone.js as an example). Cluster.js only receives
+    // frames with directionToClient=true. BoundCluster.js receives frames with
+    // directionToClient=false.
+    filteredCommands = filteredCommands.filter(command => {
+      // Only filter commands that have a direction string property
+      if (typeof command.direction === 'string') {
+        // Filter out commands marked as DIRECTION_SERVER_TO_CLIENT when
+        // frameControl.directionToClient = false
+        if (frame.frameControl.directionToClient === false
+          && command.direction === Cluster.DIRECTION_SERVER_TO_CLIENT) {
+          return false;
+        }
+      }
+      return true;
+    });
+
+    const command = filteredCommands
       .sort((a, b) => (a.isResponse ? 0 : 1) - (b.isResponse ? 0 : 1))
       .pop();
 

package/lib/Cluster.js

@@ -304,6 +304,15 @@ class Cluster extends EventEmitter {
     return this.prototype === Cluster.prototype ? GLOBAL_COMMANDS : {};
   }
 
+  /**
+   * Constants that refer to the direction of a frame. The direction of a frame
+   * is read from the frameControl property in the ZCL header. Usually a client cluster
+   * sends commands to a server cluster (the cluster holding the attribute values), but
+   * this can also be the other way around.
+   */
+  static DIRECTION_SERVER_TO_CLIENT = 'DIRECTION_SERVER_TO_CLIENT';
+  static DIRECTION_CLIENT_TO_SERVER = 'DIRECTION_CLIENT_TO_SERVER';
+
   /**
    * Returns log id string for this cluster.
    * @returns {string}
@@ -691,11 +700,34 @@ class Cluster extends EventEmitter {
   async handleFrame(frame, meta, rawFrame) {
     const commands = this.constructor.commandsById[frame.cmdId] || [];
 
-    // Determine correct command
-    const command = commands.filter(cmd => frame.frameControl.clusterSpecific === !cmd.global
+    // Filter commands of this cluster based on cluster specific vs global,
+    // and manufacturer specific vs not manufacturer specific.
+    let filteredCommands = commands.filter(cmd => frame.frameControl.clusterSpecific === !cmd.global
       && (cmd.global || frame.frameControl.manufacturerSpecific === !!cmd.manufacturerId)
       && (cmd.global || !frame.frameControl.manufacturerSpecific
-        || frame.manufacturerId === cmd.manufacturerId))
+        || frame.manufacturerId === cmd.manufacturerId));
+
+    // Try to filter based on frame direction, note: this is optional as a cluster command
+    // does not always have a 'direction' property. The filter ensure that multiple commands
+    // can share the same command id. If so, it is required to add the direction property
+    // to both command definitions (see iasZone.js as an example). Cluster.js only receives
+    // frames with directionToClient=true. BoundCluster.js receives frames with
+    // directionToClient=false.
+    filteredCommands = filteredCommands.filter(command => {
+      // Only filter commands that have a direction string property
+      if (typeof command.direction === 'string') {
+        // Filter out commands marked as DIRECTION_CLIENT_TO_SERVER when
+        // frameControl.directionToClient = true
+        if (frame.frameControl.directionToClient
+          && command.direction === Cluster.DIRECTION_CLIENT_TO_SERVER) {
+          return false;
+        }
+      }
+      return true;
+    });
+
+    // Sort and pop the selected command from the array
+    const command = filteredCommands
       .sort((a, b) => (a.isResponse ? 1 : 0) - (b.isResponse ? 1 : 0))
       .pop();
 

package/lib/clusters/iasZone.js

@@ -49,7 +49,9 @@ const ATTRIBUTES = {
 
 const COMMANDS = {
   zoneStatusChangeNotification: {
-    id: 0,
+    id: 0x00,
+    // Add direction property as "zoneEnrollResponse" has same command id.
+    direction: Cluster.DIRECTION_SERVER_TO_CLIENT,
     args: {
       zoneStatus: ZONE_STATUS_DATA_TYPE,
       extendedStatus: ZCLDataTypes.uint8,
@@ -57,6 +59,50 @@ const COMMANDS = {
       delay: ZCLDataTypes.uint16,
     },
   },
+  zoneEnrollResponse: {
+    id: 0x00,
+    // Add direction property as "zoneStatusChangeNotification" has same command id.
+    direction: Cluster.DIRECTION_CLIENT_TO_SERVER,
+    args: {
+      enrollResponseCode: ZCLDataTypes.enum8({
+        success: 0x00,
+        notSupported: 0x01,
+        noEnrollPermit: 0x02,
+        tooManyZones: 0x03,
+      }),
+      zoneId: ZCLDataTypes.uint8,
+    },
+  },
+  zoneEnrollRequest: {
+    id: 0x01,
+    // Add direction property as "initiateNormalOperationMode" has same command id.
+    direction: Cluster.DIRECTION_SERVER_TO_CLIENT,
+    args: {
+      zoneType: ZCLDataTypes.enum16({
+        standard: 0x0000,
+        motionSensor: 0x000d,
+        contactSwitch: 0x0015,
+        fireSensor: 0x0028,
+        waterSensor: 0x002a,
+        carbonMonoxideSensor: 0x002b,
+        personalEmergencyDevice: 0x002c,
+        vibrationMovementSensor: 0x002d,
+        remoteControl: 0x010f,
+        keyFob: 0x0115,
+        keyPad: 0x021d,
+        standardWarningDevice: 0x0225,
+        glassBreakSensor: 0x0226,
+        securityRepeater: 0x0229,
+        invalid: 0xffff,
+      }),
+      manufacturerCode: ZCLDataTypes.uint16,
+    },
+  },
+  initiateNormalOperationMode: {
+    id: 0x01,
+    // Add direction property as "zoneEnrollRequest" has same command id.
+    direction: Cluster.DIRECTION_CLIENT_TO_SERVER,
+  },
 };
 
 class IASZoneCluster extends Cluster {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zigbee-clusters",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Zigbee Cluster Library for Node.js",
   "main": "index.js",
   "types": "index.d.ts",