zigbee-clusters 1.7.3 → 2.0.0

package/README.md

@@ -1,7 +1,7 @@
 # Zigbee Cluster Library for Node.js
 
 This project implements the Zigbee Cluster Library (ZCL) based on the Zigbee Cluster Library
- Specification ([documentation](https://etc.athom.com/zigbee_cluster_specification.pdf)). It is designed to work with Homey's Zigbee stack and can be used in Homey Apps to implement drivers for Zigbee devices that work with Homey.
+Specification ([documentation](https://etc.athom.com/zigbee_cluster_specification.pdf)). It is designed to work with Homey's Zigbee stack and can be used in Homey Apps to implement drivers for Zigbee devices that work with Homey.
 
 Note: if you are looking for the best way to implement Zigbee drivers for Homey take a look at [node-homey-zigbeedriver](https://github.com/athombv/node-homey-zigbeedriver).
 
@@ -13,6 +13,16 @@ Make sure to take a look at the API documentation: [https://athombv.github.io/no
 
 `$ npm install --save zigbee-clusters`
 
+## Breaking changes
+
+v2.0.0
+
+- Changed `Cluster.readAttributes` signature, attributes must now be specified as an array of strings.
+
+```js
+zclNode.endpoints[1].clusters.basic.readAttributes(["modelId", "manufacturerName"]);
+```
+
 ## Release
 
 Merge to production and include `#patch`, `#minor` or `#major` in the PR/commit message. Or merge to production and run the "Deploy" workflow and provide a version bump parameter.
@@ -27,13 +37,16 @@ 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)
 
 ### Client/Server clusters
+
 A cluster can be implemented in two ways:
-* As server
-* As client
+
+- As server
+- As client
 
 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` (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
@@ -43,68 +56,79 @@ In order to communicate with a Zigbee node retrieve a `node` instance from `Mana
 ### Basic communication with node
 
 ## Sending a command
+
 `/drivers/my-driver/device.js`
+
 ```js
-const Homey = require('homey');
-const { ZCLNode, CLUSTER } = require('zigbee-clusters');
+const Homey = require("homey");
+const { ZCLNode, CLUSTER } = require("zigbee-clusters");
 
 class MyDevice extends Homey.Device {
-    onInit() {
-        // Get ZigBeeNode instance from ManagerZigBee
-        this.homey.zigbee.getNode(this)
-          .then(async node => {
-            // Create ZCLNode instance
-            const zclNode = new ZCLNode(node);
-
-            // Send toggle command to onOff cluster on endpoint 1
-            await zclNode.endpoints[1].clusters[CLUSTER.ON_OFF.NAME].toggle();
-
-            // Send moveToLevel command to levelControl cluster on endpoint 1 and don't wait for
-            // the default response confirmation.
-            await zclNode.endpoints[1].clusters[CLUSTER.LEVEL_CONTROL.NAME].moveToLevel({
-              level: 100,
-              transitionTime: 2000
-            }, {
-              // This is an optional flag that disables waiting for a default response from the
-              // receiving node as a confirmation that the command is received and executed.
-              // You should only use this flag if the device does not follow the
-              // Zigbee specification and refuses to send a default response.
-              waitForResponse: true,
-            });
-          });
-    }
+  onInit() {
+    // Get ZigBeeNode instance from ManagerZigBee
+    this.homey.zigbee.getNode(this).then(async (node) => {
+      // Create ZCLNode instance
+      const zclNode = new ZCLNode(node);
+
+      // Send toggle command to onOff cluster on endpoint 1
+      await zclNode.endpoints[1].clusters[CLUSTER.ON_OFF.NAME].toggle();
+
+      // Send moveToLevel command to levelControl cluster on endpoint 1 and don't wait for
+      // the default response confirmation.
+      await zclNode.endpoints[1].clusters[CLUSTER.LEVEL_CONTROL.NAME].moveToLevel(
+        {
+          level: 100,
+          transitionTime: 2000,
+        },
+        {
+          // This is an optional flag that disables waiting for a default response from the
+          // receiving node as a confirmation that the command is received and executed.
+          // You should only use this flag if the device does not follow the
+          // Zigbee specification and refuses to send a default response.
+          waitForResponse: true,
+
+          // This is an optional property that allows for adjusting the response
+          // timeout (25000ms) before the command is considered rejected.
+          timeout: 10000,
+        }
+      );
+    });
+  }
 }
 ```
 
 ## Receiving an attribute report
 
 `/drivers/my-driver/device.js`
+
 ```js
-const Homey = require('homey');
-const { ZCLNode, CLUSTER } = require('zigbee-clusters');
+const Homey = require("homey");
+const { ZCLNode, CLUSTER } = require("zigbee-clusters");
 
 class MyDevice extends Homey.Device {
   onInit() {
     // Get ZigBeeNode instance from ManagerZigBee
-    this.homey.zigbee.getNode(this)
-      .then(async node => {
-        // Create ZCLNode instance
-        const zclNode = new ZCLNode(node);
-
-        // Configure reporting
-        await zclNode.endpoints[1].clusters[CLUSTER.COLOR_CONTROL.NAME].configureReporting({
-          currentSaturation: {
-            minInterval: 0,
-            maxInterval: 300,
-            minChange: 1
-          }
-        });
-
-        // And listen for incoming attribute reports by binding a listener on the cluster
-        zclNode.endpoints[1].clusters[CLUSTER.COLOR_CONTROL.NAME].on('attr.currentSaturation', (currentSaturation) => {
-          // handle reported attribute value
-        });
+    this.homey.zigbee.getNode(this).then(async (node) => {
+      // Create ZCLNode instance
+      const zclNode = new ZCLNode(node);
+
+      // Configure reporting
+      await zclNode.endpoints[1].clusters[CLUSTER.COLOR_CONTROL.NAME].configureReporting({
+        currentSaturation: {
+          minInterval: 0,
+          maxInterval: 300,
+          minChange: 1,
+        },
       });
+
+      // And listen for incoming attribute reports by binding a listener on the cluster
+      zclNode.endpoints[1].clusters[CLUSTER.COLOR_CONTROL.NAME].on(
+        "attr.currentSaturation",
+        (currentSaturation) => {
+          // handle reported attribute value
+        }
+      );
+    });
   }
 }
 ```
@@ -112,11 +136,12 @@ class MyDevice extends Homey.Device {
 ### Implementing a cluster
 
 It is very easy to add support for a new cluster or add commands and/or attributes to an existing
- cluster. All implemented clusters are listed in [lib/clusters/index.js](https://github.com/athombv/node-zigbee-clusters/blob/production/lib/clusters/index.js). It also exports a constant `CLUSTER` object for easy reference to a specific cluster name and/or id (e.g. `CLUSTER.WINDOW_COVERING` -> `{NAME: "windowCovering", ID: 258})`.
+cluster. All implemented clusters are listed in [lib/clusters/index.js](https://github.com/athombv/node-zigbee-clusters/blob/production/lib/clusters/index.js). It also exports a constant `CLUSTER` object for easy reference to a specific cluster name and/or id (e.g. `CLUSTER.WINDOW_COVERING` -> `{NAME: "windowCovering", ID: 258})`.
 
 This example shows in a simplified way how the OnOff cluster is implemented ([actual implementation](https://github.com/athombv/node-zigbee-clusters/blob/production/lib/clusters/onOff.js)). All the information with regard to the ids, names, available attributes and commands can be found in the Zigbee Cluster Library Specification [section 3.8.](https://etc.athom.com/zigbee_cluster_specification.pdf):
 
 `zigbee-clusters/lib/clusters/onOff.js`
+
 ```js
 // Define the cluster attributes
 const ATTRIBUTES = {
@@ -140,13 +165,12 @@ const COMMANDS = {
 
 // Implement the OnOff cluster by extending `Cluster`
 class OnOffCluster extends Cluster {
-
   static get ID() {
     return 6; // The cluster id
   }
 
   static get NAME() {
-    return 'onOff'; // The cluster name
+    return "onOff"; // The cluster name
   }
 
   static get ATTRIBUTES() {
@@ -156,32 +180,32 @@ class OnOffCluster extends Cluster {
   static get COMMANDS() {
     return COMMANDS; // Returns the defined commands
   }
-
 }
 
 // Add the cluster to the clusters that will be available on the `ZCLNode`
 Cluster.addCluster(OnOffCluster);
 
 module.exports = OnOffCluster;
-
 ```
 
 After a cluster is implemented it can be used on a `ZCLNode` instance like this:
+
 ```
 await zclNode.endpoints[1].clusters[CLUSTER.ON_OFF.NAME].toggle();
 ```
-Note that `CLUSTER.ON_OFF.NAME` is just a string that refers to `onOff` in `zigbee-clusters/lib/clusters/onOff.js`
 
+Note that `CLUSTER.ON_OFF.NAME` is just a string that refers to `onOff` in `zigbee-clusters/lib/clusters/onOff.js`
 
 ### Implementing a bound cluster
+
 Zigbee nodes can send commands to Homey via bound clusters. This requires a binding to be created on a specific endpoint and cluster. Next, a `BoundCluster` implementation must be registered with the `ZCLNode` which implements handlers for the incomming commands:
 
 `/lib/LevelControlBoundCluster.js`
+
 ```js
-const { BoundCluster } = require('zigbee-clusters');
+const { BoundCluster } = require("zigbee-clusters");
 
 class LevelControlBoundCluster extends BoundCluster {
-
   constructor({ onMove }) {
     super();
     this._onMove = onMove;
@@ -197,30 +221,34 @@ class LevelControlBoundCluster extends BoundCluster {
 }
 
 module.exports = LevelControlBoundCluster;
-
 ```
+
 `/drivers/my-driver/device.js`
 
 ```js
-const LevelControlBoundCluster = require('../../lib/LevelControlBoundCluster');
+const LevelControlBoundCluster = require("../../lib/LevelControlBoundCluster");
 
 // Register the `BoundCluster` implementation with the `ZCLNode`
-zclNode.endpoints[1].bind(CLUSTER.LEVEL_CONTROL.NAME, new LevelControlBoundCluster({
-  onMove: (payload) => {
-    // Do something with the received payload
-  },
-}));
+zclNode.endpoints[1].bind(
+  CLUSTER.LEVEL_CONTROL.NAME,
+  new LevelControlBoundCluster({
+    onMove: (payload) => {
+      // Do something with the received payload
+    },
+  })
+);
 ```
 
 ### Implementing a custom cluster
+
 There are cases where it is required to implement a custom cluster, for example to handle manufacturer specific cluster implementations. Often these manufacturer specific cluster implementations are extensions of existing clusters. An example is the `IkeaSpecificSceneCluster` ([complete implementation](https://github.com/athombv/com.ikea.tradfri-example/tree/master/lib/IkeaSpecificSceneCluster.js)):
 
 `lib/IkeaSpecificSceneCluster.js`
+
 ```js
-const { ScenesCluster, ZCLDataTypes } = require('zigbee-clusters');
+const { ScenesCluster, ZCLDataTypes } = require("zigbee-clusters");
 
 class IkeaSpecificSceneCluster extends ScenesCluster {
-
   // Here we override the `COMMANDS` getter from the `ScenesClusters` by
   // extending it with the custom command we'd like to implement `ikeaSceneMove`.
   static get COMMANDS() {
@@ -228,7 +256,7 @@ class IkeaSpecificSceneCluster extends ScenesCluster {
       ...super.COMMANDS,
       ikeaSceneMove: {
         id: 0x08,
-        manufacturerId: 0x117C,
+        manufacturerId: 0x117c,
         args: {
           mode: ZCLDataTypes.enum8({
             up: 0,
@@ -252,32 +280,30 @@ class IkeaSpecificSceneCluster extends ScenesCluster {
       },
     };
   }
-
 }
 
 module.exports = IkeaSpecificSceneCluster;
-
-
 ```
 
 `/drivers/my-driver/device.js`
+
 ```js
-const IkeaSpecificSceneCluster = require('../../lib/IkeaSpecificSceneCluster');
+const IkeaSpecificSceneCluster = require("../../lib/IkeaSpecificSceneCluster");
 
 // Important: we have created a new `Cluster` instance which needs to be added before
 // it becomes available on any `ZCLNode` instance.
 Cluster.addCluster(IkeaSpecificSceneCluster);
 
 // Example invocation of custom cluster command
-zclNode.endpoints[1].clusters['scenes'].ikeaSceneMove({mode: 0, transitionTime: 10});
-
+zclNode.endpoints[1].clusters["scenes"].ikeaSceneMove({ mode: 0, transitionTime: 10 });
 ```
 
 This also works for `BoundClusters`, if a node sends commands to Homey using a custom cluster it is necessary to implement a custom `BoundCluster` and bind it to the `ZCLNode` instance. For an example check the implementation in the `com.ikea.tradfri` driver [remote_control](https://github.com/athombv/com.ikea.tradfri-example/tree/master/drivers/remote_control/device.js).
 
 ## Contributing
+
 Great if you'd like to contribute to this project, a few things to take note of before submitting a PR:
-* This project enforces ESLint, validate by running `npm run lint`.
-* This project implements a basic test framework based on mocha, see [test](https://github.com/athombv/node-zigbee-clusters/blob/production/test) directory.
-* This project uses several [GitHub Action workflows](https://github.com/athombv/node-zigbee-clusters/blob/production/.github/workflows) (e.g. ESLint, running test and versioning/publishing).
 
+- This project enforces ESLint, validate by running `npm run lint`.
+- This project implements a basic test framework based on mocha, see [test](https://github.com/athombv/node-zigbee-clusters/blob/production/test) directory.
+- This project uses several [GitHub Action workflows](https://github.com/athombv/node-zigbee-clusters/blob/production/.github/workflows) (e.g. ESLint, running test and versioning/publishing).

package/index.d.ts

@@ -11,8 +11,13 @@ type ConstructorOptions = {
   sendFrame: (endpointId: number, clusterId: number, frame: Buffer) => Promise<void>;
 };
 type ZCLNodeCluster = EventEmitter & {
-  readAttributes: (...attributeNames: string[]) => Promise<{ [attributeName: string]: any }>;
-  writeAttributes: (attributes: { [attributeName: string]: any }) => Promise<{ [attributeName: string]: { id: number, status: 'SUCCESS' | 'FAILURE' } }>;
+  readAttributes: (
+    attributeNames: string[],
+    opts: { timeout: number }
+  ) => Promise<{ [attributeName: string]: any }>;
+  writeAttributes: (attributes: {
+    [attributeName: string]: any;
+  }) => Promise<{ [attributeName: string]: { id: number; status: "SUCCESS" | "FAILURE" } }>;
 };
 type ZCLNodeEndpoint = {
   clusters: { [clusterName: string]: ZCLNodeCluster };

package/lib/Cluster.js

@@ -398,9 +398,14 @@ class Cluster extends EventEmitter {
    * Command which reads a given set of attributes from the remote cluster.
    * Note: do not mix regular and manufacturer specific attributes.
    * @param {string[]} attributeNames
+   * @param {{timeout: number}} opts
    * @returns {Promise<{}>} - Object with attribute values (e.g. `{ onOff: true }`)
    */
-  async readAttributes(...attributeNames) {
+  async readAttributes(attributeNames, opts) {
+    if (attributeNames instanceof Array === false) {
+      throw new Error('Expected attribute names array, as of zigbee-clusters@2.0.0 call readAttributes([\'myAttr\'])');
+    }
+
     if (!attributeNames.length) {
       attributeNames = Object.keys(this.constructor.attributes);
     }
@@ -424,7 +429,7 @@ class Cluster extends EventEmitter {
       const { attributes } = await super.readAttributes({
         attributes: [...attrIds],
         manufacturerId,
-      });
+      }, opts);
 
       debug(this.logId, 'read attributes result', { attributes });
       const result = this.constructor.attributeArrayStatusDataType.fromBuffer(attributes, 0);
@@ -956,7 +961,7 @@ class Cluster extends EventEmitter {
     return new Promise((resolve, reject) => {
       const t = setTimeout(() => {
         delete this._trxHandlers[trxSequenceNumber];
-        reject(new Error('Timeout: Expected Default Response'));
+        reject(new Error('Timeout: Expected Response'));
       }, timeout);
       this._trxHandlers[trxSequenceNumber] = async frame => {
         delete this._trxHandlers[trxSequenceNumber];
@@ -1084,8 +1089,14 @@ class Cluster extends EventEmitter {
               return this.sendFrame(payload);
             }
 
+            // Check if a valid timeout override is provided
+            let responseTimeout;
+            if (typeof opts.timeout === 'number') {
+              responseTimeout = opts.timeout;
+            }
+
             const [response] = await Promise.all([
-              this._awaitPacket(payload.trxSequenceNumber),
+              this._awaitPacket(payload.trxSequenceNumber, responseTimeout),
               this.sendFrame(payload),
             ]);
 

package/package.json

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