Comment on page
Zigbee Apps
How to upgrade your Zigbee App to the new Zigbee API introduced in Homey 5.0.0
npm install --save homey-zigbeedriver zigbee-clusters
npm uninstall homey-meshdriver
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 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.
In case you need some inspiration, or need an example, take a look at Athom's open source Zigbee apps which have already been migrated to SDK v3 and
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 ofonNodeInit()
.this.node.on(‘online’)
is removed in favour ofthis.onEndDeviceAnnounce()
.getClusterEndpoint
returnsnull
if not found.cluster
property is changed from string value (e.g.genOnOff
) to an object which is exported byconst { CLUSTER } = require(‘zigbee-clusters’);
registerReportListener
is deprecated in favour ofBoundCluster
implementation.registerAttrReportListener
is deprecated in favour ofconfigureAttributeReporting
.calculateZigbeeDimDuration
renamed tocalculateLevelControlTransitionTime
.calculateColorControlTransitionTime
is added for thecolorControl
cluster.
ZigBeeXYLightDevice
is removed in favour ofZigBeeLightDevice
, it detects if the light supports hue and saturation or XY only.
Last modified 2yr ago