Configuring Zigbee in nRF Connect SDK

Note

Support for Zigbee R22 has been deprecated in nRF Connect SDK v2.8.0 and it will be removed in one of the future releases, following the deprecation policy. As a result, the nRF52833, nRF52840 and nRF5340 SoCs are not recommended for new Zigbee designs. Experimental support for Zigbee R23 is available for the nRF54L Series as an nRF Connect SDK Add-on.

This page describes what is needed to start working with Zigbee in the nRF Connect SDK.

Required libraries and drivers

Zigbee requires the following modules to properly operate in the nRF Connect SDK:

Mandatory configuration

To use the Zigbee protocol, set the CONFIG_ZIGBEE Kconfig option. Setting this option enables all the peripherals required for the correct operation of the Zigbee protocol and allows you to use them.

After that, you have to define the Zigbee device role for the Zigbee application or sample by setting one of the following Kconfig options:

Setting any of these options enables the respective ZBOSS role library. This is needed because End Devices use different libraries than Routers and Coordinators.

For instructions about how to set Kconfig options, see Configuring and building.

Sleepy End Device behavior

The Sleepy End Device (SED) behavior is a Zigbee stack feature that enables the sleepy behavior for the end device.

By default, the end device regularly polls its parent for data. When the SED behavior is enabled and no frames are available for reception after the last poll, the SED disables its radio until the next scheduled poll. The Zigbee stack’s own scheduler informs the application about periods of time when nothing is scheduled for any of the device roles. This allows the stack to enter the sleep state during these periods, which also powers off some peripherals for the SED.

When the Zigbee stack thread goes to sleep, the Zigbee thread can enter the suspend state for the same amount of time as the stack’s sleep. The thread will be automatically resumed after the sleep period is over or on an event.

For this feature to work, make sure to call the zb_set_rx_on_when_idle() ZBOSS API, as described in Configuring sleepy behavior for end devices in the ZBOSS documentation. This feature does not require enabling any additional options in Kconfig.

In the Zigbee light switch sample in the nRF Connect SDK, after you enable the SED behavior extension, the sleepy behavior can be triggered by pressing a predefined button when the device is booting. This action results in calling the ZBOSS API that activates this feature.

Power saving during sleep

With the sleepy behavior enabled, the unused part of RAM memory is powered off, which allows to lower the power consumption even more. The sleep current of MCU can be lowered to about 1.8 uA by completing the following steps:

  1. Turn off UART by setting CONFIG_SERIAL to n.

  2. For current measurements for the nRF52840 DK (PCA10056), the nRF52833 DK (PCA10100), or the nRF5340 (PCA10095), set SW6 to nRF ONLY position to get the desired results.

  3. Enable the CONFIG_RAM_POWER_DOWN_LIBRARY Kconfig option.

Optional configuration

After enabling the Zigbee protocol and defining the Zigbee device role, you can enable additional options in Kconfig and modify ZBOSS stack start options.

Device operational channel

You can enable one of the following alternative options to select the channel on which the Zigbee device can operate:

IEEE 802.15.4 EUI-64 configuration

The Zigbee stack uses the EUI-64 address that is configured in the IEEE 802.15.4 shim layer. By default, it uses an address from Nordic Semiconductor’s pool.

If your devices should use a different address, you can change the address according to your company’s addressing scheme.

An IEEE EUI-64 address consists of two parts:

  • Company ID - a 24-bit MA-L (MAC Address Block Large), formerly called OUI (Organizationally Unique Identifier)

  • Extension identifier - a 40-bit device unique identifier

You can configure the EUI-64 for a device in the following ways:

Use the default

By default, the company ID is set to Nordic Semiconductor’s MA-L (f4-ce-36). The extension identifier is set to the DEVICEID from the factory information configuration registers (FICR).

Replace the company ID

You can enable CONFIG_IEEE802154_VENDOR_OUI_ENABLE to replace Nordic Semiconductor’s company ID with your own company ID. Specify your company ID in CONFIG_IEEE802154_VENDOR_OUI.

The extension identifier is set to the default, namely the DEVICEID from FICR.

Replace the full EUI-64

You can provide the full EUI-64 value by programming certain user information configuration registers (UICR). For nRF52 Series devices, the CUSTOMER registers block is used. For nRF53 Series devices, the OTP registers block is used.

To use the EUI-64 value from the UICR, enable CONFIG_IEEE802154_NRF5_UICR_EUI64_ENABLE and set CONFIG_IEEE802154_NRF5_UICR_EUI64_REG to the base of the two consecutive registers that contain your EUI-64 value.

