zigbee-clusters 2.0.1 → 2.1.1

package/index.d.ts

@@ -11,14 +11,168 @@ type ConstructorOptions = {
   sendFrame: (endpointId: number, clusterId: number, frame: Buffer) => Promise<void>;
 };
 type ZCLNodeCluster = EventEmitter & {
-  readAttributes: (
+  /**
+   * Command which requests the remote cluster to report its generated commands. Generated
+   * commands are commands which may be sent by the remote cluster.
+   *
+   * TODO: handle the case where `lastResponse===false`. It might be possible that there are
+   *  more commands to be reported than can be transmitted in one report (in practice very
+   *  unlikely though). If `lastResponse===false` invoke `discoverCommandsGenerated` again
+   *  starting from the index where the previous invocation stopped (`maxResults`).
+   *
+   * TODO: The manufacturer-specific sub-field SHALL be set to 0 to discover standard commands
+   *  in a ZigBee cluster or 1 to discover manufacturer-specific commands in either a standard or
+   *  a manufacturer-specific cluster. A manufacturer ID in this field of 0xffff (wildcard) will
+   *  discover any manufacture- specific
+   *  commands.
+   *
+   * @param {object} [opts=]
+   * @param {number} [opts.startValue=0]
+   * @param {number} [opts.maxResults=250]
+   * @returns {Promise<number[]>}
+   */
+  discoverCommandsGenerated({
+    startValue,
+    maxResults,
+  }?: {
+    startValue?: number;
+    maxResults?: number;
+  }): Promise<number[]>;
+  /**
+   * Command which requests the remote cluster to report its received commands. Received
+   * commands are commands which may be received by the remote cluster.
+   *
+   * TODO: handle the case where `lastResponse===false`. It might be possible that there are
+   *  more commands to be reported than can be transmitted in one report (in practice very
+   *  unlikely though). If `lastResponse===false` invoke `discoverCommandsGenerated` again
+   *  starting from the index where the previous invocation stopped (`maxResults`).
+   *
+   * TODO: The manufacturer-specific sub-field SHALL be set to 0 to discover standard commands
+   *  in a ZigBee cluster or 1 to discover manufacturer-specific commands in either a standard or
+   *  a manufacturer-specific cluster. A manufacturer ID in this field of 0xffff (wildcard) will
+   *  discover any manufacture- specific commands.
+   *
+   * @param {object} [opts=]
+   * @param {number} [opts.startValue=0]
+   * @param {number} [opts.maxResults=255]
+   * @returns {Promise<number[]>}
+   */
+  discoverCommandsReceived({
+    startValue,
+    maxResults,
+  }?: {
+    startValue?: number;
+    maxResults?: number;
+  }): Promise<number[]>;
+  /**
+   * 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.<string, unknown>>} - Object with values (e.g. `{ onOff: true }`)
+   */
+  readAttributes(
     attributeNames: string[],
-    opts: { timeout: number }
-  ) => Promise<{ [attributeName: string]: any }>;
-  writeAttributes: (attributes: {
-    [attributeName: string]: any;
-  }) => Promise<{ [attributeName: string]: { id: number; status: "SUCCESS" | "FAILURE" } }>;
+    opts?: {
+      timeout: number;
+    }
+  ): Promise<{
+    [x: string]: unknown;
+  }>;
+  /**
+   * Command which writes a given set of attribute key-value pairs to the remote cluster.
+   * Note: do not mix regular and manufacturer specific attributes.
+   * @param {object} attributes - Object with attribute names as keys and their values (e.g. `{
+   * onOff: true, fakeAttributeName: 10 }`.
+   * @returns {Promise<*|{attributes: *}>}
+   */
+  writeAttributes(attributes?: object): Promise<
+    | any
+    | {
+        attributes: any;
+      }
+  >;
+  /**
+   * Command which configures attribute reporting for the given `attributes` on the remote cluster.
+   * Note: do not mix regular and manufacturer specific attributes.
+   * @param {object} attributes - Attribute reporting configuration (e.g. `{ onOff: {
+   * minInterval: 0, maxInterval: 300, minChange: 1 } }`)
+   * @returns {Promise<void>}
+   */
+  configureReporting(attributes?: object): Promise<void>;
+  /**
+   * @typedef {object} ReadReportingConfiguration
+   * @property {ZCLDataTypes.enum8Status} status
+   * @property {'reported'|'received'} direction
+   * @property {number} attributeId
+   * @property {ZCLDataType.id} [attributeDataType]
+   * @property {number} [minInterval]
+   * @property {number} [maxInterval]
+   * @property {number} [minChange]
+   * @property {number} [timeoutPeriod]
+   */
+  /**
+   * Command which retrieves the reporting configurations for the given `attributes` from the
+   * remote cluster. Currently this only takes the 'reported' into account, this represents the
+   * reports the remote cluster would sent out, instead of receive (which is likely the most
+   * interesting).
+   * Note: do not mix regular and manufacturer specific attributes.
+   * @param {Array} attributes - Array with number/strings (either attribute id, or attribute name).
+   * @returns {Promise<ReadReportingConfiguration[]>} - Returns array with
+   * ReadReportingConfiguration objects per attribute.
+   */
+  readReportingConfiguration(attributes?: any[]): Promise<
+    {
+      status: any;
+      direction: "reported" | "received";
+      attributeId: number;
+      attributeDataType?: ZCLDataType.id;
+      minInterval?: number;
+      maxInterval?: number;
+      minChange?: number;
+      timeoutPeriod?: number;
+    }[]
+  >;
+  /**
+   * Command which discovers the implemented attributes on the remote cluster.
+   *
+   * TODO: handle the case where `lastResponse===false`. It might be possible that there are
+   *  more commands to be reported than can be transmitted in one report (in practice very
+   *  unlikely though). If `lastResponse===false` invoke `discoverCommandsGenerated` again
+   *  starting from the index where the previous invocation stopped (`maxResults`).
+   *
+   * TODO: The manufacturer specific sub-field SHALL be set to 0 to discover standard attributes
+   *  in a ZigBee cluster or 1 to discover manufacturer specific attributes in either a standard
+   *  or a manufacturer specific cluster.
+   *
+   * @returns {Promise<Array>} - Array with string or number values (depending on if the
+   * attribute
+   * is implemented in zigbee-clusters or not).
+   */
+  discoverAttributes(): Promise<any[]>;
+  /**
+   * Command which discovers the implemented attributes on the remote cluster, the difference with
+   * `discoverAttributes` is that this command also reports the access control field of the
+   * attribute (whether it is readable/writable/reportable).
+   *
+   * TODO: handle the case where `lastResponse===false`. It might be possible that there are
+   *  more commands to be reported than can be transmitted in one report (in practice very
+   *  unlikely though). If `lastResponse===false` invoke `discoverCommandsGenerated` again
+   *  starting from the index where the previous invocation stopped (`maxResults`).
+   *
+   * TODO: The manufacturer-specific sub-field SHALL be set to 0 to discover standard attributes
+   *  in a ZigBee cluster or 1 to discover manufacturer-specific attributes in either a standard
+   *  or a manufacturer- specific cluster. A manufacturer ID in this field of 0xffff (wildcard)
+   *  will discover any manufacture-specific attributes.
+   *
+   * @returns {Promise<Array>} - Returns an array with objects with attribute names as keys and
+   * following object as values: `{name: string, id: number, acl: { readable: boolean, writable:
+   * boolean, reportable: boolean } }`. Note that `name` is optional based on whether the
+   * attribute is implemented in zigbee-clusters.
+   */
+  discoverAttributesExtended(): Promise<any[]>;
 };
