Developing with ZBOSS for Zigbee
Zigbee stack migration guide

This page describes steps required to migrate between different versions of the Zigbee stack that introduced major changes and updates.

Zigbee stack migration guide: v3.11.1.0 to v3.11.2.0

Read this section for a brief summary of the most fundamental API changes and extensions in v3.11.2.0.

Updates and extensions inside the ZBOSS ZCL

The ZBOSS Zigbee Cluster Library (ZCL) was updated to version 8. To comply with the newest revision, you must migrate applications built with the older version of the ZBOSS stack to the ZCL8 API.

For an overview of the application development with ZBOSS ZCL8, see the ZCL8 support and compatibility modes on the Zigbee stack API overview page.


The ZBOSS ZCL was extended with Nordic's addons which enable to build ZCL8-compatible devices. Use these macros to declare sets of attributes with cluster revision attribute.

New type or function Notes and recommendations
ZB_ZCL_DECLARE_BASIC_SERVER_ATTRIB_LIST(attr_list, zcl_version, power_source) Call this macro to declare Basic cluster server attributes.
ZB_ZCL_DECLARE_BASIC_CLIENT_ATTRIB_LIST(attr_list) Call this macro to declare Basic cluster client attributes.
ZB_ZCL_DECLARE_IDENTIFY_CLIENT_ATTRIB_LIST(attr_list) Call this macro to declare Identify cluster client attributes.
ZB_ZCL_DECLARE_IDENTIFY_SERVER_ATTRIB_LIST(attr_list, identify_time) Call this macro to declare Identify cluster server attributes.
ZB_ZCL_DECLARE_COLOR_CONTROL_CLIENT_ATTRIB_LIST(attr_list) Call this macro to declare Color Control cluster client attributes.
ZB_ZCL_DECLARE_COLOR_CONTROL_ATTRIB_LIST_HS(attr_list, current_hue, current_saturation, color_mode, options, number_primaries, enhanced_color_mode, color_capabilities) Call this macro to declare Color Control cluster with Hue and Saturation capabilities.
ZB_ZCL_DECLARE_GROUPS_CLIENT_ATTRIB_LIST(attr_list) Call this macro to declare Groups cluster client attributes.
ZB_ZCL_DECLARE_SCENES_CLIENT_ATTRIB_LIST(attr_list) Call this macro to declare Scenes cluster client attributes.
ZB_ZCL_DECLARE_LEVEL_CONTROL_CLIENT_ATTRIB_LIST(attr_list) Call this macro to declare Level Control cluster client attributes.
ZB_ZCL_DECLARE_ON_OFF_CLIENT_ATTRIB_LIST(attr_list) Call this macro to declare OnOff cluster client attributes.

ZCL device callback implementation update

Make sure that the function that is implementing the ZCL device callback, passed with the call to ZB_ZCL_REGISTER_DEVICE_CB, assigns RET_NOT_IMPLEMENTED when the callback ID is not handled. For an example, check the implementation of zcl_device_cb in the Light bulb sample.

Updates to HA file structure

Legacy HA device definitions were removed due to ZCL8 incompatiblities. The sample device definitions can be found next to every Zigbee application.

Copy the legacy HA device definition files from previous releases to your application and align it with Updates and extensions inside the ZBOSS ZCL.