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

release/esp-zigbee-sdk-v1.3.0(a824e1a1)

Closes TZ-769, TZ-793, TZ-738, TZ-754, TZ-781, and TZ-808

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

RELEASE_NOTES.md

@@ -1,5 +1,29 @@
 # Espressif Zigbee SDK Release Notes
 
+## 26-Apr-2024
+1.3.0 version release of ESP-ZIGBEE-SDK is based on esp-idf v5.1.3
+
+### Features
+- Updated esp-zboss-lib to v1.3.0
+- Updated esp-zigbee-lib to v1.3.0
+- Supported ZCL commissioning cluster
+- Supported devive sleep before join network
+- Supported the parameter of pointer type for scheduler_alarm
+- Supported event fd setting in application
+
+### Bug Fixes
+- Fixed the transition id checking for touchlink identify command
+- Fixed the zdo binding user callback
+- Disabled response default command for broadcasted frame
+- Closes: https://github.com/espressif/esp-zigbee-sdk/issues/276
+- Closes: https://github.com/espressif/esp-zigbee-sdk/issues/310
+- Closes: https://github.com/espressif/esp-zigbee-sdk/issues/314
+- Closes: https://github.com/espressif/esp-zigbee-sdk/issues/318
+- Closes: https://github.com/espressif/esp-zigbee-sdk/issues/325
+
+### Break Changes
+- Renamed `esp_zb_radio_mode_t`, `esp_zb_host_connection_mode_t`, `zb_esp_uart_init_mode` and `esp_zb_serial_mode_t`
+
 ## 12-Apr-2024
 1.2.3 version release of ESP-ZIGBEE-SDK is based on esp-idf v5.1.3
 

components/esp-zigbee-lib/idf_component.yml

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

components/esp-zigbee-lib/include/cli/zb_esp_cli.h

@@ -120,6 +120,12 @@ bool esp_zb_cli_agent_ep_handler_report(uint8_t bufid);
  */
 bool esp_zb_cli_agent_ep_handler_ping(uint8_t bufid);
 
+/**
+ * @brief Register the esp zigbee cli command
+ *
+ */
+void zb_cli_register_command(void);
+
 #ifdef __cplusplus
 }
 #endif

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

@@ -242,6 +242,20 @@ esp_err_t esp_zb_time_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint1
  */
 esp_err_t esp_zb_binary_input_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p);
 
+/**
+ * @brief Add an attribute in Commissioning 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_commissioning_cluster_add_attr(esp_zb_attribute_list_t *attr_list, uint16_t attr_id, void *value_p);
+
 /**
  * @brief Add an attribute in shade config cluster.
  *

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

@@ -168,6 +168,19 @@ esp_zb_attribute_list_t *esp_zb_shade_config_cluster_create(esp_zb_shade_config_
  */
 esp_zb_attribute_list_t *esp_zb_binary_input_cluster_create(esp_zb_binary_input_cluster_cfg_t *binary_input_cfg);
 
+/**
+ * @brief  Create a standard commissioning cluster attribute list.
+ *
+ * @note  This only contains the mandatory attribute. The ZCL spec 13.2.1.1 strongly recommended that this cluster only
+ *        be deplayed on a single device endpoint, so we only supports single cluster instance for time being. Creating
+ *        multiple clusters on different endpoints may cause unexpected behaviour.
+ * @param[in] commissioning_cfg  Configuration parameters for this cluster defined by @ref esp_zb_commissioning_cluster_cfg_s
+ *
+ * @return Pointer to attribute list @ref esp_zb_attribute_list_s
+ *
+ */
+esp_zb_attribute_list_t *esp_zb_commissioning_cluster_create(esp_zb_commissioning_cluster_cfg_t *commissioning_cfg);
+
 /**
  * @brief  Create a standard door lock cluster attribute list.
  *
@@ -588,6 +601,20 @@ esp_err_t esp_zb_cluster_list_add_shade_config_cluster(esp_zb_cluster_list_t *cl
  */
 esp_err_t esp_zb_cluster_list_add_binary_input_cluster(esp_zb_cluster_list_t *cluster_list, esp_zb_attribute_list_t *attr_list, uint8_t role_mask);
 