+
 type ZCLNodeEndpoint = {
   clusters: { [clusterName: string]: ZCLNodeCluster };
 };
@@ -40,4 +194,5 @@ declare module "zigbee-clusters" {
   export const CLUSTER: {
     [key: string]: { ID: number; NAME: string; ATTRIBUTES: any; COMMANDS: any };
   };
+  export var ZCLNodeCluster;
 }

package/lib/Cluster.js

@@ -340,8 +340,9 @@ class Cluster extends EventEmitter {
    *  discover any manufacture- specific
    *  commands.
    *
-   * @param {number} [startValue=0]
-   * @param {number} [maxResults=250]
+   * @param {object} [opts=]
+   * @param {number} [opts.startValue=0]
+   * @param {number} [opts.maxResults=250]
    * @returns {Promise<number[]>}
    */
   async discoverCommandsGenerated({ startValue = 0, maxResults = 250 } = {}) {
@@ -374,8 +375,9 @@ class Cluster extends EventEmitter {
    *  a manufacturer-specific cluster. A manufacturer ID in this field of 0xffff (wildcard) will
    *  discover any manufacture- specific commands.
    *
-   * @param {number} [startValue=0]
-   * @param {number} [maxResults=250]
+   * @param {object} [opts=]
+   * @param {number} [opts.startValue=0]
+   * @param {number} [opts.maxResults=255]
    * @returns {Promise<number[]>}
    */
   async discoverCommandsReceived({ startValue = 0, maxResults = 255 } = {}) {
@@ -398,8 +400,8 @@ 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 }`)
+   * @param {{timeout: number}} [opts=]
+   * @returns {Promise<Object.<string, unknown>>} - Object with values (e.g. `{ onOff: true }`)
    */
   async readAttributes(attributeNames, opts) {
     if (attributeNames instanceof Array === false) {

package/package.json

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

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  // Change this to match your project
+  "include": ["lib/**/*", "index.js"],
+  "compilerOptions": {
+    // Tells TypeScript to read JS files, as
+    // normally they are ignored as source files
+    "allowJs": true,
+    // Generate d.ts files
+    "declaration": true,
+    // This compiler run should
+    // only output d.ts files
+    "emitDeclarationOnly": true,
+    // Types should go into this directory.
+    // Removing this would place the .d.ts files
+    // next to the .js files
+    "outDir": "dist",
+    // go to js file when using IDE functions like
+    // "Go to Definition" in VSCode
+    "declarationMap": true
+  }
+}