The nRF5 SDK for Thread and Zigbee provides several helper functions that are intended to facilitate the end user application implementation. They implement the default behavior of a Zigbee device and are used in the Zigbee examples in this SDK.
The Zigbee default signal handler is a function called from the zboss_signal_handler() function that is mandatory for each application.
Because most of Zigbee devices behave in a similar way, zigbee_default_signal_handler() was introduced to provide a default logic to handle stack signals.
As a result, the minimal implementation of zboss_signal_handler includes only a call to the default signal handler:
With this call, the device will be able to join the Zigbee network or join a new network when it leaves the previous one.
In general, using the default signal handler is worth considering, because of the following reasons:
Apart from that, the default signal handler serves as a good starting point for a custom signal handler implementation.
In its complete implementation, the zboss_signal_handler
allows the application to control a broader set of basic functionalities, including joining, commissioning, and network formation.
There are in fact cases in which the default handler will not be sufficient and needs to be extended. For example, when the application wants to use the procedure of the initiator of finding & binding or use the production configuration feature.
If the application wants to change or extend the default behavior, use a switch-case statement and then the default signal handler inside the default case:
Whenever zigbee_default_signal_handler() is used, the stack should be started using a call to zboss_start_no_autostart():
The reason for this is that although the Zigbee stack provides some automatic initialization procedure with zboss_start(), the default signal handler requires the application to start the stack without those mechanisms.
Starting the stack with zboss_start_no_autostart() has the following advantages:
When the stack is started through zboss_start_no_autostart(), the stack generates the following signals:
The reception of these signals determines the behavior of the default signal handler:
Once the BDB initialization procedure is finished, depending on the data stored inside the Zigbee persistent storage, the stack will complete one of the following scenarios:
Both scenarios will cause different behavior of the the default signal handler.
For factory new devices, the default signal handler will:
start_network_rejoin()
to start the Zigbee network rejoining on routers and end devices. Once the procedure is started, the device tries to join the network until cancellation. Each try takes place after a longer period of waiting time, for a total maximum of 15 minutes. Devices may behave differently because the implementation of start_network_rejoin()
is different for different Zigbee roles. See Zigbee network rejoining for more information.Once handling of the signal is finished, the stack will generate the ZB_BDB_SIGNAL_STEERING signal, and will continue to Zigbee network formation and commissioning.
For devices that have been already commissioned, the default handler will:
start_network_rejoin()
.Once finished, the stack will generate the ZB_BDB_SIGNAL_STEERING signal, and continue to Zigbee network formation and commissioning.
According to the logic implemented inside the default signal handler, the devices can either form a network or join an existing network:
The default signal handler implements the same behaviour for handling ZB_ZDO_SIGNAL_LEAVE for both routers and end devices. When leaving the network, the default handler calls start_network_rejoin()
to start Zigbee network rejoining to join a new network.
Once start_network_rejoin()
is called, the stack will generate the ZB_BDB_SIGNAL_STEERING signal and will continue to Zigbee network formation and commissioning.
The Zigee network rejoin procedure is a mechanism that is similar to the ZDO rejoin backoff procedure. It is implemented to work with both routers and end devices and simplify handling of cases such as device joining, rejoining, or leaving the network. It is used in default_signal_handler() by default.
If the network is left by a router or an end device, the device will try to join any open network.
user_input_indicate()
, but it needs to be implemented in the application (for example, by calling user_input_indicate() when a button is pressed). The procedure will be restarted only if the device does not join and the procedure is not running.The Zigbee rejoin procedure retries to join a network with each try after a specified amount of time: 2^n seconds, where n
is the number of retries. The period is limited to 15 minutes if the result is higher than that.
start_network_rejoin()
is called, the rejoin procedure is started and depending on the device role:stop_network_rejoin(ZB_TRUE)
, to be called after the amount of time specified in ZB_DEV_REJOIN_TIMEOUT_MS
. Once called, the alarm stops the rejoin.stop_network_rejoin(was_scheduled)
is called, the network rejoin is cancelled and the alarms scheduled by start_network_rejoin()
are cancelled.stop_network_rejoin()
is called with was_scheduled
set to ZB_TRUE
, user_input_indicate()
can restart the rejoin procedure.user_input_indicate()
restarts the rejoin procedure if the device did not join the network and is not trying to join a network. It is safe to call this function from an interrupt and to call it multiple times.user_input_indicate()
must not be called.The Zigbee stack provides the following mechanisms to reduce power consumption:
On Zigbee sleepy end devices, the sleep_threshold period lasts approximately 15 ms by default and can be modified by using the zb_sleep_set_threshold API.
If the device implements a Zigbee sleepy end device, the ZB_COMMON_SIGNAL_CAN_SLEEP signal is generated whenever the device can be put into the deep sleep mode. This signal can also be handled using the Zigbee default signal handler. If so, it will allow the Zigbee stack to enter the deep sleep state.
If the default behavior is not applicable for the application, you can customize the sleep functionality by using the following options: