Configuring Zigbee libraries in nRF Connect SDK

The Zigbee protocol in nRF Connect SDK can be customized by enabling and configuring several Zigbee libraries. This page lists options and steps required for configuring each of them.

Configuring ZBOSS OSIF

The Zigbee ZBOSS OSIF layer subsystem acts as the linking layer between the ZBOSS Zigbee stack and the nRF Connect SDK. The layer is automatically enabled when you enable the ZBOSS library with the CONFIG_ZIGBEE Kconfig option.

For more information about the library, see Zigbee ZBOSS OSIF.

Configuring Zigbee application utilities

The Zigbee application utilities library provides a set of components that are ready for use in Zigbee applications.

To enable and use this library, set the CONFIG_ZIGBEE_APP_UTILS Kconfig option.

For additional logs for this library, configure the CONFIG_ZIGBEE_APP_UTILS_LOG_LEVEL Kconfig option. See Zephyr’s logger options for more information.

Default signal handler

The default signal handler provides the default logic for handling ZBOSS stack signals. For more information, see Zigbee default signal handler.

After enabling the Zigbee application utilities library, you can use this component by calling the zigbee_default_signal_handler() in the application’s zboss_signal_handler() implementation.

Configuring Zigbee error handler

The Zigbee error handler library provides a set of macros that can be used to assert on nrfxlib’s Zigbee ZBOSS stack API return codes.

To use this library, include its zigbee_error_handler.h header in your application and pass the error code that should be checked using its macros.

For more information about the library, see Zigbee error handler.

Configuring Zigbee FOTA

The Zigbee Over The Air Device Firmware Upgrade (Zigbee FOTA) library provides a mechanism to upgrade the firmware of the device through the Zigbee network.

To enable and configure the library, you must set the CONFIG_ZIGBEE_FOTA Kconfig option. Other Zigbee FOTA Kconfig options can be used with default values.

Because the Zigbee OTA DFU performs the upgrade using the DFU target library, the are several non-Zigbee options that must be set to configure the update process:

Configuring these options and updating the default values (at least updating the image_version to the application version) allows you to use Zigbee FOTA in the Zigbee: Light switch sample. Alternatively, you can use overlay-fota.conf file during the sample building process.

Enabling Zigbee FOTA in an application

If you want to use the Zigbee FOTA functionality in your application, you must add several code snippets to its main file:

  • Because the Zigbee OTA DFU library provides only the definition of the OTA endpoint, the application has to include it inside the device context:

    #include <zigbee_fota.h>
extern zb_af_endpoint_desc_t ota_upgrade_client_ep;
ZBOSS_DECLARE_DEVICE_CTX_2_EP(<your_device>_ctx, ota_upgrade_client_ep, <your_application>_ep);

  • The application is informed about the update status though a callback. The callback must reboot the device once the firmware update is completed:

    static void ota_evt_handler(const struct zigbee_fota_evt *evt)
{
    switch (evt->id) {
    case ZIGBEE_FOTA_EVT_FINISHED:
        LOG_INF("Reboot application.");
        sys_reboot(SYS_REBOOT_COLD);
        break;
    }
}

  • Apart from the library initialization, the application must pass ZCL events to the Zigbee FOTA library. If the application does not implement additional ZCL event handlers, the Zigbee FOTA handler may be passed directly to the ZBOSS stack:

    /* Initialize Zigbee FOTA download service. */