The following example shows how to replace the full EUI-64 on an nRF52840 device:

  1. Enable CONFIG_IEEE802154_NRF5_UICR_EUI64_ENABLE.

  2. Specify the offset for the UICR registers in CONFIG_IEEE802154_NRF5_UICR_EUI64_REG. This example uses UICR->CUSTOMER[0] and UICR->CUSTOMER[1], which means that you can keep the default value 0.

  3. Build and program your application erasing the whole memory (replace serial_number with the serial number of your debugger):

     west build -b nrf52840dk/nrf52840 -p always
 west flash --snr serial_number --erase

  4. Program the registers UICR->CUSTOMER[0] and UICR->CUSTOMER[1] with your EUI-64 value (replace serial_number with the serial number of your debugger):

     nrfjprog --snr serial_number --memwr 0x10001080 --val 0x11223344
 nrfjprog --snr serial_number --memwr 0x10001084 --val 0x55667788
 nrfjprog --snr serial_number --reset

    If you used a different value for CONFIG_IEEE802154_NRF5_UICR_EUI64_REG, you must use different register addresses.

At the end of the configuration process, you can check the EUI-64 value using Zigbee shell:

> zdo eui64
8877665544332211
Done

Note

Alternatively, you may use the Production Configuration feature to change the address. The Production Configuration takes precedence over the shim’s configuration.

ZBOSS stack start options

Zigbee is initialized after Zephyr’s kernel start. The ZBOSS stack can be started using one of the following options:

The dedicated thread can be configured using the following options:

Custom logging per module

Logging is handled with the CONFIG_LOG option. This option enables logging for both the stack and Zephyr’s Logging API.

Default Zigbee application logging

The Zigbee application uses the INF logging level by default. This level can be changed only by modifying the sample code.

Stack logs

The stack logs are independent from Zephyr’s Logging API. To customize them, use the following options:

  • CONFIG_ZBOSS_ERROR_PRINT_TO_LOG - Allows the application to log ZBOSS error names; enabled by default.

  • CONFIG_ZBOSS_TRACE_MASK - Sets the modules from which ZBOSS will log the debug messages with CONFIG_ZBOSS_TRACE_LOG_LEVEL; no module is set by default.

  • CONFIG_ZBOSS_TRAF_DUMP - Enables logging of the received 802.15.4 frames over ZBOSS trace log if CONFIG_ZBOSS_TRACE_LOG_LEVEL is set; disabled by default.

The stack logs are provided in a binary format and you can configure how they are printed:

  • CONFIG_ZBOSS_TRACE_HEXDUMP_LOGGING - Stack logs are printed as hexdump using Zephyr’s Logging. This option is enabled by default.

  • CONFIG_ZBOSS_TRACE_BINARY_LOGGING - Stack logs are printed in the binary format using one of the following independent serial backends of your choice:

    To specify the serial device, you need to set the ncs,zboss-trace-uart choice in devicetree like this:

    chosen {
    ncs,zboss-trace-uart = &uart1;
};

    Note

    When you select CONFIG_ZBOSS_TRACE_USB_CDC_LOGGING, the USB peripheral is enabled and the USB CDC serial is configured as a part of the zb_osif_serial_logger_init() function. The application does not wait for the connection to be established and unreceived data is lost. For this reason, start collecting the data as soon as you need to.

    See CDC ACM for more information about how to configure USB CDC ACM instance for logging ZBOSS trace messages.

  • CONFIG_ZBOSS_TRACE_BINARY_NCP_TRANSPORT_LOGGING - Stack logs are printed in the binary format using the NCP transport channel.

Stack logs are stored in the internal buffer if they are printed using Zephyr’s Logging or the independent serial backend. You can customize the buffer size with the CONFIG_ZBOSS_TRACE_LOGGER_BUFFER_SIZE. The buffer size must be larger than 256 and smaller than 2147483648. If NCP transport channel is used, stack logs are stored in the buffer used for NCP transport, which size can be configured with CONFIG_ZIGBEE_UART_TX_BUF_LEN.

Zephyr’s logger options

You can configure custom logger options for each Zigbee and ZBOSS module. To do this, configure the related Kconfig option for one or more modules:

For each of the modules, you can set the following logging options:

  • LOG_LEVEL_OFF - Turns off logging for this module.

  • LOG_LEVEL_ERR - Enables logging only for errors.

  • LOG_LEVEL_WRN - Enables logging for errors and warnings.

  • LOG_LEVEL_INF - Enables logging for informational messages, errors, and warnings.

  • LOG_LEVEL_DBG - Enables logging for debug messages, informational messages, errors, and warnings.

For example, setting CONFIG_ZBOSS_TRACE_LOG_LEVEL_INF will enable logging of informational messages, errors, and warnings for the ZBOSS Trace module.

Reduced power consumption

You can reduce the amount of power used by your device by enabling the RAM power-down library. This library is also used for Power saving during sleep.

Upgrading Zigbee application

When upgrading the Zigbee application, use the Static and dynamic configuration of the Partition Manager to ensure that ZBOSS’ NVRAM is placed in the same area of flash. This is because enabling additional features (for example, Zephyr’s Non-Volatile Storage (NVS)) can change the placement of the partition in the flash and the ZBOSS settings can be lost, as the application is not able to find the partition.

The static configuration is required regardless of the application version and the upgrading method (Zigbee FOTA or Secure bootloader chain).