Merge branch 'release/esp-zigbee-sdk-v1.5.0' into 'main'

esp-zigbee-sdk: release/v1.5.0(6bd34178)

See merge request espressif/esp-zigbee-sdk!139

RELEASE_NOTES.md

@@ -1,5 +1,40 @@
 # Espressif Zigbee SDK Release Notes
 
+## 27-Aug-2024
+1.5.0 version release of ESP-ZIGBEE-SDK is based on esp-idf v5.1.4
+
+### Features
+- Added support for ZCL OTA upgrade optional header setting
+- Added support for ZCL OTA upgrade frame fragmentation
+- Added support for ZCL light sensor device
+- Added support for ZCL pH measurement cluster
+- Added support for ZCL electrical conductivity measurement cluster
+- Added support for ZCL gateway endpoint without a client cluster to handle report attribute commands
+- Added support for NWK maximum children setting
+
+### Bug Fixes
+- Fixed the issue with syncing ZCL diagnostic cluster attributes with the stack
+- Fixed the crashing issue caused by the RX queue being busy when enabling ZB_RADIO_SPINEL_UART
+- Fixed the unexpected delay in setpoint execution when using the thermostat cluster weekly schedule
+- Fixed the incorrect check for the minimum dead band of the thermostat cluster
+- Fixed the invalid endpoint ID in some core action messages
+
+### Changes
+- Updated esp-zboss-lib to v1.5.0
+- Updated esp-zigbee-lib to v1.5.0
+- Optimized ZCL OTA upgrade rate
+- Deprecated `esp_zb_main_loop_iteration()`; use `esp_zb_stack_main_loop()` instead
+- Unified the MACRO format for the default attributes of carbon dioxide, PM2.5, temperature, flow, and humidity measurement clusters
+
+### Breaking Changes
+- Renamed `esp_zb_window_covering_controller_cluster_create()` to `esp_zb_window_covering_controller_clusters_create()`
+- Renamed `esp_zb_on_off_switch_cfg_cluster_create()` to `esp_zb_on_off_switch_config_cluster_create()`
+- Changed the parameter of `esp_zb_ias_ace_cluster_create()` from `uint8_t` to `esp_zb_ias_ace_cluster_cfg_t *`
+- Changed the parameter of `esp_zb_touchlink_commissioning_cluster_create()` from `void` to `esp_zb_touchlink_commissioning_cfg_t *`
+- Changed the parameter of `esp_zb_diagnostics_cluster_create()` from `void` to `esp_zb_diagnostics_cluster_cfg_t *`
+- Changed the parameter of `esp_zb_price_cluster_create()` from `void` to `esp_zb_price_cluster_cfg_t *`
+
+
 ## 19-Jul-2024
 1.4.1 version release of ESP-ZIGBEE-SDK is based on esp-idf v5.1.4
 

components/esp-zigbee-lib/idf_component.yml

@@ -1,4 +1,4 @@
-version: "1.4.1"
+version: "1.5.0"
 description: esp-zigbee library component
 url: https://github.com/espressif/esp-zigbee-sdk
 dependencies:

components/esp-zigbee-lib/include/esp_zigbee_attribute.h

@@ -558,6 +558,48 @@ esp_err_t esp_zb_analog_output_cluster_add_attr(esp_zb_attribute_list_t *attr_li
  */
 esp_err_t esp_zb_analog_value_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p);
 
+/**
+ * @brief Add an attribute in electrical conductivity measurement cluster.
+ *
+ * @param[in] attr_list A pointer to attribute list @ref esp_zb_attribute_list_s
+ * @param[in] attr_id  An attribute id to be added
+ * @param[in] value_p A pointer to attribute value wants to add
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if attribute is existed or unsupported
+ *
+ */
+esp_err_t esp_zb_ec_measurement_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p);
+
+/**
+ * @brief Add an attribute in pH measurement cluster.
+ *
+ * @param[in] attr_list A pointer to attribute list @ref esp_zb_attribute_list_s
+ * @param[in] attr_id  An attribute id to be added
+ * @param[in] value_p A pointer to attribute value wants to add
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if attribute is existed or unsupported
+ *
+ */
+esp_err_t esp_zb_ph_measurement_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p);
+
+/**
+ * @brief Add an attribute in wind speed measurement cluster.
+ *
+ * @param[in] attr_list A pointer to attribute list @ref esp_zb_attribute_list_s
+ * @param[in] attr_id  An attribute id to be added
+ * @param[in] value_p A pointer to attribute value wants to add
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if attribute is existed or unsupported
+ *
+ */
+esp_err_t esp_zb_wind_speed_measurement_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p);
+
 /**
  * @brief Add an attribute in carbon dioxide measurement cluster.
  *

components/esp-zigbee-lib/include/esp_zigbee_cluster.h

@@ -111,7 +111,7 @@ esp_zb_attribute_list_t *esp_zb_on_off_cluster_create(esp_zb_on_off_cluster_cfg_
  * @return Pointer to attribute list @ref esp_zb_attribute_list_s
  *
  */
