Zigbee

ZigBee is a wireless communication standard that extends the IEEE 802.15.4 standard, it uses 2 different frequencies (2.4GHz, 869-915MHz), and is very similar to Z-Wave.

Introduction to ZigBee

A ZigBee Device is made up of one or more Endpoints, these are collections of Clusters.

A Cluster is essentially a capability of the device, and might have attributes that can be read or written to. It may also support commands which are used to perform more complicated actions. Clusters come in 3 forms: inputs, outputs or both. Input clusters can have commands sent to them to perform actions, where as output clusters instead send these commands to a bound device.

An example device:

Device:
  - Endpoint: 0
    - Cluster: genBasic
      type: input
      manufacturerName: IKEA of Sweden
      modelId: Trådfri dimmer
    - Cluster: genOnOff
      type input
      onOff: 1
    - Cluster: genLevelCtrl
      type input
      currentLevel: 189
      onLevel: 255
  - Endpoint: 1
    - Cluster: genBasic
      type input
      manufacturerName: IKEA of Sweden
      modelId: Trådfri dimmer
    - Cluster: msTemperatureMeasurement
      measuredValue: 25
      tolerance: 1

Homey automatically converts all values and variable names to the appropriate format so you don't have to worry about low-level things such as Buffers. A list of possible commands may be found below.

MeshDriver

A library named MeshDriver has been developed to ease development of ZigBee devices in Homey. It mainly maps ZigBee endpoints and clusters to Homey's capabilities. It is recommended for most app developers to use this library.

Pairing

ZigBee Pairing is handled by Homey for security reasons, and Homey will only pass control over the ZigBee device to your driver after a successful pair.

To ensure the correct driver will be loaded when pairing a device, your driver must have a matching Manufacturer Name, Product Id, ZigBee Device Id and ZigBee Profile Id.

To find out the correct values, first pair your device as a basic ZigBee device and open Settings > ZigBee. The Network Graph shows all devices that are connected to Homey. Click on a device to show all the information necessary to create a driver.'

Creating a ZigBee Driver

To inform Homey that your driver supports controlling ZigBee devices, add a zigbee object to your driver object in your app’s /app.json.

/app.json

{
  "id": "com.athom.example",
  ...
    "drivers": [
      {
        "id": "my_driver",
        "name": {
          "en": "My Driver"
        },
        "class": "socket",
        "capabilities": [ "onoff", "dim" ],
        "zigbee": {
          "manufacturerName": "IKEA of Sweden", // Case sensitive
        "productId": [
          "TRADFRI bulb E27 opal 980lm",
          "Another type of light"
        ], // Can also be an array to support multiple devices
        "learnmode": {
          "image": "/drivers/my_driver/assets/learnmode.svg",
          "instruction": {
            "en": "Press the button on your device three times"
          }
        },
      }
      }
    ]
}

ZigBee Cluster Documentation

The full ZigBee Cluster Specification can be found at ZigBee Cluster Specification (PDF).

Visit ZigBee-Clusters Reference for an interactive clusters browser.

Advanced API

Sending a command:

/app.js

node.endpoints[0].clusters['genLevelCtrl'].do("moveToLevel", {level: 255, transtime: 1})
  .then(result => {
  })
  .catch(err => {
  });

Reading a value:

/app.js

node.endpoints[0].clusters['genBasic'].read("manufacturerName")
  .then(result => {
  })
  .catch(err => {
  });

Binding

Binding is used when working with Server Clusters, it binds two clusters together. This makes a Server cluster send its commands to Homey’s bound clusters, and can be used to, for example, cause a wall switch to send its On/Off Commands to Homey.

Binding a cluster to Homey:

/driver.js

this.node.endpoints[0].clusters['genOnOff'].bind()
  .then(result => {
  })
  .catch(err => {
    if(err) Homey.log('Something went wrong while binding the genOnOff cluster', err);
  });

Listening to commands sent from the device:

/driver.js

node.on('command', (command) => {
  console.log(command);
});

Child Topics

• Clusters Reference