+/**
+ * @brief Add Commissioning 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_commissioning_cluster(esp_zb_cluster_list_t *cluster_list, esp_zb_attribute_list_t *attr_list, uint8_t role_mask);
+
 /**
  * @brief Add ias zone cluster (attribute list) in a cluster list.
  *
@@ -1126,6 +1153,20 @@ esp_err_t esp_zb_cluster_list_update_shade_config_cluster(esp_zb_cluster_list_t
  */
 esp_err_t esp_zb_cluster_list_update_binary_input_cluster(esp_zb_cluster_list_t *cluster_list, esp_zb_attribute_list_t *attr_list, uint8_t role_mask);
 
+/**
+ * @brief Update Commissioning 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 update
+ * @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_update_commissioning_cluster(esp_zb_cluster_list_t *cluster_list, esp_zb_attribute_list_t *attr_list, uint8_t role_mask);
+
 /**
  * @brief Update ias zone cluster (attribute list) in a cluster list.
  *

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

@@ -99,6 +99,9 @@ typedef enum esp_zb_core_action_callback_id_s {
     ESP_ZB_CORE_PRICE_PUBLISH_PRICE_CB_ID               = 0x0017,   /*!< Price publish price, refer to esp_zb_zcl_price_publish_price_message_t */
     ESP_ZB_CORE_PRICE_PUBLISH_TIER_LABELS_CB_ID         = 0x0018,   /*!< Price publish tier labels, refer to esp_zb_zcl_price_publish_tier_labels_message_t */
     ESP_ZB_CORE_PRICE_PRICE_ACK_CB_ID                   = 0x0019,   /*!< Price price acknowledgement, refer to esp_zb_zcl_price_ack_message_t */
+    ESP_ZB_CORE_COMM_RESTART_DEVICE_CB_ID               = 0x001a,   /*!< Commissioning restart device, refer to esp_zigbee_zcl_commissioning_restart_device_message_t */
+    ESP_ZB_CORE_COMM_OPERATE_STARTUP_PARAMS_CB_ID       = 0x001b,   /*!< Commissioning operate startup parameters, refer to esp_zigbee_zcl_commissioning_operate_startup_parameters_message_t */
+    ESP_ZB_CORE_COMM_COMMAND_RESP_CB_ID                 = 0x001c,   /*!< Commissioning command response, refer to esp_zigbee_zcl_commissioning_command_response_message_t */
     ESP_ZB_CORE_CMD_READ_ATTR_RESP_CB_ID                = 0x1000,   /*!< Read attribute response, refer to esp_zb_zcl_cmd_read_attr_resp_message_t */
     ESP_ZB_CORE_CMD_WRITE_ATTR_RESP_CB_ID               = 0x1001,   /*!< Write attribute response, refer to esp_zb_zcl_cmd_write_attr_resp_message_t */
     ESP_ZB_CORE_CMD_REPORT_CONFIG_RESP_CB_ID            = 0x1002,   /*!< Configure report response, refer to esp_zb_zcl_cmd_config_report_resp_message_t */