-esp_zb_attribute_list_t *esp_zb_on_off_switch_cfg_cluster_create(esp_zb_on_off_switch_cluster_cfg_t *on_off_switch_cfg);
+esp_zb_attribute_list_t *esp_zb_on_off_switch_config_cluster_create(esp_zb_on_off_switch_cluster_cfg_t *on_off_switch_cfg);
 
 /**
  * @brief  Create a standard level cluster attribute list.
@@ -207,12 +207,12 @@ esp_zb_attribute_list_t *esp_zb_ias_zone_cluster_create(esp_zb_ias_zone_cluster_
  * @brief  Create a standard IAS ACE cluster attribute list.
  *
  * @note  This only contains the mandatory attribute.
- * @param[in] zone_table_size Maximum number of entries in the zone table.
+ * @param[in] ias_ace_cfg Configuration parameters for this cluster defined by @ref esp_zb_ias_ace_cluster_cfg_s
  *
  * @return Pointer to attribute list @ref esp_zb_attribute_list_s
  *
  */
-esp_zb_attribute_list_t *esp_zb_ias_ace_cluster_create(uint8_t zone_table_size);
+esp_zb_attribute_list_t *esp_zb_ias_ace_cluster_create(esp_zb_ias_ace_cluster_cfg_t *ias_ace_cfg);
 
 /**
  * @brief  Create a standard IAS WD cluster attribute list.
@@ -323,10 +323,12 @@ esp_zb_attribute_list_t *esp_zb_ota_cluster_create(esp_zb_ota_cluster_cfg_t *ota
  *
  * @note  This only contains the `ZB_ZCL_ATTR_GLOBAL_CLUSTER_REVISION_ID` and touchlink commissioning cluster has no attributes.
  *
+ * @param[in] tl_cfg  Configuration parameters for this cluster defined by @ref esp_zb_touchlink_commissioning_cfg_s
+ *
  * @return pointer to attribute list @ref esp_zb_attribute_list_s
  *
  */
-esp_zb_attribute_list_t *esp_zb_touchlink_commissioning_cluster_create(void);
+esp_zb_attribute_list_t *esp_zb_touchlink_commissioning_cluster_create(esp_zb_touchlink_commissioning_cfg_t *tl_cfg);
 
 /**
  * @brief  Create a standard thermostat cluster attribute list
@@ -388,6 +390,39 @@ esp_zb_attribute_list_t *esp_zb_analog_output_cluster_create(esp_zb_analog_outpu
  */
 esp_zb_attribute_list_t *esp_zb_analog_value_cluster_create(esp_zb_analog_value_cluster_cfg_t *analog_value_cfg);
 
