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 SDK 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. This tutorial provides only a brief summary of the most fundamental API changes and extensions.
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. |
Make sure that the function that is implementing the ZCL device callback, passed with the call to ZB_ZCL_DECLARE_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 Zigbee Light Control example.
| Legacy type or function | New type or function | Notes and recommendations |
|---|---|---|
| typedef zb_uint8_t* (*zb_zcl_ota_upgrade_next_data_ind_t)(zb_uint8_t index, zb_uint32_t offset, zb_uint8_t size) | typedef zb_ret_t (*zb_zcl_ota_upgrade_next_data_ind_t)(zb_uint8_t index, zb_zcl_parsed_hdr_t *zcl_header, zb_uint32_t offset, zb_uint8_t size, zb_uint8_t** data) | Callback function for sending the next portion of data, called on Next Image Block request. Changed to accept more arguments and return error code. |
Zigbee's secur module received minor changes to unify the usage of APIs used for managing install codes.
The following APIs for managing install codes have been replaced in the ZBOSS API:
| Legacy type or function | New type or function | Notes and recommendations |
|---|---|---|
| zb_ret_t zb_secur_ic_add(zb_ieee_addr_t address, zb_uint8_t ic_type, zb_uint8_t <em>ic) | void zb_secur_ic_add(zb_ieee_addr_t address, zb_uint8_t ic_type, zb_uint8_t *ic, zb_secur_ic_add_cb_t cb) | Add install code for the device with the specified long address. Provide a callback function that is to be called after the install code has been added. |
| zb_ret_t zb_secur_ic_get_list(zb_uint8_t table, zb_uint8_t *cnt) | void zb_secur_ic_get_list_req(zb_uint8_t param) | Get the list of the install codes. Provide buffer with zb_secur_ic_get_list_req_t structure as the buffer's parameter. |
| zb_ret_t zb_secur_ic_get_by_idx(zb_uint8_t* param, zb_uint8_t index) | void zb_secur_ic_get_by_idx_req(zb_uint8_t param) | Get the install code by index. Provide buffer with zb_secur_ic_get_by_idx_req_t structure as the buffer's parameter. |
| zb_ret_t zb_secur_ic_remove(zb_ieee_addr_t address) | void zb_secur_ic_remove_req(zb_uint8_t param) | Remove the install code for the device with the specified long address. Provide buffer with zb_secur_ic_remove_req_t structure as the buffer's parameter. |
| zb_ret_t zb_secur_ic_remove_all(void) | void zb_secur_ic_remove_all_req(zb_uint8_t param) | Remove the install code for all devices. Provide buffer with zb_secur_ic_remove_all_req_t structure as the buffers's parameter. |
| zb_ret_t zb_secur_ic_str_add(zb_ieee_addr_t address, char *ic_str) | void zb_secur_ic_str_add(zb_ieee_addr_t address, char *ic_str, zb_secur_ic_add_cb_t cb) | Add install code for the device from the character string. Provide device address, install code string, and callback function that is to be called after the install code addition. |
Minor changes were made in the Zigbee stack framework in the nRF5 SDK for Thread and Zigbee v4.2.0.
| Legacy type or function | New type or function | Notes and recommendations |
|---|---|---|
| zb_void_t | void | zb_void_t is not available anymore. Replace the old type in your application with the new one. |
Changes were made in the ZBOSS OSIF layer functions.
| Legacy type or function | New type or function | Notes and recommendations |
|---|---|---|
| void zb_nrf52_priph_disable(void) | void zb_nrf52_periph_disable(void) | Renamed without other changes. |
| void zb_nrf52_priph_enable(void) | void zb_nrf52_periph_enable(void) | Renamed without other changes. |
| void zb_nrf52_general_init(void) | void zb_osif_init(void) | Renamed without other changes. |
| void zb_nrf52_abort(void) | void zb_osif_abort(void) | Renamed without other changes. |
| void zb_nrf52_enable_all_inter(void) | void zb_osif_enable_all_inter(void) | Renamed without other changes. |
| void zb_nrf52_disable_all_inter(void) | void zb_osif_disable_all_inter(void) | Renamed without other changes. |
| void hw_aes128(zb_uint8_t *key, zb_uint8_t *msg, zb_uint8_t *c) | void zb_osif_aes128_hw_encrypt(zb_uint8_t *key, zb_uint8_t *msg, zb_uint8_t *c) | Renamed without other changes. |
| zb_uint32_t zb_nrf52_sleep(zb_uint32_t sleep_tmo) | zb_uint32_t zb_osif_sleep(zb_uint32_t sleep_tmo) | Renamed without other changes. |
The following functions have been removed without any replacement:
| Legacy type or function | Notes and recommendations |
|---|---|
| zb_time_t osif_transceiver_time_get(void) | Removed as no loger required. |
| void zb_nrf52_sleep_init(void) | Made part of zb_osif_init(). |
| void osif_sleep_using_transc_timer(zb_time_t timeout) | Removed as no longer required. |
| zb_time_t osif_sub_trans_timer(zb_time_t t2, zb_time_t t1) | Removed as no longer required. |
| zb_nrf52_radio_stats_t* zb_nrf52_get_radio_stats(void) | Removed as no longer required. |
| void zb_nrf_802154_mac_osif_init(void) | Removed as no longer required. |
The following functions have been added:
| Legacy type or function | Notes and recommendations |
|---|---|
| void zb_osif_wake_up(void) | Function that is called after zb_osif_sleep() is finished and the ZBOSS timer is reenabled. |
Changes were made in the structure of directiories. The BDB and ZCL layer implementation was removed from the main ZBOSS library and is now provided in sources.
The following project files must be extended to include new ZBOSS sources:
<InstallFolder>\external\zboss\src\zcl <InstallFolder>\external\zboss\src\commissioning\bdb <InstallFolder>\external\zboss\osif\zb_nrf52_logger.c Moreover, add the following include path during the compilation of the new ZBOSS sources:
<InstallFolder>\external\zboss\src\include | Old directory or file path | New directory or file path |
|---|---|
<InstallFolder>\external\zboss\zb_error\zb_error_to_string.c | <InstallFolder>\external\zboss\src\zb_error\zb_error_to_string.c |
<InstallFolder>\external\zboss\addons\zcl\zb_zcl_ota_upgrade_addons.c | <InstallFolder>\components\zigbee\ota\zb_zcl_ota_upgrade_addons.c |
<InstallFolder>\external\zboss\addons | <InstallFolder>\external\zboss\include\addons |
<InstallFolder>\external\zboss\zb_error | <InstallFolder>\external\zboss\src\zb_error |
The following source files were deleted:
<InstallFolder>\external\zboss\osif\zb_nrf52_sdk_config_deps.c <InstallFolder>\external\zboss\addons\zcl\zb_zcl_common_addons.c The following library was added:
<InstallFolder>\external\zboss\lib\gcc\libgppb.a It is now required to add this library to your project when building a Zigbee coordinator or a Zigbee router.
Add the following defines to your project:
CONFIG_ZIGBEE_ERROR_TO_STRING_ENABLED LIBZBOSS_CONFIG_FILE="libzboss_config.h" – if compiling Zigbee Router or Zigbee Coordinator.LIBZBOSS_CONFIG_FILE="libzboss_config.ed.h" – if compiling Zigbee End Device.ZBOSS_BUILD ZB_NRF_INTERNAL ZB_NVRAM_FLASH_AUTO_ADDRESS ZB_ZCL_SCENES_OPTIONAL_COMMANDS_DISABLED Remove the following defines from your project:
ZB_TRACE_LEVEL ZB_TRACE_MASK