@@ -278,7 +281,7 @@ void esp_zb_identify_notify_handler_register(uint8_t endpoint, esp_zb_identify_n
  * @param[in] endpoint The specific endpoint for @p cluster
  * @param[in] cluster The specific cluster for @p command
  * @param[in] command The specific command ID is required to handle for users.
- * @return 
+ * @return
  *      - ESP_OK: on success
  *      - ESP_FAIL: on failure
  */
@@ -768,6 +771,33 @@ void esp_zb_scheduler_alarm(esp_zb_callback_t cb, uint8_t param, uint32_t time);
  */
 void esp_zb_scheduler_alarm_cancel(esp_zb_callback_t cb, uint8_t param);
 
+/**
+ * @brief Schedule user alarm - callback to be executed after timeout.
+ *
+ * @note Function will be called via scheduler after timeout expired in millisecond. Timer resolution depends on implementation. Same callback can be scheduled for execution more then once.
+ *
+ * @param[in] cb - function to call via scheduler
+ * @param[in] param - parameter to pass to the function
+ * @param[in] time - timeout, in millisecond
+ *
+ * @return
+ *      - the handle used to cancel the user alarm
+ */
+esp_zb_user_cb_handle_t esp_zb_scheduler_user_alarm(esp_zb_user_callback_t cb, void *param, uint32_t time);
+
+/**
+ * @brief Cancel scheduled user alarm.
+ *
+ * @note This function cancel previously scheduled user alarm.
+ *
+ * @param[in] handle - the handle returned by esp_zb_scheduler_user_alarm
+ *
+ * @return
+ *      - ESP_OK: on success
+ *      - ESP_ERR_NOT_FOUND: not found the user alarm
+ */
+esp_err_t esp_zb_scheduler_user_alarm_cancel(esp_zb_user_cb_handle_t handle);
+
 /**
  * @brief  Set BDB commissioning mode.
  *

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

@@ -19,6 +19,9 @@ typedef uint8_t esp_zb_64bit_addr_t[8];
 typedef esp_zb_64bit_addr_t esp_zb_ieee_addr_t;
 typedef void (*esp_zb_zcl_cluster_init_t)(void);
 typedef void (*esp_zb_callback_t)(uint8_t param);
+typedef void (*esp_zb_user_callback_t)(void* param);
+typedef uint8_t esp_zb_user_cb_handle_t;
+#define ESP_ZB_USER_CB_HANDLE_INVALID (0x00)
 
 /**
  * @brief The Zigbee address union consist of 16 bit short address and 64 bit long address.
@@ -427,6 +430,27 @@ typedef struct esp_zb_binary_input_cluster_cfg_s {
     uint8_t  status_flags;                             /*!< Status flags */
 } esp_zb_binary_input_cluster_cfg_t;
 
+/**
+ * @brief Zigbee default attribute for Commissioning cluster.
+ *
+ */
+typedef struct esp_zb_commissioning_cluster_cfg_s {
+    uint16_t           short_address;               /**< Short Address */
+    esp_zb_ieee_addr_t extended_panid;              /**< Extended Panid */
+    uint16_t           panid;                       /**< Panid */
+    uint32_t           channel_mask;                /**< Channel Mask */
+    uint8_t            protocol_version;            /**< Protocol Version */
+    uint8_t            stack_profile;               /**< Stack Profile */
+    uint8_t            startup_control;             /**< Startup Control */
+    esp_zb_ieee_addr_t trust_center_address;        /**< Trust Center Address */
+    uint8_t            network_key[16];             /**< Network Key */
+    bool               use_insecure_join;           /**< Use Insecure Join */
+    uint8_t            preconfigured_link_key[16];  /**< Preconfigured Link Key */
+    uint8_t            network_key_seq_num;         /**< Network Key Seq Num */
+    uint8_t            network_key_type;            /**< Network Key Type */
+    uint16_t           network_manager_address;     /**< Network Manager Address */
+} esp_zb_commissioning_cluster_cfg_t;
+
 /**
  * @brief The IAS zone application callback
  *

components/esp-zigbee-lib/include/zcl/esp_zigbee_zcl_command.h

@@ -271,6 +271,51 @@ typedef struct esp_zb_zcl_identify_query_cmd_s {
     esp_zb_zcl_address_mode_t address_mode;         /*!< APS addressing mode constants refer to esp_zb_zcl_address_mode_t */
 } esp_zb_zcl_identify_query_cmd_t;
 
