4.1.6. Compatibility Layer

The compatibility layer is a set of definitions, macros and functions that are used to bridge the gap between the v1.x and v2.x APIs. It is used to ensure that the project based on v1.x can run correctly with v2.x SDK. The headers of the compatibility layer are in the include/compat directory.

Note

The ABI compatibility is NOT guaranteed. The compatibility layer is provided for quick evaluation of the v2.x SDK. It is not recommended to be used in production code.

4.1.6.1. Required Migration Steps

The following changes are required to migrate a project from v1.x to v2.x using the compatibility layer:

Enable the compatibility layer by setting ZB_SDK_1xx to y in idf.pymenuconfig or adding CONFIG_ZB_SDK_1xx=y to the sdkconfig.defaults file.
Change the subtype of zb_storage partition in the partitions.csv file from fat to nvs.
Initialize the zb_storage partition as NVS storage by calling nvs_flash_init_partition("zb_storage").

4.1.6.2. Behavioral Changes

Though the compatibility layer is designed to be API compatible and keep the same behavior as v1.x as much as possible, there are still some behavioral changes introduced due to the different implementation of the Zigbee core stack in v2.x.

esp_zigbee_core.h
- esp_zb_main_loop_iteration() has been deprecated and removed.
- esp_zb_stack_main_loop_iteration() is no longer supported, it is defined as an empty macro.
- esp_zb_nvram_erase_at_start() is no longer supported, it is defined as an empty macro.
- esp_zb_scheduler_queue_size_set() is no longer used, it is defined as an empty macro.
- The light sleep is now controlled by the ESP-IDF configuration: CONFIG_FREERTOS_USE_TICKLESS_IDLE and CONFIG_PM_ENABLE, so the following functions are no longer used and defined as empty macros:
  esp_zb_sleep_is_enable()
  
  esp_zb_sleep_enable()
  
  esp_zb_sleep_now()
  
  esp_zb_sleep_set_threshold()
- The power source and transfer size fields in the Zigbee node descriptor are now generated according to the device's settings, so the following functions are no longer used and defined as empty macros:
  esp_zb_set_node_descriptor_power_source()
  
  esp_zb_set_node_descriptor_transfer_size()
- The BDB related functions are moved to bdb/esp_zigbee_bdb_commissioning.h :
  esp_zb_set_primary_network_channel_set()
  
  esp_zb_get_primary_network_channel_set()
  
  esp_zb_set_secondary_network_channel_set()
  
  esp_zb_get_secondary_network_channel_set()
  
  esp_zb_bdb_is_factory_new()
  
  esp_zb_bdb_get_scan_duration()
  
  esp_zb_bdb_set_scan_duration()
  
  esp_zb_bdb_open_network()
  
  esp_zb_bdb_close_network()
  
  esp_zb_bdb_dev_joined()
  
  esp_zb_bdb_start_top_level_commissioning()
  
  esp_zb_bdb_reset_via_local_action()
  
  esp_zb_set_bdb_commissioning_mode()
  
  esp_zb_get_bdb_commissioning_mode()
  
  esp_zb_bdb_cancel_steering()
  
  esp_zb_bdb_cancel_formation()
  
  esp_zb_get_bdb_commissioning_status()
- The ZDO signal related symbols are moved to zdo/esp_zigbee_zdo_common.h :
  esp_zb_app_signal_handler()
  
  esp_zb_app_signal_get_params()
zdo/esp_zigbee_zdo_common.h
- The following signals though provided, will never be generated by the Zigbee stack in v2.x:
  ESP_ZB_ZDO_SIGNAL_DEFAULT_START
  
  ESP_ZB_ZDO_SIGNAL_ERROR
  
  ESP_ZB_ZDO_SIGNAL_PRODUCTION_CONFIG_READY
  
  ESP_ZB_COMMON_SIGNAL_CAN_SLEEP
  
  ESP_ZB_BDB_SIGNAL_STEERING_CANCELLED
  
  ESP_ZB_BDB_SIGNAL_FORMATION_CANCELLED
  
  ESP_ZB_BDB_SIGNAL_TC_REJOIN_DONE
  
  ESP_ZB_BDB_SIGNAL_TOUCHLINK_NWK_STARTED
  
  ESP_ZB_BDB_SIGNAL_TOUCHLINK_NWK_JOINED_ROUTER
  
  ESP_ZB_BDB_SIGNAL_TOUCHLINK_TARGET
  
  ESP_ZB_BDB_SIGNAL_TOUCHLINK_NWK
  
  ESP_ZB_ZGP_SIGNAL_COMMISSIONING
  
  ESP_ZB_ZGP_SIGNAL_MODE_CHANGE
  
  ESP_ZB_ZGP_SIGNAL_APPROVE_COMMISSIONING
esp_zigbee_secur.h
- The multiple global link key is not supported yet, so the following functions are defined as ESP_ERR_NOT_SUPPORTED.
  esp_zb_secur_multi_TC_standard_preconfigure_key_add()
  
  esp_zb_secur_multi_TC_standard_preconfigure_key_remove()
  
  esp_zb_secur_multi_standard_distributed_key_add()
  
  esp_zb_secur_multi_standard_distributed_key_remove()
- The Install Code from string is no longer supported, so the following functions are defined as ESP_ERR_NOT_SUPPORTED.
  esp_zb_secur_ic_str_add()
  
  esp_zb_secur_ic_str_set()
aps/esp_zigbee_aps.h
- The following functions are no longer supported, they will always return ESP_ERR_NOT_SUPPORTED.
  esp_zb_apsme_transport_key_request()
  
  esp_zb_apsme_switch_key_request()
platform/esp_zigbee_platform.h
- The following functions are moved to nwk/esp_zigbee_nwk.h :
  esp_zb_set_default_long_poll_interval()
  
  esp_zb_get_default_long_poll_interval()
- The following functions are moved to mac/esp_zigbee_mac.h :
  esp_zb_platform_mac_config_set()
  
  esp_zb_platform_mac_config_get()
- esp_zb_mac_raw_frame_callback_t and esp_zb_mac_raw_frame_handler_register() are removed, they are not supported in v2.x.
The following headers are removed:
- esp_zigbee_trace.h
- zgp/esp_zigbee_zgp.h
- zgp/esp_zigbee_zgpd.h
- zgp/esp_zigbee_zgps.h
zcl/esp_zigbee_zcl_core.h
- The ZCL framework is redesigned in v2.x, so the following functions are defined as empty function or ESP_ERR_NOT_SUPPORTED:
  esp_zb_device_cb_id_handler_register()
  
  esp_zb_zcl_add_privilege_command()
  
  esp_zb_zcl_delete_privilege_command()
  
  esp_zb_identify_notify_handler_register(), please handle the attribute change of the identify cluster.
  
  esp_zb_raw_command_handler_register(), please use ezb_zcl_raw_command_handler_register() instead.
esp_zigbee_cluster.h
- esp_zb_cluster_list_update_{cluster_name}_cluster() are deprecated and removed.
zcl/esp_zigbee_zcl_command.h
- esp_zb_zcl_scenes_table_clear_by_index() defined as ESP_ERR_NOT_SUPPORTED.
Due to the limitations of the ESP Zigbee SDK v2.x, some clusters are not provided in the compatibility layer:
- The following clusters are only provided via v2.x APIs:
  ias_zone
  
  ias_ace
  
  ias_wd
  
  electrical_measurement
  
  ota_update
- The following clusters are not supported yet in v2.x:
  commissioning
  
  diagnostics
  
  drlc
  
  green_power