This page describes required changes to successfully migrate from the nRF5 SDK for Thread and Zigbee v3.2.0 to v4.0.0 (ZBOSS stack v3.1.0 to ZBOSS stack v3.3.0). Read this page alongside the ZBOSS section of the Zigbee release notes. This section lists all the changes in the nRF5 SDK for Thread and Zigbee v4.0.0 that are related to the stack.
To migrate, complete the following steps:
The Memory Buffer API received significant modifications with the implementation of buffer searching and handling.
The new buffer API uses only the buffer ID in buffer operations. Moreover, all ZBOSS API elements have been updated in such a way to require passing buffer IDs instead of buffer pointers. See the following table for examples.
| Legacy type or function | New type or function |
|---|---|
| zb_zcl_default_resp_payload_t * ZB_ZCL_READ_DEFAULT_RESP(zb_buf_t * p_buf) | zb_zcl_default_resp_payload_t * ZB_ZCL_READ_DEFAULT_RESP(zb_bufid_t buffer) |
| zb_uint8_t * ZB_ZCL_START_PACKET(zb_buf_t * p_buf) | void * ZB_ZCL_START_PACKET(zb_bufid_t bufid) |
| ZB_ZCL_ON_OFF_SEND_REQ(zb_bif_t * p_buf, ... ) | ZB_ZCL_ON_OFF_SEND_REQ(zb_bufid_t bufid, ... ) |
The following types and functions have been removed from the ZBOSS API without any replacement:
| Type or function | Notes and recommendations |
|---|---|
| zb_buf_t | The pointer-based buffer API has been completely removed. From now on, use the ID-based buffer API. To avoid confusion between buffer ID and zb_uint8_t, a new type zb_bufid_t was introduced. |
| zb_uint8_t ZB_REF_FROM_BUF(zb_buf_t * p_buf) | There is only one buffer representation, so the translation function has been removed. Remove it from your code. |
| zb_buf_t * ZB_BUF_FROM_REF(zb_uint8_t param) | There is only one buffer representation, so the translation function has been removed. Remove it from your code. |
| ZB_SET_BUF_PARAM(zb_buf_t p_buf, void * p_mem, type_t) | The API was simplified. Use ZB_BUF_GET_PARAM() instead. |
| size_t ZB_SET_BUF_PARAM_PTR(zb_buf_t p_buf, void * p_mem, type_t) | The API was simplified. Use ZB_BUF_GET_PARAM() instead. |
The following API for managing buffers has been replaced in the ZBOSS API:
| Legacy type or function | New type or function | Notes and recommendations |
|---|---|---|
| zb_ret_t ZB_GET_IN_BUF_DELAYED(zb_callback_t callback) | zb_ret_t zb_buf_get_in_delayed(zb_callback_t callback) | Allocate IN buffer. Call a callback when the buffer is available. |
| zb_ret_t ZB_GET_IN_BUF_DELAYED(zb_callback_t callback) | zb_ret_t zb_buf_get_in_delayed_ext(zb_callback2_t callback, zb_uint16_t arg, zb_uint_t max_size) | Allocate IN buffer. max_size is a required maximum buffer payload size (in bytes). Call this function to use extended buffer. |
| zb_ret_t ZB_GET_OUT_BUF_DELAYED(zb_callback_t callback) | zb_ret_t zb_buf_get_out_delayed(zb_callback_t callback) | Allocate OUT buffer. Call a callback when the buffer is available. |
| zb_ret_t ZB_GET_OUT_BUF_DELAYED2(zb_callback2_t callback, zb_uint16_t user_param) | zb_ret_t zb_buf_get_out_delayed_ext(zb_callback2_t callback, zb_uint16_t arg, zb_uint_t max_size) | Allocate OUT buffer. max_size is a required maximum buffer payload size (in bytes). Call this function to use extended buffer. |
| zb_buf_t * ZB_GET_OUT_BUF() | zb_bufid_t zb_buf_get_out() | Allocate an OUT buffer of the defualt size. |
| zb_buf_t * ZB_GET_IN_BUF() | zb_bufid_t zb_buf_get(zb_bool_t is_in, zb_uint_t max_size) | Allocator for input buffer has been removed. Use generic allocator. |
| zb_void_t ZB_BUF_REUSE(zb_buf_t * p_buf) | void * zb_buf_reuse(zb_bufid_t bufid) | Reuse buffer data space by setting data start and length to 0 and cleaning buffer contents. |
| zb_void_t zb_free_buf(zb_buf_t *buf) | void zb_buf_free(zb_bufid_t bufid) | Use the new function that frees packet buffer and puts it into the list of free buffers. |
| ZB_FREE_BUF_BY_REF(zb_uint8_t param) | void zb_buf_free(zb_bufid_t bufid) | Use the new function that releases packet buffer and puts it into the list of free buffers. |
| zb_uint8_t ZB_BUF_LEN(zb_buf_t * p_buf) | zb_uint_t zb_buf_len(zb_bufid_t bufid) | Use the new function that returns the current length of the buffer using the provided buffer ID. |
| zb_uint8_t ZB_BUF_LEN_BY_REF(zb_uint8_t param) | zb_uint_t zb_buf_len(zb_bufid_t bufid) | Use the new function that returns the current length of the buffer using the provided buffer ID. |
| zb_uint8_t * ZB_BUF_BEGIN(zb_buf_t * p_buf) | void * zb_buf_begin(zb_bufid_t bufid) | Return the pointer to the beginning of data stored in the buffer corresponding to the provided buffer ID. |
| zb_uint8_t * ZB_BUF_BEGIN_FROM_REF(zb_uint8_t param) | void * zb_buf_begin(zb_bufid_t bufid) | Due to API unification, there is no need to implement two variants of this function. |
| ZB_BUF_INITIAL_ALLOC(zb_buf_t * p_buf, zb_uint8_t size, zb_void_t * p_mem) | void * zb_buf_initial_alloc(zb_bufid_t buf, zb_uint_t size) | Initial data space allocation in the buffer. Use the buffer ID and the memory size for choosing buffer and memory size, respectively. |
| type_t * ZB_GET_BUF_PARAM(zb_buf_t * p_buf, type_t) | type_t * ZB_BUF_GET_PARAM(zb_bufid_t bufid, type_t) | Get or allocate the buffer tail of type_t size using the buffer ID. |
| zb_void_t * ZB_GET_BUF_TAIL(zb_buf_t * p_buf, zb_uint8_t size) | void * zb_buf_get_tail(zb_bufid_t bufid, zb_uint_t size) | Get or allocate the buffer tail of size size using the buffer ID. |
| zb_void_t * ZB_BUF_CUT_LEFT(zb_buf_t * p_buf, zb_uint8_t size) | void * zb_buf_cut_left(zb_bufid_t bufid, zb_uint_t size) | Cut space at the beginning of the buffer. Use the buffer ID for choosing the required buffer. |
| zb_void_t ZB_BUF_CUT_LEFT2(zb_buf_t * p_buf, zb_uint8_t size) | void * zb_buf_cut_left(zb_bufid_t bufid, zb_uint_t size) | Cut space at the beginning of the buffer. Use the buffer ID for choosing the required buffer. |
| zb_void_t ZB_BUF_CUT_RIGHT(zb_buf_t * p_buf, zb_uint8_t size) | void zb_buf_cut_right(zb_bufid_t bufid, zb_uint_t size) | Cut space at the end of the buffer. |
| ZB_BUF_ALLOC_RIGHT(zb_buf_t * p_buf, zb_uint8_t size, zb_void_t * p_mem) | void * zb_buf_alloc_right(zb_bufid_t bufid, zb_uint_t size) | Allocate space at the end of the buffer. Use the buffer ID for choosing the required buffer. |
| ZB_BUF_ALLOC_LEFT(zb_buf_t * p_buf, zb_uint8_t size, zb_void_t * p_mem) | void * zb_buf_alloc_left(zb_bufid_t bufid, zb_uint_t size) | Allocate the stated space at the beginning of the buffer. Use the buffer ID for choosing the required buffer. |
| zb_void_t ZB_BUF_COPY(zb_buf_t * p_dst_buf, zb_buf_t * p_src_buf) | void zb_buf_copy(zb_bufid_t dst_buf, zb_bufid_t src_buf) | Copy buffer data from the buffer pointed by the src_buf buffer ID to the dst_buf buffer ID. |
| ((zb_buf_t *)p_buf)->u.hdr.status | zb_int16_t zb_buf_get_status(zb_bufid_t bufid) | Since there is no pointer-based buffer API, this helper function has been introduced. |
| ((zb_buf_t *)p_buf)->u.hdr.status | void zb_buf_set_status(zb_bufid_t bufid) | Since there is no pointer-based buffer API, this helper function has been introduced. |
The nRF5 SDK for Thread and Zigbee v4.0.0 added new Scheduler API. Use only the new API in your applications.
The new API always saves space for stack callbacks, which allows to avoid overloading the ZBOSS stack.
If there is no space for application callbacks in the scheduler queue, the macros from the new API will return error code RET_OVERFLOW.
See the table below and replace the old API with the new one in your application. The old API is deprecated.
| Legacy API | New API |
|---|---|
| ZB_SCHEDULE_CALLBACK(func, param) | ZB_SCHEDULE_APP_CALLBACK(func, param) |
| ZB_SCHEDULE_CALLBACK2(func, param, user_param) | ZB_SCHEDULE_APP_CALLBACK2(func, param, user_param) |
| ZB_SCHEDULE_ALARM(func, param, timeout_bi) | ZB_SCHEDULE_APP_ALARM(func, param, timeout_bi) |
| ZB_SCHEDULE_ALARM_CANCEL(func, param) | ZB_SCHEDULE_APP_ALARM_CANCEL(func, param) |
ZDO received several updates to statuses and parameters.
If you used mentioned API in your application, make sure it complies with the new parameters.
The following ZDO API elements have been changed:
| Type or function | Status or parameter added | Notes and recommendations |
|---|---|---|
| zb_zdp_status_t | ZB_ZDP_STATUS_INVALID_INDEX | The status signalizes that the index of the received command is out of bounds. |
| zb_zdo_signal_device_annce_params_t | zb_ieee_addr_t ieee_addr and zb_uint8_t capability | The new fields represent mandatory parameters received in Device_annce command. |
| zb_zdo_mgmt_nwk_update_notify_param_t | zb_uint8_t enhanced | The new parameter is responsible for sending the enhanced notify command. |
The following ZDO API elements have been removed:
| Type | Status or parameter removed | Notes and recommendations |
|---|---|---|
| zb_zdo_mgmt_nwk_update_notify_param_t | zb_uint8_t tsn | The parameter was removed. |
According to the Zigbee Specification revision 22, the Zigbee devices can now use Sub-GHz frequencies. To differentiate this new set of channels from the original one, a page parameter was added.
For more information, see the Zigbee Specification revision 22, section 3.2.2.2.1 (Channel List Structure).
If you used mentioned API in your application, make sure it complies with the new parameters.
| Type or function | Status or parameter added | Notes and recommendations |
|---|---|---|
| zb_nwk_pib_cache_t | zb_uint8_t phy_current_page | A page corresponds to a certain frequency band. The original 2.4 GHz channels are now located on the zero page. |
APS received minor changes in order to unify the structures.
The status fields type was unified to zb_ret_t for the following API elements:
The replaced status field type is zb_uint8_t.
If you used mentioned API in your application, make sure it complies with the new fields type.
The Zigbee Green Power (ZGP) API received minor updates in the nRF5 SDK for Thread and Zigbee v4.0.0.
| Legacy type or function | New type or function | Notes and recommendations |
|---|---|---|
| ZB_FINISH_GPDF_PACKET(zbbuf, ptr) | zb_finish_gpdf_packet(zb_bufid_t buf_ref, zb_uint8_t** ptr) | Call this function instead of the macro. |
| Removed type or function | Notes and recommendations |
|---|---|
| ZB_GPDF_GET_BYTES_WRITTEN(zbbuf, ptr) | This macro is not available in the new version. No replacement is available. |
Minor changes were made in the Zigbee stack framework in the the nRF5 SDK for Thread and Zigbee v4.0.0.
| Legacy type or function | New type or function | Notes and recommendations |
|---|---|---|
| ZB_PRODUCTION_CONFIG_MAX_SIZE | ZB_PRODUCTION_CONFIG_APP_MAX_SIZE | Name of define has been changed to make it clear what the define is used for. Replace the old name in your application with the new one. |
| zb_void_t zb_set_channel(zb_uint32_t channel_mask) | void zb_set_channel_mask(zb_uint32_t channel_mask) | The function was renamed to make it clear what the purpose of the API call is. Replace the old name in your application. |