+/* ZCL commisssioning cluster */
+
+/**
+ * @brief The Zigbee ZCL commisssioning restart device command struct
+ *
+ */
+typedef struct esp_zb_zcl_comm_restart_device_cmd_s {
+    esp_zb_zcl_basic_cmd_t zcl_basic_cmd;                        /*!< Basic command info */
+    esp_zb_zcl_address_mode_t address_mode;                      /*!< APS addressing mode constants refer to esp_zb_zcl_address_mode_t */
+    esp_zb_zcl_commissioning_restart_device_options_t options;   /*!< Restart device options */
+    uint8_t delay;                                               /*!< Seconds of delay before starting the restart procedure */
+    uint8_t jitter;                                              /*!< Parameter to calculate the additional milliseconds should be added to delay */
+} esp_zb_zcl_comm_restart_device_cmd_t;
+
+/**
+ * @brief The Zigbee ZCL commisssioning save startup parameters command struct
+ *
+ */
+typedef struct esp_zb_zcl_comm_save_startup_params_cmd_s {
+    esp_zb_zcl_basic_cmd_t zcl_basic_cmd;               /*!< Basic command info */
+    esp_zb_zcl_address_mode_t address_mode;             /*!< APS addressing mode constants refer to esp_zb_zcl_address_mode_t */
+    uint8_t index;                                      /*!< Index to save the parameter set */
+} esp_zb_zcl_comm_save_startup_params_cmd_t;
+
+/**
+ * @brief The Zigbee ZCL commisssioning restore startup parameters command struct
+ *
+ */
+typedef struct esp_zb_zcl_comm_restore_startup_params_cmd_s {
+    esp_zb_zcl_basic_cmd_t zcl_basic_cmd;             /*!< Basic command info */
+    esp_zb_zcl_address_mode_t address_mode;           /*!< APS addressing mode constants refer to esp_zb_zcl_address_mode_t */
+    uint8_t index;                                    /*!< Index of the saved the parameter set to be restored */
+} esp_zb_zcl_comm_restore_startup_params_cmd_t;
+
+/**
+ * @brief The Zigbee ZCL commisssioning reset startup parameters command struct
+ *
+ */
+typedef struct esp_zb_zcl_comm_reset_startup_params_cmd_s {
+    esp_zb_zcl_basic_cmd_t zcl_basic_cmd;                             /*!< Basic command info */
+    esp_zb_zcl_address_mode_t address_mode;                           /*!< APS addressing mode constants refer to esp_zb_zcl_address_mode_t */
+    esp_zb_zcl_commissioning_reset_startup_param_options_t options;   /*!< Reset startup parameter options */
+    uint8_t index;                                                    /*!< Index of the saved parameters to be erased */
+} esp_zb_zcl_comm_reset_startup_params_cmd_t;
+
 /* ZCL level cluster */
 
 /**
@@ -1095,7 +1140,7 @@ typedef struct esp_zb_zcl_frame_header_s {
     uint8_t fc;          /*!< A 8-bit Frame control */
     uint16_t manuf_code; /*!< Manufacturer code */
     uint8_t tsn;         /*!< Transaction sequence number */
-    uint8_t rssi;        /*!< Signal strength */
+    int8_t rssi;         /*!< Signal strength */
 } esp_zb_zcl_frame_header_t;
 
 /**
@@ -1529,6 +1574,43 @@ typedef struct esp_zb_zcl_price_publish_tier_labels_message_s {
     esp_zb_zcl_price_tier_label_entry_t *tier_labels;       /*!< Tier labels published in the command */
 } esp_zb_zcl_price_publish_tier_labels_message_t;
 