+/**
+ * @brief  Create a standard electrical conductivity measurement cluster attribute list.
+ *
+ * @note  This only contains the mandatory attribute.
+ * @param[in] ec_measurement_cfg  Configuration parameters for this cluster defined by @ref esp_zb_ec_measurement_cluster_cfg_s
+ *
+ * @return Pointer to attribute list @ref esp_zb_attribute_list_s
+ *
+ */
+esp_zb_attribute_list_t *esp_zb_ec_measurement_cluster_create(esp_zb_ec_measurement_cluster_cfg_t *ec_measurement_cfg);
+
+/**
+ * @brief  Create a standard pH measurement cluster attribute list.
+ *
+ * @note  This only contains the mandatory attribute.
+ * @param[in] ph_measurement_cfg  Configuration parameters for this cluster defined by @ref esp_zb_ph_measurement_cluster_cfg_s
+ *
+ * @return Pointer to attribute list @ref esp_zb_attribute_list_s
+ *
+ */
+esp_zb_attribute_list_t *esp_zb_ph_measurement_cluster_create(esp_zb_ph_measurement_cluster_cfg_t *ph_measurement_cfg);
+
+/**
+ * @brief  Create a standard wind speed measurement cluster attribute list.
+ *
+ * @note  This only contains the mandatory attribute.
+ * @param[in] wind_speed_measurement_cfg  Configuration parameters for this cluster defined by @ref esp_zb_wind_speed_measurement_cluster_cfg_s
+ *
+ * @return Pointer to attribute list @ref esp_zb_attribute_list_s
+ *
+ */
+esp_zb_attribute_list_t *esp_zb_wind_speed_measurement_cluster_create(esp_zb_wind_speed_measurement_cluster_cfg_t *wind_speed_measurement_cfg);
+
 /**
  * @brief  Create a standard carbon dioxide measurement attribute list
  *
@@ -431,10 +466,12 @@ esp_zb_attribute_list_t *esp_zb_metering_cluster_create(esp_zb_metering_cluster_
 /**
  * @brief  Create a standard diagnostics attribute list
  *
+ * @param[in] diag_cfg  Configuration parameters for this cluster defined by @ref esp_zb_diagnostics_cluster_cfg_s
+ *
  * @return pointer to attribute list @ref esp_zb_attribute_list_s
  *
  */
-esp_zb_attribute_list_t *esp_zb_diagnostics_cluster_create(void);
+esp_zb_attribute_list_t *esp_zb_diagnostics_cluster_create(esp_zb_diagnostics_cluster_cfg_t *diag_cfg);
 
 /**
  * @brief  Create a standard metering attribute list
@@ -449,10 +486,12 @@ esp_zb_attribute_list_t *esp_zb_meter_identification_cluster_create(esp_zb_meter
 /**
  * @brief  Create a standard metering attribute list
  *
+ * @param[in] price_cfg Configuration parameters for this cluster defined by @ref esp_zb_price_cluster_cfg_s
+ *
  * @return pointer to attribute list @ref esp_zb_attribute_list_s
  *
  */
-esp_zb_attribute_list_t *esp_zb_price_cluster_create(void);
+esp_zb_attribute_list_t *esp_zb_price_cluster_create(esp_zb_price_cluster_cfg_t *price_cfg);
 
 /**************************************** ADD CLUSTER ***********************************/
 /**
@@ -920,6 +959,48 @@ esp_err_t esp_zb_cluster_list_add_analog_output_cluster(esp_zb_cluster_list_t *c
  */
 esp_err_t esp_zb_cluster_list_add_analog_value_cluster(esp_zb_cluster_list_t *cluster_list, esp_zb_attribute_list_t *attr_list, uint8_t role_mask);
 
+/**
+ * @brief Add electrical conductivity measurement cluster (attribute list) in a cluster list.
+ *
+ * @param[in] cluster_list A pointer to cluster list @ref esp_zb_cluster_list_s
+ * @param[in] attr_list  An attribute list which wants to add
+ * @param[in] role_mask  A role of server or client for this cluster (attribute list) refer to esp_zb_zcl_cluster_role_t
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if cluster list not initialized
+ *
+ */
+esp_err_t esp_zb_cluster_list_add_ec_measurement_cluster(esp_zb_cluster_list_t *cluster_list, esp_zb_attribute_list_t *attr_list, uint8_t role_mask);
+
+/**
+ * @brief Add pH measurement cluster (attribute list) in a cluster list.
+ *
+ * @param[in] cluster_list A pointer to cluster list @ref esp_zb_cluster_list_s
+ * @param[in] attr_list  An attribute list which wants to add
+ * @param[in] role_mask  A role of server or client for this cluster (attribute list) refer to esp_zb_zcl_cluster_role_t
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if cluster list not initialized
+ *
+ */
+esp_err_t esp_zb_cluster_list_add_ph_measurement_cluster(esp_zb_cluster_list_t *cluster_list, esp_zb_attribute_list_t *attr_list, uint8_t role_mask);
+
+/**
+ * @brief Add wind speed measurement cluster (attribute list) in a cluster list.
+ *
+ * @param[in] cluster_list A pointer to cluster list @ref esp_zb_cluster_list_s
+ * @param[in] attr_list  An attribute list which wants to add
+ * @param[in] role_mask  A role of server or client for this cluster (attribute list) refer to esp_zb_zcl_cluster_role_t
+ *
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_ARG if cluster list not initialized
+ *
+ */
+esp_err_t esp_zb_cluster_list_add_wind_speed_measurement_cluster(esp_zb_cluster_list_t *cluster_list, esp_zb_attribute_list_t *attr_list, uint8_t role_mask);
+
 /**
  * @brief Add carbon dioxide measurement cluster (attribute list) in a cluster list.
  *

components/esp-zigbee-lib/include/esp_zigbee_core.h

@@ -637,7 +637,7 @@ void esp_zb_zcl_reset_nvram_to_factory_default(void);
  * loaded after esp_zb_start() call.
  *
  * @note Zigbee stack is not looped in this routine. Instead, it schedules callback and returns.  Caller
- * must run  esp_zb_main_loop_iteration() after this routine.
+ * must run  esp_zb_stack_main_loop() after this routine.
  *
  * @note Application should later call Zigbee commissioning initiation - for instance,
  * esp_zb_bdb_start_top_level_commissioning().
@@ -647,6 +647,14 @@ void esp_zb_zcl_reset_nvram_to_factory_default(void);
  */
 esp_err_t esp_zb_start(bool autostart);
 
