Configuring Zigbee libraries

The Zigbee protocol in the Zigbee add-on for the 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.

For details about the Kconfig options mentioned here, see the Kconfig search in the nRF Connect SDK documentation.

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_ADD_ON 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_CHOICE 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 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_CHOICE 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:

  • zcl_scenes_init()

  • zcl_scenes_cb()

  • settings_subsys_init()

  • settings_load()

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. 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 interface.

  • 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 with the CONFIG_ZIGBEE_LOGGER_EP_LOG_LEVEL_CHOICE Kconfig option.

    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.