Zigbee Apps

How to upgrade your Zigbee App to the new Zigbee API introduced in Homey 5.0.0

Updating dependencies

Install homey-zigbeedriver and zigbee-clusters:

npm install --save homey-zigbeedriver zigbee-clusters

And uninstall homey-meshdriver:

npm uninstall homey-meshdriver

Updating the driver manifest

The most notable change here is the addition of the endpoints property which needs to contain the endpoint definition. Additionally, the number of properties which are used to identify a Zigbee device have been reduced, and only the following two are required:

• productId

• manufacturerId

Therefore, the following can be removed:

• deviceId

• profileId

To discover the endpoint definition of your Zigbee device, use the "interview" button in the Zigbee developer tools. It is not safe to assume the endpoint ids you might have used before are equal. It is advised to test this with your device, since an incorrect endpoint definition will result in a non-functioning device.

The endpoint definition is currently dynamic such that it does not require a repair for it to be updated on the device. In the future this might change.

For more information on how to add the endpoints definition see the Zigbee guide.

Updating drivers

For many drivers it will be very easy to update SDK v3 and homey-zigbeedriver.

If your driver extends ZigBeeLightDevice it is as easy as replacing the imports from:

const { ZigBeeLightDevice } = require('homey-meshdriver');

class DimmableBulb extends ZigBeeLightDevice {}

module.exports = DimmableBulb;

To:

const { ZigBeeLightDevice } = require('homey-zigbeedriver');

class DimmableBulb extends ZigBeeLightDevice {}

module.exports = DimmableBulb;

If your driver extends ZigBeeDevice the first step is to replace the homey-meshdriver imports with homey-zigbeedriver, for example:

const { ZigBeeDevice } = require('homey-zigbeedriver');

class MyZigBeeDevice extends ZigBeeDevice {}

module.exports = MyZigBeeDevice;

The next steps depends on the implementation of the driver:

• For directly sending commands to the node check the Zigbee guide > Driver and Device > Commands.

• For registering capabilities check the Zigbee guide > Driver and Device > Capabilities.

• For configuration attribute reporting check the Zigbee guide > Driver and Device > Attribute Reporting.

• For bindings and groups (new!) check the Zigbee guide > Driver and Device > Bindings and Groups.

• For implementing custom clusters (new!) check the Zigbee guide > Driver and Device > Custom Cluster.

• If your app implements custom Flows or accesses Managers for other reasons, check the updated SDK v3 documentation.

Examples

In case you need some inspiration, or need an example, take a look at the following example app which has been migrated to SDK v3 and homey-zigbeedriver com.ikea.tradfri.

Breaking changes for homey-zigbeedriver

This is a non exhaustive list of breaking changes in homey-zigbeedriver with respect to homey-meshdriver which might be good to be aware of:

• MeshDevice is removed in favour of ZigBeeDevice.

• onMeshInit() is deprecated in favour of onNodeInit().

• this.node.on(‘online’) is removed in favour of this.onEndDeviceAnnounce().

• getClusterEndpoint returns null if not found.

• cluster property is changed from string value (e.g. genOnOff) to an object which is exported by const { CLUSTER } = require(‘zigbee-clusters’);

• registerReportListener is deprecated in favour of BoundCluster implementation.

• registerAttrReportListener is deprecated in favour of configureAttributeReporting.

• calculateZigbeeDimDuration renamed to calculateLevelControlTransitionTime.

  • calculateColorControlTransitionTime is added for the colorControl cluster.

• ZigBeeXYLightDevice is removed in favour of ZigBeeLightDevice, it detects if the light supports hue and saturation or XY only.