+/**
+ * @brief Get the stack is started or not.
+ *
+ * @return true if the stack has been started, false otherwise.
+ *
+ */
+bool esp_zb_is_started(void);
+
 /**
  * @brief  Acquire Zigbee lock.
  *
@@ -666,12 +674,28 @@ void esp_zb_lock_release(void);
 /**
  * @brief  Zigbee main loop iteration.
  *
- * @note Must be called after esp_zb_int() and esp_zb_start()
+ * @deprecated Please use esp_zb_stack_main_loop() instead
+ * @note Must be called after esp_zb_init() and esp_zb_start()
    inside the application's main cycle.
  *
  */
+ESP_ZB_DEPRECATED
 void esp_zb_main_loop_iteration(void);
 
+/**
+ * @brief Zigbee stack main loop iteration once.
+ *
+ * @note Must be called after esp_zb_init() and esp_zb_start().
+ */
+void esp_zb_stack_main_loop_iteration(void);
+
+/**
+ * @brief  Zigbee stack main loop.
+ *
+ * @note Must be called after esp_zb_init() and esp_zb_start(), it’s an infinite main loop.
+ */
+void esp_zb_stack_main_loop(void);
+
 /**
  * @brief  Zigbee CLI example main loop iteration.
  *

components/esp-zigbee-lib/include/esp_zigbee_ota.h

@@ -28,6 +28,19 @@ typedef struct esp_zb_ota_zcl_information_s {
     uint16_t manufacturer_specific;     /*!< The manufacturer specific  data */
 } esp_zb_ota_zcl_information_t;
 
+/**
+ * @brief The ZCL ota upgrade header optional structure
+ *
+ */
+typedef struct esp_zb_ota_file_optional_s {
+    uint8_t security_credential_version;        /*!< Indicate security credential version type such as SE1.0 or SE2.0 that the client
+                                                     is required to have, before it SHALL install the image. */
+    esp_zb_ieee_addr_t upgrade_file_destination;/*!< Indicates that this OTA file contains security credential/certificate data or
+                                                     other type of information that is specific to a particular device.*/
+    uint16_t minimum_hardware_version;          /*!< Represent the earliest hardware platform version this image SHOULD be used on. */
+    uint16_t maximum_hardware_version;          /*!< Represent the latest hardware platform version this image SHOULD be used on. */
+} esp_zb_ota_file_optional_t;
+
 /**
  * @brief The Zigbee ZCL OTA file header struct.
  *
@@ -37,6 +50,8 @@ typedef struct esp_zb_ota_file_header_s {
     uint16_t image_type;                       /*!< Image type value to distinguish the products */
     uint32_t file_version;                     /*!< File version represents the release and build number of the image’s application and stack */
     uint32_t image_size;                       /*!< Total image size in bytes transferred from the server to the client */
+    uint16_t field_control;                    /*!< Indicate whether additional optional information */
+    esp_zb_ota_file_optional_t optional;       /*!< The optional header controlled by the filed contorl, @see esp_zb_ota_file_optional_t */
 } esp_zb_ota_file_header_t;
 
 /**