 |
nRF5 SDK for Thread and Zigbee v4.0.0
|
|
nRF5 SDK for Thread and Zigbee v4.0.0
|
This page lists new API elements and new features introduced in the nRF5 SDK for Thread and Zigbee v4.0.0 (ZBOSS stack v3.3.0), in accordance with the revision 22 of the Zigbee Core Specification.
The NVRAM feature of the nRF5 SDK for Thread and Zigbee v4.0.0 has been updated with new API elements, namely new datasets for application data (number 3 and number 4).
| New type or function | Notes and recommendations |
|---|---|
| void zb_nvram_register_app3_read_cb(zb_nvram_read_app_data_t cb) | Register application callback for reading ZB_NVRAM_APP_DATA3. |
| void zb_nvram_register_app4_read_cb(zb_nvram_read_app_data_t cb) | Register application callback for reading ZB_NVRAM_APP_DATA4. |
| void zb_nvram_register_app3_write_cb(zb_nvram_write_app_data_t wcb, zb_nvram_get_app_data_size_t gcb) | Register application callback for writing to ZB_NVRAM_APP_DATA3. |
| void zb_nvram_register_app4_write_cb(zb_nvram_write_app_data_t wcb, zb_nvram_get_app_data_size_t gcb) | Register application callback for writing to ZB_NVRAM_APP_DATA4. |
| void zb_nvram_erase(void) | Erase all data from NVRAM. Previously only zb_nvram_erase_at_start() function was available. Better to use zb_nvram_clear(). |
| New type or function | Notes and recommendations |
|---|---|
| zb_uint16_t zb_nwk_get_parent(void) | Gets short address of the parent node. |
| zb_pan_id_conflict_info_t | Structure that includes information about neighboring PAN IDs. Should be passed to zb_start_pan_id_resolution(). |
| void zb_start_pan_id_conflict_resolution(zb_uint8_t param) | Starts resolving PAN IDs resolution. Use after catching signal ZB_NWK_SIGNAL_PANID_CONFLICT_DETECTED. |
| void zb_enable_auto_pan_id_conflict_resolution(zb_bool_t status) | Enables auto PAN ID conflict resolution if status ZB_TRUE, disables PAN ID conflict resolution if status ZB_FALSE. By default auto PAN ID resolution is disabled. |
The following stack API elements have been added in zboss_api.h:
| New type or function | Notes and recommendations |
|---|---|
| void zb_set_pan_id(zb_uint16_t pan_id) | Defines PAN ID for the current device. |
| void zb_secur_nwk_key_switch_procedure(zb_uint8_t param) | Initiates procedure of NWK key switching. Only for the Trust Center |
| void zb_secur_set_tc_rejoin_enabled(zb_bool_t enable) | Specifies whether Trust Center Rejoin is allowed. |
| zb_channel_page_num_t | Enumeration includes known pages. The main page and four Sub-GHz pages. See Zigbee Specification revision 22 section 3.2.2.2.1 (Channel List Structure) |
| void zb_production_config_disable(zb_bool_t val) | Disables production configuration usage at runtime if val is set to ZB_TRUE. |
| zb_bool_t zb_is_production_config_disabled(void) | Returns ZB_TRUE if production configuration usage is disabled and ZB_FALSE if production configuration is enabled. |
| void zb_tc_set_use_installcode(zb_uint8_t use_ic) | Enables install codes usage. Only for the Trust Center |
The following set of signals has been added to the stack API in the stack v3.3.0:
| Signal | Notes and recommendations |
|---|---|
| ZB_ZDO_SIGNAL_DEVICE_AUTHORIZED | The signal notifies the Zigbee Trust center application about a new device that is authorized in the network. In case of Zigbee R21 devices, it notifies that the TCKL exchange procedure was finished. For the legacy devices, it shows that the Transport key was sent to the device. The signal is generated on successful or failed authorization or on authorization timeout. The signal returns RET_OK when the device information is updated. |
| ZB_ZDO_SIGNAL_DEVICE_UPDATE | The signal notifies that a Zigbee Trust center or parent router application receives the information about a new device that has joined, rejoined, or left the network. It is generated when a standard device securely rejoins, unsecurely joins or leaves the network, or when a standard device rejoins the trust center. |
| ZB_NWK_SIGNAL_PANID_CONFLICT_DETECTED | The signal notifies that a PAN ID conflict has been detected. The application has to decide whether to initiate its resolution or not. |
The following ZDO API elements have been added:
| New type or function | Notes and recommendations |
|---|---|
| zb_uint8_t zb_zdo_mgmt_nwk_enhanced_update_req(zb_uint8_t param, zb_callback_t cb) | Performs the Mgmt_NWK_Enhanced_Update_req request. param parameter contains the index of the buffer with the call parameters. The cb parameter carries the user function to call when the notification is sent. |
| void zb_zdo_mgmt_nwk_unsol_enh_update_notify(zb_uint8_t param, zb_callback_t cb) | Performs Mgmt_NWK_Enhanced_Update_req request. The function contains two parameters. The param must contain the index of the buffer with the call parameters. Note that they must be kept in the buffer according to zb_zdo_mgmt_nwk_unsol_enh_update_notify_param_t. The cb parameter carries the user function to call when the notification has been sent. |
| void zb_zdo_disable_network_mgmt_channel_update(zb_bool_t disable) | Disable channel update (concerns the coordinator role only). The current ZB channel can be changed inside the stack for internal reasons or as a result of processing Mgmt NWK Update Notify commands. Call this function to prevent such channel changes in case the application is not supposed to have them. The zb_bool_t disable parameter specifies if the channel update is disabled (it is enabled by default). |
| zb_zdo_mgmt_nwk_unsol_enh_update_notify_t | Notification structure for Mgmt_NWK_Unsolicited_Enhanced_Update_notify. |
| zb_zdo_mgmt_nwk_unsol_enh_update_notify_param_t | Parameters for Mgmt_NWK_Unsolicited_Enhanced_Update_notify. The structure includes notification parameter of zb_zdo_mgmt_nwk_unsol_enh_update_notify_t type and addr of zb_uint16_t for the address. |
| zb_zdo_mgmt_nwk_ieee_joining_list_param_t | Parameters for Mgmt_NWK_IEEE_Joining_List_req. |
| zb_zdo_mgmt_nwk_ieee_joining_list_req_t | Request for Mgmt_NWK_IEEE_Joining_List_req. |
| zb_zdo_mgmt_nwk_ieee_joining_list_rsp_t | Response for Mgmt_NWK_IEEE_Joining_List_rsp. |
The stack v3.3.0 introduced the Many-To-One Route Request (MTORR) feature. See Zigbee Specification revision 22 section 3.6.3.5 (Route Discovery) for more information about Many-To-One Route Request (MTORR).
The following APIs have been added:
| New type or function | Notes and recommendations |
|---|---|
| void zb_start_concentrator_mode(zb_uint8_t radius, zb_uint32_t disc_time) | Enable Concentrator mode for the device (disabled by default). Concentrator initiates a many-to-one-route discovery. See Zigbee Specification revision 22 section 3.6.3.5 (Route Discovery). |
| void zb_stop_concentrator_mode(void) | Disable Concentrator mode for the device. |
Also, the stack v3.3.0 allows for starting many-to-one route discovery. A source device, which initiates a many-to-one route discovery, is designed as a concentrator.
The APS fragmentation has been added in the stack v3.3.0. It is used when an ASDU is too large to be transmitted within a single MAC data frame, an acknowledged unicast transmission was requested, and fragmentation is permitted for this frame. In such a case, the ASDU shall be fragmented into a number of smaller byte strings, here referred to as "blocks". Each block is transmitted in a separate frame.
Transactions not using APS acknowledgements may not be fragmented. Multicast and broadcast transmissions are not permitted to use fragmentation.
APS fragmentation uses Extended buffers.
For details, see Zigbee Specification revision 22, subclause 2.2.8.4.5 (Fragmented Transmissions).
The stack v3.3.0 comes with extended buffers, which allow to allocate more continuous memory.
The usual buffer size is 128 bytes. To allocate more continuous memory, use extended buffers.
To use extended buffers, set max_size parameter in functions zb_buf_get(zb_bool_t is_in, zb_uint_t max_size) or zb_buf_get_out_delayed_ext(zb_callback2_t callback, zb_uint16_t arg, zb_uint_t max_size) to the number of needed payload size to get extended buffer. Otherwise, set max_size parameter to 0.
The following new API provides an interface for enabling various features of the Works With All Hubs (WWAH) cluster:
| New type or function | Notes and recommendations |
|---|---|
| ZB_BDB_SIGNAL_WWAH_REJOIN_STARTED | When the device lost the connection with the parent device, it sends this signal. RET_OK is received if the parent device receives a Leave command from the child device. The signal does not return any error status. |
Below are the baseline assumptions of Work With All Hubs initiative:
The goal of this cluster is to enable hubs to provide improved security, interoperability, and customer experience for devices that enable this cluster. See more information about this cluster in the API reference: ZCL Work With All Hubs (WWAH) cluster.
Also see the following documents:
The stack v3.3.0 comes with several new custom features.
Use the following functions for the newly added APS-unencrypted Transport Key sending mode:
| New type or function | Notes and recommendations |
|---|---|
| void zb_disable_transport_key_aps_encryption(void) | Disable APS-encryption of Transport Key from the ZC. |
| void zb_enable_transport_key_aps_encryption(void) | Enable APS-encryption of Transport Key from the ZC. |
| zb_bool_t zb_is_transport_key_aps_encryption_enabled(void) | Get the status of the APS-encryption of Transport Key from the ZC. |
Use the following set of API to send APS user payload:
| New type or function | Notes and recommendations |
|---|---|
| zb_ret_t zb_aps_send_user_payload(zb_uint8_t param, zb_addr_u dst_addr, zb_uint16_t profile_id, zb_uint16_t cluster_id, zb_uint8_t dst_endpoint, zb_uint8_t src_endpoint, zb_uint8_t addr_mode, zb_bool_t aps_ack_is_enabled, zb_uint8_t *payload_ptr, zb_uint8_t payload_size) | Send user payload using APS. |
| zb_uint8_t * zb_aps_get_aps_payload(zb_uint8_t param, zb_uint8_t *aps_payload_size) | Get pointer to an APS payload. |
| void zb_aps_set_user_data_tx_cb(zb_aps_user_payload_callback_t cb) | Set callback to notify about the results of transmitting an APS frame with user payload. |
| zb_aps_user_payload_cb_status_t | Enumeration stores APS user payload tranmission statuses. |
| typedef void (* zb_aps_user_payload_callback_t)(zb_uint8_t param) | Callback to notify an application of sending an APS user payload status. |
In the nRF5 SDK for Thread and Zigbee v4.0.0, you can disable the NWK security completely. To control the security mode, the following API:
| New type or function | Notes and recommendations |
|---|---|
| void zb_disable_nwk_security(void) | Disable NWK security. |
| void zb_enable_nwk_security(void) | Enable NWK security if it was disabled previously. |
In the nRF5 SDK for Thread and Zigbee v4.0.0, you can change macTransactionPersistenceTime. Use the following function to set the desired value for macTransactionPersistenceTime: void zb_set_mac_transaction_persistence_time(zb_uint16_t ms).
See also IEEE Std 802.15.4-2006 specification Table 86 (MAC PIB attributes).
If you need to send a NWK frame without putting destination IEEE, use the function zb_nwk_set_ieee_policy(zb_bool_t put_always) with parameter put_always set to ZB_FALSE. This allows to send all NWK frametypes without putting destination IEEE, except for the NWK Command frame type.
The nRF5 SDK for Thread and Zigbee v4.0.0 includes stack compatability with the Control4 network and the Control4 Hub.
Due to Control4's legacy Zigbee behavior, use zb_permit_control4_network() function to enable interoperability with Control4 in the default version of the stack. This function allows device to catch all packets with the specific Control4 destination key field value in the frame structure. This function does not guarantee the correct behavior of the device in the Control4 network. It only allows the device to come into such network. To use all functionalities of the device in the Control4 network, the Control4 Network cluster must be implemented.
Control4 uses its own profile ZB_AF_CONTROL4_PROFILE_ID. The stack v3.3.0 includes only the alpha version of ZCL Control4 Network cluster.