+/**
+ * @brief The Zigbee ZCL commissioning restart device callback message struct
+ */
+typedef struct esp_zigbee_zcl_commissioning_restart_device_message_s {
+    esp_zb_device_cb_common_info_t info;                        /*!< The common information for Zigbee device callback */
+    esp_zb_zcl_commissioning_restart_device_payload_t msg_in;   /*!< Received restart device payload */
+} esp_zigbee_zcl_commissioning_restart_device_message_t;
+
+/**
+ * @brief The Zigbee ZCL commissioning startup parameters operation struct
+ */
+typedef enum {
+    ESP_ZB_ZCL_COMMISSIONING_STARTUP_PARAMETERS_OPERATION_SAVE,       /*!< Indicates to save startup parameter set */
+    ESP_ZB_ZCL_COMMISSIONING_STARTUP_PARAMETERS_OPERATION_RESTORE,    /*!< Indicates to restore startup parameter set */
+    ESP_ZB_ZCL_COMMISSIONING_STARTUP_PARAMETERS_OPERATION_ERASE,      /*!< Indicates to erase startup parameter set */
+    ESP_ZB_ZCL_COMMISSIONING_STARTUP_PARAMETERS_OPERATION_RESET,      /*!< Indicates to reset startup parameter set */
+    ESP_ZB_ZCL_COMMISSIONING_STARTUP_PARAMETERS_OPERATION_RESET_ALL,  /*!< Indicates to reset all startup parameter set */
+} esp_zb_zcl_commissioning_startup_parameters_operation_t;
+
+/**
+ * @brief The Zigbee ZCL commissioning startup parameters operation callback message struct
+ */
+typedef struct esp_zigbee_zcl_commissioning_operate_startup_parameters_message_s {
+    esp_zb_device_cb_common_info_t info;                                 /*!< The common information for Zigbee device callback */
+    esp_zb_zcl_commissioning_startup_parameters_operation_t operation;   /*!< Operation on startup parameter set */
+    uint8_t index;                                                       /*!< Index of the startup parameter set to be operated on */
+    esp_zb_zcl_status_t status;                                          /*!< Result of the operation, will be sent in the response */
+} esp_zigbee_zcl_commissioning_operate_startup_parameters_message_t;
+
+/**
+ * @brief The Zigbee ZCL commissioning startup parameters operation callback message struct
+ */
+typedef struct esp_zigbee_zcl_commissioning_command_response_message_s {
+    esp_zb_device_cb_common_info_t info;                    /*!< The common information for Zigbee device callback */
+    esp_zb_zcl_status_t status;                             /*!< Status of the received response */
+} esp_zigbee_zcl_commissioning_command_response_message_t;
+
 /**
  * @brief The Zigbee zcl door lock callback message struct
  *
@@ -2071,6 +2153,44 @@ uint8_t esp_zb_zcl_identify_trigger_effect_cmd_req(esp_zb_zcl_identify_trigger_e
  */
 uint8_t esp_zb_zcl_identify_query_cmd_req(esp_zb_zcl_identify_query_cmd_t *cmd_req);
 
+/* ZCL commissioning cluster list command */
+
+/**
+ * @brief   Send commissioning restart device command
+ *
+ * @param[in]  cmd_req  pointer to the commissioning restart device command @ref esp_zb_zcl_comm_restart_device_cmd_s
+ *
+ * @return The transaction sequence number
+ */
+uint8_t esp_zb_zcl_comm_restart_device_cmd_req(esp_zb_zcl_comm_restart_device_cmd_t *cmd_req);
+
+/**
+ * @brief   Send commissioning save startup parameters command
+ *
+ * @param[in]  cmd_req  pointer to the commissioning save startup parameters command @ref esp_zb_zcl_comm_save_startup_params_cmd_s
+ *
+ * @return The transaction sequence number
+ */
+uint8_t esp_zb_zcl_comm_save_startup_params_cmd_req(esp_zb_zcl_comm_save_startup_params_cmd_t *cmd_req);
+
+/**
+ * @brief   Send commissioning restore startup parameters command
+ *
+ * @param[in]  cmd_req  pointer to the commissioning restore startup parameters command @ref esp_zb_zcl_comm_restore_startup_params_cmd_s
+ *
+ * @return The transaction sequence number
+ */
+uint8_t esp_zb_zcl_comm_restore_startup_params_cmd_req(esp_zb_zcl_comm_restore_startup_params_cmd_t *cmd_req);
+
+/**
+ * @brief   Send commissioning reset startup parameters command
+ *
+ * @param[in]  cmd_req  pointer to the commissioning reset startup parameters command @ref esp_zb_zcl_comm_reset_startup_params_cmd_s
+ *
+ * @return The transaction sequence number
+ */
+uint8_t esp_zb_zcl_comm_reset_startup_params_cmd_req(esp_zb_zcl_comm_reset_startup_params_cmd_t *cmd_req);
+
 /* ZCL level control cluster list command */
 
 /**