zigbee_fota_init(ota_evt_handler);
/* Register callback for handling ZCL commands. */
ZB_ZCL_REGISTER_DEVICE_CB(zigbee_fota_zcl_cb);

  • The periodical OTA server discovery must be started from the signal handler. The application should pass the received signals to the Zigbee FOTA library:

    void zboss_signal_handler(zb_bufid_t bufid)
{
    /* Pass signal to the OTA client implementation. */
    zigbee_fota_signal_handler(bufid);
    ...

  • To inform the MCUboot about successful device firmware upgrade, the application must call the following function once it is sure that all intended functionalities work after the upgrade:

    boot_write_img_confirmed();

See the samples/zigbee/light_switch/src/main.c file of the Zigbee: Light switch sample for an example implementation of the Zigbee FOTA in an application.

Options for generating Zigbee FOTA upgrade image

By enabling the Zigbee OTA DFU, the west tool will automatically generate the upgrade image. To specify the target device of the generated image, use the following Kconfig options:

The manufacturer ID, image type and version of the generated image are obtained from the application settings.

The upgrade image will be created in a dedicated directory in the build/zephyr/ directory.

Configuring Zigbee endpoint logger

The Zigbee endpoint logger library provides an endpoint handler for parsing and logging incoming ZCL frames with all their fields.

To enable the endpoint logger library in your application, complete the following steps:

  1. Enable the library by setting the CONFIG_ZIGBEE_LOGGER_EP Kconfig option.

  2. Define the logging level for the library by setting the CONFIG_ZIGBEE_LOGGER_EP_LOG_LEVEL Kconfig option. See Zephyr’s logger options for more information.

  3. Include the required header file include/zigbee/zigbee_logger_eprxzcl.h into your project.

  4. Register zigbee_logger_eprxzcl_ep_handler() as handler for the given your_ep_number endpoint using ZB_AF_SET_ENDPOINT_HANDLER, after the device context is registered with ZB_AF_REGISTER_DEVICE_CTX, but before starting the Zigbee stack:

    ZB_AF_REGISTER_DEVICE_CTX(&your_device_ctx);
ZB_AF_SET_ENDPOINT_HANDLER(your_ep_number, zigbee_logger_eprxzcl_ep_handler);

    For applications that implement multiple handlers, zigbee_logger_eprxzcl_ep_handler() can be registered as handler for each endpoint.

    Note

    If Zigbee shell is already enabled and configured for the given endpoint, set the CONFIG_ZIGBEE_SHELL_DEBUG_CMD Kconfig option to enable the endpoint logger instead of registering a handler. This is because the Zigbee shell library registers its own handler for the endpoint.

For more information about the library, see Zigbee endpoint logger.

Configuring Zigbee ZCL scene helper

The Zigbee ZCL scene helper library provides a set of functions that implement the callbacks required by the ZCL scene cluster in the application.

To enable the Zigbee ZCL scene helper library, set the CONFIG_ZIGBEE_SCENES Kconfig option.

Because the library uses Zephyr’s Settings subsystem, the application must call the following functions for the library to work correctly:

For more information about the library, see Zigbee ZCL scene helper.

Configuring Zigbee shell

The Zigbee shell library implements a set of Zigbee shell commands that can be used with all Zigbee samples for testing and debugging.

You can add support for Zigbee shell commands to any of the available Zigbee samples, except for the NCP sample. Some of the commands use an endpoint for sending packets, so no endpoint handler is allowed to be registered for this endpoint.

To extend a sample with the Zigbee shell command support, set the following Kconfig options:

  • CONFIG_ZIGBEE_SHELL - This option enables Zigbee shell and Zephyr’s Shell.

  • CONFIG_ZIGBEE_SHELL_ENDPOINT - This option specifies the endpoint number to be used by the Zigbee shell instance. The endpoint must be present at the device and you must not register an endpoint handler for this endpoint.

  • CONFIG_ZIGBEE_SHELL_DEBUG_CMD - This option enables commands useful for testing and debugging. This option also enables logging of the incoming ZCL frames. Logging of the incoming ZCL frames uses the logging level set in CONFIG_ZIGBEE_LOGGER_EP_LOG_LEVEL.

    Note

    Using debug commands can make the device unstable.

  • CONFIG_ZIGBEE_SHELL_LOG_LEVEL - This option sets the logging level for Zigbee shell logs. See Zephyr’s logger options for more information.