node-zigbee-clusters

KO | EN

gitlite — search

#hacktoberfest #react #llm #go #golang #android #machine-learning #rust #deep-learning #linux #docker #macos #kubernetes #security

node-zigbee-clusters

(★ 13)

Zigbee Cluster Library for Node.js

node-zigbee-clusters 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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.

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).

The [node-homey-zigbeedriver](https://github.com/athombv/node-homey-zigbeedriver) library implements this project and does a lot of the heavy lifting that is required for most Zigbee drivers for Homey. In the case you need to divert from [node-homey-zigbeedriver](https://github.com/athombv/node-homey-zigbeedriver) it is possible to directly use the Zigbee Cluster Library for Node.js.

Make sure to take a look at the API documentation: [https://athombv.github.io/node-zigbee-clusters](https://athombv.github.io/node-zigbee-clusters).

## Installation

`$ npm install --save zigbee-clusters`

## Breaking changes

v3.0.0

- **iasZone**: Unified `zoneType` enum keys between attribute and `zoneEnrollRequest` command to match ZCL spec (Table 8-5). See [#176](https://github.com/athombv/node-zigbee-clusters/pull/176) for full impact analysis.
  - `cabonMonoxideSensor` -> `carbonMonoxideSensor` (typo fix)
  - `keyfob` -> `keyFob` (spec says "Key fob" - two words)
  - `standard` -> `standardCIE` (in `zoneEnrollRequest`)
  - `invalid` -> `invalidZoneType` (in `zoneEnrollRequest`)
  - `keyPad` -> `keypad` (in `zoneEnrollRequest`, spec says "Keypad" - one word)
  - Added missing `doorWindowHandle` (0x0016) zone type from spec

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.

## About Zigbee Clusters

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 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)

### Client/Server clusters

A cluster can be implemented in two ways:

- 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

In order to communicate with a Zigbee node retrieve a `node` instance from `ManagerZigBee` and create a `ZCLNode` instance using that node. This step encapsulates the `node` with the Zigbee Clusters functionality and allows sending and receiving ZCL commands.

### Basic communication with node

## Sending a command

`/drivers/my-driver/device.js`

```js
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,

// This is an optional property that allows for adjusting the default response
          // timeout (10000ms) before the command is considered rejected.
          // The timeout starts after sending the frame and receiving a low-level ack.
          timeout: 5000,
        }
      );
    });
  }
}
```

## Receiving an attribute report

`/drivers/my-driver/device.js`

```js
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
        }
      );
    });
  }
}
```

### 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})`.

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 = {
  onOff: { id: 0, type: ZCLDataTypes.bool },
};

// Define the cluster commands (with potential required arguments)
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 specify types
      onTime: ZCLDataTypes.uint16,
      offWaitTime: ZCLDataTypes.uint16,
    },
  },
};

// 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
  }

static get ATTRIBUTES() {
    return ATTRIBUTES; // Returns the defined attributes
  }

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`

### 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");

class LevelControlBoundCluster extends BoundCluster {
  constructor({ onMove }) {
    super();
    this._onMove = onMove;
  }

// This function name is directly derived from the `move`
  // command in `zigbee-clusters/lib/clusters/levelControl.js`
  // the payload received is the payload specified in
  // `LevelControlCluster.COMMANDS.move.args`
  move(payload) {
    this._onMove(payload);
  }
}

module.exports = LevelControlBoundCluster;
```

`/drivers/my-driver/device.js`

```js
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
    },
  })
);
```

### 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");

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() {
    return {
      ...super.COMMANDS,
      ikeaSceneMove: {
        id: 0x08,
        manufacturerId: 0x117c,
        args: {
          mode: ZCLDataTypes.enum8({
            up: 0,
            down: 1,
          }),
          transitionTime: ZCLDataTypes.uint16,
        },
      },
    };
  }

// It is also possible to implement manufacturer specific attributes, but beware, do not mix
  // these with regular attributes in one command (e.g. `Cluster#readAttributes` should be
  // called with only manufacturer specific attributes or only with regular attributes).
  static get ATTRIBUTES() {
    return {
      manufAttribute: {
        id: 0,
        type: ZCLDataTypes.uint8,
        manufacturerId: 0x1234,
      },
    };
  }
}

module.exports = IkeaSpecificSceneCluster;
```

`/drivers/my-driver/device.js`

```js
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 });
```

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).

## TypeScript Types

This project includes auto-generated TypeScript definitions (`index.d.ts`) for all clusters, attributes, and commands.

### Manual Generation

To regenerate TypeScript types after modifying cluster definitions:

```bash
npm run generate-types
```

This runs `scripts/generate-types.js` which loads all cluster modules and generates typed interfaces.

### Automatic Generation (GitHub Actions)

TypeScript types are automatically regenerated when changes are pushed to the `develop` branch that affect:
- `lib/clusters/**/*.js` - cluster definitions
- `scripts/generate-types.js` - the generator script

The workflow commits updated types back to `develop` if changes are detected.

## 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).

node-zigbee-clusters

node-zigbee-clusters 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

node-zigbee-clusters

node-zigbee-clusters 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README