Zigbee ZCL scene helper

Note

Zigbee R22 is currently in maintenance mode, and it is not recommended to use it for new Zigbee designs. While critical bug fixes and security updates will be provided as necessary, it will not receive any enhancements or new features. The Zigbee R23 add-on represents Nordic’s primary solution for future Zigbee developments, offering improvements, support for new features, and support for the nRF52840 SoC and new platforms such as the nRF54L series.

The Zigbee ZCL scene helper library provides a set of functions that implement the callbacks required by the ZCL scene cluster in the application. You can use this library to implement these mandatory callbacks and save the configured scenes in the non-volatile memory. For this purpose, it uses Zephyr’s Settings subsystem.

This library is capable of recalling attribute values for the following ZCL clusters:

• On/off

• Level control

• Window covering

If you are implementing clusters that are not included in this list, you must implement their logic manually instead of using this library.

Configuration

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()

You must implement these functions in the following manner:

• settings_subsys_init() must be called before zcl_scenes_init()

• settings_load() must be called after zcl_scenes_init()

• zcl_scenes_cb() must be called in the ZCL device callback:

  static void zcl_device_cb(zb_bufid_t bufid)
  {
     zb_zcl_device_callback_param_t  *device_cb_param =
        ZB_BUF_GET_PARAM(bufid, zb_zcl_device_callback_param_t);
     switch (device_cb_param->device_cb_id) {
     ...
     default:
        if (zcl_scenes_cb(bufid) == ZB_FALSE) {
              device_cb_param->status = RET_ERROR;
        }
        break;
     }
  }
  

Setting the CONFIG_ZIGBEE_SCENES Kconfig option allows you to configure the following library-specific Kconfig options:

• CONFIG_ZIGBEE_SCENES_ENDPOINT - This option sets the endpoint number on which the device implements the ZCL scene cluster.

• CONFIG_ZIGBEE_SCENE_TABLE_SIZE - This option sets the value for the number of scenes that can be configured.

To configure the logging level of the library, use the CONFIG_ZIGBEE_SCENES_LOG_LEVEL Kconfig option.

API documentation

Header file: include/zigbee/zigbee_zcl_scenes.h

Source file: subsys/zigbee/lib/zigbee_scenes/zigbee_zcl_scenes.c

group Zigbee ZCL scenes helper library.

Library for handling ZCL scenes events for common clusters.

Provides ZCL callback event processing function that handles ZCL scenes commands.

Functions

void zcl_scenes_init(void)

Initialize the Zigbee ZCL scenes helper library.

This function initializes the ZCL scene table as well as registers the settings observer for restoring scene table entries.

zb_bool_t zcl_scenes_cb(zb_bufid_t bufid)

Function for passing ZCL callback events to the scenes helper library logic.

Parameters:

bufid – [in] Reference to the Zigbee stack buffer used to pass event.

Return values:

• ZB_TRUE – if the event was handled by the library

• ZB_FALSE – if the event was not handled by the library