Update forked idf components

25 files changed, 4241 insertions, 1049 deletions

diff --git a/lib/bt/host/bluedroid/api/include/api/esp_a2dp_api.h b/lib/bt/host/bluedroid/api/include/api/esp_a2dp_api.h
index 7020750c..71d3d597 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_a2dp_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_a2dp_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -9,11 +9,16 @@
 
 #include "esp_err.h"
 #include "esp_bt_defs.h"
+#include "esp_a2dp_legacy_api.h"
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
+#define ESP_A2D_MAX_SEPS        1               /*!< Maximum number of Stream Endpoint that supported */
+
+typedef uint16_t esp_a2d_conn_hdl_t;            /*!< Connection handle, associate with specific device that connected */
+
 /**
  * @brief Media codec types supported by A2DP.
  */
@@ -31,6 +36,102 @@ typedef uint8_t esp_a2d_mct_t;
 typedef uint16_t esp_a2d_psc_t;
 
 /**
+ * @brief A2DP SBC sampling frequency bit mask in CIE
+ */
+#define ESP_A2D_SBC_CIE_SF_16K                  (0x8)       /*!< SBC sampling frequency 16kHz  */
+#define ESP_A2D_SBC_CIE_SF_32K                  (0x4)       /*!< SBC sampling frequency 32kHz */
+#define ESP_A2D_SBC_CIE_SF_44K                  (0x2)       /*!< SBC sampling frequency 44.1kHz  */
+#define ESP_A2D_SBC_CIE_SF_48K                  (0x1)       /*!< SBC sampling frequency 48kHz */
+
+/**
+ * @brief A2DP SBC channel mode bit mask in CIE
+ */
+#define ESP_A2D_SBC_CIE_CH_MODE_MONO            (0x8)       /*!< SBC channel mode Mono */
+#define ESP_A2D_SBC_CIE_CH_MODE_DUAL_CHANNEL    (0x4)       /*!< SBC channel mode Dual Channel */
+#define ESP_A2D_SBC_CIE_CH_MODE_STEREO          (0x2)       /*!< SBC channel mode Stereo */
+#define ESP_A2D_SBC_CIE_CH_MODE_JOINT_STEREO    (0x1)       /*!< SBC channel mode Stereo */
+
+/**
+ * @brief A2DP SBC block length bit mask in CIE
+ */
+#define ESP_A2D_SBC_CIE_BLOCK_LEN_4             (0x8)       /*!< SBC block length 4 */
+#define ESP_A2D_SBC_CIE_BLOCK_LEN_8             (0x4)       /*!< SBC block length 8 */
+#define ESP_A2D_SBC_CIE_BLOCK_LEN_12            (0x2)       /*!< SBC block length 12 */
+#define ESP_A2D_SBC_CIE_BLOCK_LEN_16            (0x1)       /*!< SBC block length 16 */
+
+/**
+ * @brief A2DP SBC number of subbands bit mask in CIE
+ */
+#define ESP_A2D_SBC_CIE_NUM_SUBBANDS_4          (0x2)       /*!< SBC number of subbands 4 */
+#define ESP_A2D_SBC_CIE_NUM_SUBBANDS_8          (0x1)       /*!< SBC number of subbands 8 */
+
+/**
+ * @brief A2DP SBC allocation method bit mask in CIE
+ */
+#define ESP_A2D_SBC_CIE_ALLOC_MTHD_SRN          (0x2)       /*!< SBC allocation method SNR */
+#define ESP_A2D_SBC_CIE_ALLOC_MTHD_LOUDNESS     (0x1)       /*!< SBC allocation method Loudness */
+
+/**
+ * @brief A2DP SBC media codec capabilities information struct
+ */
+typedef struct {
+    uint8_t ch_mode         : 4;        /*!< Channel mode */
+    uint8_t samp_freq       : 4;        /*!< Sampling frequency */
+    uint8_t alloc_mthd      : 2;        /*!< Allocation method */
+    uint8_t num_subbands    : 2;        /*!< Number of subbands */
+    uint8_t block_len       : 4;        /*!< Block length */
+    uint8_t min_bitpool;                /*!< Minimum bitpool */
+    uint8_t max_bitpool;                /*!< Maximum bitpool */
+} __attribute__((packed)) esp_a2d_cie_sbc_t;
+
+/**
+ * @brief A2DP MPEG-1, 2 media codec capabilities information struct (Not supported yet)
+ */
+typedef struct {
+    uint8_t     ch_mode         : 4;        /*!< Channel mode */
+    uint8_t     crc             : 1;        /*!< CRC protection */
+    uint8_t     layer           : 3;        /*!< Layers of MPEG-1,2 Audio */
+    uint8_t     samp_freq       : 6;        /*!< Sampling frequency */
+    uint8_t     mpf             : 1;        /*!< Media payload format */
+    uint8_t     rfu             : 1;        /*!< Reserved */
+    uint8_t     bri1            : 7;        /*!< Bit rate index part 1 */
+    uint8_t     vbr             : 1;        /*!< Support of VBR */
+    uint8_t     bri2;                       /*!< Bit rate index part 2 */
+} __attribute__((packed)) esp_a2d_cie_m12_t;
+
+/**
+ * @brief A2DP MPEG-2, 4 media codec capabilities information struct (Not supported yet)
+ */
+typedef struct {
+    uint8_t     drc             : 1;        /*!< Support of MPEG-D DRC */
+    uint8_t     obj_type        : 7;        /*!< Object type */
+    uint8_t     samp_freq1      : 8;        /*!< Sampling frequency part 1 */
+    uint8_t     ch              : 4;        /*!< Channels */
+    uint8_t     samp_freq2      : 4;        /*!< Sampling frequency part 2 */
+    uint8_t     br1             : 7;        /*!< Bit rate part 1 */
+    uint8_t     vbr             : 1;        /*!< Support of VBR */
+    uint8_t     br2;                        /*!< Bit rate part 2 */
+    uint8_t     br3;                        /*!< Bit rate part 3 */
+} __attribute__((packed)) esp_a2d_cie_m24_t;
+
+/**
+ * @brief A2DP ATRAC media codec capabilities information struct (Not supported yet)
+ */
+typedef struct {
+    uint8_t     rfu1            : 2;        /*!< Reserved */
+    uint8_t     ch_mode         : 3;        /*!< Channel mode */
+    uint8_t     version         : 3;        /*!< Version */
+    uint8_t     bri1            : 3;        /*!< Bit rate index part 1 */
+    uint8_t     vbr             : 1;        /*!< Support of VBR */
+    uint8_t     samp_freq       : 2;        /*!< Sampling frequency */
+    uint8_t     rfu2            : 2;        /*!< Reserved */
+    uint8_t     bri2;                       /*!< Bit rate index part 2 */
+    uint8_t     bri3;                       /*!< Bit rate index part 3 */
+    uint16_t    max_sul;                    /*!< Maximum SUL */
+    uint8_t     rfu3;                       /*!< Reserved */
+} __attribute__((packed)) esp_a2d_cie_atrac_t;
+
+/**
  * @brief A2DP media codec capabilities union
  */
 typedef struct {
@@ -40,10 +141,15 @@ typedef struct {
 #define ESP_A2D_CIE_LEN_M24          (6)
 #define ESP_A2D_CIE_LEN_ATRAC        (7)
     union {
-        uint8_t sbc[ESP_A2D_CIE_LEN_SBC];      /*!< SBC codec capabilities */
-        uint8_t m12[ESP_A2D_CIE_LEN_M12];      /*!< MPEG-1,2 audio codec capabilities */
-        uint8_t m24[ESP_A2D_CIE_LEN_M24];      /*!< MPEG-2, 4 AAC audio codec capabilities */
-        uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC];  /*!< ATRAC family codec capabilities */
+        uint8_t sbc[ESP_A2D_CIE_LEN_SBC] __attribute__((deprecated));       /*!< SBC codec capabilities, deprecated, use sbc_info instead */
+        uint8_t m12[ESP_A2D_CIE_LEN_M12] __attribute__((deprecated));       /*!< MPEG-1,2 audio codec capabilities, deprecated, use m12_info instead */
+        uint8_t m24[ESP_A2D_CIE_LEN_M24] __attribute__((deprecated));       /*!< MPEG-2, 4 AAC audio codec capabilities, deprecated, use m24_info instead */
+        uint8_t atrac[ESP_A2D_CIE_LEN_ATRAC] __attribute__((deprecated));   /*!< ATRAC family codec capabilities, deprecated, use atrac_info instead */
+
+        esp_a2d_cie_sbc_t   sbc_info;          /*!< SBC codec capabilities */
+        esp_a2d_cie_m12_t   m12_info;          /*!< MPEG-1,2 audio codec capabilities */
+        esp_a2d_cie_m24_t   m24_info;          /*!< MPEG-2, 4 AAC audio codec capabilities */
+        esp_a2d_cie_atrac_t atrac_info;        /*!< ATRAC family codec capabilities */
     } cie;                                     /*!< A2DP codec information element */
 } __attribute__((packed)) esp_a2d_mcc_t;
 
@@ -104,6 +210,16 @@ typedef enum {
 } esp_a2d_init_state_t;
 
 /**
+ * @brief Bluetooth A2DP SEP register states
+ */
+typedef enum {
+    ESP_A2D_SEP_REG_SUCCESS = 0,               /*!< A2DP stream endpoint register success */
+    ESP_A2D_SEP_REG_FAIL,                      /*!< A2DP stream endpoint register generic fail */
+    ESP_A2D_SEP_REG_UNSUPPORTED,               /*!< A2DP stream endpoint register fail, unsupported codec type or param */
+    ESP_A2D_SEP_REG_INVALID_STATE,             /*!< A2DP stream endpoint register fail, invalid state */
+} esp_a2d_sep_reg_state_t;
+
+/**
  * @brief Bluetooth A2DP set delay report value states
  */
 typedef enum {
@@ -112,14 +228,24 @@ typedef enum {
 } esp_a2d_set_delay_value_state_t;
 
 /**
+ * @brief A2DP profile status parameters
+ */
+typedef struct {
+    bool a2d_snk_inited;                   /*!< A2DP sink initialization */
+    bool a2d_src_inited;                   /*!< A2DP source initialization */
+    uint8_t conn_num;                      /*!< Number of connections */
+} esp_a2d_profile_status_t;
+
+/**
  * @brief A2DP callback events
  */
 typedef enum {
     ESP_A2D_CONNECTION_STATE_EVT = 0,          /*!< connection state changed event */
     ESP_A2D_AUDIO_STATE_EVT,                   /*!< audio stream transmission state changed event */
-    ESP_A2D_AUDIO_CFG_EVT,                     /*!< audio codec is configured, only used for A2DP SINK */
+    ESP_A2D_AUDIO_CFG_EVT,                     /*!< audio codec is configured */
     ESP_A2D_MEDIA_CTRL_ACK_EVT,                /*!< acknowledge event in response to media control commands */
     ESP_A2D_PROF_STATE_EVT,                    /*!< indicate a2dp init&deinit complete */
+    ESP_A2D_SEP_REG_STATE_EVT,                 /*!< indicate a2dp steam endpoint register status */
     ESP_A2D_SNK_PSC_CFG_EVT,                   /*!< protocol service capabilities configured，only used for A2DP SINK */
     ESP_A2D_SNK_SET_DELAY_VALUE_EVT,           /*!< indicate a2dp sink set delay report value complete,  only used for A2DP SINK */
     ESP_A2D_SNK_GET_DELAY_VALUE_EVT,           /*!< indicate a2dp sink get delay report value complete,  only used for A2DP SINK */
@@ -127,6 +253,17 @@ typedef enum {
 } esp_a2d_cb_event_t;
 
 /**
+ * @brief A2DP audio buffer
+ */
+typedef struct {
+    uint16_t    buff_size;                      /*!< audio buff size */
+    uint16_t    number_frame;                   /*!< number of encoded frame in this buff */
+    uint32_t    timestamp;                      /*!< timestamp of the first frame */
+    uint16_t    data_len;                       /*!< audio data len */
+    uint8_t    *data;                           /*!< pointer to audio data start */
+} esp_a2d_audio_buff_t;                         /*!< struct to store audio data */
+
+/**
  * @brief A2DP state callback parameters
  */
 typedef union {
@@ -136,6 +273,8 @@ typedef union {
     struct a2d_conn_stat_param {
         esp_a2d_connection_state_t state;      /*!< one of values from esp_a2d_connection_state_t */
         esp_bd_addr_t remote_bda;              /*!< remote bluetooth device address */
+        esp_a2d_conn_hdl_t conn_hdl;           /*!< connection handle */
+        uint16_t audio_mtu;                    /*!< MTU of audio connection */
         esp_a2d_disc_rsn_t disc_rsn;           /*!< reason of disconnection for "DISCONNECTED" */
     } conn_stat;                               /*!< A2DP connection status */
 
@@ -144,7 +283,8 @@ typedef union {
      */
     struct a2d_audio_stat_param {
         esp_a2d_audio_state_t state;           /*!< one of the values from esp_a2d_audio_state_t */
-        esp_bd_addr_t remote_bda;              /*!< remote bluetooth device address */
+        esp_bd_addr_t remote_bda;              /*!< remote bluetooth device address*/
+        esp_a2d_conn_hdl_t conn_hdl;           /*!< connection handle */
     } audio_stat;                              /*!< audio stream playing state */
 
     /**
@@ -152,6 +292,7 @@ typedef union {
      */
     struct a2d_audio_cfg_param {
         esp_bd_addr_t remote_bda;              /*!< remote bluetooth device address */
+        esp_a2d_conn_hdl_t conn_hdl;           /*!< connection handle */
         esp_a2d_mcc_t mcc;                     /*!< A2DP media codec capability information */
     } audio_cfg;                               /*!< media codec configuration information */
 
@@ -171,6 +312,14 @@ typedef union {
     } a2d_prof_stat;                           /*!< status to indicate a2d prof init or deinit */
 
     /**
+     * @brief ESP_A2D_SEP_REG_STATE_EVT
+     */
+    struct a2d_sep_reg_stat_param {
+        uint8_t seid;                          /*!< the stream endpoint to register */
+        esp_a2d_sep_reg_state_t reg_state;     /*!< stream endpoint register state */
+    } a2d_sep_reg_stat;                        /*!< status to indicate a2d sep register success or not */
+
+    /**
      * @brief ESP_A2D_SNK_PSC_CFG_EVT
      */
     struct a2d_psc_cfg_param {
@@ -213,25 +362,31 @@ typedef void (* esp_a2d_cb_t)(esp_a2d_cb_event_t event, esp_a2d_cb_param_t *para
 /**
  * @brief           A2DP sink data callback function
  *
- * @param[in]       buf : pointer to the data received from A2DP source device and is PCM format decoded from SBC decoder;
- *                  buf references to a static memory block and can be overwritten by upcoming data
+ * @param[in]       conn_hdl: connection handle
  *
- * @param[in]       len : size(in bytes) in buf
+ * @param[in]       audio_buf: pointer to the data received from A2DP source device, should be freed by
+ *                  calling esp_a2d_audio_buff_free
  */
-typedef void (* esp_a2d_sink_data_cb_t)(const uint8_t *buf, uint32_t len);
+typedef void (* esp_a2d_sink_audio_data_cb_t)(esp_a2d_conn_hdl_t conn_hdl, esp_a2d_audio_buff_t *audio_buf);
 
 /**
- * @brief           A2DP source data read callback function
+ * @brief           Allocate a audio buffer to store and send audio data, can be used in both sink and source.
  *
- * @param[in]       buf : buffer to be filled with PCM data stream from higher layer
+ * @param[in]       size: buffer size to allocate
  *
- * @param[in]       len : size(in bytes) of data block to be copied to buf. -1 is an indication to user
- *                  that data buffer shall be flushed
+ * @return          allocated audio buffer, if Bluedroid is not enabled, no memory, or size is
+ *                  zeros, will return NULL
+ *
+ */
+esp_a2d_audio_buff_t *esp_a2d_audio_buff_alloc(uint16_t size);
+
+/**
+ * @brief           Free a audio buffer allocated by esp_a2d_audio_buff_alloc.
  *
- * @return          size of bytes read successfully, if the argument len is -1, this value is ignored.
+ * @param[in]       audio_buf: audio buffer to free
  *
  */
-typedef int32_t (* esp_a2d_source_data_cb_t)(uint8_t *buf, int32_t len);
+void esp_a2d_audio_buff_free(esp_a2d_audio_buff_t *audio_buf);
 
 /**
  * @brief           Register application callback function to A2DP module. This function should be called
@@ -248,23 +403,20 @@ typedef int32_t (* esp_a2d_source_data_cb_t)(uint8_t *buf, int32_t len);
  */
 esp_err_t esp_a2d_register_callback(esp_a2d_cb_t callback);
 
-
 /**
- * @brief           Register A2DP sink data output function; For now the output is PCM data stream decoded
- *                  from SBC format. This function should be called only after esp_bluedroid_enable()
- *                  completes successfully, used only by A2DP sink. The callback is invoked in the context
- *                  of A2DP sink task whose stack size is configurable through menuconfig.
+ * @brief           Register A2DP sink audio data output function, the output format is undecoded audio data
+ *                  frame in esp_a2d_audio_buff_t, user shall call esp_a2d_audio_buff_free to free the buff
+ *                  when the data is consumed.
  *
- * @param[in]       callback: A2DP sink data callback function
+ * @param[in]       callback: A2DP sink audio data callback function
  *
  * @return
  *                  - ESP_OK: success
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
- *                  - ESP_FAIL: if callback is a NULL function pointer
+ *                  - ESP_FAIL: others
  *
  */
-esp_err_t esp_a2d_sink_register_data_callback(esp_a2d_sink_data_cb_t callback);
-
+esp_err_t esp_a2d_sink_register_audio_data_callback(esp_a2d_sink_audio_data_cb_t callback);
 
 /**
  *
@@ -282,6 +434,23 @@ esp_err_t esp_a2d_sink_register_data_callback(esp_a2d_sink_data_cb_t callback);
  */
 esp_err_t esp_a2d_sink_init(void);
 
+/**
+ * @brief           Register a a2dp sink Stream Endpoint (SEP) with specific codec capability, shall register
+ *                  SEP after a2dp sink initializing and before a2dp connection establishing. Register the same
+ *                  SEP index repeatedly will overwrite the old one.
+ *
+ * @param[in]       seid: local SEP identifier, start from 0, less than ESP_A2D_MAX_SEPS
+ *
+ * @param[in]       mcc: codec capability, currently only supports SBC
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
+ *                  - ESP_ERR_INVALID_ARG: invalid parameter
+ *                  - ESP_FAIL: others
+ *
+ */
+esp_err_t esp_a2d_sink_register_stream_endpoint(uint8_t seid, const esp_a2d_mcc_t *mcc);
 
 /**
  *
@@ -297,7 +466,6 @@ esp_err_t esp_a2d_sink_init(void);
  */
 esp_err_t esp_a2d_sink_deinit(void);
 
-
 /**
  *
  * @brief           Connect to remote bluetooth A2DP source device. This API must be called after
@@ -313,7 +481,6 @@ esp_err_t esp_a2d_sink_deinit(void);
  */
 esp_err_t esp_a2d_sink_connect(esp_bd_addr_t remote_bda);
 
-
 /**
  *
  * @brief           Disconnect from the remote A2DP source device. This API must be called after
@@ -359,7 +526,6 @@ esp_err_t esp_a2d_sink_set_delay_value(uint16_t delay_value);
  */
 esp_err_t esp_a2d_sink_get_delay_value(void);
 
-
 /**
  *
  * @brief           Media control commands. This API can be used for both A2DP sink and source
@@ -375,6 +541,17 @@ esp_err_t esp_a2d_sink_get_delay_value(void);
  */
 esp_err_t esp_a2d_media_ctrl(esp_a2d_media_ctrl_t ctrl);
 
+/**
+ * @brief       This function is used to get the status of A2DP
+ *
+ * @param[out]  profile_status - A2DP status
+ *
+ * @return
+ *              - ESP_OK: success
+ *              - other: failed
+ */
+esp_err_t esp_a2d_get_profile_status(esp_a2d_profile_status_t *profile_status);
+
 
 /**
  *
@@ -392,6 +569,23 @@ esp_err_t esp_a2d_media_ctrl(esp_a2d_media_ctrl_t ctrl);
  */
 esp_err_t esp_a2d_source_init(void);
 
+/**
+ * @brief           Register a a2dp source Stream Endpoint (SEP) with specific codec capability, shall register
+ *                  SEP after a2dp source initializing and before a2dp connection establishing. Register the same
+ *                  SEP index repeatedly will overwrite the old one.
+ *
+ * @param[in]       seid: local SEP identifier, start from 0, less than ESP_A2D_MAX_SEPS
+ *
+ * @param[in]       mcc: codec capability, currently, only SBC supported
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
+ *                  - ESP_ERR_INVALID_ARG: invalid parameter
+ *                  - ESP_FAIL: others
+ *
+ */
+esp_err_t esp_a2d_source_register_stream_endpoint(uint8_t seid, const esp_a2d_mcc_t *mcc);
 
 /**
  *
@@ -407,23 +601,24 @@ esp_err_t esp_a2d_source_init(void);
  */
 esp_err_t esp_a2d_source_deinit(void);
 
-
 /**
- * @brief           Register A2DP source data input function. For now, the input shoule be PCM data stream.
- *                  This function should be called only after esp_bluedroid_enable() completes
- *                  successfully. The callback is invoked in the context of A2DP source task whose
- *                  stack size is configurable through menuconfig.
+ * @brief           Send a audio buff with encoded audio data to sink, the audio data len shall not bigger than
+ *                  audio connection mtu (retrieved from ESP_A2D_CONNECTION_STATE_EVT). if the return value is
+ *                  ESP_OK, then the audio buff is consumed, otherwise, audio buff can be reused by user.
+ *
+ * @param[in]       conn_hdl: connection handle
  *
- * @param[in]       callback: A2DP source data callback function
+ * @param[in]       audio_buf: encoded audio data
  *
  * @return
  *                  - ESP_OK: success
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
- *                  - ESP_FAIL: if callback is a NULL function pointer
+ *                  - ESP_ERR_INVALID_ARG: invalid parameter
+ *                  - ESP_ERR_INVALID_SIZE: data len bigger than mtu
+ *                  - ESP_FAIL: buffer queue is full, try again later
  *
  */
-esp_err_t esp_a2d_source_register_data_callback(esp_a2d_source_data_cb_t callback);
-
+esp_err_t esp_a2d_source_audio_data_send(esp_a2d_conn_hdl_t conn_hdl, esp_a2d_audio_buff_t *audio_buf);
 
 /**
  *
@@ -440,7 +635,6 @@ esp_err_t esp_a2d_source_register_data_callback(esp_a2d_source_data_cb_t callbac
  */
 esp_err_t esp_a2d_source_connect(esp_bd_addr_t remote_bda);
 
-
 /**
  *
  * @brief           Disconnect from the remote A2DP sink device. This API must be called
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_a2dp_legacy_api.h b/lib/bt/host/bluedroid/api/include/api/esp_a2dp_legacy_api.h
new file mode 100644
index 00000000..2e59d058
--- /dev/null
+++ b/lib/bt/host/bluedroid/api/include/api/esp_a2dp_legacy_api.h
@@ -0,0 +1,77 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ *  Some legacy APIs of A2DP, will be removed in the future
+ */
+
+#pragma once
+
+#include "esp_err.h"
+#include "esp_bt_defs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief           [Deprecated] A2DP sink data callback function
+ *
+ * @param[in]       buf : pointer to the data received from A2DP source device and is PCM format decoded from SBC decoder;
+ *                  buf references to a static memory block and can be overwritten by upcoming data
+ *
+ * @param[in]       len : size(in bytes) in buf
+ */
+typedef void (* esp_a2d_sink_data_cb_t)(const uint8_t *buf, uint32_t len);
+
+/**
+ * @brief           [Deprecated] A2DP source data read callback function
+ *
+ * @param[in]       buf : buffer to be filled with PCM data stream from higher layer
+ *
+ * @param[in]       len : size(in bytes) of data block to be copied to buf. -1 is an indication to user
+ *                  that data buffer shall be flushed
+ *
+ * @return          size of bytes read successfully, if the argument len is -1, this value is ignored.
+ *
+ */
+typedef int32_t (* esp_a2d_source_data_cb_t)(uint8_t *buf, int32_t len);
+
+/**
+ * @brief           [Deprecated] Register A2DP sink data output function; For now the output is PCM data stream decoded
+ *                  from SBC format. This function should be called only after esp_bluedroid_enable()
+ *                  completes successfully, used only by A2DP sink. The callback is invoked in the context
+ *                  of A2DP sink task whose stack size is configurable through menuconfig.
+ *
+ * @param[in]       callback: A2DP sink data callback function
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
+ *                  - ESP_FAIL: if callback is a NULL function pointer
+ *
+ */
+esp_err_t esp_a2d_sink_register_data_callback(esp_a2d_sink_data_cb_t callback);
+
+/**
+ * @brief           [Deprecated] Register A2DP source data input function. For now, the input should be PCM data stream.
+ *                  This function should be called only after esp_bluedroid_enable() completes
+ *                  successfully. The callback is invoked in the context of A2DP source task whose
+ *                  stack size is configurable through menuconfig.
+ *
+ * @param[in]       callback: A2DP source data callback function
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
+ *                  - ESP_FAIL: if callback is a NULL function pointer
+ *
+ */
+esp_err_t esp_a2d_source_register_data_callback(esp_a2d_source_data_cb_t callback);
+
+#ifdef __cplusplus
+}
+#endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_avrc_api.h b/lib/bt/host/bluedroid/api/include/api/esp_avrc_api.h
index f226577e..6fae9c1b 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_avrc_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_avrc_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -18,6 +18,10 @@ extern "C" {
 
 #define ESP_AVRC_TRANS_LABEL_MAX        15       /*!< max transaction label */
 
+#define ESP_AVRC_CA_IMAGE_HANDLE_LEN    7        /* The image handle length is fixed to 7, specified by Basic Image Profile */
+#define ESP_AVRC_CA_MTU_MIN             255      /* Minimal MTU can be used in Cover Art OBEX connection */
+#define ESP_AVRC_CA_MTU_MAX             1691     /* Maximum MTU can be used in Cover Art OBEX connection */
+
 /// AVRC feature bit mask
 typedef enum {
     ESP_AVRC_FEAT_RCTG = 0x0001,                 /*!< remote control target */
@@ -30,14 +34,18 @@ typedef enum {
 
 /// AVRC supported features flag retrieved in SDP record
 typedef enum {
+    /* CT and TG common features flag */
     ESP_AVRC_FEAT_FLAG_CAT1 = 0x0001,                             /*!< category 1 */
     ESP_AVRC_FEAT_FLAG_CAT2 = 0x0002,                             /*!< category 2 */
     ESP_AVRC_FEAT_FLAG_CAT3 = 0x0004,                             /*!< category 3 */
     ESP_AVRC_FEAT_FLAG_CAT4 = 0x0008,                             /*!< category 4 */
     ESP_AVRC_FEAT_FLAG_BROWSING = 0x0040,                         /*!< browsing */
-    ESP_AVRC_FEAT_FLAG_COVER_ART_GET_IMAGE_PROP = 0x0080,         /*!< Cover Art GetImageProperties */
-    ESP_AVRC_FEAT_FLAG_COVER_ART_GET_IMAGE = 0x0100,              /*!< Cover Art GetImage */
-    ESP_AVRC_FEAT_FLAG_COVER_ART_GET_LINKED_THUMBNAIL = 0x0200,   /*!< Cover Art GetLinkedThumbnail */
+    /* CT only features flag */
+    ESP_AVRC_FEAT_FLAG_COVER_ART_GET_IMAGE_PROP = 0x0080,         /*!< CT support Cover Art GetImageProperties */
+    ESP_AVRC_FEAT_FLAG_COVER_ART_GET_IMAGE = 0x0100,              /*!< CT support Cover Art GetImage */
+    ESP_AVRC_FEAT_FLAG_COVER_ART_GET_LINKED_THUMBNAIL = 0x0200,   /*!< CT support Cover Art GetLinkedThumbnail */
+    /* TG only features flag */
+    ESP_AVRC_FEAT_FLAG_TG_COVER_ART = 0x0100,                     /*!< TG support Cover Art */
 } esp_avrc_feature_flag_t;
 
 /// AVRC passthrough command code
@@ -133,8 +141,11 @@ typedef enum {
     ESP_AVRC_CT_PLAY_STATUS_RSP_EVT = 3,         /*!< play status response event */
     ESP_AVRC_CT_CHANGE_NOTIFY_EVT = 4,           /*!< notification event */
     ESP_AVRC_CT_REMOTE_FEATURES_EVT = 5,         /*!< feature of remote device indication event */
-    ESP_AVRC_CT_GET_RN_CAPABILITIES_RSP_EVT = 6,     /*!< supported notification events capability of peer device */
+    ESP_AVRC_CT_GET_RN_CAPABILITIES_RSP_EVT = 6, /*!< supported notification events capability of peer device */
     ESP_AVRC_CT_SET_ABSOLUTE_VOLUME_RSP_EVT = 7, /*!< set absolute volume response event */
+    ESP_AVRC_CT_COVER_ART_STATE_EVT = 8,         /*!< cover art client connection state changed event */
+    ESP_AVRC_CT_COVER_ART_DATA_EVT = 9,          /*!< cover art client data event */
+    ESP_AVRC_CT_PROF_STATE_EVT = 10,             /*!< Indicate AVRCP controller init or deinit complete */
 } esp_avrc_ct_cb_event_t;
 
 /// AVRC Target callback events
@@ -145,6 +156,7 @@ typedef enum {
     ESP_AVRC_TG_SET_ABSOLUTE_VOLUME_CMD_EVT = 3,   /*!< set absolute volume command from remote device */
     ESP_AVRC_TG_REGISTER_NOTIFICATION_EVT = 4,     /*!< register notification event */
     ESP_AVRC_TG_SET_PLAYER_APP_VALUE_EVT = 5,      /*!< set application attribute value, attribute refer to esp_avrc_ps_attr_ids_t */
+    ESP_AVRC_TG_PROF_STATE_EVT = 6,                /*!< Indicate AVRCP target init or deinit complete */
 } esp_avrc_tg_cb_event_t;
 
 /// AVRC metadata attribute mask
@@ -155,7 +167,8 @@ typedef enum {
     ESP_AVRC_MD_ATTR_TRACK_NUM = 0x8,             /*!< track position on the album */
     ESP_AVRC_MD_ATTR_NUM_TRACKS = 0x10,           /*!< number of tracks on the album */
     ESP_AVRC_MD_ATTR_GENRE = 0x20,                /*!< track genre */
-    ESP_AVRC_MD_ATTR_PLAYING_TIME = 0x40          /*!< total album playing time in miliseconds */
+    ESP_AVRC_MD_ATTR_PLAYING_TIME = 0x40,         /*!< total album playing time in milliseconds */
+    ESP_AVRC_MD_ATTR_COVER_ART = 0x80             /*!< cover art image handle */
 } esp_avrc_md_attr_mask_t;
 
 /// AVRC event notification ids
@@ -261,6 +274,12 @@ typedef enum {
     ESP_AVRC_PLAYBACK_ERROR = 0xFF,               /*!< error */
 } esp_avrc_playback_stat_t;
 
+/// AVRC Cover Art connection error code
+typedef enum {
+    ESP_AVRC_COVER_ART_DISCONNECTED,              /*!< Cover Art connection disconnected or connection failed */
+    ESP_AVRC_COVER_ART_CONNECTED,                 /*!< Cover Art connection established */
+} esp_avrc_cover_art_conn_state_t;
+
 /// AVRCP notification parameters
 typedef union
 {
@@ -277,6 +296,27 @@ typedef struct {
     uint8_t   attr_val;                      /*!< player application attribute value */
 } esp_avrc_set_app_value_param_t;
 
+/**
+ * @brief AVRCP profile status parameters
+ */
+typedef struct {
+    bool avrc_ct_inited;                   /*!< AVRCP CT initialization */
+    bool avrc_tg_inited;                   /*!< AVRCP TG initialization */
+    uint8_t ct_cover_art_conn_num;         /*!< Number of cover art client connections */
+} esp_avrc_profile_status_t;
+
+/**
+ * @brief Bluetooth AVRCP Initiation states
+ */
+typedef enum {
+    ESP_AVRC_INIT_SUCCESS = 0,                /*!< Indicate init successful */
+    ESP_AVRC_INIT_ALREADY,                    /*!< Indicate init repeated */
+    ESP_AVRC_INIT_FAIL,                       /*!< Indicate init fail */
+    ESP_AVRC_DEINIT_SUCCESS,                  /*!< Indicate deinit successful */
+    ESP_AVRC_DEINIT_ALREADY,                  /*!< Indicate deinit repeated */
+    ESP_AVRC_DEINIT_FAIL,                     /*!< Indicate deinit fail */
+} esp_avrc_init_state_t;
+
 /// AVRC controller callback parameters
 typedef union {
     /**
@@ -307,6 +347,15 @@ typedef union {
     } meta_rsp;                                  /*!< metadata attributes response */
 
     /**
+     * @brief ESP_AVRC_CT_PLAY_STATUS_RSP_EVT
+     */
+    struct avrc_ct_get_play_status_rsp_param {
+        uint32_t song_length;                    /*!< total length of the playing song in milliseconds */
+        uint32_t song_position;                  /*!< current position of the playing song in milliseconds elapsed */
+        esp_avrc_playback_stat_t play_status;    /*!< current status of playing */
+    } play_status_rsp;                           /*!< get play status command response */
+
+    /**
      * @brief ESP_AVRC_CT_CHANGE_NOTIFY_EVT
      */
     struct avrc_ct_change_notify_param {
@@ -337,6 +386,32 @@ typedef union {
     struct avrc_ct_set_volume_rsp_param {
         uint8_t volume;                          /*!< the volume which has actually been set, range is 0 to 0x7f, means 0% to 100% */
     } set_volume_rsp;                            /*!< set absolute volume response event */
+
+    /**
+     * @brief ESP_AVRC_CT_COVER_ART_STATE_EVT
+     */
+    struct avrc_ct_cover_art_state_param {
+        esp_avrc_cover_art_conn_state_t state;   /*!< indicate the Cover Art connection status */
+        esp_bt_status_t reason;                  /*!< the disconnect reason of Cover Art connection */
+    } cover_art_state;                           /*!< AVRC Cover Art connection state change event */
+
+    /**
+     * @brief ESP_AVRC_CT_COVER_ART_DATA_EVT
+     */
+    struct avrc_ct_cover_art_data_param {
+        esp_bt_status_t status;                 /*!< indicate whether the get operation is success, p_data is valid only when status is ESP_BT_STATUS_SUCCESS */
+        bool final;                             /*!< indicate whether this data event is the final one, true if we have received the entire object */
+        uint16_t data_len;                      /*!< the data length of this data event, in bytes */
+        uint8_t *p_data;                        /*!< pointer to data, should copy to other buff before event callback return */
+    } cover_art_data;                           /*!< AVRC Cover Art data event */
+
+    /**
+     * @brief ESP_AVRC_CT_PROF_STATE_EVT
+     */
+    struct avrc_ct_init_stat_param {
+        esp_avrc_init_state_t state;            /*!< avrc ct initialization param */
+    } avrc_ct_init_stat;                        /*!< status to indicate avrcp ct init or deinit */
+
 } esp_avrc_ct_cb_param_t;
 
 /// AVRC target callback parameters
@@ -389,6 +464,13 @@ typedef union {
         esp_avrc_set_app_value_param_t *p_vals; /*!< point to the id and value of player application attribute */
     } set_app_value;                            /*!< set player application value */
 
+    /**
+     * @brief ESP_AVRC_TG_PROF_STATE_EVT
+     */
+    struct avrc_tg_init_stat_param {
+        esp_avrc_init_state_t state;            /*!< avrc tg initialization param */
+    } avrc_tg_init_stat;                        /*!< status to indicate avrcp tg init or deinit */
+
 } esp_avrc_tg_cb_param_t;
 
 /**
@@ -429,6 +511,7 @@ esp_err_t esp_avrc_ct_register_callback(esp_avrc_ct_cb_t callback);
  * @brief           Initialize the bluetooth AVRCP controller module, This function should be called
  *                  after esp_bluedroid_enable() completes successfully. Note: AVRC cannot work independently,
  *                  AVRC should be used along with A2DP and AVRC should be initialized before A2DP.
+ *                  ESP_AVRC_CT_PROF_STATE_EVT with ESP_AVRC_INIT_SUCCESS will reported to the APP layer.
  *
  * @return
  *                  - ESP_OK: success
@@ -443,6 +526,7 @@ esp_err_t esp_avrc_ct_init(void);
  * @brief           De-initialize AVRCP controller module. This function should be called after
  *                  after esp_bluedroid_enable() completes successfully. Note: AVRC cannot work independently,
  *                  AVRC should be used along with A2DP and AVRC should be deinitialized before A2DP.
+ *                  ESP_AVRC_CT_PROF_STATE_EVT with ESP_AVRC_DEINIT_SUCCESS will reported to the APP layer.
  *
  * @return
  *                  - ESP_OK: success
@@ -551,6 +635,18 @@ esp_err_t esp_avrc_ct_send_metadata_cmd(uint8_t tl, uint8_t attr_mask);
  */
 esp_err_t esp_avrc_ct_send_passthrough_cmd(uint8_t tl, uint8_t key_code, uint8_t key_state);
 
+/**
+ * @brief           Send get play status command to AVRCP target. This function should be called after
+ *                  ESP_AVRC_CT_CONNECTION_STATE_EVT is received and AVRCP connection is established.
+ *
+ * @param[in]       tl : transaction label, 0 to 15, consecutive commands should use different values.
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
+ *                  - ESP_FAIL: others
+ */
+esp_err_t esp_avrc_ct_send_get_play_status_cmd(uint8_t tl);
 
 /**
  * @brief           Register application callbacks to AVRCP target module. This function should be
@@ -571,6 +667,7 @@ esp_err_t esp_avrc_tg_register_callback(esp_avrc_tg_cb_t callback);
  * @brief           Initialize the bluetooth AVRCP target module, This function should be called
  *                  after esp_bluedroid_enable() completes successfully. Note: AVRC cannot work independently,
  *                  AVRC should be used along with A2DP and AVRC should be initialized before A2DP.
+ *                  ESP_AVRC_TG_PROF_STATE_EVT with ESP_AVRC_INIT_SUCCESS will reported to the APP layer.
  *
  * @return
  *                  - ESP_OK: success
@@ -585,6 +682,7 @@ esp_err_t esp_avrc_tg_init(void);
  * @brief           De-initialize AVRCP target module. This function should be called after
  *                  after esp_bluedroid_enable() completes successfully. Note: AVRC cannot work independently,
  *                  AVRC should be used along with A2DP and AVRC should be deinitialized before A2DP.
+ *                  ESP_AVRC_TG_PROF_STATE_EVT with ESP_AVRC_DEINIT_SUCCESS will reported to the APP layer.
  *
  * @return
  *                  - ESP_OK: success
@@ -656,11 +754,11 @@ bool esp_avrc_psth_bit_mask_operation(esp_avrc_bit_mask_op_t op, esp_avrc_psth_b
 
 /**
  *
- * @brief           Get the requested event notification capabilies on local AVRC target. The capability is returned
+ * @brief           Get the requested event notification capabilities on local AVRC target. The capability is returned
  *                  in a bit mask representation in evt_set. This function should be called after esp_avrc_tg_init().
  *
  *                  For capability type "ESP_AVRC_RN_CAP_ALLOWED_EVT, the retrieved event set is constant and
- *                  it covers all of the notifcation events that can possibly be supported with current
+ *                  it covers all of the notification events that can possibly be supported with current
  *                  implementation.
  *
  *                  For capability type ESP_AVRC_RN_CAP_SUPPORTED_EVT, the event set covers the notification
@@ -729,6 +827,102 @@ bool esp_avrc_rn_evt_bit_mask_operation(esp_avrc_bit_mask_op_t op, esp_avrc_rn_e
 esp_err_t esp_avrc_tg_send_rn_rsp(esp_avrc_rn_event_ids_t event_id, esp_avrc_rn_rsp_t rsp,
                                   esp_avrc_rn_param_t *param);
 
+/**
+ *
+ * @brief           Start the process to establish OBEX connection used in Cover Art Client. Once the operation done,
+ *                  ESP_AVRC_CT_COVER_ART_STATE_EVT will come, operation result can be found in event param. This API
+ *                  can be used only when AVRC Cover Art feature is enabled.
+ *
+ * @param[in]       mtu: MTU used in lower level connection, should not smaller than ESP_AVRC_CA_MTU_MIN or larger than
+ *                  ESP_AVRC_CA_MTU_MAX, if value is not valid, will be reset to ESP_AVRC_CA_MTU_MAX. This can limit
+ *                  the max data length in cover_art_data event.
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC CT is not initialized
+ *                  - ESP_ERR_NOT_SUPPORTED: if peer device does not support Cover Art function
+ *
+ */
+esp_err_t esp_avrc_ct_cover_art_connect(uint16_t mtu);
+
+/**
+ *
+ * @brief           Start the process to release the OBEX connection used in Cover Art Client.Once the operation done,
+ *                  ESP_AVRC_CT_COVER_ART_STATE_EVT will come, operation result can be found in event param. This API
+ *                  can be used only when AVRC Cover Art feature is enabled.
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC CT is not initialized
+ *                  - ESP_ERR_NOT_SUPPORTED: if peer device does not support Cover Art function
+ *
+ */
+esp_err_t esp_avrc_ct_cover_art_disconnect(void);
+
+/**
+ *
+ * @brief           Start the process to get image properties from Cover Art server. This API can be used only when AVRC
+ *                  Cover Art feature is enabled.
+ *
+ * @param[in]       image_handle: pointer to image handle with a length of ESP_AVRC_CA_IMAGE_HANDLE_LEN bytes, can be freed
+ *                  after this function return
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC CT is not initialized
+ *                  - ESP_ERR_NOT_SUPPORTED: if peer device does not support Cover Art function
+ *
+ */
+esp_err_t esp_avrc_ct_cover_art_get_image_properties(uint8_t *image_handle);
+
+/**
+ *
+ * @brief           Start the process to get image from Cover Art server. This API can be used only when AVRC Cover Art
+ *                  feature is enabled.
+ *
+ * @param[in]       image_handle: pointer to image handle with a length of ESP_AVRC_CA_IMAGE_HANDLE_LEN bytes, can be freed
+ *                  after this function return
+ *
+ * @param[in]       image_descriptor: pointer to image descriptor, will be cache internally by bluetooth stack, can be freed
+ *                  once this api return
+ *
+ * @param[in]       image_descriptor_len: the length of image descriptor
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC CT is not initialized
+ *                  - ESP_ERR_NOT_SUPPORTED: if peer device does not support Cover Art function
+ *
+ */
+esp_err_t esp_avrc_ct_cover_art_get_image(uint8_t *image_handle, uint8_t *image_descriptor, uint16_t image_descriptor_len);
+
+/**
+ *
+ * @brief           Start the process to get linked thumbnail from Cover Art server. This API can be used only when AVRC
+ *                  Cover Art feature is enabled.
+ *
+ * @param[in]       image_handle: pointer to image handle with a length of ESP_AVRC_CA_IMAGE_HANDLE_LEN bytes, can be freed
+ *                  after this function return
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not enabled or AVRC CT is not initialized
+ *                  - ESP_ERR_NOT_SUPPORTED: if peer device does not support Cover Art function
+ *
+ */
+esp_err_t esp_avrc_ct_cover_art_get_linked_thumbnail(uint8_t *image_handle);
+
+/**
+ * @brief       This function is used to get the status of AVRCP
+ *
+ * @param[out]  profile_status - AVRCP status
+ *
+ * @return
+ *              - ESP_OK: success
+ *              - other: failed
+ */
+esp_err_t esp_avrc_get_profile_status(esp_avrc_profile_status_t *profile_status);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_ble_cte_api.h b/lib/bt/host/bluedroid/api/include/api/esp_ble_cte_api.h
new file mode 100644
index 00000000..80dc5b15
--- /dev/null
+++ b/lib/bt/host/bluedroid/api/include/api/esp_ble_cte_api.h
@@ -0,0 +1,379 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef __ESP_BLE_CTE_API_H__
+#define __ESP_BLE_CTE_API_H__
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#include "esp_err.h"
+#include "esp_bt_defs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// BLE CTE callback event type
+typedef enum {
+    ESP_BLE_CTE_SET_CONNLESS_TRANS_PARAMS_CMPL_EVT = 0,     /*!< When CTE set connectionless transmit parameters complete, the event comes */
+    ESP_BLE_CTE_SET_CONNLESS_TRANS_ENABLE_CMPL_EVT,         /*!< When CTE set connectionless transmit enable complete, the event comes */
+    ESP_BLE_CTE_SET_CONNLESS_IQ_SAMPLING_ENABLE_CMPL_EVT,   /*!< When CTE set connectionless IQ sampling enable complete, the event comes */
+    ESP_BLE_CTE_SET_CONN_RECV_PARAMS_CMPL_EVT,              /*!< When CTE set connection receive parameters complete, the event comes */
+    ESP_BLE_CTE_SET_CONN_TRANS_PARAMS_CMPL_EVT,             /*!< When CTE set connection transmit parameters complete, the event comes */
+    ESP_BLE_CTE_SET_CONN_REQ_ENABLE_CMPL_EVT,               /*!< When CTE set connection CTE request enable complete, the event comes */
+    ESP_BLE_CTE_SET_CONN_RSP_ENABLE_CMPL_EVT,               /*!< When CTE set connection CTE response enable complete, the event comes */
+    ESP_BLE_CTE_READ_ANT_INFOR_CMPL_EVT,                    /*!< When CTE read antenna information complete, the event comes */
+    ESP_BLE_CTE_CONNLESS_IQ_REPORT_EVT,                     /*!< When the device receives CTE connectionless IQ information, the event comes */
+    ESP_BLE_CTE_CONN_IQ_REPORT_EVT,                         /*!< When the device receives CTE connection IQ information , the event comes */
+    ESP_BLE_CTE_REQUEST_FAILED_EVT,                         /*!< When CTE request progress failed , the event comes */
+    ESP_BLE_CTE_EVT_MAX,                                    /*!< when maximum advertising event complete, the event comes */
+} esp_ble_cte_cb_event_t;
+
+#define ESP_BLE_CTE_SAMPLING_DISABLE              (0x00)
+#define ESP_BLE_CTE_SAMPLING_ENABLE               (0x01)
+
+#define ESP_BLE_CTE_ADV_WITH_CTE_DISABLE          (0x00)
+#define ESP_BLE_CTE_ADV_WITH_CTE_ENABLE           (0x01)
+
+// Constant Tone Extension length in 8 µs units
+#define ESP_BLE_CTE_MIN_CTE_LENGTH                (0x02)
+#define ESP_BLE_CTE_MAX_CTE_LENGTH                (0x14)
+
+#define ESP_BLE_CTE_TYPE_AOA                      (0x00) /*!< AoA Constant Tone Extension */
+#define ESP_BLE_CTE_TYPE_AOD_WITH_1US             (0x01) /*!< AoD Constant Tone Extension with 1 µs slots */
+#define ESP_BLE_CTE_TYPE_AOD_WITH_2US             (0x02) /*!< AoD Constant Tone Extension with 2 µs slots */
+typedef uint8_t   esp_ble_cte_type_t;
+
+#define ESP_BLE_CTE_MIN_CTE_COUNT                 (0x01)
+#define ESP_BLE_CTE_MAX_CTE_COUNT                 (0x10)
+
+#define ESP_BLE_CTE_MIN_SWITCHING_PATTERN_LENGTH  (0x02)
+#define ESP_BLE_CTE_MAX_SWITCHING_PATTERN_LENGTH  (0x4B)
+
+#define ESP_BLE_CTE_SLOT_DURATION_1US             (0x01)
+#define ESP_BLE_CTE_SLOT_DURATION_2US             (0x02)
+typedef uint8_t   esp_ble_cte_slot_dur_type_t;
+
+#define ESP_BLE_CTE_MIN_SAMPLED_CTES              (0x00)
+#define ESP_BLE_CTE_MAX_SAMPLED_CTES              (0x10)
+
+#define ESP_BLE_CTE_TYPES_AOA_RESPONSE            (0x01)
+#define ESP_BLE_CTE_TYPES_AOD_RESPONSE_WITH_1US   (0x02)
+#define ESP_BLE_CTE_TYPES_AOD_RESPONSE_WITH_2US   (0x04)
+#define ESP_BLE_CTE_TYPES_ALL     (ESP_BLE_CTE_TYPES_AOA_RESPONSE | ESP_BLE_CTE_TYPES_AOD_RESPONSE_WITH_1US | ESP_BLE_CTE_TYPES_AOD_RESPONSE_WITH_2US)
+typedef uint8_t   esp_ble_cte_conn_cte_types_t;
+
+#define ESP_BLE_CTE_REQUEST_FOR_CONNECTION_DISABLE      (0x00)
+#define ESP_BLE_CTE_REQUEST_FOR_CONNECTION_ENABLE       (0x01)
+
+#define ESP_BLE_CTE_MIN_REQUESTED_CTE_LENGTH            (0x02)
+#define ESP_BLE_CTE_MAX_REQUESTED_CTE_LENGTH            (0x14)
+
+#define ESP_BLE_CTE_RESPONSE_FOR_CONNECTION_DISABLE     (0x00)
+#define ESP_BLE_CTE_RESPONSE_FOR_CONNECTION_ENABLE      (0x01)
+
+typedef struct {
+    uint8_t adv_handle;                    /*!< Used to identify an advertising set */
+    uint8_t cte_len;                       /*!< Constant Tone Extension length in 8 µs units, range: 0x02 to 0x14 */
+    esp_ble_cte_type_t cte_type;           /*!< AoA or AoD Constant Tone Extension */
+    uint8_t cte_count;                     /*!< The number of Constant Tone Extensions to transmit in each periodic advertising interval, range: 0x01 to 0x10 */
+    uint8_t switching_pattern_len;         /*!< The number of Antenna IDs in the pattern, range: 0x02 to 0x4B */
+    uint8_t *antenna_ids;                  /*!< Antenna ID in the pattern */
+} __attribute__((packed)) esp_ble_cte_connless_trans_params_t;
+
+typedef struct {
+    uint8_t adv_handle;    /*!< Identifier for the advertising set in which Constant Tone Extension is being enabled or disabled */
+    uint8_t cte_enable;    /*!< Advertising with Constant Tone Extension is enabled or disabled */
+} __attribute__((packed)) esp_ble_cte_trans_enable_params_t;
+
+typedef struct {
+    uint16_t sync_handle;                   /*!< Identifier for the periodic advertising train */
+    uint8_t sampling_en;                    /*!< Enable or disable connectionless IQ sampling */
+    esp_ble_cte_slot_dur_type_t slot_dur;   /*!< Switching and sampling slots, 1 us or 2 us */
+    uint8_t max_sampled_ctes;               /*!< The maximum number of CTE to sample and report in each periodic advertising interval, range: 0x00 - 0x10 */
+    uint8_t switching_pattern_len;          /*!< The number of Antenna IDs in the pattern, range: 0x02 to 0x4B */
+    uint8_t *antenna_ids;                   /*!< Antenna ID in the pattern */
+} __attribute__((packed)) esp_ble_cte_iq_sampling_params_t;
+
+typedef struct {
+    uint16_t conn_handle;                  /*!< Connection_Handle */
+    uint8_t sampling_en;                   /*!< Enable or disable connection IQ sampling */
+    esp_ble_cte_slot_dur_type_t slot_dur;  /*!< Switching and sampling slots, 1 us or 2 us */
+    uint8_t switching_pattern_len;         /*!< The number of Antenna IDs in the pattern, range: 0x02 to 0x4B */
+    uint8_t *antenna_ids;                  /*!< Antenna ID in the pattern */
+} __attribute__((packed)) esp_ble_cte_recv_params_params_t;
+
+typedef struct {
+    uint16_t conn_handle;                     /*!< Connection_Handle */
+    esp_ble_cte_conn_cte_types_t cte_types;   /*!< Allow AoA or AoD Constant Tone Extension Response */
+    uint8_t switching_pattern_len;            /*!< The number of Antenna IDs in the pattern, range: 0x02 to 0x4B */
+    uint8_t *antenna_ids;                     /*!< Antenna ID in the pattern */
+} __attribute__((packed)) esp_ble_cte_conn_trans_params_t;
+
+typedef struct {
+    uint16_t conn_handle;                      /*!< Connection_Handle */
+    uint8_t enable;                            /*!< Enable or disable Constant Tone Extension Request for the connection */
+    uint16_t cte_req_interval;                 /*!< Requested interval for initiating the CTE Request procedure in number of underlying connection events, range: 0x0000 - 0xFFFF */
+    uint8_t req_cte_len;                       /*!< Minimum length of the Constant Tone Extension being requested in 8 µs units, range: 0x02 - 0x14 */
+    esp_ble_cte_type_t req_cte_Type;           /*!< AoA or AoD Constant Tone Extension, range: 0x00 - 0x02 */
+} __attribute__((packed)) esp_ble_cte_req_en_params_t;
+
+typedef struct {
+    uint16_t conn_handle;          /*!< Connection_Handle */
+    uint8_t enable;                /*!< Enable or disable Constant Tone Extension Response for the connection */
+} __attribute__((packed)) esp_ble_cte_rsp_en_params_t;
+
+/**
+ * @brief CTE callback parameters union
+ */
+typedef union {
+    /**
+     * @brief ESP_BLE_CTE_SET_CONNLESS_TRANS_PARAMS_CMPL_EVT
+     */
+    struct ble_set_trans_params_cmpl_evt_param {
+        esp_bt_status_t status;           /*!< Indicate setting transmit parameters status, status = (controller error code | 0x100) if status is not equal to 0 */
+    } set_trans_params_cmpl;              /*!< Event parameter of ESP_BLE_CTE_SET_CONNLESS_TRANS_PARAMS_CMPL_EVT */
+
+    /**
+     * @brief ESP_BLE_CTE_SET_CONNLESS_TRANS_ENABLE_CMPL_EVT
+     */
+    struct ble_set_trans_enable_cmpl_evt_param {
+        esp_bt_status_t status;           /*!< Indicate setting transmit enable status, status = (controller error code | 0x100) if status is not equal to 0 */
+    } set_trans_enable_cmpl;              /*!< Event parameter of ESP_BLE_CTE_SET_CONNLESS_TRANS_ENABLE_CMPL_EVT */
+
+    /**
+     * @brief ESP_BLE_CTE_SET_CONNLESS_IQ_SAMPLING_ENABLE_CMPL_EVT
+     */
+    struct ble_set_iq_sampling_en_cmpl_evt_param {
+        esp_bt_status_t status;             /*!< Indicate setting IQ sampling enable status, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t sync_handle;               /*!< Sync_Handle identifying the periodic advertising */
+    } iq_sampling_enable_cmpl;              /*!< Event parameter of ESP_BLE_CTE_SET_CONNLESS_IQ_SAMPLING_ENABLE_CMPL_EVT */
+
+    /**
+     * @brief ESP_BLE_CTE_SET_CONN_RECV_PARAMS_CMPL_EVT
+     */
+    struct ble_set_conn_recv_params_cmpl_evt_param {
+        esp_bt_status_t status;           /*!< Indicate setting received parameters status, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t conn_handle;             /*!< The connection identifier */
+    } conn_recv_params_cmpl;              /*!< Event parameter of ESP_BLE_CTE_SET_CONN_RECV_PARAMS_CMPL_EVT */
+
+    /**
+     * @brief ESP_BLE_CTE_SET_CONN_TRANS_PARAMS_CMPL_EVT
+     */
+    struct ble_set_conn_trans_params_cmpl_evt_param {
+        esp_bt_status_t status;            /*!< Indicate setting connection transmit parameters status, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t conn_handle;              /*!< The connection identifier */
+    } conn_trans_params_cmpl;              /*!< Event parameter of ESP_BLE_CTE_SET_CONN_TRANS_PARAMS_CMPL_EVT */
+
+    /**
+     * @brief ESP_BLE_CTE_SET_CONN_REQ_ENABLE_CMPL_EVT
+     */
+    struct ble_set_conn_req_en_cmpl_evt_param {
+        esp_bt_status_t status;      /*!< Indicate setting connection request enable status, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t conn_handle;        /*!< The connection identifier */
+    } conn_req_en_cmpl;              /*!< Event parameter of ESP_BLE_CTE_SET_CONN_REQ_ENABLE_CMPL_EVT */
+
+    /**
+     * @brief ESP_BLE_CTE_SET_CONN_RSP_ENABLE_CMPL_EVT
+     */
+    struct ble_set_conn_rsp_en_cmpl_evt_param {
+        esp_bt_status_t status;      /*!< Indicate setting connection response enable status, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t conn_handle;        /*!< The connection identifier */
+    } conn_rsp_en_cmpl;              /*!< Event parameter of ESP_BLE_CTE_SET_CONN_RSP_ENABLE_CMPL_EVT */
+
+    /**
+     * @brief ESP_BLE_CTE_READ_ANT_INFOR_CMPL_EVT
+     */
+    struct ble_read_ant_infor_cmpl_evt_param {
+        esp_bt_status_t status;                      /*!< Indicate reading antenna information status, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint8_t supported_switching_sampling_rates;  /*!< bit 0: 1 µs switching supported for AoD transmission
+                                                          bit 1: 1 µs sampling supported for AoD reception
+                                                          bit 2: 1 µs switching and sampling supported for AoA reception */
+        uint8_t num_antennae;                        /*!< The number of antennae supported by the Controller */
+        uint8_t max_switching_pattern_len;           /*!< Maximum length of antenna switching pattern supported by the Controller */
+        uint8_t max_cte_len;                         /*!< Maximum length of a transmitted Constant Tone Extension supported in 8 µs units */
+    } read_ant_infor_cmpl;                           /*!< Event parameter of ESP_BLE_CTE_READ_ANT_INFOR_CMPL_EVT */
+
+    /**
+     * @brief ESP_BLE_CTE_CONNLESS_IQ_REPORT_EVT
+     */
+    struct ble_cte_connless_iq_rpt_evt_param {
+        uint16_t sync_handle;                      /*!< Sync_Handle identifying the periodic advertising train */
+        uint8_t channel_idx;                       /*!< The index of the channel on which the packet was received */
+        int16_t rssi;                              /*!< RSSI of the packet, Range: -1270 to +200, Units: 0.1 dBm */
+        uint8_t rssi_ant_id;                       /*!< Antenna ID */
+        uint8_t cte_type;                          /*!< The type of Constant Tone Extension, range: 0x00 - 0x02 */
+        uint8_t slot_dur;                          /*!< Switching and sampling slots, 1 us or 2us, range: 0x01 - 0x02 */
+        uint8_t pkt_status;                        /*!< indicates whether the received packet had a valid CRC, range: 0x00 - 0x02 and 0xFF */
+        uint16_t periodic_evt_counter;             /*!< The value of paEventCounter for the reported AUX_SYNC_IND PDU */
+        uint8_t sample_count;                      /*!< Total number of sample pairs, range: 0x00 and 0x09 - 0x52*/
+        uint8_t *i_sample;                         /*!< I sample for the reported packet. No valid sample available if value is 0x80 */
+        uint8_t *q_sample;                         /*!< Q sample for the reported packet. No valid sample available if value is 0x80 */
+    } connless_iq_rpt;                             /*!< Event parameter of ESP_BLE_CTE_CONNLESS_IQ_REPORT_EVT */
+
+    /**
+     * @brief ESP_BLE_CTE_CONN_IQ_REPORT_EVT
+     */
+    struct ble_cte_conn_iq_rpt_evt_param {
+        uint16_t conn_handle;                    /*!< Connection_Handle */
+        uint8_t rx_phy;                          /*!< The receiver PHY for the connection, range: 0x01 - 0x02 */
+        uint8_t data_channel_idx;                /*!< The index of the data channel on which the Data Physical Channel PDU was received, range: 0x00 - 0x24 */
+        int16_t rssi;                            /*!< RSSI of the packet, range: -1270 - +200, units: 0.1 dBm */
+        uint8_t rssi_ant_id;                     /*!< ID of the antenna on which the RSSI is measured */
+        uint8_t cte_type;                        /*!< AoA or AoD Constant Tone Extension, range: 0x00 - 0x02 */
+        uint8_t slot_dur;                        /*!< Switching and sampling slots, range: 0x01 - 0x02 */
+        uint8_t pkt_status;                      /*!< indicates whether the received packet had a valid CRC, range: 0x00 - 0x02 and 0xFF */
+        uint16_t conn_evt_counter;               /*!< The value of connEventCounter for the reported PDU */
+        uint8_t sample_count;                    /*!< Total number of sample pairs, range: 0x00 and 0x09 - 0x52 */
+        uint8_t *i_sample;                       /*!< I sample for the reported PDU. No valid sample available if value is 0x80 */
+        uint8_t *q_sample;                       /*!< Q sample for the reported PDU,. No valid sample available if value is 0x80 */
+    } conn_iq_rpt;                               /*!< Event parameter of ESP_BLE_CTE_CONN_IQ_REPORT_EVT */
+
+    /**
+     * @brief ESP_BLE_CTE_REQUEST_FAILED_EVT
+     */
+    struct ble_cte_req_failed_evt_param{
+        uint8_t  reason;                        /*!< value: 0x00, LL_CTE_RSP PDU received successfully but without a Constant Tone Extension field;
+                                                    value: 0x01 to 0xFF, Peer rejected the request, see [Vol 1] Part F controller error codes and descriptions */
+        uint16_t conn_handle;                   /*!< Connection_Handle */
+    } req_failed_evt;                           /*!< Event parameter of ESP_BLE_CTE_REQUEST_FAILED_EVT */
+
+} esp_ble_cte_cb_param_t;
+
+/**
+ * @brief CTE callback function type
+ * @param event : Event type
+ * @param param : Point to callback parameter, currently is union type
+ */
+typedef void (* esp_ble_cte_cb_t)(esp_ble_cte_cb_event_t event, esp_ble_cte_cb_param_t *param);
+
+/**
+ * @brief           This function is called to occur cte event
+ *
+ * @param[in]       callback: callback function
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_cte_register_callback(esp_ble_cte_cb_t callback);
+
+/**
+ * @brief           This function is called to get the current cte callback
+ *
+ * @return
+ *                  - esp_ble_cte_cb_t : callback function
+ *
+ */
+esp_ble_cte_cb_t esp_ble_cte_get_callback(void);
+
+/**
+ * @brief           This function is called to set parameters for the transmission of CTE in the periodic advertising.
+ *
+ * @param[in]       cte_trans_params: pointer to User defined cte_trans_params data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_cte_set_connectionless_trans_params(esp_ble_cte_connless_trans_params_t *cte_trans_params);
+
+/**
+ * @brief           This function is called to request that the Controller enables or disables the use of CTE in the periodic advertising.
+ *
+ * @param[in]       cte_trans_enable: pointer to User defined cte_trans_enable data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_cte_set_connectionless_trans_enable(esp_ble_cte_trans_enable_params_t *cte_trans_enable);
+
+/**
+ * @brief           This function is called to request that the Controller enables or disables capturing IQ samples from the CTE
+*                   of periodic advertising packets.
+ *
+ * @param[in]       iq_sampling_en: pointer to User defined iq_sampling_en data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_cte_set_connectionless_iq_sampling_enable(esp_ble_cte_iq_sampling_params_t *iq_sampling_en);
+
+/**
+ * @brief           This function is called to enable or disable sampling received CTE fields on the connection.
+ *
+ * @param[in]       cte_recv_params: pointer to User defined cte_recv_params data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_cte_set_connection_receive_params(esp_ble_cte_recv_params_params_t *cte_recv_params);
+
+/**
+ * @brief           This function is called to set the parameters used for transmitting CTE requested by the peer
+ *                  device on the connection.
+ *
+ * @param[in]       cte_conn_trans_params: pointer to User defined cte_conn_trans_params data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_cte_set_connection_transmit_params(esp_ble_cte_conn_trans_params_t *cte_conn_trans_params);
+
+/**
+ * @brief           This function is called to request the Controller to start or stop initiating the CTE Request
+ *                  procedure  on a connection.
+ *
+ * @param[in]       cte_conn_req_en: pointer to User defined cte_conn_req_en data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_cte_connection_cte_request_enable(esp_ble_cte_req_en_params_t *cte_conn_req_en);
+
+/**
+ * @brief           This function is called to request the Controller to respond to LL_CTE_REQ PDUs with
+ *                  LL_CTE_RSP PDUs on the specified connection.
+ *
+ * @param[in]       cte_conn_rsp_en: pointer to User defined cte_conn_rsp_en data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_cte_connection_cte_response_enable(esp_ble_cte_rsp_en_params_t *cte_conn_rsp_en);
+
+/**
+ * @brief           This function is called to read the parameters of a transmitted CTE supported by the Controller.
+ *
+ * @param[in]       none.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_cte_read_antenna_information(void);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __ESP_BLE_CTE_API_H__ */
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_ble_iso_api.h b/lib/bt/host/bluedroid/api/include/api/esp_ble_iso_api.h
new file mode 100644
index 00000000..5531393e
--- /dev/null
+++ b/lib/bt/host/bluedroid/api/include/api/esp_ble_iso_api.h
@@ -0,0 +1,660 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef __ESP_BLE_ISO_API_H__
+#define __ESP_BLE_ISO_API_H__
+
+#include <stdint.h>
+#include <stdbool.h>
+
+#include "esp_err.h"
+#include "esp_bt_defs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/// ISO BLE callback event type
+typedef enum {
+    ESP_BLE_ISO_BIG_CREATE_CMPL_EVT = 0,                     /*!< When BIG create complete, the event comes */
+    ESP_BLE_ISO_BIG_TERMINATE_CMPL_EVT,                      /*!< When BIG terminate complete, the event comes */
+    ESP_BLE_ISO_BIG_SYNC_ESTABLISHED_EVT,                    /*!< When BIG sync established, the event comes */
+    ESP_BLE_ISO_BIG_SYNC_LOST_EVT,                           /*!< When BIG sync lost, the event comes */
+    ESP_BLE_ISO_BIG_SYNC_TERMINATE_CMPL_EVT,                 /*!< When BIG sync terminate complete, the event comes */
+    ESP_BLE_ISO_BIGINFO_ADV_REPORT_EVT,                      /*!< When receiving an Advertising PDU that contained a BIGInfo field, the event comes */
+    ESP_BLE_ISO_ISO_DATA_PATH_UPDATE_EVT,                    /*!< When ISO data path update complete, the event comes */
+    ESP_BLE_ISO_READ_ISO_TX_SYNC_CMPL_EVT,                   /*!< When reading tx sync complete, the event comes */
+    ESP_BLE_ISO_READ_LINK_QUALITY_CMPL_EVT,                  /*!< When reading link quality complete, the event comes */
+    ESP_BLE_ISO_SET_CIG_PARAMS_CMPL_EVT,                     /*!< When CIG parameters set complete, the event comes */
+    ESP_BLE_ISO_CREATE_CIS_CMPL_EVT,                         /*!< When CIS create complete, the event comes */
+    ESP_BLE_ISO_REMOVE_CIG_CMPL_EVT,                         /*!< When CIG remove complete, the event comes */
+    ESP_BLE_ISO_CIS_REQUEST_EVT,                             /*!< When Receiving CIS request event, the event comes */
+    ESP_BLE_ISO_ACCEPT_CIS_REQ_CMPL_EVT,                     /*!< When CIS request event accept complete, the event comes */
+    ESP_BLE_ISO_REJECT_CIS_REQ_CMPL_EVT,                     /*!< When CIS request event reject complete, the event comes */
+    ESP_BLE_ISO_CIS_ESTABLISHED_EVT,                         /*!< When CIS is established, the event comes */
+    ESP_BLE_ISO_CIS_DISCONNECTED_EVT,                        /*!< When CIS is disconnected, the event comes */
+    ESP_BLE_ISO_EVT_MAX,                                     /*!< when maximum advertising event complete, the event comes */
+} esp_ble_iso_cb_event_t;
+
+typedef enum {
+    ESP_BLE_ISO_DATA_PATH_UNKNOWN = 0,
+    ESP_BLE_ISO_DATA_PATH_SETUP   = 1,
+    ESP_BLE_ISO_DATA_PATH_REMOVE  = 2,
+    ESP_BLE_ISO_DATA_PATH_MAX,
+} ESP_BLE_ISO_DATA_PATH_UPDATE_TYPE;
+
+#define ESP_BLE_ISO_DATA_PATH_DIR_INPUT            (0x00)
+#define ESP_BLE_ISO_DATA_PATH_DIR_OUTPUT           (0x01)
+
+#define ESP_BLE_ISO_DATA_PATH_DIR_INPUT_BIT_MASK  (1 << 0)
+#define ESP_BLE_ISO_DATA_PATH_DIR_OUTPUT_BIT_MASK (1 << 1)
+#define ESP_BLE_ISO_DATA_PATH_DIR_ALL_BIT_MASK    (ESP_BLE_ISO_DATA_PATH_DIR_INPUT_BIT_MASK | ESP_BLE_ISO_DATA_PATH_DIR_OUTPUT_BIT_MASK)
+
+#define ESP_BLE_MAX_BIS_NUM      (31)
+#define ESP_BLE_MAX_CIS_NUM      (31)
+
+#define BLE_ISO_SDU_INT_MIN       (0x0000FF)
+#define BLE_ISO_SDU_INT_MAX       (0x0FFFFF)
+
+#define BLE_ISO_WORST_CASE_SCA_LEVEL_500_PPM    (0x00)
+#define BLE_ISO_WORST_CASE_SCA_LEVEL_250_PPM    (0x01)
+#define BLE_ISO_WORST_CASE_SCA_LEVEL_150_PPM    (0x02)
+#define BLE_ISO_WORST_CASE_SCA_LEVEL_100_PPM    (0x03)
+#define BLE_ISO_WORST_CASE_SCA_LEVEL_75_PPM     (0x04)
+#define BLE_ISO_WORST_CASE_SCA_LEVEL_50_PPM     (0x05)
+#define BLE_ISO_WORST_CASE_SCA_LEVEL_30_PPM     (0x06)
+#define BLE_ISO_WORST_CASE_SCA_LEVEL_20_PPM     (0x07)
+
+#define BLE_ISO_PACKING_SEQUENTIAL                      (0x00)
+#define BLE_ISO_PACKING_INTERLEAVED                     (0x00)
+
+#define BLE_ISO_FRAMING_UNFRAMED_PDU                    (0x00)
+#define BLE_ISO_FRAMING_FRAMED_PDU_SEGMENTABLE_MODE     (0x01)
+#define BLE_ISO_FRAMING_FRAMED_PDU_UNSEGMENTABLE_MODE   (0x02)
+
+#define BLE_ISO_MAX_TRANSPORT_LATENCY_MIN               (0x0005)
+#define BLE_ISO_MAX_TRANSPORT_LATENCY_MAX               (0x0FA0)
+
+#if (BLE_FEAT_ISO_BIG_BROCASTER_EN == TRUE)
+typedef struct {
+    uint8_t big_handle;             /*!< Used to identify the BIG, value 0x00 to 0xEF */
+    uint8_t adv_handle;             /*!< Used to identify the periodic advertising train, value 0x00 to 0xEF */
+    uint8_t num_bis;                /*!< Total number of BISes in the BIG, value 0x01 to 0x1F */
+    uint32_t sdu_interval;          /*!< The interval, in microseconds, of periodic SDUs, value 0x0000FF to 0x0FFFFF*/
+    uint16_t max_sdu;               /*!< Maximum size of an SDU, in octets, value 0x0001 to 0x0FFF */
+    uint16_t max_transport_latency; /*!< Maximum transport latency, in milliseconds, value 0x0005 to 0x0FA0 */
+    uint8_t rtn;                    /*!< The number of times that every BIS Data PDU should be retransmitted, value 0x00 to 0x1E */
+    uint8_t phy;                    /*!< The transmitter PHY of packets, value bit[0, 2] */
+    uint8_t packing;                /*!< The preferred method of arranging subevents of multiple BISes, value 0x00 to 0x01 */
+    uint8_t framing;                /*!< The format of the BIS Data PDUs and the mode of framed PDUs that the Controller shall use on the specified BIG, value 0x00 to 0x02 */
+    uint8_t encryption;             /*!< The encryption mode of the BISes in the BIG, value 0x00 to 0x01 */
+    uint8_t broadcast_code[16];     /*!< The code used to derive the session key that is used to encrypt and decrypt BIS payloads */
+} esp_ble_iso_big_creat_params_t;
+
+typedef struct {
+    uint8_t big_handle;    /*!< Used to identify the BIG, value 0x00 to 0xEF */
+    uint8_t adv_handle;    /*!< Used to identify the periodic advertising train, value 0x00 to 0xEF */
+    uint8_t num_bis;       /*!< Total number of BISes in the BIG, value 0x01 to 0x1F */
+    uint32_t sdu_interval; /*!< The interval, in microseconds, of periodic SDUs, value 0x0000FF to 0x0FFFFF*/
+    uint16_t iso_interval; /*!< the time between two consecutive BIG anchor points, Range: 0x0004 to 0x0C80, Time = N × 1.25 ms */
+    uint8_t nse;           /*!< The total number of subevents in each interval of each BIS in the BIG, value 0x01 to 0x1F */
+    uint16_t max_sdu;      /*!< Maximum size, in octets, of an SDU */
+    uint16_t max_pdu;      /*!< Maximum size, in octets, of payload, value 0x0001 to 0x00FB */
+    uint8_t phy;           /*!< The transmitter PHY of packets */
+    uint8_t packing;       /*!< The preferred method of arranging subevents of multiple BISes, value 0x00 to 0x01 */
+    uint8_t framing;       /*!< The format of the BIS Data PDUs and the mode of framed PDUs that the Controller shall use on the specified BIG, value 0x00 to 0x02 */
+    uint8_t bn;            /*!< The number of new payloads in each interval for each BIS, value 0x01 to 0x07 */
+    uint8_t irc;           /*!< The number of times the scheduled payloads are transmitted in a given event, value 0x01 to 0x0F */
+    uint8_t pto;           /*!< Offset used for pre-transmissions, value 0x00 to 0x0F */
+    uint8_t encryption;    /*!< The encryption mode of the BISes in the BIG, value 0x00 to 0x01 */
+    uint8_t broadcast_code[16]; /*!< The code used to derive the session key that is used to encrypt and decrypt BIS payloads */
+} esp_ble_iso_big_creat_test_params_t;
+
+#endif //#if (BLE_FEAT_ISO_BIG_BROCASTER_EN == TRUE)
+
+#if (BLE_FEAT_ISO_BIG_SYNCER_EN == TRUE)
+typedef struct {
+    uint8_t big_handle;               /*!< Used to identify the BIG, value 0x00 to 0xEF */
+    uint16_t sync_handle;             /*!< Identifier of the periodic advertising train, value 0x0000 to 0x0EFF*/
+    uint8_t encryption;               /*!< Broadcast_Code is valid or invalid, value 0x00 to 0x01 */
+    uint8_t bc_code[16];              /*!< 128-bit code used for deriving the session key for decrypting payloads of BISes in the BIG */
+    uint8_t mse;                      /*!< Maximum number of subevents that should be used to receive data payloads in each BIS event, value 0x00 to 0x1F */
+    uint16_t big_sync_timeout;        /*!< Synchronization timeout for the BIG, Range: 0x000A to 0x4000, Time = N × 10 ms, Time Range: 100 ms to 163.84 s*/
+    uint8_t num_bis;                  /*!< Total number of BISes to synchronize, value 0x01 to 0x1F */
+    uint8_t bis[ESP_BLE_MAX_BIS_NUM]; /*!< Index of a BIS, value 0x01 to 0x1F */
+} esp_ble_iso_big_sync_creat_params_t;
+
+#endif // #if (BLE_FEAT_ISO_BIG_SYNCER_EN == TRUE)
+
+typedef struct {
+    uint16_t iso_handle;       /*!< Connection handle of the CIS or BIS*/
+    uint8_t data_path_dir;     /*!< The direction for which the data path is being configured, value 0x00 to 0x01 */
+    uint8_t data_path_id;      /*!< The data transport path used, value 0x00 to 0xFE */
+    uint8_t coding_fmt;        /*!< See Assigned Numbers for Coding Format */
+    uint16_t company_id;       /*!< Company ID, see Assigned Numbers for Company Identifier. Shall be ignored if coding_fmt is not 0xFF*/
+    uint16_t vs_codec_id;      /*!< Vendor-defined codec ID, Shall be ignored if coding_fmt is not 0xFF */
+    uint32_t controller_delay; /*!< Controller delay in microseconds, range: 0x000000 to 0x3D0900, time range: 0 s to 4 s*/
+    uint8_t codec_cfg_len;     /*!< Length of codec configuration */
+    uint8_t *codec_cfg;        /*!< Codec-specific configuration data */
+} esp_ble_iso_set_data_path_params_t;
+
+typedef struct {
+    uint16_t iso_handle;   /*!< Connection handle of the CIS or BIS. Range: 0x0000 to 0x0EFF */
+    uint8_t data_path_dir; /*!< which directions are to have the data path removed */
+} __attribute__((packed)) esp_ble_iso_remove_data_path_params_t;
+
+struct ble_iso_cis_params {
+    uint8_t cis_id;          /*!< Used to identify a CIS */
+    uint16_t max_sdu_c_to_p; /*!< Maximum size, in octets, of the payload from the Central’s Host */
+    uint16_t max_sdu_p_to_c; /*!< Maximum size, in octets, of the payload from the Peripheral’s Host */
+    uint8_t phy_c_to_p;      /*!< The transmitter PHY of packets from the Central */
+    uint8_t phy_p_to_c;      /*!< The transmitter PHY of packets from the Peripheral */
+    uint8_t rtn_c_to_p;      /*!< Number of times every CIS Data PDU should be retransmitted from the Central to the Peripheral */
+    uint8_t rtn_p_to_c;      /*!< Number of times every CIS Data PDU should be retransmitted from the Peripheral to the Central */
+} __attribute__((packed));
+
+struct ble_iso_cis_params_test {
+    uint8_t cis_id;          /*!< Used to identify a CIS */
+    uint8_t nse;             /*!< Maximum number of subevents in each CIS event */
+    uint16_t max_sdu_c_to_p; /*!< Maximum size, in octets, of the payload from the Central’s Host */
+    uint16_t max_sdu_p_to_c; /*!< Maximum size, in octets, of the payload from the Peripheral’s Host */
+    uint16_t max_pdu_c_to_p; /*!< Maximum size, in octets, of the payload from the Central’s Link Layer to the Peripheral’s Link Layer */
+    uint16_t max_pdu_p_to_c; /*!< Maximum size, in octets, of the payload from the Peripheral’s Link Layer to the Central’s Link Layer */
+    uint8_t phy_c_to_p;      /*!< The transmitter PHY of packets from the Central */
+    uint8_t phy_p_to_c;      /*!< The transmitter PHY of packets from the Peripheral */
+    uint8_t bn_c_to_p;       /*!< The burst number for Central to Peripheral */
+    uint8_t bn_p_to_c;       /*!< The burst number for Peripheral to Central */
+} __attribute__((packed));
+
+#if (BLE_FEAT_ISO_CIG_CENTRAL_EN == TRUE)
+struct esp_ble_iso_set_cig_params {
+    uint8_t cig_id;           /*!< Used to identify the CIG */
+    uint32_t sdu_int_c_to_p;  /*!< The interval, in microseconds, of periodic SDUs */
+    uint32_t sdu_int_p_to_c;  /*!< The interval, in microseconds, of periodic SDUs */
+    uint8_t worse_case_SCA;   /*!< The worst-case sleep clock accuracy of all the Peripherals that will participate in the CIG */
+    uint8_t packing;          /*!< The preferred method of arranging subevents of multiple CISes */
+    uint8_t framing;          /*!< The format of the CIS Data PDUs of the specified CISes' framing mode that the Host is requesting for the CIG */
+    uint16_t mtl_c_to_p;      /*!< The maximum transport latency from the Central to the Peripheral, in milliseconds */
+    uint16_t mtl_p_to_c;      /*!< The maximum transport latency from the Peripheral to the Central, in milliseconds */
+    uint8_t cis_cnt;          /*!< Total number of CIS configurations in the CIG being added or modified */
+    struct ble_iso_cis_params cis_params[ESP_BLE_MAX_CIS_NUM]; /*!< */
+}__attribute__((packed));
+
+struct esp_ble_iso_set_cig_params_test {
+    uint8_t cig_id;          /*!< Used to identify the CIG */
+    uint32_t sdu_int_c_to_p; /*!< The interval, in microseconds, of periodic SDUs */
+    uint32_t sdu_int_p_to_c; /*!< The interval, in microseconds, of periodic SDUs */
+    uint8_t ft_c_to_p;       /*!< The flush timeout in multiples of ISO_Interval for each payload sent from the Central to Peripheral */
+    uint8_t ft_p_to_c;       /*!< The flush timeout in multiples of ISO_Interval for each payload sent from the Peripheral to Central */
+    uint16_t iso_interval;   /*!< Time between consecutive CIS anchor points. Range: 0x0004 to 0x0C80, Time = N × 1.25 ms, Time Range: 5 ms to 4 s */
+    uint8_t worse_case_SCA;  /*!< The worst-case sleep clock accuracy of all the Peripherals that will participate in the CIG */
+    uint8_t packing;         /*!< The preferred method of arranging subevents of multiple CISes */
+    uint8_t framing;         /*!< The format of the CIS Data PDUs of the specified CISes' framing mode that the Host is requesting for the CIG */
+    uint8_t cis_cnt;         /*!< Total number of CIS configurations in the CIG being added or modified */
+    struct ble_iso_cis_params_test cis_params_test[ESP_BLE_MAX_CIS_NUM];
+} __attribute__((packed));
+
+struct esp_ble_gatt_cis_hdl {
+    uint16_t cis_hdl; /*!< Connection handle of a CIS */
+    uint16_t acl_hdl; /*!< Connection handle of an ACL connection */
+}__attribute__((packed));
+
+struct esp_ble_iso_create_cis_params {
+    uint8_t cis_count; /*!< Total number of CISes to be created */
+    struct esp_ble_gatt_cis_hdl cis_hdl_info[ESP_BLE_MAX_CIS_NUM];
+}__attribute__((packed));
+#endif // #if (BLE_FEAT_ISO_CIG_CENTRAL_EN == TRUE)
+
+/**
+ * @brief ISO callback parameters union
+ */
+typedef union {
+    /**
+     * @brief ESP_BLE_ISO_BIG_CREATE_CMPL_EVT
+     */
+    struct ble_big_create_cmpl_evt_param {
+        esp_bt_status_t status;     /*!< Indicate the BIG was successfully created */
+        uint8_t big_handle;         /*!< The identifier of the BIG */
+        uint32_t big_sync_delay;    /*!< The maximum time, in microseconds, for transmission of PDUs of all BISes in a BIG event */
+        uint32_t transport_latency; /*!< The actual transport latency, in microseconds */
+        uint8_t phy;                /*!< The PHY used to create the BIG */
+        uint8_t nse;                /*!< The number of subevents in each BIS event in the BIG. The value shall be an integer multiple of BN */
+        uint8_t bn;                 /*!< The number of new payloads in each BIS event */
+        uint8_t pto;                /*!< Offset used for pre-transmissions */
+        uint8_t irc;                /*!< The number of times a payload is transmitted in a BIS event */
+        uint16_t max_pdu;           /*!< Maximum size, in octets, of the payload */
+        uint16_t iso_interval;      /*!< The time between two consecutive BIG anchor points, Time = N × 1.25 ms */
+        uint8_t num_bis;            /*!< Total number of BISes in the BIG */
+        uint16_t bis_handle[ESP_BLE_MAX_BIS_NUM]; /*!< Connection handle of a BIS */
+    } create_big_cmpl;              /*!< Event parameter of ESP_BLE_ISO_BIG_CREATE_CMPL_EVT */
+    /**
+     * @brief ESP_BLE_ISO_BIG_TERMINATE_CMPL_EVT
+     */
+    struct ble_big_term_cmpl_evt_param {
+        esp_bt_status_t status;/*!< Indicate BIG terminate complete */
+        uint8_t big_handle;    /*!< The identifier of the BIG */
+        uint8_t reason;        /*!< Reason for termination. See [Vol 1] Part F, Controller Error Codes for a list of error codes and descriptions */
+    } term_big_cmpl;           /*!< Event parameter of ESP_BLE_ISO_BIG_TERMINATE_CMPL_EVT */
+    /**
+     * @brief ESP_BLE_ISO_BIG_SYNC_ESTABLISHED_EVT
+     */
+    struct ble_big_sync_estab_evt_param {
+        esp_bt_status_t status;     /*!< Indicate synchronization to the BIG is completed */
+        uint8_t big_handle;         /*!< The identifier of the BIG */
+        uint32_t transport_latency; /*!< The actual transport latency, in microseconds */
+        uint8_t nse;                /*!< The number of subevents in each BIS event in the BIG */
+        uint8_t bn;                 /*!< The number of new payloads in each BIS event */
+        uint8_t pto;                /*!< The offset in number of ISO_Intervals for pre transmissions of data packets */
+        uint8_t irc;                /*!< The number of times a payload is transmitted in a BIS event */
+        uint16_t max_pdu;           /*!< The maximum size of every BIS Data PDU for every BIS in the BIG */
+        uint16_t iso_interval;      /*!< The time duration between two consecutive BIG anchor points */
+        uint8_t num_bis;            /*!< The total number of BISes in the BIG */
+        uint16_t bis_handle[ESP_BLE_MAX_BIS_NUM]; /*!< Connection handle of a BIS in the BIG */
+    } big_sync_estab;               /*!< Event parameter of ESP_BLE_ISO_BIG_SYNC_ESTABLISHED_EVT */
+    /**
+     * @brief ESP_BLE_ISO_BIG_SYNC_LOST_EVT
+     */
+    struct ble_big_sync_lost_evt_param {
+        uint8_t big_handle; /*!< The identifier of a BIG */
+        uint8_t reason;     /*!< The synchronization to BIG is terminated. See [Vol 1] Part F, Controller Error Codes for a list of error codes and descriptions */
+    } big_sync_lost;        /*!< Event parameter of ESP_BLE_ISO_BIG_SYNC_LOST_EVT */
+    /**
+     * @brief ESP_BLE_ISO_BIG_SYNC_TERMINATE_CMPL_EVT
+     */
+    struct ble_big_sync_term_cmpl_evt_param {
+        esp_bt_status_t status;     /*!< Indicate BIG sync terminate success or not */
+        uint8_t big_handle;         /*!< Identifier of the BIG */
+    } term_big_sync;                /*!< Event parameter of ESP_BLE_ISO_BIG_SYNC_TERMINATE_CMPL_EVT */
+    /**
+     * @brief ESP_BLE_ISO_BIGINFO_ADV_REPORT_EVT
+     */
+    struct ble_biginfo_report_evt_param {
+        uint16_t sync_handle;  /*!< Identify the periodic advertising train containing the BIGInfo field */
+        uint8_t num_bis;       /*!< The total number of BISes in the BIG */
+        uint8_t nse;           /*!< The total number of subevents that are used to transmit BIS Data PDUs for each BIS in a BIG event */
+        uint16_t iso_interval; /*!< The time duration between two consecutive BIG anchor points */
+        uint8_t bn;            /*!< The number of new payloads for each BIS */
+        uint8_t pto;           /*!< The offset in number of ISO_Intervals for pre transmissions of data packets */
+        uint8_t irc;           /*!< The number of times the scheduled data packet is transmitted */
+        uint16_t max_pdu;      /*!< The maximum size of every BIS Data PDU for every BIS in the BIG */
+        uint32_t sdu_interval; /*!< The time interval of the periodic SDUs */
+        uint16_t max_sdu;      /*!< The maximum size of an SDU */
+        uint8_t phy;           /*!< The transmitter PHY of packets */
+        uint8_t framing;       /*!< The format of the BIS Data PDUs and the mode of framed PDUs that the Controller used on the specified BIG */
+        uint8_t encryption;    /*!< The encryption mode of the BISes in the BIG */
+    } biginfo_report;          /*!< Event parameter of ESP_BLE_ISO_BIGINFO_ADV_REPORT_EVT */
+    /**
+     * @brief ESP_BLE_ISO_ISO_DATA_PATH_UPDATE_EVT
+     */
+    struct ble_iso_data_path_update_evt_param {
+        esp_bt_status_t status;     /*!< Indicate data path update success status */
+        ESP_BLE_ISO_DATA_PATH_UPDATE_TYPE op_type; /*!< data path update type, setup or remove */
+        uint16_t iso_hdl;   /*!< Connection handle of the CIS or BIS */
+    } data_path;            /*!< Event parameter of ESP_BLE_ISO_ISO_DATA_PATH_UPDATE_EVT */
+    /**
+     * @brief ESP_BLE_ISO_READ_ISO_TX_SYNC_CMPL_EVT
+     */
+    struct ble_iso_read_tx_sync_evt_param {
+        esp_bt_status_t status;  /*!< Indicate tx sync read success status */
+        uint16_t iso_hdl;       /*!< Connection handle of the CIS or BIS */
+        uint16_t pkt_seq_num;   /*!< The packet sequence number of an SDU */
+        uint32_t tx_time_stamp; /*!< The CIG reference point or BIG anchor point of a transmitted SDU derived using the Controller's free running reference clock (in microseconds) */
+        uint32_t time_offset;   /*!< The time offset, in microseconds, that is associated with a transmitted SDU */
+    } read_tx_sync;             /*!< Event parameter of ESP_BLE_ISO_READ_ISO_TX_SYNC_CMPL_EVT */
+    /**
+     * @brief ESP_BLE_ISO_READ_LINK_QUALITY_CMPL_EVT
+     */
+    struct ble_iso_read_link_quality_evt_param {
+        esp_bt_status_t status;       /*!< Indicate link quality read success status */
+        uint16_t iso_hdl;             /*!< The identifier of the BIS or CIS */
+        uint32_t tx_unacked_pkts;     /*!< for CIS, The Link Layer does not receive an acknowledgment for a CIS Data PDU that it transmitted at least once by its flush point*/
+        uint32_t tx_flushed_pkts;     /*!< for CIS, The Link Layer does not transmit a specific payload by its flush point */
+        uint32_t tx_last_subevt_pkts; /*!< for CIS in Peripheral role, The Link Layer transmits a CIS Data PDU in the last subevent of a CIS event */
+        uint32_t retransmitted_pkts;  /*!< for CIS, The Link Layer retransmits a CIS Data PDU */
+        uint32_t crc_error_pkts;      /*!< for CIS and BIS, The Link Layer receives a packet with a CRC error */
+        uint32_t rx_unreceived_pkts;  /*!< for CIS and BIS, The Link Layer does not receive a specific payload by its flush point (on a CIS) or the end of the event */
+        uint32_t duplicate_pkts;      /*!< for CIS, The Link Layer receives a retransmission of a CIS Data PDU */
+    } read_link_quality;              /*!< Event parameter of ESP_BLE_ISO_READ_LINK_QUALITY_CMPL_EVT */
+    /**
+     * @brief ESP_BLE_ISO_SET_CIG_PARAMS_CMPL_EVT
+     */
+    struct ble_iso_set_cig_params_evt_param {
+        esp_bt_status_t status;    /*!< Indicate CIG parameters update success status */
+        uint8_t cig_id;    /*!< Used to identify a CIG */
+        uint8_t cis_count; /*!< Total number of CIS configurations added or modified by this command */
+        uint16_t cis_hdl[ESP_BLE_MAX_CIS_NUM]; /*!< Connection handle of the CIS in the CIG */
+    } set_cig_params;      /*!< Event parameter of ESP_BLE_ISO_SET_CIG_PARAMS_CMPL_EVT */
+    /**
+     * @brief ESP_BLE_ISO_CREATE_CIS_CMPL_EVT
+     */
+    struct ble_iso_create_cis_params_evt_param {
+        esp_bt_status_t status; /*!< Indicate creating cis success status */
+    } create_cis;               /*!< Event parameter of ESP_BLE_ISO_CREATE_CIS_CMPL_EVT */
+    /**
+     * @brief ESP_BLE_ISO_CIS_ESTABLISHED_EVT
+     */
+    struct ble_iso_cis_estab_evt_params{
+        esp_bt_status_t status;    /*!< Indicate the CIS is successfully established or not */
+        uint16_t cis_handle;       /*!< Connection handle of the CIS */
+        uint32_t cig_sync_delay;   /*!< The maximum time, in microseconds, for transmission of PDUs of all CISes in a CIG event */
+        uint32_t cis_sync_delay;   /*!< he maximum time, in microseconds, for transmission of PDUs of the speci-fied CIS in a CIG event */
+        uint32_t trans_lat_c_to_p; /*!< The actual transport latency, in microseconds, from Central to Peripheral */
+        uint32_t trans_lat_p_to_c; /*!< The actual transport latency, in microseconds, from Peripheral to Central */
+        uint8_t phy_c_to_p;        /*!< The transmitter PHY of packets from the Central */
+        uint8_t phy_p_to_c;        /*!< The transmitter PHY of packets from the Peripheral */
+        uint8_t nse;               /*!< Maximum number of subevents in each CIS event */
+        uint8_t bn_c_to_p;         /*!< The burst number for Central to Peripheral transmission */
+        uint8_t bn_p_to_c;         /*!< The burst number for Peripheral to Central transmission */
+        uint8_t ft_c_to_p;         /*!< The flush timeout, in multiples of the ISO_Interval for the CIS, for each payload sent from the Central to the Peripheral */
+        uint8_t ft_p_to_c;         /*!< The flush timeout, in multiples of the ISO_Interval for the CIS, for each payload sent from the Peripheral to the Central */
+        uint16_t max_pdu_c_to_p;   /*!< Maximum size, in octets, of the payload from Central to Peripheral */
+        uint16_t max_pdu_p_to_c;   /*!< Maximum size, in octets, of the payload from Peripheral to Central */
+        uint16_t iso_interval;     /*!< The time between two consecutive CIS anchor points, Time = N × 1.25 ms */
+#if (BLE_FEAT_ISO_60_EN == TRUE)
+        uint32_t sub_interval;     /*!< Time, in microseconds, between the start of consecutive subevents in a CIS event */
+        uint16_t max_sdu_c_to_p;   /*!< Maximum size, in octets, of the payload from the Central’s Host */
+        uint16_t max_sdu_p_to_c;   /*!< Maximum size, in octets, of the payload from the Peripheral’s Host */
+        uint32_t sdu_int_c_to_p;   /*!< Time, in microseconds, between the start of consecutive SDUs sent by the Central */
+        uint32_t sdu_int_p_to_c;   /*!< Time, in microseconds, between the start of consecutive SDUs sent by the Peripheral */
+        uint8_t framing;           /*!< The format of the CIS Data PDUs and the mode of framed PDUs that the Controller used on the specified CIG */
+#endif // #if (BLE_FEAT_ISO_60_EN == TRUE)
+    } cis_estab;                   /*!< Event parameter of ESP_BLE_ISO_CIS_ESTABLISHED_EVT */
+    /**
+     * @brief ESP_BLE_ISO_CIS_DISCONNECTED_EVT
+     */
+    struct ble_iso_cis_dis_evt_params{
+        uint16_t cis_handle; /*!< Connection handle of the CIS */
+        uint8_t reason;      /*!< Reason for disconnection. See [Vol 1] Part F, Controller Error Codes for error codes and descriptions */
+    } cis_disconnected;      /*!< Event parameter of ESP_BLE_ISO_CIS_DISCONNECTED_EVT */
+    /**
+     * @brief ESP_BLE_ISO_CIS_REQUEST_EVT
+     */
+    struct ble_iso_cis_request_evt_params{
+        uint16_t acl_handle; /*!< Connection handle of the ACL */
+        uint16_t cis_handle; /*!< Connection handle of the CIS */
+        uint8_t cig_id;      /*!< Identifier of the CIG */
+        uint8_t cis_id;      /*!< Identifier of the CIS */
+    } cis_request;           /*!< Event parameter of ESP_BLE_ISO_CIS_REQUEST_EVT */
+    /**
+     * @brief ESP_BLE_ISO_REMOVE_CIG_CMPL_EVT
+     */
+    struct ble_iso_remove_cig_params{
+        esp_bt_status_t status; /*!< Indicate CIG remove succeeded or not*/
+        uint8_t cig_id;         /*!< Identifier of a CIG */
+    } remove_cig;               /*!< Event parameter of ESP_BLE_ISO_REMOVE_CIG_CMPL_EVT */
+    /**
+     * @brief ESP_BLE_ISO_ACCEPT_CIS_REQ_CMPL_EVT
+     */
+    struct ble_iso_accept_req_evt_params{
+        esp_bt_status_t status; /*!< Indicate the CIS request is accepted successfully */
+    } accept_req;               /*!< Event parameter of ESP_BLE_ISO_ACCEPT_CIS_REQ_CMPL_EVT */
+    /**
+     * @brief ESP_BLE_ISO_REJECT_CIS_REQ_CMPL_EVT
+     */
+    struct ble_iso_reject_req_evt_params{
+        esp_bt_status_t status; /*!< Indicate the CIS request is rejected successfully */
+        uint16_t cis_handle;    /*!< The connection handle of the CIS to be rejected */
+    } reject_req;               /*!< Event parameter of ESP_BLE_ISO_REJECT_CIS_REQ_CMPL_EVT */
+
+} esp_ble_iso_cb_param_t;
+
+/**
+ * @brief ISO callback function type
+ * @param event : Event type
+ * @param param : Point to callback parameter, currently is union type
+ */
+typedef void (* esp_ble_iso_cb_t)(esp_ble_iso_cb_event_t event, esp_ble_iso_cb_param_t *param);
+
+/**
+ * @brief           This function is called to occur iso event, such as scan result
+ *
+ * @param[in]       callback: callback function
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_register_callback(esp_ble_iso_cb_t callback);
+
+/**
+ * @brief           This function is called to get the current iso callback
+ *
+ * @return
+ *                  - esp_ble_iso_cb_t : callback function
+ *
+ */
+esp_ble_iso_cb_t esp_ble_iso_get_callback(void);
+
+
+
+#if (BLE_FEAT_ISO_BIG_BROCASTER_EN == TRUE)
+
+/**
+ * @brief           This function is called to create BIG.
+ *
+ * @param[in]       big_creat_param: pointer to User defined big_creat_param data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_create_big(esp_ble_iso_big_creat_params_t *big_creat_param);
+
+/**
+ * @brief           This function is called to create BIG test.
+ *
+ * @param[in]       big_creat_test_param: pointer to User defined big_creat_test_param data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_create_big_test(esp_ble_iso_big_creat_test_params_t *big_creat_test_param);
+
+/**
+ * @brief           This function is called to terminate a BIG.
+ *
+ * @param[in]       big_handle: Used to identify the BIG.
+ * @param[in]       reason: indicate the reason why the BIG is to be terminated.
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_terminate_big(uint8_t big_handle, uint8_t reason);
+#endif // #if (BLE_FEAT_ISO_BIG_BROCASTER_EN == TRUE)
+
+#if (BLE_FEAT_ISO_BIG_SYNCER_EN == TRUE)
+
+/**
+ * @brief           This function is called to create BIG sync.
+ *
+ * @param[in]       big_sync_create_param: pointer to User defined big_sync_create_param data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_big_create_sync(esp_ble_iso_big_sync_creat_params_t *big_sync_create_param);
+
+/**
+ * @brief           This function is called to terminate BIG sync.
+ *
+ * @param[in]       big_handle: Identifier of the BIG.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_big_terminate_sync(uint8_t big_handle);
+#endif // #if (BLE_FEAT_ISO_BIG_SYNCER_EN == TRUE)
+
+/**
+ * @brief           This function is called to set iso data path.
+ *
+ * @param[in]       data_path_params: pointer to User defined data_path_params data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_set_iso_data_path(esp_ble_iso_set_data_path_params_t *data_path_params);
+
+/**
+ * @brief           This function is called to remove iso data path.
+ *
+ * @param[in]       data_path_params: pointer to User defined data_path_params data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_remove_iso_data_path(esp_ble_iso_remove_data_path_params_t *data_path_params);
+
+/**
+ * @brief           This function is called to read tx sync.
+ *
+ * @param[in]       iso_handle: Connection handle of the CIS or BIS.
+
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_read_iso_tx_sync(uint16_t iso_handle);
+
+/**
+ * @brief           This function is called to read link quality.
+ *
+ * @param[in]       iso_handle: Connection handle of the CIS or BIS.
+
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_read_link_quality(uint16_t iso_handle);
+
+#if (BLE_FEAT_ISO_CIG_PERIPHERAL_EN == TRUE)
+/**
+ * @brief           This function is called to accept cis request.
+ *
+ * @param[in]       cis_handle: Connection handle of the CIS
+
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_accept_cis_request(uint16_t cis_handle);
+
+/**
+ * @brief           This function is called to reject cis request.
+ *
+ * @param[in]       cis_handle: Connection handle of the CIS
+ * @param[in]       reason: The reason for rejecting the CIS request
+ *
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_reject_cis_request(uint16_t cis_handle, uint8_t reason);
+#endif // #if (BLE_FEAT_ISO_CIG_PERIPHERAL_EN == TRUE)
+
+#if (BLE_FEAT_ISO_CIG_CENTRAL_EN == TRUE)
+
+/**
+ * @brief           This function is called to set cig parameters.
+ *
+ * @param[in]       cig_params: pointer to User defined cig_params data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_set_cig_parameters(struct esp_ble_iso_set_cig_params *cig_params);
+
+/**
+ * @brief           This function is called to set cig test parameters.
+ *
+ * @param[in]       cig_params_test: pointer to User defined cig_params_test data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_set_cig_parameters_test(struct esp_ble_iso_set_cig_params_test *cig_params_test);
+
+/**
+ * @brief           This function is called to create cis.
+ *
+ * @param[in]       creat_cis_params: pointer to User defined creat_cis_params data structure.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_create_cis(struct esp_ble_iso_create_cis_params *creat_cis_params);
+
+/**
+ * @brief           This function is called to remove CIG.
+ *
+ * @param[in]       cig_id: Identifier of a CIG.
+
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_remove_cig(uint8_t cig_id);
+#endif // #if (BLE_FEAT_ISO_CIG_CENTRAL_EN == TRUE)
+
+#if (BLE_FEAT_ISO_CIG_EN == TRUE)
+
+/**
+ * @brief           This function is called to disconnect cis.
+ *
+ * @param[in]       cis_handle: Connection handle of the CIS
+ * @param[in]       reason: The reason for disconnecting the CIS. ESP_HCI_ERR_REMOTE_USER_TERM_CONN is recommended.
+ *
+ *                  The value of the reason is one of the following values:
+ *                  - ESP_HCI_ERR_AUTH_FAIL
+ *                  - ESP_HCI_ERR_REMOTE_USER_TERM_CONN
+ *                  - ESP_HCI_ERR_REMOTE_LOW_RESOURCES
+ *                  - ESP_HCI_ERR_REMOTE_POWER_OFF
+ *                  - ESP_HCI_ERR_UNSUPP_REMOTE_FEATURE
+ *                  - ESP_HCI_ERR_PAIRING_NOT_SUPPORTED
+ *                  - ESP_HCI_ERR_UNACCEPT_CONN_PARAM
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_iso_disconnect_cis(uint16_t cis_handle, uint8_t reason);
+#endif // #if (BLE_FEAT_ISO_CIG_EN == TRUE)
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __ESP_BLE_ISO_API_H__ */
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_bt_defs.h b/lib/bt/host/bluedroid/api/include/api/esp_bt_defs.h
index 182f8760..d6a2718a 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_bt_defs.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_bt_defs.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -19,7 +19,83 @@ extern "C" {
         return ESP_ERR_INVALID_STATE;                \
     }
 
-#define ESP_BT_STATUS_BASE_FOR_HCI_ERR  0X0100  /* base for converting HCI error code to ESP status */
+#define ESP_BT_STATUS_BASE_FOR_HCI_ERR           0X0100  /* base for converting HCI error code to ESP status */
+
+/* See [Vol 1] Part F, Controller Error Codes for a list of error codes and descriptions */
+
+#define ESP_HCI_ERR_SUCCESS                      0x00 /* Success */
+#define ESP_HCI_ERR_UNKNOWN_CMD                  0x01 /* Unknown HCI Command */
+#define ESP_HCI_ERR_UNKNOWN_CONN_ID              0x02 /* Unknown Connection Identifier */
+#define ESP_HCI_ERR_HW_FAILURE                   0x03 /* Hardware Failure */
+#define ESP_HCI_ERR_PAGE_TIMEOUT                 0x04 /* Page Timeout */
+#define ESP_HCI_ERR_AUTH_FAIL                    0x05 /* Authentication Failure */
+#define ESP_HCI_ERR_PIN_OR_KEY_MISSING           0x06 /* PIN or Key Missing */
+#define ESP_HCI_ERR_MEM_CAPACITY_EXCEEDED        0x07 /* Memory Capacity Exceeded */
+#define ESP_HCI_ERR_CONN_TIMEOUT                 0x08 /* Connection Timeout */
+#define ESP_HCI_ERR_CONN_LIMIT_EXCEEDED          0x09 /* Connection Limit Exceeded */
+#define ESP_HCI_ERR_SYNC_CONN_LIMIT_EXCEEDED     0x0A /* ASynchronous Connection Limit To A Device Exceeded */
+#define ESP_HCI_ERR_CONN_ALREADY_EXISTS          0x0B /* Connection Already Exists */
+#define ESP_HCI_ERR_CMD_DISALLOWED               0x0C /* Command Disallowed */
+#define ESP_HCI_ERR_INSUFFICIENT_RESOURCES       0x0D /* Connection Rejected due to Limited Resources */
+#define ESP_HCI_ERR_INSUFFICIENT_SECURITY        0x0E /* Connection Rejected Due To Security Reasons */
+#define ESP_HCI_ERR_BD_ADDR_UNACCEPTABLE         0x0F /* Connection Rejected due to Unacceptable BD_ADDR */
+#define ESP_HCI_ERR_CONN_ACCEPT_TIMEOUT          0x10 /* Connection Accept Timeout Exceeded */
+#define ESP_HCI_ERR_UNSUPP_FEATURE_PARAM_VAL     0x11 /* Unsupported Feature or Parameter Value */
+#define ESP_HCI_ERR_INVALID_PARAM                0x12 /* Invalid HCI Command Parameters */
+#define ESP_HCI_ERR_REMOTE_USER_TERM_CONN        0x13 /* Remote User Terminated Connection */
+#define ESP_HCI_ERR_REMOTE_LOW_RESOURCES         0x14 /* Remote Device Terminated Connection due to Low Resources */
+#define ESP_HCI_ERR_REMOTE_POWER_OFF             0x15 /* Remote Device Terminated Connection due to Power Off */
+#define ESP_HCI_ERR_LOCALHOST_TERM_CONN          0x16 /* Connection Terminated By Local Host */
+#define ESP_HCI_ERR_REPEATED_ATTEMPTS            0x17 /* Repeated Attempts */
+#define ESP_HCI_ERR_PAIRING_NOT_ALLOWED          0x18 /* Pairing Not Allowed */
+#define ESP_HCI_ERR_UNKNOWN_LMP_PDU              0x19 /* Unknown LMP PDU */
+#define ESP_HCI_ERR_UNSUPP_REMOTE_FEATURE        0x1A /* Unsupported Remote Feature */
+#define ESP_HCI_ERR_SCO_OFFSET_REJECTED          0x1B /* SCO Offset Rejected */
+#define ESP_HCI_ERR_SCO_INTERVAL_REJECTED        0x1C /* SCO Interval Rejected */
+#define ESP_HCI_ERR_SCO_AIR_MODE_REJECTED        0x1D /* SCO Air Mode Rejected */
+#define ESP_HCI_ERR_INVALID_LL_PARAM             0x1E /* Invalid LMP Parameters / Invalid LL Parameters */
+#define ESP_HCI_ERR_UNSPECIFIED                  0x1F /* Unspecified Error */
+#define ESP_HCI_ERR_UNSUPP_LL_PARAM_VAL          0x20 /* Unsupported LMP Parameter Value / Unsupported LL Parameter Value */
+#define ESP_HCI_ERR_ROLE_CHANGE_NOT_ALLOWED      0x21 /* Role Change Not Allowed */
+#define ESP_HCI_ERR_LL_RESP_TIMEOUT              0x22 /* LMP Response Timeout / LL Response Timeout */
+#define ESP_HCI_ERR_LL_PROC_COLLISION            0x23 /* LMP Error Transaction Collision / LL Procedure Collision */
+#define ESP_HCI_ERR_LMP_PDU_NOT_ALLOWED          0x24 /* LMP PDU Not Allowed */
+#define ESP_HCI_ERR_ENC_MODE_NOT_ACCEPTABLE      0x25 /* Encryption Mode Not Acceptable */
+#define ESP_HCI_ERR_LINK_KEY_CANNOT_BE_CHANGED   0x26 /* Link Key cannot be Changed */
+#define ESP_HCI_ERR_REQUESTED_QOS_NOT_SUPPORTED  0x27 /* Requested QoS Not Supported */
+#define ESP_HCI_ERR_INSTANT_PASSED               0x28 /* Instant Passed */
+#define ESP_HCI_ERR_PAIRING_NOT_SUPPORTED        0x29 /* Pairing With Unit Key Not Supported */
+#define ESP_HCI_ERR_DIFF_TRANS_COLLISION         0x2A /* Different Transaction Collision */
+#define ESP_HCI_ERR_UNDEFINED_0x2B               0x2B /* Reserved for future use */
+#define ESP_HCI_ERR_QOS_UNACCEPTABLE_PARAM       0x2C /* QoS Unacceptable Parameter */
+#define ESP_HCI_ERR_QOS_REJECTED                 0x2D /* QoS Rejected */
+#define ESP_HCI_ERR_CHAN_ASSESS_NOT_SUPPORTED    0x2E /* Channel Classification Not Supported */
+#define ESP_HCI_ERR_INSUFF_SECURITY              0x2F /* Insufficient Security */
+#define ESP_HCI_ERR_PARAM_OUT_OF_MANDATORY_RANGE 0x30 /* Parameter Out Of Mandatory Range */
+#define ESP_HCI_ERR_UNDEFINED_0x31               0x31 /* Reserved for future use */
+#define ESP_HCI_ERR_ROLE_SWITCH_PENDING          0x32 /* Role Switch Pending */
+#define ESP_HCI_ERR_UNDEFINED_0x33               0x33 /* Reserved for future use */
+#define ESP_HCI_ERR_RESERVED_SLOT_VIOLATION      0x34 /* Reserved Slot Violation */
+#define ESP_HCI_ERR_ROLE_SWITCH_FAILED           0x35 /* Role Switch Failed */
+#define ESP_HCI_ERR_EXT_INQ_RESP_TOO_LARGE       0x36 /* Extended Inquiry Response Too Large */
+#define ESP_HCI_ERR_SIMPLE_PAIR_NOT_SUPP_BY_HOST 0x37 /* Secure Simple Pairing Not Supported By Host */
+#define ESP_HCI_ERR_HOST_BUSY_PAIRING            0x38 /* Host Busy - Pairing*/
+#define ESP_HCI_ERR_CONN_REJECTED_DUE_TO_NO_CHAN 0x39 /* Connection Rejected due to No Suitable Channel Found */
+#define ESP_HCI_ERR_CONTROLLER_BUSY              0x3A /* Controller Busy */
+#define ESP_HCI_ERR_UNACCEPT_CONN_PARAM          0x3B /* Unacceptable Connection Parameters */
+#define ESP_HCI_ERR_ADV_TIMEOUT                  0x3C /* Advertising Timeout */
+#define ESP_HCI_ERR_TERM_DUE_TO_MIC_FAIL         0x3D /* Connection Terminated due to MIC Failure */
+#define ESP_HCI_ERR_CONN_FAIL_TO_ESTAB           0x3E /* Connection Failed to be Established / Synchronization Timeout */
+#define ESP_HCI_ERR_MAC_CONN_FAILED              0x3F /* Previously used */
+#define ESP_HCI_ERR_CLOCK_ADJUST_REJECTED        0x40 /* Coarse Clock Adjustment Rejected but Will Try to Adjust Using Clock Dragging */
+#define ESP_HCI_ERR_SUBMAP_NOT_DEFINED           0x41 /* Type0 Submap Not Defined */
+#define ESP_HCI_ERR_UNKNOWN_ADV_IDENTIFIER       0x42 /* Unknown Advertising Identifier */
+#define ESP_HCI_ERR_LIMIT_REACHED                0x43 /* Limit Reached */
+#define ESP_HCI_ERR_OP_CANCELLED_BY_HOST         0x44 /* Operation Cancelled by Host */
+#define ESP_HCI_ERR_PACKET_TOO_LONG              0x45 /* Packet Too Long */
+#define ESP_HCI_ERR_TOO_LATE                     0x46 /* Too Late */
+#define ESP_HCI_ERR_TOO_EARLY                    0x47 /* Too Early */
+#define ESP_HCI_ERR_INSUFFICIENT_CHANNELS        0x48 /* Insufficient Channels */
 
 /* relate to BT_STATUS_xxx in bt_def.h */
 /// Status Return Value
@@ -110,6 +186,14 @@ typedef enum {
     ESP_BT_STATUS_HCI_CONN_TOUT_DUE_TO_MIC_FAILURE,
     ESP_BT_STATUS_HCI_CONN_FAILED_ESTABLISHMENT,
     ESP_BT_STATUS_HCI_MAC_CONNECTION_FAILED,
+    ESP_BT_STATUS_HCI_CCA_REJECTED,
+    ESP_BT_STATUS_HCI_TYPE0_SUBMAP_NOT_DEFINED,
+    ESP_BT_STATUS_HCI_UNKNOWN_ADV_ID,
+    ESP_BT_STATUS_HCI_LIMIT_REACHED,
+    ESP_BT_STATUS_HCI_OPT_CANCEL_BY_HOST,
+    ESP_BT_STATUS_HCI_PKT_TOO_LONG,
+    ESP_BT_STATUS_HCI_TOO_LATE,
+    ESP_BT_STATUS_HCI_TOO_EARLY,
 } esp_bt_status_t;
 
 
@@ -137,6 +221,25 @@ typedef uint8_t esp_link_key[ESP_BT_OCTET16_LEN];      /* Link Key */
 #define ESP_BLE_CONN_SUP_TOUT_MIN           0x000A       /*!< relate to BTM_BLE_CONN_SUP_TOUT_MIN in stack/btm_ble_api.h */
 #define ESP_BLE_CONN_SUP_TOUT_MAX           0x0C80       /*!< relate to ESP_BLE_CONN_SUP_TOUT_MAX in stack/btm_ble_api.h */
 
+#define ESP_BLE_PHY_1M_PREF_MASK       (1 << 0) /*!< The Host prefers use the LE1M transmitter or receiver PHY */
+#define ESP_BLE_PHY_2M_PREF_MASK       (1 << 1) /*!< The Host prefers use the LE2M transmitter or receiver PHY */
+#define ESP_BLE_PHY_CODED_PREF_MASK    (1 << 2) /*!< The Host prefers use the LE CODED transmitter or receiver PHY */
+typedef uint8_t esp_ble_phy_mask_t;
+
+/**
+* @brief create connection parameters
+*/
+typedef struct {
+    uint16_t scan_interval;       /*!< Initial scan interval, in units of 0.625ms, the range is 0x0004(2.5ms) to 0xFFFF(10.24s). */
+    uint16_t scan_window;         /*!< Initial scan window, in units of 0.625ms, the range is 0x0004(2.5ms) to 0xFFFF(10.24s). */
+    uint16_t interval_min;        /*!< Minimum connection interval, in units of 1.25ms, the range is 0x0006(7.5ms) to 0x0C80(4s). */
+    uint16_t interval_max;        /*!< Maximum connection interval, in units of 1.25ms, the range is 0x0006(7.5ms) to 0x0C80(4s). */
+    uint16_t latency;             /*!< Connection latency, the range is 0x0000(0) to 0x01F3(499). */
+    uint16_t supervision_timeout; /*!< Connection supervision timeout, in units of 10ms, the range is from 0x000A(100ms) to 0x0C80(32s). */
+    uint16_t min_ce_len;          /*!< Minimum connection event length, in units of 0.625ms, setting to 0 for no preferred parameters. */
+    uint16_t max_ce_len;          /*!< Maximum connection event length, in units of 0.625ms, setting to 0 for no preferred parameters. */
+} esp_ble_conn_params_t;
+
 /// Check the param is valid or not
 #define ESP_BLE_IS_VALID_PARAM(x, min, max)  (((x) >= (min) && (x) <= (max)) )
 
@@ -179,8 +282,11 @@ typedef enum {
 
 /// white list address type
 typedef enum {
-    BLE_WL_ADDR_TYPE_PUBLIC        = 0x00,
-    BLE_WL_ADDR_TYPE_RANDOM        = 0x01,
+    BLE_WL_ADDR_TYPE_PUBLIC        = 0x00,  /*!< Public Device Address */
+    BLE_WL_ADDR_TYPE_RANDOM        = 0x01,  /*!< Random Device Address */
+#if (CONFIG_BT_BLE_50_FEATURES_SUPPORTED)
+    BLE_WL_ADDR_TYPE_ANONYMOUS     = 0xFF,  /*!< Devices sending anonymous advertisements, use to enable anonymous advertising report for scanning */
+#endif // (CONFIG_BT_BLE_50_FEATURES_SUPPORTED)
 } esp_ble_wl_addr_type_t;
 
 /// Used to exchange the encryption key in the init key & response key
@@ -201,6 +307,10 @@ typedef uint8_t esp_ble_key_mask_t;            /* the key mask type */
 #define ESP_BD_ADDR_STR         "%02x:%02x:%02x:%02x:%02x:%02x"
 #define ESP_BD_ADDR_HEX(addr)   addr[0], addr[1], addr[2], addr[3], addr[4], addr[5]
 
+#define ESP_BLE_ADV_NAME_LEN_MAX 29
+
+#define ESP_INVALID_CONN_HANDLE  0xfff
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_bt_device.h b/lib/bt/host/bluedroid/api/include/api/esp_bt_device.h
index 6e12765c..60758f1e 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_bt_device.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_bt_device.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -129,6 +129,17 @@ esp_err_t esp_bt_dev_get_device_name(void) __attribute__((deprecated("Please use
 esp_err_t esp_bt_dev_coex_status_config(esp_bt_dev_coex_type_t type, esp_bt_dev_coex_op_t op, uint8_t status);
 
 /**
+ * @brief           This function is used to get the path name of the Bluetooth bond keys
+ *                  saved in the NVS module.
+ * @param[out]      file_path: buffer to store the config file path, max length NVS_KEY_NAME_MAX_SIZE
+ *
+ * @return
+ *                   - ESP_OK: success
+ *
+ */
+esp_err_t esp_bt_config_file_path_get(char *file_path);
+
+/**
  * @brief           This function is used to update the path name of bluetooth bond keys saved in the NVS module
  *                  and need to be called before esp_bluedroid_init().
  * @param[in]       file_path: the name of config file path, the length of file_path should be less than NVS_NS_NAME_MAX_SIZE
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_bt_main.h b/lib/bt/host/bluedroid/api/include/api/esp_bt_main.h
index b13ae94d..b9b60e3d 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_bt_main.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_bt_main.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -30,11 +30,13 @@ typedef enum {
  */
 typedef struct {
     bool ssp_en; /*!< Whether SSP(secure simple pairing) or legacy pairing is used for Classic Bluetooth */
+    bool sc_en; /*!< Whether secure connection host support is enabled or disabled for Classic Bluetooth */
 } esp_bluedroid_config_t;
 
 #define BT_BLUEDROID_INIT_CONFIG_DEFAULT()                                                                             \
     {                                                                                                                  \
         .ssp_en = true,                                                                                                \
+        .sc_en = false,                                                                                                \
     }
 
 /**
@@ -55,7 +57,10 @@ esp_bluedroid_status_t esp_bluedroid_get_status(void);
 esp_err_t esp_bluedroid_enable(void);
 
 /**
- * @brief     Disable bluetooth, must prior to esp_bluedroid_deinit().
+ * @brief     Disable Bluetooth, must be called prior to esp_bluedroid_deinit().
+ *
+ * @note      Before calling this API, ensure that all activities related to
+ *            the application, such as connections, scans, etc., are properly closed.
  *
  * @return
  *            - ESP_OK : Succeed
@@ -92,6 +97,11 @@ esp_err_t esp_bluedroid_init_with_cfg(esp_bluedroid_config_t *cfg);
  */
 esp_err_t esp_bluedroid_deinit(void);
 
+#if defined(CONFIG_EXAMPLE_CI_ID) && defined(CONFIG_EXAMPLE_CI_PIPELINE_ID)
+// Only for internal used (CI example test)
+char *esp_bluedroid_get_example_name(void);
+#endif
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h b/lib/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h
index ea52baf0..066103fa 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -229,6 +229,23 @@ typedef enum {
     ESP_GAP_BLE_ADD_DEV_TO_RESOLVING_LIST_COMPLETE_EVT,          /*!< when add a device to the resolving list completes, the event comes*/
     ESP_GAP_BLE_VENDOR_CMD_COMPLETE_EVT,                         /*!< When vendor hci command complete, the event comes */
     ESP_GAP_BLE_SET_PRIVACY_MODE_COMPLETE_EVT,                   /*!< When set privacy mode complete, the event comes */
+    ESP_GAP_BLE_SET_CSA_SUPPORT_COMPLETE_EVT,                    /*!< When set CSA support complete, the event comes */
+    ESP_GAP_BLE_SET_VENDOR_EVT_MASK_COMPLETE_EVT,                /*!< When set vendor event mask complete, the event comes */
+    ESP_GAP_BLE_VENDOR_HCI_EVT,                                  /*!< When BLE vendor HCI event received, the event comes */
+    // BLE power control
+    ESP_GAP_BLE_ENH_READ_TRANS_PWR_LEVEL_EVT,                    /*!< When reading the current and maximum transmit power levels of the local Controller complete, the event comes */
+    ESP_GAP_BLE_READ_REMOTE_TRANS_PWR_LEVEL_EVT,                 /*!< When reading the transmit power level used by the remote Controller on the ACL connection complete, the event comes */
+    ESP_GAP_BLE_SET_PATH_LOSS_RPTING_PARAMS_EVT,                 /*!< when set the path loss threshold reporting parameters complete, the event comes */
+    ESP_GAP_BLE_SET_PATH_LOSS_RPTING_ENABLE_EVT,                 /*!< when enable or disable path loss reporting complete, the event comes */
+    ESP_GAP_BLE_SET_TRANS_PWR_RPTING_ENABLE_EVT,                 /*!< when enable or disable the reporting to the local Host of transmit power level changes complete, the event comes */
+    ESP_GAP_BLE_PATH_LOSS_THRESHOLD_EVT,                         /*!< when receive a path loss threshold crossing, the event comes */
+    ESP_GAP_BLE_TRANS_PWR_RPTING_EVT,                            /*!< when receive a transmit power level report, the event comes */
+    // BLE connection subrating
+    ESP_GAP_BLE_SET_DEFAULT_SUBRATE_COMPLETE_EVT,                /*!< when set default subrate complete, the event comes */
+    ESP_GAP_BLE_SUBRATE_REQUEST_COMPLETE_EVT,                    /*!< when subrate request command complete, the event comes */
+    ESP_GAP_BLE_SUBRATE_CHANGE_EVT,                              /*!< when Connection Subrate Update procedure has completed and some parameters of the specified connection have changed, the event comes */
+    ESP_GAP_BLE_SET_HOST_FEATURE_CMPL_EVT,                       /*!< When host feature set complete, the event comes */
+    ESP_GAP_BLE_READ_CHANNEL_MAP_COMPLETE_EVT,                   /*!< When BLE channel map result is received, the event comes */
     ESP_GAP_BLE_EVT_MAX,                                         /*!< when maximum advertising event complete, the event comes */
 } esp_gap_ble_cb_event_t;
 
@@ -631,6 +648,7 @@ typedef struct
 {
     esp_bd_addr_t  bd_addr;               /*!< peer address */
     esp_ble_bond_key_info_t bond_key;     /*!< the bond key information */
+    esp_ble_addr_type_t bd_addr_type;     /*!< peer address type */
 } esp_ble_bond_dev_t;                     /*!< the ble bond device type */
 
 
@@ -662,20 +680,54 @@ typedef struct {
 } esp_ble_local_oob_data_t;
 
 /**
+* @brief Definition of the authentication failed reason
+*/
+typedef enum {
+    // Failure reason defined in Bluetooth Core Spec 5.0 Vol3, Part H, 3.5.5
+    ESP_AUTH_SMP_PASSKEY_FAIL = 78,         /*!< The user input of passkey failed */
+    ESP_AUTH_SMP_OOB_FAIL,                  /*!< The OOB data is not available */
+    ESP_AUTH_SMP_PAIR_AUTH_FAIL,            /*!< The authentication requirements cannot be met */
+    ESP_AUTH_SMP_CONFIRM_VALUE_FAIL,        /*!< The confirm value does not match the calculated comparison value */
+    ESP_AUTH_SMP_PAIR_NOT_SUPPORT,          /*!< Pairing is not supported by the device */
+    ESP_AUTH_SMP_ENC_KEY_SIZE,              /*!< The resultant encryption key size is not long enough */
+    ESP_AUTH_SMP_INVALID_CMD,               /*!< The SMP command received is not supported by this device */
+    ESP_AUTH_SMP_UNKNOWN_ERR,               /*!< Pairing failed due to an unspecified reason */
+    ESP_AUTH_SMP_REPEATED_ATTEMPT,          /*!< Pairing or authentication procedure is disallowed */
+    ESP_AUTH_SMP_INVALID_PARAMETERS,        /*!< The command length is invalid or that a parameter is outside the specified range */
+    ESP_AUTH_SMP_DHKEY_CHK_FAIL,            /*!< The DHKey Check value received doesn’t match the one calculated by the local device */
+    ESP_AUTH_SMP_NUM_COMP_FAIL,             /*!< The confirm values in the numeric comparison protocol do not match */
+    ESP_AUTH_SMP_BR_PARING_IN_PROGR,        /*!< Pairing Request sent over the BR/EDR transport is in progress */
+    ESP_AUTH_SMP_XTRANS_DERIVE_NOT_ALLOW,   /*!< The BR/EDR Link Key or BLE LTK cannot be used to derive */
+
+    // Failure reason defined in Bluedroid Host
+    ESP_AUTH_SMP_INTERNAL_ERR,              /*!< Internal error in pairing procedure */
+    ESP_AUTH_SMP_UNKNOWN_IO,                /*!< Unknown IO capability, unable to decide association model */
+    ESP_AUTH_SMP_INIT_FAIL,                 /*!< SMP pairing initiation failed */
+    ESP_AUTH_SMP_CONFIRM_FAIL,              /*!< The confirm value does not match */
+    ESP_AUTH_SMP_BUSY,                      /*!< Pending security request on going */
+    ESP_AUTH_SMP_ENC_FAIL,                  /*!< The Controller failed to start encryption */
+    ESP_AUTH_SMP_STARTED,                   /*!< SMP pairing process started */
+    ESP_AUTH_SMP_RSP_TIMEOUT,               /*!< Security Manager timeout due to no SMP command being received */
+    ESP_AUTH_SMP_DIV_NOT_AVAIL,             /*!< Encrypted Diversifier value not available */
+    ESP_AUTH_SMP_UNSPEC_ERR,                /*!< Unspecified failed reason */
+    ESP_AUTH_SMP_CONN_TOUT,                 /*!< Pairing process failed due to connection timeout */
+} esp_ble_auth_fail_rsn_t;
+
+/**
   * @brief Structure associated with ESP_AUTH_CMPL_EVT
   */
 typedef struct
 {
-    esp_bd_addr_t         bd_addr;               /*!< BD address peer device. */
-    bool                  key_present;           /*!< Valid link key value in key element */
-    esp_link_key          key;                   /*!< Link key associated with peer device. */
-    uint8_t               key_type;              /*!< The type of Link Key */
-    bool                  success;               /*!< TRUE of authentication succeeded, FALSE if failed. */
-    uint8_t               fail_reason;           /*!< The HCI reason/error code for when success=FALSE */
-    esp_ble_addr_type_t   addr_type;             /*!< Peer device address type */
-    esp_bt_dev_type_t     dev_type;              /*!< Device type */
-    esp_ble_auth_req_t    auth_mode;             /*!< authentication mode */
-} esp_ble_auth_cmpl_t;                           /*!< The ble authentication complete cb type */
+    esp_bd_addr_t             bd_addr;               /*!< BD address of peer device */
+    bool                      key_present;           /*!< True if the link key value is valid; false otherwise */
+    esp_link_key              key;                   /*!< Link key associated with peer device */
+    uint8_t                   key_type;              /*!< The type of link key */
+    bool                      success;               /*!< True if authentication succeeded; false otherwise */
+    esp_ble_auth_fail_rsn_t   fail_reason;           /*!< The HCI reason/error code for failure when success is false */
+    esp_ble_addr_type_t       addr_type;             /*!< Peer device address type */
+    esp_bt_dev_type_t         dev_type;              /*!< Device type */
+    esp_ble_auth_req_t        auth_mode;             /*!< Authentication mode */
+} esp_ble_auth_cmpl_t;                               /*!< The ble authentication complete cb type */
 
 /**
   * @brief union associated with ble security
@@ -846,6 +898,10 @@ typedef uint8_t esp_ble_gap_adv_type_t;
 /// Extend advertising tx power, range: [-127, +126] dBm
 #define EXT_ADV_TX_PWR_NO_PREFERENCE                      (127) /*!< host has no preference for tx power */
 
+
+/// max number of advertising sets to enable or disable
+#define EXT_ADV_NUM_SETS_MAX                              (10) /*!< max evt instance num */
+
 /**
 * @brief ext adv parameters
 */
@@ -926,19 +982,27 @@ typedef struct {
     esp_ble_gap_sync_t filter_policy;       /*!< Configures the filter policy for periodic advertising sync:
                                                  0: Use Advertising SID, Advertiser Address Type, and Advertiser Address parameters to determine the advertiser to listen to.
                                                  1: Use the Periodic Advertiser List to determine the advertiser to listen to. */
-    #if (CONFIG_BT_BLE_FEAT_CREATE_SYNC_ENH)
+#if (CONFIG_BT_BLE_FEAT_CREATE_SYNC_ENH)
     esp_ble_gap_sync_t reports_disabled;    /*!< Supported only by esp32c2, esp32c6, and esp32h2; can be set by menuconfig:
                                                  0: Reporting initially enabled.
                                                  1: Reporting initially disabled. */
     esp_ble_gap_sync_t filter_duplicates;   /*!< Supported only by esp32c2, esp32c6, and esp32h2; can be set by menuconfig:
                                                  0: Duplicate filtering initially disabled.
                                                  1: Duplicate filtering initially enabled. */
-    #endif
+#endif // (CONFIG_BT_BLE_FEAT_CREATE_SYNC_ENH)
     uint8_t sid;                            /*!< SID of the periodic advertising */
     esp_ble_addr_type_t addr_type;          /*!< Address type of the periodic advertising */
     esp_bd_addr_t addr;                     /*!< Address of the periodic advertising */
     uint16_t skip;                          /*!< Maximum number of periodic advertising events that can be skipped */
     uint16_t sync_timeout;                  /*!< Synchronization timeout */
+#if (CONFIG_BT_BLE_FEAT_CTE_EN)
+    uint8_t sync_cte_type;                  /*!< Whether to only synchronize to periodic advertising with certain types of CTE (Constant Tone Extension)
+                                                bit 0: Do not sync to packets with an AoA CTE
+                                                bit 1: Do not sync to packets with an AoD CTE with 1 μs slots
+                                                bit 2: Do not sync to packets with an AoD CTE with 2 μs slots
+                                                bit 3: Do not sync to packets with a type 3 CTE (currently reserved for future use)
+                                                bit 4: Do not sync to packets without a CTE */
+#endif // BT_BLE_FEAT_CTE_EN
 } esp_ble_gap_periodic_adv_sync_params_t;
 
 /**
@@ -970,13 +1034,20 @@ typedef struct {
     uint16_t sync_handle;                          /*!< periodic advertising train handle */
     uint8_t tx_power;                              /*!< periodic advertising tx power*/
     int8_t rssi;                                   /*!< periodic advertising rssi */
+#if (CONFIG_BT_BLE_FEAT_CTE_EN) // #if (BLE_FEAT_CTE_EN == TRUE)
+    uint8_t cte_type;                              /*!< The type of Constant Tone Extension
+                                                    0x00: AoA Constant Tone Extension
+                                                    0x01: AoD Constant Tone Extension with 1 μs slots
+                                                    0x02: AoD Constant Tone Extension with 2 μs slots
+                                                    0xFF: No Constant Tone Extension */
+#endif // BT_BLE_FEAT_CTE_EN
     esp_ble_gap_ext_adv_data_status_t data_status; /*!< periodic advertising data type*/
     uint8_t data_length;                           /*!< periodic advertising data length */
     uint8_t data[251];                             /*!< periodic advertising data */
 } esp_ble_gap_periodic_adv_report_t;
 
 /**
-* @brief perodic adv sync establish parameters
+* @brief periodic adv sync establish parameters
 */
 typedef struct {
     uint8_t status;                               /*!< periodic advertising sync status */
@@ -1031,11 +1102,123 @@ typedef struct {
 } esp_ble_gap_past_params_t;
 #endif // #if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE)
 
-typedef enum{
+typedef enum {
     ESP_BLE_NETWORK_PRIVACY_MODE    = 0X00,    /*!< Network Privacy Mode for peer device (default) */
     ESP_BLE_DEVICE_PRIVACY_MODE     = 0X01,    /*!< Device Privacy Mode for peer device */
 } esp_ble_privacy_mode_t;
 
+#define ESP_BLE_VENDOR_SCAN_REQ_RECV_EVT_MASK   BIT(0)  /*!< Vendor BLE legacy SCAN_REQ received event mask */
+#define ESP_BLE_VENDOR_CHMAP_UPDATE_EVT_MASK    BIT(1)  /*!< Vendor BLE channel map update event mask */
+#define ESP_BLE_VENDOR_SLEEP_WAKEUP_EVT_MASK    BIT(3)  /*!< Vendor BLE sleep wakeup event mask */
+#define ESP_BLE_VENDOR_CONN_REQ_RECV_EVT_MASK   BIT(4)  /*!< Vendor BLE CONNECT_IND and AUX_CONNECT_REQ received event mask */
+#define ESP_BLE_VENDOR_CONN_RSP_RECV_EVT_MASK   BIT(5)  /*!< Vendor BLE AUX_CONNECT_RSP received event mask */
+typedef uint32_t esp_ble_vendor_evt_mask_t;
+
+#define ESP_BLE_VENDOR_PDU_RECV_EVT         (0)     /*!< Vendor BLE specify PDU received event */
+#define ESP_BLE_VENDOR_CHAN_MAP_UPDATE_EVT  (1)     /*!< Vendor BLE channel map update complete event */
+#define ESP_BLE_VENDOR_SLEEP_WAKEUP_EVT     (2)     /*!< Vendor BLE sleep wakeup event */
+typedef uint8_t esp_ble_vendor_evt_t;
+
+typedef enum {
+    ESP_BLE_VENDOR_PDU_SCAN_REQ = 0,                /*!< SCAN_REQ PDU type */
+    ESP_BLE_VENDOR_PDU_CONN_REQ,                    /*!< CONNECT_IND and AUX_CONNECT_REQ PDU type */
+    ESP_BLE_VENDOR_PDU_CONN_RSP,                    /*!< AUX_CONNECT_RSP PDU type */
+} esp_ble_vendor_pdu_t;
+
+/**
+ * @brief BLE vendor event parameters union
+ */
+typedef union {
+    /**
+     * @brief ESP_BLE_VENDOR_PDU_RECV_EVT
+     */
+    struct ble_pdu_recv_evt_param {
+        esp_ble_vendor_pdu_t type;                  /*!< The type of LE PDU */
+        uint8_t handle;                             /*!< The handle of advertising set */
+        esp_ble_addr_type_t addr_type;              /*!< The address type of peer device */
+        esp_bd_addr_t peer_addr;                    /*!< The address of peer device */
+    } pdu_recv;                                     /*!< Event parameter of ESP_BLE_VENDOR_PDU_RECV_EVT */
+    /**
+     * @brief ESP_BLE_VENDOR_CHAN_MAP_UPDATE_EVT
+     */
+    struct ble_chan_map_update_evt_param {
+        uint8_t status;                             /*!< Indicate the channel map update status (HCI error code) */
+        uint16_t conn_handle;                       /*!< The connection handle */
+        esp_gap_ble_channels ch_map;                /*!< The channel map after updated */
+    } chan_map_update;                              /*!< Event parameter of ESP_BLE_VENDOR_CHAN_MAP_UPDATE_EVT */
+    /**
+     * @brief ESP_BLE_VENDOR_SLEEP_WAKEUP_EVT
+     */
+    struct ble_sleep_wakeup_evt_param {
+        // No parameters
+    } sleep_wakeup;                                 /*!< Event parameter of ESP_BLE_VENDOR_SLEEP_WAKEUP_EVT */
+} esp_ble_vendor_evt_param_t;
+
+/**
+* @brief path loss report parameters
+*/
+typedef struct {
+    uint16_t conn_handle;    /*!< Connection_Handle */
+	uint8_t high_threshold;  /*!< High threshold for the path loss (dB) */
+	uint8_t high_hysteresis; /*!< Hysteresis value for the high threshold (dB) */
+	uint8_t low_threshold;   /*!< Low threshold for the path loss (dB) */
+	uint8_t low_hysteresis;  /*!< Hysteresis value for the low threshold (dB) */
+	uint16_t min_time_spent; /*!< Minimum time in number of connection events to be observed
+                             once the path loss crosses the threshold before an event is generated */
+} esp_ble_path_loss_rpt_params_t;
+
+typedef enum {
+	/*!< No PHY is set, should not be used */
+	ESP_BLE_CONN_TX_POWER_PHY_NONE = 0,
+	/*!< LE 1M PHY */
+	ESP_BLE_CONN_TX_POWER_PHY_1M = 0x01,
+	/*!< LE 2M PHY */
+	ESP_BLE_CONN_TX_POWER_PHY_2M = 0x02,
+	/*!< LE Coded PHY using S=8 coding */
+	ESP_BLE_CONN_TX_POWER_PHY_CODED_S8 = 0x03,
+	/*!< LE Coded PHY using S=2 coding */
+	ESP_BLE_CONN_TX_POWER_PHY_CODED_S2 = 0x04,
+} esp_ble_tx_power_phy_t;
+
+typedef enum {
+	/*!< Low zone entered */
+	ESP_BLE_CONN_PATH_LOSS_ZONE_ENTERED_LOW = 0x00,
+	/*!< Middle zone entered */
+	ESP_BLE_CONN_PATH_LOSS_ZONE_ENTERED_MIDDLE = 0x01,
+	/*!< High zone entered */
+	ESP_BLE_CONN_PATH_LOSS_ZONE_ENTERED_HIGH = 0x02,
+} esp_ble_path_loss_zone_t;
+
+/**
+* @brief Connection subrating default parameters
+*/
+typedef struct {
+    uint16_t subrate_min;         /*!< Minimum subrate factor allowed in requests by a Peripheral. Range: 0x0001 to 0x01F4, default: 0x0001 */
+    uint16_t subrate_max;         /*!< Maximum subrate factor allowed in requests by a Peripheral. Range: 0x0001 to 0x01F4, default: 0x0001. subrate_max × (max_latency + 1) should not be greater than 500 */
+    uint16_t max_latency;         /*!< Maximum Peripheral latency allowed in requests by a Peripheral, in units of subrated connection intervals.
+                                    Range: 0x0000 to 0x01F3, default: 0x0000 */
+    uint16_t continuation_number; /*!< Minimum number of underlying connection events to remain active after a packet containing a Link Layer
+                                    PDU with a non-zero Length field is sent or received in requests by a Peripheral. Range: 0x0000 to 0x01F3,
+                                    default: 0x0000. continuation_number should not greater than or equal to subrate_max */
+    uint16_t supervision_timeout; /*!< Maximum supervision timeout allowed in requests by a Peripheral (N * 10 ms). Range: 0x000A to 0x0C80,
+                                    Time Range: 100 ms to 32 s, default: 0x0C80 (32 s) */
+} esp_ble_default_subrate_param_t;
+
+/**
+* @brief Connection subrating request parameters
+*/
+typedef struct {
+    uint16_t conn_handle;         /*!< Connection handle of the ACL */
+    uint16_t subrate_min;         /*!< Minimum subrate factor to be applied to the underlying connection interval. Range: 0x0001 to 0x01F4 */
+    uint16_t subrate_max;         /*!< Maximum subrate factor to be applied to the underlying connection interval. Range: 0x0001 to 0x01F4 */
+    uint16_t max_latency;         /*!< Maximum Peripheral latency for the connection in units of subrated connection intervals. Range: 0x0000 to 0x01F3 */
+    uint16_t continuation_number; /*!< Minimum number of underlying connection events to remain active after a packet containing
+                                    a Link Layer PDU with a non-zero Length field is sent or received. Range: 0x0000 to 0x01F3 */
+    uint16_t supervision_timeout; /*!< Supervision timeout for this connection (N * 10 ms). Range: 0x000A to 0x0C80, Time Range: 100 ms to 32 s
+                                    The supervision_timeout, in milliseconds, shall be greater than 2 × current connection interval × subrate_max × (max_latency + 1) */
+} esp_ble_subrate_req_param_t;
+
+
 /**
  * @brief Gap callback parameters union
  */
@@ -1122,12 +1305,6 @@ typedef union {
     struct ble_adv_stop_cmpl_evt_param {
         esp_bt_status_t status;                     /*!< Indicate adv stop operation success status */
     } adv_stop_cmpl;                                /*!< Event parameter of ESP_GAP_BLE_ADV_STOP_COMPLETE_EVT */
-    /**
-     * @brief ESP_GAP_BLE_ADV_CLEAR_COMPLETE_EVT
-     */
-    struct ble_adv_clear_cmpl_evt_param {
-        esp_bt_status_t status;                     /*!< Indicate adv clear operation success status */
-    } adv_clear_cmpl;                                /*!< Event parameter of ESP_GAP_BLE_ADV_CLEAR_COMPLETE_EVT */
 #endif // #if (BLE_42_FEATURE_SUPPORT == TRUE)
     /**
      * @brief ESP_GAP_BLE_SET_STATIC_RAND_ADDR_EVT
@@ -1141,13 +1318,13 @@ typedef union {
     struct ble_update_conn_params_evt_param {
         esp_bt_status_t status;                    /*!< Indicate update connection parameters success status */
         esp_bd_addr_t bda;                         /*!< Bluetooth device address */
-        uint16_t min_int;                          /*!< Min connection interval */
-        uint16_t max_int;                          /*!< Max connection interval */
+        uint16_t min_int;                          /*!< Minimum connection interval. If the master initiates the connection parameter update, this value is not applicable for the slave and will be set to zero. */
+        uint16_t max_int;                          /*!< Maximum connection interval. If the master initiates the connection parameter update, this value is not applicable for the slave and will be set to zero. */
         uint16_t latency;                          /*!< Slave latency for the connection in number of connection events. Range: 0x0000 to 0x01F3 */
-        uint16_t conn_int;                         /*!< Current connection interval */
+        uint16_t conn_int;                         /*!< Current connection interval in milliseconds, calculated as N × 1.25 ms */
         uint16_t timeout;                          /*!< Supervision timeout for the LE Link. Range: 0x000A to 0x0C80.
-                                                     Mandatory Range: 0x000A to 0x0C80 Time = N * 10 msec */
-    } update_conn_params;                          /*!< Event parameter of ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT */
+                                                    This value is calculated as N × 10 ms */
+    } update_conn_params;                          /*!< Event parameter for ESP_GAP_BLE_UPDATE_CONN_PARAMS_EVT */
     /**
      * @brief ESP_GAP_BLE_SET_PKT_LENGTH_COMPLETE_EVT
      */
@@ -1205,6 +1382,14 @@ typedef union {
         esp_bd_addr_t remote_addr;                  /*!< The remote device address */
     } read_rssi_cmpl;                               /*!< Event parameter of ESP_GAP_BLE_READ_RSSI_COMPLETE_EVT */
     /**
+     * @brief ESP_GAP_BLE_READ_CHANNEL_MAP_COMPLETE_EVT
+     */
+    struct ble_read_ble_channel_map_cmpl_evt_param {
+        esp_bt_status_t status;                     /*!< Status of the read channel map operation */
+        uint8_t channel_map[ESP_GAP_BLE_CHANNELS_LEN]; /*!< The BLE channel map, represented as a 5-byte array */
+        esp_bd_addr_t remote_addr;                  /*!< The remote device address */
+    } read_ble_channel_map_cmpl;                         /*!< Event parameter of ESP_GAP_BLE_READ_CHANNEL_MAP_COMPLETE_EVT */
+    /**
      * @brief ESP_GAP_BLE_UPDATE_WHITELIST_COMPLETE_EVT
      */
     struct ble_update_whitelist_cmpl_evt_param {
@@ -1251,77 +1436,93 @@ typedef union {
     struct ble_set_perf_phy_cmpl_evt_param {
         esp_bt_status_t status;                     /*!< Indicate perf phy set status */
     } set_perf_phy;                                 /*!< Event parameter of ESP_GAP_BLE_SET_PREFERRED_PHY_COMPLETE_EVT */
+#if (BLE_50_EXTEND_ADV_EN == TRUE)
     /**
      * @brief ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT
      */
     struct ble_ext_adv_set_rand_addr_cmpl_evt_param {
         esp_bt_status_t status;                      /*!< Indicate extend advertising random address set status */
+        uint8_t instance;                            /*!< extend advertising handle */
     } ext_adv_set_rand_addr;                         /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_SET_RAND_ADDR_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT
      */
     struct ble_ext_adv_set_params_cmpl_evt_param {
         esp_bt_status_t status;                     /*!< Indicate extend advertising parameters set status */
+        uint8_t instance;                           /*!< extend advertising handle */
     } ext_adv_set_params;                           /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_SET_PARAMS_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT
      */
      struct ble_ext_adv_data_set_cmpl_evt_param {
         esp_bt_status_t status;                      /*!< Indicate extend advertising data set status */
+        uint8_t instance;                            /*!< extend advertising handle */
     } ext_adv_data_set;                              /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_DATA_SET_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT
      */
     struct ble_ext_adv_scan_rsp_set_cmpl_evt_param {
         esp_bt_status_t status;                      /*!< Indicate extend advertising scan response data set status */
+        uint8_t instance;                            /*!< extend advertising handle */
     } scan_rsp_set;                                  /*!< Event parameter of ESP_GAP_BLE_EXT_SCAN_RSP_DATA_SET_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT
      */
     struct ble_ext_adv_start_cmpl_evt_param {
         esp_bt_status_t status;                     /*!< Indicate advertising start operation success status */
+        uint8_t instance_num;                       /*!< extend advertising handle numble*/
+        uint8_t instance[EXT_ADV_NUM_SETS_MAX];                       /*!< extend advertising handle list*/
     } ext_adv_start;                                /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_START_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT
      */
     struct ble_ext_adv_stop_cmpl_evt_param {
         esp_bt_status_t status;                     /*!< Indicate advertising stop operation success status */
+        uint8_t instance_num;                       /*!< extend advertising handle numble*/
+        uint8_t instance[EXT_ADV_NUM_SETS_MAX];                       /*!< extend advertising handle list*/
     } ext_adv_stop;                                 /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_STOP_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT
      */
     struct ble_ext_adv_set_remove_cmpl_evt_param {
         esp_bt_status_t status;                     /*!< Indicate advertising stop operation success status */
+        uint8_t instance;                           /*!< extend advertising handle */
     } ext_adv_remove;                               /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_SET_REMOVE_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT
      */
     struct ble_ext_adv_set_clear_cmpl_evt_param {
         esp_bt_status_t status;                     /*!< Indicate advertising stop operation success status */
+        uint8_t instance;                           /*!< extend advertising handle */
     } ext_adv_clear;                                /*!< Event parameter of ESP_GAP_BLE_EXT_ADV_SET_CLEAR_COMPLETE_EVT */
+#endif // #if (BLE_50_EXTEND_ADV_EN == TRUE)
     /**
      * @brief ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT
      */
     struct ble_periodic_adv_set_params_cmpl_param {
         esp_bt_status_t status;                    /*!< Indicate periodic advertisingparameters set status */
+        uint8_t instance;                          /*!< extend advertising handle */
     } peroid_adv_set_params;                       /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_SET_PARAMS_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT
      */
     struct ble_periodic_adv_data_set_cmpl_param {
         esp_bt_status_t status;                    /*!< Indicate periodic advertising data set status */
+        uint8_t instance;                           /*!< extend advertising handle */
     } period_adv_data_set;                         /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_DATA_SET_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT
      */
     struct ble_periodic_adv_start_cmpl_param {
         esp_bt_status_t status;                   /*!< Indicate periodic advertising start status */
+        uint8_t instance;                         /*!< extend advertising handle */
     } period_adv_start;                           /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_START_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT
      */
     struct ble_periodic_adv_stop_cmpl_param {
         esp_bt_status_t status;                  /*!< Indicate periodic advertising stop status */
+        uint8_t instance;                        /*!< extend advertising handle */
     } period_adv_stop;                           /*!< Event parameter of ESP_GAP_BLE_PERIODIC_ADV_STOP_COMPLETE_EVT */
     /**
      * @brief ESP_GAP_BLE_PERIODIC_ADV_CREATE_SYNC_COMPLETE_EVT
@@ -1506,6 +1707,19 @@ typedef union {
         uint16_t num_of_pkt;                        /*!< number of packets received, only valid if update_evt is DTM_TEST_STOP_EVT and shall be reported as 0 for a transmitter */
     } dtm_state_update;                             /*!< Event parameter of ESP_GAP_BLE_DTM_TEST_UPDATE_EVT */
     /**
+     * @brief ESP_GAP_BLE_SET_PRIVACY_MODE_COMPLETE_EVT
+     */
+    struct ble_set_privacy_mode_cmpl_evt_param {
+        esp_bt_status_t status;                     /*!< Indicate privacy mode set operation success status */
+    } set_privacy_mode_cmpl;                        /*!< Event parameter of ESP_GAP_BLE_SET_PRIVACY_MODE_COMPLETE_EVT */
+#if (BLE_VENDOR_HCI_EN == TRUE)
+    /**
+     * @brief ESP_GAP_BLE_ADV_CLEAR_COMPLETE_EVT
+     */
+    struct ble_adv_clear_cmpl_evt_param {
+        esp_bt_status_t status;                     /*!< Indicate adv clear operation success status */
+    } adv_clear_cmpl;                               /*!< Event parameter of ESP_GAP_BLE_ADV_CLEAR_COMPLETE_EVT */
+    /**
      * @brief ESP_GAP_BLE_VENDOR_CMD_COMPLETE_EVT
      */
     struct vendor_cmd_cmpl_evt_param {
@@ -1514,11 +1728,136 @@ typedef union {
         uint8_t         *p_param_buf;               /*!< The point of parameter buffer */
     } vendor_cmd_cmpl;                              /*!< Event parameter of ESP_GAP_BLE_VENDOR_CMD_COMPLETE_EVT */
     /**
-     * @brief ESP_GAP_BLE_SET_PRIVACY_MODE_COMPLETE_EVT
+     * @brief ESP_GAP_BLE_SET_CSA_SUPPORT_COMPLETE_EVT
+     */
+    struct ble_set_csa_support_cmpl_evt_param {
+        esp_bt_status_t status;                     /*!< Indicate CSA support set operation success status */
+    } set_csa_support_cmpl;                         /*!< Event parameter of ESP_GAP_BLE_SET_CSA_SUPPORT_COMPLETE_EVT */
+    /**
+     * @brief ESP_GAP_BLE_SET_VENDOR_EVT_MASK_COMPLETE_EVT
+     */
+    struct ble_set_vendor_evt_mask_cmpl_evt_param {
+        esp_bt_status_t status;                     /*!< Indicate set vendor event mask operation success status */
+    } set_vendor_evt_mask_cmpl;                     /*!< Event parameter of ESP_GAP_BLE_SET_VENDOR_EVT_MASK_COMPLETE_EVT */
+    /**
+     * @brief ESP_GAP_BLE_VENDOR_HCI_EVT
+     */
+    struct ble_vendor_hci_event_evt_param {
+        esp_ble_vendor_evt_t subevt_code;           /*!< Subevent code for BLE vendor HCI event */
+        esp_ble_vendor_evt_param_t param;           /*!< Event parameter of BLE vendor HCI subevent */
+        uint8_t param_len;                          /*!< The length of the event parameter buffer (for internal use only) */
+        uint8_t *param_buf;                         /*!< The pointer of the event parameter buffer (for internal use only) */
+    } vendor_hci_evt;                               /*!< Event parameter of ESP_GAP_BLE_VENDOR_HCI_EVT */
+#endif // #if (BLE_VENDOR_HCI_EN == TRUE)
+#if (BLE_FEAT_POWER_CONTROL_EN == TRUE)
+    /**
+     * @brief ESP_GAP_BLE_ENH_READ_TRANS_PWR_LEVEL_EVT
+     */
+    struct ble_enh_read_trans_pwr_level_param {
+        esp_bt_status_t status;               /*!< Indicate enhance reading transmit power level complete status, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t conn_handle;                 /*!< Connection_Handle */
+        uint8_t phy;                          /*!< 1M, 2M, Coded S2 or Coded S8 phy
+                                                   0x01: LE 1M PHY
+                                                   0x02: LE 2M PHY
+                                                   0x03: LE Coded PHY with S=8 data coding
+                                                   0x04: LE Coded PHY with S=2 data coding
+                                                */
+        int8_t cur_tx_pwr_level;              /*!< Current transmit power level, Range: -127 to 20, Units: dBm */
+        int8_t max_tx_pwr_level;              /*!< Maximum transmit power level, Range: -127 to 20, Units: dBm */
+    } enh_trans_pwr_level_cmpl;               /*!< Event parameter of ESP_GAP_BLE_SET_CSA_SUPPORT_COMPLETE_EVT */
+    /**
+     * @brief ESP_GAP_BLE_READ_REMOTE_TRANS_PWR_LEVEL_EVT
+     */
+    struct ble_read_remote_trans_pwr_level_param {
+        esp_bt_status_t status;              /*!< Indicate reading remote transmit power level complete status, status = (controller error code | 0x100) if status is not equal to 0 */
+    } read_remote_trans_pwr_level_cmpl;      /*!< Event parameter of ESP_GAP_BLE_READ_REMOTE_TRANS_PWR_LEVEL_EVT */
+    /**
+     * @brief ESP_GAP_BLE_SET_PATH_LOSS_RPTING_PARAMS_EVT
+     */
+    struct ble_set_path_loss_rpting_param {
+        esp_bt_status_t status;            /*!< Indicate setting path loss reporting paramwters complete status, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t conn_handle;              /*!< The ACL connection identifier */
+    } set_path_loss_rpting_params;         /*!< Event parameter of ESP_GAP_BLE_SET_PATH_LOSS_RPTING_PARAMS_EVT */
+    /**
+     * @brief ESP_GAP_BLE_SET_PATH_LOSS_RPTING_ENABLE_EVT
+     */
+    struct ble_set_path_loss_rpting_enable {
+        esp_bt_status_t status;           /*!< Indicate setting path loss reporting enable complete status, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t conn_handle;             /*!< The ACL connection identifier */
+    } set_path_loss_rpting_enable;       /*!< Event parameter of ESP_GAP_BLE_SET_PATH_LOSS_RPTING_ENABLE_EVT */
+    /**
+     * @brief ESP_GAP_BLE_SET_TRANS_PWR_RPTING_ENABLE_EVT
+     */
+    struct ble_set_trans_pwr_rpting_enable {
+        esp_bt_status_t status;        /*!< Indicate setting transmit power reporting enable complete status, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t conn_handle;          /*!< The ACL connection identifier */
+    } set_trans_pwr_rpting_enable;     /*!< Event parameter of ESP_GAP_BLE_SET_TRANS_PWR_RPTING_ENABLE_EVT */
+    /**
+     * @brief ESP_GAP_BLE_PATH_LOSS_THRESHOLD_EVT
+     */
+    struct ble_path_loss_thres_evt {
+        uint16_t conn_handle;         /*!< The ACL connection identifier */
+        uint8_t cur_path_loss;        /*!< Current path loss (always zero or positive), Units: dB */
+        esp_ble_path_loss_zone_t zone_entered; /*!< which zone was entered. If cur_path_loss is set to 0xFF then zone_entered shall be ignored */
+    } path_loss_thres_evt;            /*!< Event parameter of ESP_GAP_BLE_PATH_LOSS_THRESHOLD_EVT */
+    /**
+     * @brief ESP_GAP_BLE_TRANS_PWR_RPTING_EVT
+     */
+    struct ble_trans_power_report_evt {
+        esp_bt_status_t status;      /*!< Indicate esp_ble_gap_read_remote_transmit_power_level() command success, status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t conn_handle;        /*!< The ACL connection identifier */
+        uint8_t reason;              /*!< indicate why the event was sent and the device whose transmit power level is being reported
+                                          0x00: Local transmit power changed
+                                          0x01: Remote transmit power changed
+                                          0x02: esp_ble_gap_read_remote_transmit_power_level() command completed,
+                                          In this case, the phy, tx_power_level, tx_power_level_flag and delta parameters shall refer to the remote device */
+        esp_ble_tx_power_phy_t phy; /*!< 1M, 2M, Coded S2 or Coded S8 phy
+                                          0x01: LE 1M PHY
+                                          0x02: LE 2M PHY
+                                          0x03: LE Coded PHY with S=8 data coding
+                                          0x04: LE Coded PHY with S=2 data coding */
+        int8_t tx_power_level;      /*!< Transmit power level, range: -127 to 20, units: dBm
+                                          0x7E: Remote device is not managing power levels on this PHY
+                                          0x7F: Transmit power level is not available */
+        uint8_t tx_power_level_flag; /*!< whether the transmit power level that is being reported has reached its minimum and/or maximum level */
+        int8_t delta;                /*!< Change in transmit power level (positive indicates increased power, negative indicates decreased power, zero indicates unchanged) Units: dB.
+                                          0x7F: Change is not available or is out of range */
+    } trans_power_report_evt;        /*!< Event parameter of ESP_GAP_BLE_TRANS_PWR_RPTING_EVT */
+
+#endif // #if (BLE_FEAT_POWER_CONTROL_EN == TRUE)
+#if (BLE_FEAT_CONN_SUBRATING == TRUE)
+    /**
+     * @brief ESP_GAP_BLE_SET_DEFAULT_SUBRATE_COMPLETE_EVT
+     */
+    struct ble_default_subrate_evt {
+        esp_bt_status_t status;       /*!< Indicate setting default subrate command success, status = (controller error code | 0x100) if status is not equal to 0 */
+    } set_default_subrate_evt;        /*!< Event parameter of ESP_GAP_BLE_SET_DEFAULT_SUBRATE_COMPLETE_EVT */
+    /**
+     * @brief ESP_GAP_BLE_SUBRATE_REQUEST_COMPLETE_EVT
+     */
+    struct ble_subrate_request_evt {
+        esp_bt_status_t status;              /*!< Indicate subrate request command success, status = (controller error code | 0x100) if status is not equal to 0 */
+    } subrate_req_cmpl_evt;          /*!< Event parameter of ESP_GAP_BLE_SUBRATE_REQUEST_COMPLETE_EVT */
+    /**
+     * @brief ESP_GAP_BLE_SUBRATE_CHANGE_EVT
+     */
+    struct ble_subrate_change_evt {
+        esp_bt_status_t status;       /*!< command succeeded or this event was generated following a request from the peer device. status = (controller error code | 0x100) if status is not equal to 0 */
+        uint16_t conn_handle;         /*!< connection handle */
+        uint16_t subrate_factor;      /*!< New subrate factor applied to the specified underlying connection interval, range 0x0001 to 0x01F4 */
+        uint16_t peripheral_latency;  /*!< New Peripheral latency for the connection in number of subrated connection events, range: 0x0000 to 0x01F3 */
+        uint16_t continuation_number; /*!< Number of underlying connection events to remain active after a packet containing a Link Layer PDU with a non-zero Length field is sent or received, range: 0x0000 to 0x01F3 */
+        uint16_t supervision_timeout; /*!< New supervision timeout for this connection(Time = N × 10 ms). Range: 0x000A to 0x0C80, Time Range: 100 ms to 32 s */
+    } subrate_change_evt;             /*!< Event parameter of ESP_GAP_BLE_SUBRATE_CHANGE_EVT */
+#endif // #if (BLE_FEAT_CONN_SUBRATING == TRUE)
+#if (BLE_50_FEATURE_SUPPORT == TRUE)
+    /**
+     * @brief ESP_GAP_BLE_SET_HOST_FEATURE_CMPL_EVT
      */
-    struct ble_set_privacy_mode_cmpl_evt_param {
-        esp_bt_status_t status;                     /*!< Indicate privacy mode set operation success status */
-    } set_privacy_mode_cmpl;                        /*!< Event parameter of ESP_GAP_BLE_SET_PRIVACY_MODE_COMPLETE_EVT */
+    struct ble_set_host_feature_evt_param {
+        esp_bt_status_t status; /*!< Indicate host feature update success status */
+    } host_feature;     /*!< Event parameter of ESP_GAP_BLE_SET_HOST_FEATURE_CMPL_EVT */
+#endif // #if (BLE_50_FEATURE_SUPPORT == TRUE)
 } esp_ble_gap_cb_param_t;
 
 /**
@@ -1533,6 +1872,8 @@ typedef void (* esp_gap_ble_cb_t)(esp_gap_ble_cb_event_t event, esp_ble_gap_cb_p
  *
  * @param[in]       callback: callback function
  *
+ * @note            Avoid performing time-consuming operations within the callback functions.
+ *
  * @return
  *                  - ESP_OK : success
  *                  - other  : failed
@@ -1583,7 +1924,8 @@ esp_err_t esp_ble_gap_set_scan_params(esp_ble_scan_params_t *scan_params);
 /**
  * @brief           This procedure keep the device scanning the peer device which advertising on the air
  *
- * @param[in]       duration: Keeping the scanning time, the unit is second.
+ * @param[in]       duration: The scanning duration in seconds.
+ *                            Set to 0 for continuous scanning until explicitly stopped.
  *
  * @return
  *                  - ESP_OK : success
@@ -1748,15 +2090,19 @@ esp_err_t esp_ble_gap_clear_rand_addr(void);
 esp_err_t esp_ble_gap_config_local_privacy (bool privacy_enable);
 
 /**
- * @brief           set local gap appearance icon
+ * @brief           Set the local GAP appearance icon.
  *
+ * @note            This API does not restrict the input icon value.
+ *                  If an undefined or incorrect icon value is used, the device icon may not display properly.
  *
- * @param[in]       icon   - External appearance value, these values are defined by the Bluetooth SIG, please refer to
+ *                  For a complete list of valid appearance values, please refer to "2.6.2 Appearance Category ranges" at:
  *                  https://www.bluetooth.com/specifications/assigned-numbers/
  *
+ * @param[in]       icon   - External appearance value (16-bit), as defined by the Bluetooth SIG.
+ *
  * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ *                  - ESP_OK   : Success
+ *                  - ESP_FAIL : Internal failure
  *
  */
 esp_err_t esp_ble_gap_config_local_icon (uint16_t icon);
@@ -1850,17 +2196,41 @@ esp_err_t esp_ble_gap_get_device_name(void);
  *
  */
 esp_err_t esp_ble_gap_get_local_used_addr(esp_bd_addr_t local_used_addr, uint8_t * addr_type);
+
+/**
+ * @brief          This function is called to get ADV data for a specific type.
+ *
+ * @note           This is the recommended function to use for resolving ADV data by type.
+ *                 It improves upon the deprecated `esp_ble_resolve_adv_data` function by
+ *                 including an additional parameter to specify the length of the ADV data,
+ *                 thereby offering better safety and reliability.
+ *
+ * @param[in]      adv_data - pointer of ADV data which to be resolved
+ * @param[in]      adv_data_len - the length of ADV data which to be resolved.
+ * @param[in]      type   - finding ADV data type
+ * @param[out]     length - return the length of ADV data not including type
+ *
+ * @return         pointer of ADV data
+ *
+ */
+uint8_t *esp_ble_resolve_adv_data_by_type( uint8_t *adv_data, uint16_t adv_data_len, esp_ble_adv_data_type type, uint8_t *length);
+
 /**
  * @brief          This function is called to get ADV data for a specific type.
  *
- * @param[in]       adv_data - pointer of ADV data which to be resolved
- * @param[in]       type   - finding ADV data type
- * @param[out]      length - return the length of ADV data not including type
+ * @note           This function has been deprecated and will be removed in a future release.
+ *                 Please use `esp_ble_resolve_adv_data_by_type` instead, which provides
+ *                 better parameter validation and supports more accurate data resolution.
  *
- * @return          pointer of ADV data
+ * @param[in]      adv_data - pointer of ADV data which to be resolved
+ * @param[in]      type   - finding ADV data type
+ * @param[out]     length - return the length of ADV data not including type
+ *
+ * @return         pointer of ADV data
  *
  */
 uint8_t *esp_ble_resolve_adv_data(uint8_t *adv_data, uint8_t type, uint8_t *length);
+
 #if (BLE_42_FEATURE_SUPPORT == TRUE)
 /**
  * @brief           This function is called to set raw advertising data. User need to fill
@@ -1902,6 +2272,7 @@ esp_err_t esp_ble_gap_config_scan_rsp_data_raw(uint8_t *raw_data, uint32_t raw_d
  *                  - other  : failed
  */
 esp_err_t esp_ble_gap_read_rssi(esp_bd_addr_t remote_addr);
+
 #if (BLE_42_FEATURE_SUPPORT == TRUE)
 /**
  * @brief           This function is called to add a device info into the duplicate scan exceptional list.
@@ -2150,6 +2521,18 @@ esp_err_t esp_ble_get_current_conn_params(esp_bd_addr_t bd_addr, esp_gap_conn_pa
 esp_err_t esp_gap_ble_set_channels(esp_gap_ble_channels channels);
 
 /**
+* @brief           This function is used to read the current channel map
+*                  for the connection identified by remote address.
+*
+* @param[in]       bd_addr : BD address of the peer device
+*
+* @return            - ESP_OK : success
+*                    - other  : failed
+*
+*/
+esp_err_t esp_ble_gap_read_channel_map(esp_bd_addr_t bd_addr);
+
+/**
 * @brief           This function is called to authorized a link after Authentication(MITM protection)
 *
 * @param[in]       bd_addr: BD address of the peer device.
@@ -2397,15 +2780,17 @@ esp_err_t esp_ble_gap_periodic_adv_stop(uint8_t instance);
 esp_err_t esp_ble_gap_set_ext_scan_params(const esp_ble_ext_scan_params_t *params);
 
 /**
-* @brief           This function is used to enable scanning.
+* @brief           Enables extended scanning.
 *
-* @param[in]       duration  Scan duration time, where Time = N * 10 ms. Range: 0x0001 to 0xFFFF.
-* @param[in]       period    Time interval from when the Controller started its last Scan Duration until it begins the subsequent Scan Duration.
-*                            Time = N * 1.28 sec. Range: 0x0001 to 0xFFFF.
+* @param[in]       duration  Scan duration in units of 10 ms.
+*                            - Range: 0x0001 to 0xFFFF (Time = N * 10 ms).
+*                            - 0x0000: Scan continuously until explicitly disabled.
 *
+* @param[in]       period    Time interval between the start of consecutive scan durations, in units of 1.28 seconds.
+*                            - Range: 0x0001 to 0xFFFF (Time = N * 1.28 sec).
+*                            - 0x0000: Scan continuously.
 * @return            - ESP_OK : success
 *                    - other  : failed
-*
 */
 esp_err_t esp_ble_gap_start_ext_scan(uint32_t duration, uint16_t period);
 
@@ -2490,6 +2875,17 @@ esp_err_t esp_ble_gap_periodic_adv_remove_dev_from_list(esp_ble_addr_type_t addr
 esp_err_t esp_ble_gap_periodic_adv_clear_dev(void);
 
 /**
+ * @brief            Retrieve the capacity of the periodic advertiser list in the controller.
+ *
+ * @param[out]       size: Pointer to a variable where the capacity of the periodic advertiser list will be stored.
+ *
+ * @return
+ *                     - ESP_OK : Success
+ *                     - Others : Failure
+ */
+esp_err_t esp_ble_gap_get_periodic_list_size(uint8_t *size);
+
+/**
 * @brief           This function is used to set aux connection parameters
 *
 * @param[in]       addr : device address
@@ -2507,7 +2903,6 @@ esp_err_t esp_ble_gap_prefer_ext_connect_params_set(esp_bd_addr_t addr,
                                                     const esp_ble_gap_conn_params_t *phy_1m_conn_params,
                                                     const esp_ble_gap_conn_params_t *phy_2m_conn_params,
                                                     const esp_ble_gap_conn_params_t *phy_coded_conn_params);
-
 #endif //#if (BLE_50_FEATURE_SUPPORT == TRUE)
 
 #if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE)
@@ -2667,6 +3062,155 @@ esp_err_t esp_ble_gap_vendor_command_send(esp_ble_vendor_cmd_params_t *vendor_cm
  */
 esp_err_t esp_ble_gap_set_privacy_mode(esp_ble_addr_type_t addr_type, esp_bd_addr_t addr, esp_ble_privacy_mode_t mode);
 
+/**
+ * @brief           This function is used to set which channel selection algorithm(CSA) is supported.
+ *
+ * @note            - This function should only be used when there are BLE compatibility issues about channel hopping after connected.
+ *                    For example, if the peer device only supports CSA#1, this function can be called to make the Controller use CSA#1.
+ *                  - This function is not supported on ESP32.
+ *
+ * @param[in]       csa_select: 0: Channel Selection Algorighm will be selected by Controller
+ *                              1: Select the LE Channel Selection Algorighm #1
+ *                              2: Select the LE Channel Selection Algorighm #2
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ */
+esp_err_t esp_ble_gap_set_csa_support(uint8_t csa_select);
+
+/**
+ * @brief           This function is used to control which vendor events are generated by the HCI for the Host.
+ *
+ * @param[in]       event_mask: The BLE vendor HCI event mask
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ */
+esp_err_t esp_ble_gap_set_vendor_event_mask(esp_ble_vendor_evt_mask_t event_mask);
+
+/**
+ * @brief           This function is used to read the current and maximum transmit power levels of the local Controller.
+ *
+ *
+ * @param[in]       conn_handle: The ACL connection identified.
+ * @param[in]       phy: 1M, 2M, Coded S2 or Coded S8.
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ */
+esp_err_t esp_ble_gap_enhanced_read_transmit_power_level(uint16_t conn_handle, esp_ble_tx_power_phy_t phy);
+
+/**
+ * @brief           This function is used to read the transmit power level used by the remote Controller on the ACL connection.
+ *
+ *
+ * @param[in]       conn_handle: The ACL connection identifier.
+ * @param[in]       phy: 1M, 2M, Coded S2 or Coded S8.
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ */
+esp_err_t esp_ble_gap_read_remote_transmit_power_level(uint16_t conn_handle, esp_ble_tx_power_phy_t phy);
+
+/**
+ * @brief           This function is used to set the path loss threshold reporting parameters.
+ *
+ *
+ * @param[in]       path_loss_rpt_params: The path loss threshold reporting parameters.
+ *
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ */
+esp_err_t esp_ble_gap_set_path_loss_reporting_params(esp_ble_path_loss_rpt_params_t *path_loss_rpt_params);
+
+/**
+ * @brief           This function is used to enable or disable path loss reporting.
+ *
+ *
+ * @param[in]       conn_handle: The ACL connection identifier.
+ * @param[in]       enable: Reporting disabled or enabled.
+ *
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ */
+esp_err_t esp_ble_gap_set_path_loss_reporting_enable(uint16_t conn_handle, bool enable);
+
+/**
+ * @brief           This function is used to enable or disable the reporting to the local Host of transmit power level changes in the local and remote Controllers.
+ *
+ *
+ * @param[in]       conn_handle: The ACL connection identifier.
+ * @param[in]       local_enable: Disable or enable local transmit power reports.
+ * @param[in]       remote_enable: Disable or enable remote transmit power reports.
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ */
+esp_err_t esp_ble_gap_set_transmit_power_reporting_enable(uint16_t conn_handle, bool local_enable, bool remote_enable);
+
+/**
+ * @brief           This function is used to set the initial values for the acceptable parameters for subrating requests,
+ *                  for all future ACL connections where the Controller is the Central. This command does not affect any
+ *                  existing connection.
+ *
+ *
+ * @param[in]       default_subrate_params: The default subrate parameters.
+ *
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ */
+esp_err_t esp_ble_gap_set_default_subrate(esp_ble_default_subrate_param_t *default_subrate_params);
+
+/**
+ * @brief           This function is used by a Central or a Peripheral to request a change to the subrating factor and/or other parameters
+ *                  applied to an existing connection.
+ *
+ *                  If this API is issued on the Central, the following rules shall apply when the Controller initiates the Connection Subrate Update procedure:
+ *                    1. The Peripheral latency shall be less than or equal to max_latency.
+ *                    2. The subrate factor shall be between subrate_min and subrate_max.
+ *                    3. The continuation number shall be equal to the lesser of continuation_number and (subrate factor - 1).
+ *                    4. The connection supervision timeout shall be equal to supervision_timeout.
+ *
+ *                 If this API is issued on the Peripheral, the following rules shall apply when the Controller initiates the Connection Subrate Request procedure:
+ *                    1. The Peripheral latency shall be less than or equal to max_latency.
+ *                    2. The minimum and maximum subrate factors shall be between subrate_min and subrate_max.
+ *                    3. The continuation number shall be equal to the lesser of continuation_number and (maximum subrate factor - 1).
+ *                    4.The connection supervision timeout shall be equal to supervision_timeout.
+ *
+ *
+ * @param[in]       subrate_req_params: The subrate request parameters.
+ *
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ */
+esp_err_t esp_ble_gap_subrate_request(esp_ble_subrate_req_param_t *subrate_req_params);
+
+/**
+ * @brief           This function is called to set host feature.
+ *
+ * @param[in]       bit_num: the bit position in the FeatureSet.
+ * @param[in]       bit_val: the feature is enabled or disabled
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ *
+ */
+esp_err_t esp_ble_gap_set_host_feature(uint16_t bit_num, uint8_t bit_val);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h b/lib/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h
index 7c75927f..1c05ffc5 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_gap_bt_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -33,8 +33,9 @@ typedef enum {
     ESP_BT_SET_COD_MAJOR_MINOR     = 0x01,          /*!< overwrite major, minor class */
     ESP_BT_SET_COD_SERVICE_CLASS   = 0x02,          /*!< set the bits in the input, the current bit will remain */
     ESP_BT_CLR_COD_SERVICE_CLASS   = 0x04,          /*!< clear the bits in the input, others will remain */
-    ESP_BT_SET_COD_ALL             = 0x08,          /*!< overwrite major, minor, set the bits in service class */
-    ESP_BT_INIT_COD                = 0x0a,          /*!< overwrite major, minor, and service class */
+    ESP_BT_SET_COD_ALL             = 0x08,          /*!< overwrite major, minor, set the bits in service class, reserved_2 remain unchanged */
+    ESP_BT_INIT_COD                = 0x0a,          /*!< overwrite major, minor, and service class, reserved_2 remain unchanged */
+    ESP_BT_SET_COD_RESERVED_2      = 0x10,          /*!< overwrite the two least significant bits reserved_2 whose default value is 0b00; other values of reserved_2 are invalid according to Bluetooth Core Specification 5.4 */
 } esp_bt_cod_mode_t;
 
 #define ESP_BT_GAP_AFH_CHANNELS_LEN     10
@@ -209,6 +210,28 @@ typedef enum {
     ESP_BT_COD_MAJOR_DEV_UNCATEGORIZED       = 31,   /*!< Uncategorized: device not specified */
 } esp_bt_cod_major_dev_t;
 
+/// Minor device class field of Class of Device for Peripheral Major Class
+typedef enum {
+    ESP_BT_COD_MINOR_PERIPHERAL_KEYBOARD            = 0x10, /*!< Keyboard */
+    ESP_BT_COD_MINOR_PERIPHERAL_POINTING            = 0x20, /*!< Pointing */
+    ESP_BT_COD_MINOR_PERIPHERAL_COMBO               = 0x30, /*!< Combo
+                                                            ESP_BT_COD_MINOR_PERIPHERAL_KEYBOARD, ESP_BT_COD_MINOR_PERIPHERAL_POINTING
+                                                            and ESP_BT_COD_MINOR_PERIPHERAL_COMBO can be OR'd with one of the
+                                                            following values to identify a multifunctional device. e.g.
+                                                                ESP_BT_COD_MINOR_PERIPHERAL_KEYBOARD | ESP_BT_COD_MINOR_PERIPHERAL_GAMEPAD
+                                                                ESP_BT_COD_MINOR_PERIPHERAL_POINTING | ESP_BT_COD_MINOR_PERIPHERAL_SENSING_DEVICE
+                                                             */
+    ESP_BT_COD_MINOR_PERIPHERAL_JOYSTICK            = 0x01, /*!< Joystick */
+    ESP_BT_COD_MINOR_PERIPHERAL_GAMEPAD             = 0x02, /*!< Gamepad */
+    ESP_BT_COD_MINOR_PERIPHERAL_REMOTE_CONTROL      = 0x03, /*!< Remote Control */
+    ESP_BT_COD_MINOR_PERIPHERAL_SENSING_DEVICE      = 0x04, /*!< Sensing Device */
+    ESP_BT_COD_MINOR_PERIPHERAL_DIGITIZING_TABLET   = 0x05, /*!< Digitizing Tablet */
+    ESP_BT_COD_MINOR_PERIPHERAL_CARD_READER         = 0x06, /*!< Card Reader */
+    ESP_BT_COD_MINOR_PERIPHERAL_DIGITAL_PAN         = 0x07, /*!< Digital Pan */
+    ESP_BT_COD_MINOR_PERIPHERAL_HAND_SCANNER        = 0x08, /*!< Hand Scanner */
+    ESP_BT_COD_MINOR_PERIPHERAL_HAND_GESTURAL_INPUT = 0x09, /*!< Hand Gestural Input */
+} esp_bt_cod_minor_peripheral_t;
+
 /// Bits of major device class field
 #define ESP_BT_COD_MAJOR_DEV_BIT_MASK         (0x1f00) /*!< Major device bit mask */
 #define ESP_BT_COD_MAJOR_DEV_BIT_OFFSET       (8)      /*!< Major device bit offset */
@@ -290,6 +313,14 @@ typedef enum {
 #define ESP_BT_GAP_TPOLL_DFT                  (0x0028) /*!< Default poll interval, unit is 625 microseconds */
 #define ESP_BT_GAP_TPOLL_MAX                  (0x1000) /*!< Maximum poll interval, unit is 625 microseconds */
 
+/** GAP status */
+typedef struct {
+    esp_bt_gap_discovery_state_t disc_stat;  /*!< Device Discovery state */
+    esp_bt_connection_mode_t conn_mode;      /*!< Connection mode */
+    esp_bt_discovery_mode_t disc_mode;       /*!< Discovery mode */
+    uint8_t bredr_acl_link_num;              /*!< Number of bredr link connections */
+} esp_bt_gap_profile_status_t;
+
 /// GAP state callback parameters
 typedef union {
     /**
@@ -417,8 +448,9 @@ typedef union {
      * @brief ESP_BT_GAP_MODE_CHG_EVT
      */
     struct mode_chg_param {
-        esp_bd_addr_t bda;                      /*!< remote bluetooth device address*/
-        esp_bt_pm_mode_t mode;                  /*!< PM mode*/
+        esp_bd_addr_t bda;                      /*!< remote bluetooth device address */
+        esp_bt_pm_mode_t mode;                  /*!< PM mode */
+        uint16_t interval;                      /*!< Number of baseband slots. unit is 0.625ms */
     } mode_chg;                                 /*!< mode change event parameter struct */
 
     /**
@@ -959,6 +991,17 @@ esp_err_t esp_bt_gap_set_device_name(const char *name);
  */
 esp_err_t esp_bt_gap_get_device_name(void);
 
+/**
+ * @brief           Get the status of GAP
+ *
+ * @param[out]      profile_status - GAP status
+ *
+ * @return
+ *                  - ESP_OK : success
+ *                  - other  : failed
+ */
+esp_err_t esp_bt_gap_get_profile_status(esp_bt_gap_profile_status_t *profile_status);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_gatt_defs.h b/lib/bt/host/bluedroid/api/include/api/esp_gatt_defs.h
index 77f03e8b..e8cc134c 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_gatt_defs.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_gatt_defs.h
@@ -478,7 +478,7 @@ typedef uint8_t esp_gatt_char_prop_t;
  *
  * This definition specifies the maximum number of bytes that a GATT attribute can hold.
  */
-#define ESP_GATT_MAX_ATTR_LEN   512 /*!< As same as GATT_MAX_ATTR_LEN. */
+#define ESP_GATT_MAX_ATTR_LEN   517 /*!< As same as GATT_MAX_ATTR_LEN. */
 
 /**
  * @brief Enumerates the possible sources of a GATT service discovery.
@@ -682,6 +682,19 @@ typedef struct {
     esp_bt_uuid_t uuid;                       /*!< Included service UUID. */
 } esp_gattc_incl_svc_elem_t;
 
+/** @brief Represents a creat connection element. */
+typedef struct {
+    esp_bd_addr_t remote_bda;                              /*!< The Bluetooth address of the remote device */
+    esp_ble_addr_type_t remote_addr_type;                  /*!< Address type of the remote device */
+    bool is_direct;                                        /*!< Direct connection or background auto connection(by now, background auto connection is not supported */
+    bool is_aux;                                           /*!< Set to true for BLE 5.0 or higher to enable auxiliary connections; set to false for BLE 4.2 or lower. */
+    esp_ble_addr_type_t own_addr_type;                     /*!< Specifies the address type used in the connection request. Set to 0xFF if the address type is unknown. */
+    esp_ble_phy_mask_t phy_mask;                           /*!< Indicates which PHY connection parameters will be used. When is_aux is false, only the connection params for 1M PHY can be specified */
+    const esp_ble_conn_params_t *phy_1m_conn_params;       /*!< Connection parameters for the LE 1M PHY */
+    const esp_ble_conn_params_t *phy_2m_conn_params;       /*!< Connection parameters for the LE 2M PHY */
+    const esp_ble_conn_params_t *phy_coded_conn_params;    /*!< Connection parameters for the LE Coded PHY */
+} esp_ble_gatt_creat_conn_params_t;
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_gattc_api.h b/lib/bt/host/bluedroid/api/include/api/esp_gattc_api.h
index 13bf16a3..0d9837a5 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_gattc_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_gattc_api.h
@@ -15,411 +15,465 @@
 extern "C" {
 #endif
 
-/// GATT Client callback function events
+/**
+ * @brief GATT Client callback function events
+ */
 typedef enum {
-    ESP_GATTC_REG_EVT                 = 0,        /*!< When GATT client is registered, the event comes */
-    ESP_GATTC_UNREG_EVT               = 1,        /*!< When GATT client is unregistered, the event comes */
-    ESP_GATTC_OPEN_EVT                = 2,        /*!< When GATT virtual connection is set up, the event comes */
-    ESP_GATTC_READ_CHAR_EVT           = 3,        /*!< When GATT characteristic is read, the event comes */
-    ESP_GATTC_WRITE_CHAR_EVT          = 4,        /*!< When GATT characteristic write operation completes, the event comes */
-    ESP_GATTC_CLOSE_EVT               = 5,        /*!< When GATT virtual connection is closed, the event comes */
-    ESP_GATTC_SEARCH_CMPL_EVT         = 6,        /*!< When GATT service discovery is completed, the event comes */
-    ESP_GATTC_SEARCH_RES_EVT          = 7,        /*!< When GATT service discovery result is got, the event comes */
-    ESP_GATTC_READ_DESCR_EVT          = 8,        /*!< When GATT characteristic descriptor read completes, the event comes */
-    ESP_GATTC_WRITE_DESCR_EVT         = 9,        /*!< When GATT characteristic descriptor write completes, the event comes */
-    ESP_GATTC_NOTIFY_EVT              = 10,       /*!< When GATT notification or indication arrives, the event comes */
-    ESP_GATTC_PREP_WRITE_EVT          = 11,       /*!< When GATT prepare-write operation completes, the event comes */
-    ESP_GATTC_EXEC_EVT                = 12,       /*!< When write execution completes, the event comes */
-    ESP_GATTC_ACL_EVT                 = 13,       /*!< When ACL connection is up, the event comes */
-    ESP_GATTC_CANCEL_OPEN_EVT         = 14,       /*!< When GATT client ongoing connection is cancelled, the event comes */
-    ESP_GATTC_SRVC_CHG_EVT            = 15,       /*!< When "service changed" occurs, the event comes */
-    ESP_GATTC_ENC_CMPL_CB_EVT         = 17,       /*!< When encryption procedure completes, the event comes */
-    ESP_GATTC_CFG_MTU_EVT             = 18,       /*!< When configuration of MTU completes, the event comes */
-    ESP_GATTC_ADV_DATA_EVT            = 19,       /*!< When advertising of data, the event comes */
-    ESP_GATTC_MULT_ADV_ENB_EVT        = 20,       /*!< When multi-advertising is enabled, the event comes */
-    ESP_GATTC_MULT_ADV_UPD_EVT        = 21,       /*!< When multi-advertising parameters are updated, the event comes */
-    ESP_GATTC_MULT_ADV_DATA_EVT       = 22,       /*!< When multi-advertising data arrives, the event comes */
-    ESP_GATTC_MULT_ADV_DIS_EVT        = 23,       /*!< When multi-advertising is disabled, the event comes */
-    ESP_GATTC_CONGEST_EVT             = 24,       /*!< When GATT connection congestion comes, the event comes */
-    ESP_GATTC_BTH_SCAN_ENB_EVT        = 25,       /*!< When batch scan is enabled, the event comes */
-    ESP_GATTC_BTH_SCAN_CFG_EVT        = 26,       /*!< When batch scan storage is configured, the event comes */
-    ESP_GATTC_BTH_SCAN_RD_EVT         = 27,       /*!< When Batch scan read event is reported, the event comes */
-    ESP_GATTC_BTH_SCAN_THR_EVT        = 28,       /*!< When Batch scan threshold is set, the event comes */
-    ESP_GATTC_BTH_SCAN_PARAM_EVT      = 29,       /*!< When Batch scan parameters are set, the event comes */
-    ESP_GATTC_BTH_SCAN_DIS_EVT        = 30,       /*!< When Batch scan is disabled, the event comes */
-    ESP_GATTC_SCAN_FLT_CFG_EVT        = 31,       /*!< When Scan filter configuration completes, the event comes */
-    ESP_GATTC_SCAN_FLT_PARAM_EVT      = 32,       /*!< When Scan filter parameters are set, the event comes */
-    ESP_GATTC_SCAN_FLT_STATUS_EVT     = 33,       /*!< When Scan filter status is reported, the event comes */
-    ESP_GATTC_ADV_VSC_EVT             = 34,       /*!< When advertising vendor spec content event is reported, the event comes */
-    ESP_GATTC_REG_FOR_NOTIFY_EVT      = 38,       /*!< When register for notification of a service completes, the event comes */
-    ESP_GATTC_UNREG_FOR_NOTIFY_EVT    = 39,       /*!< When unregister for notification of a service completes, the event comes */
-    ESP_GATTC_CONNECT_EVT             = 40,       /*!< When the ble physical connection is set up, the event comes */
-    ESP_GATTC_DISCONNECT_EVT          = 41,       /*!< When the ble physical connection disconnected, the event comes */
-    ESP_GATTC_READ_MULTIPLE_EVT       = 42,       /*!< When the ble characteristic or descriptor multiple complete, the event comes */
-    ESP_GATTC_QUEUE_FULL_EVT          = 43,       /*!< When the gattc command queue full, the event comes */
-    ESP_GATTC_SET_ASSOC_EVT           = 44,       /*!< When the ble gattc set the associated address complete, the event comes */
-    ESP_GATTC_GET_ADDR_LIST_EVT       = 45,       /*!< When the ble get gattc address list in cache finish, the event comes */
-    ESP_GATTC_DIS_SRVC_CMPL_EVT       = 46,       /*!< When the ble discover service complete, the event comes */
-    ESP_GATTC_READ_MULTI_VAR_EVT      = 47,       /*!< When read multiple variable characteristic complete, the event comes */
+    ESP_GATTC_REG_EVT                 = 0,        /*!< This event is triggered when a GATT Client application is registered using `esp_ble_gattc_app_register`. */
+    ESP_GATTC_UNREG_EVT               = 1,        /*!< This event is triggered when a GATT Client application is unregistered using `esp_ble_gattc_app_unregister`. */
+    ESP_GATTC_OPEN_EVT                = 2,        /*!< This event is triggered when a GATT virtual connection is set up using `esp_ble_gattc_open`. */
+    ESP_GATTC_READ_CHAR_EVT           = 3,        /*!< This event is triggered upon the completion of a GATT characteristic read operation using `esp_ble_gattc_read_char`. */
+    ESP_GATTC_WRITE_CHAR_EVT          = 4,        /*!< This event is triggered upon the completion of a GATT characteristic write operation using `esp_ble_gattc_write_char`. */
+    ESP_GATTC_CLOSE_EVT               = 5,        /*!< This event is triggered when a GATT virtual connection is closed via `esp_ble_gattc_close`, or when the physical connection is terminated. */
+    ESP_GATTC_SEARCH_CMPL_EVT         = 6,        /*!< This event is triggered upon the completion of a service discovery using `esp_ble_gattc_search_service`. */
+    ESP_GATTC_SEARCH_RES_EVT          = 7,        /*!< This event is triggered each time a service result is obtained using `esp_ble_gattc_search_service`. */
+    ESP_GATTC_READ_DESCR_EVT          = 8,        /*!< This event is triggered upon the completion of a GATT characteristic descriptor read operation using `esp_ble_gattc_read_char_descr`. */
+    ESP_GATTC_WRITE_DESCR_EVT         = 9,        /*!< This event is triggered upon the completion of a GATT characteristic descriptor write operation using `esp_ble_gattc_write_char_descr`. */
+    ESP_GATTC_NOTIFY_EVT              = 10,       /*!< This event is triggered when a GATT notification or indication is received from the Server. */
+    ESP_GATTC_PREP_WRITE_EVT          = 11,       /*!< This event is triggered upon the completion of a GATT prepare-write operation using `esp_ble_gattc_prepare_write`. */
+    ESP_GATTC_EXEC_EVT                = 12,       /*!< This event is triggered upon the completion of a GATT write execution using `esp_ble_gattc_execute_write` .*/
+    ESP_GATTC_ACL_EVT                 = 13,       /*!< Deprecated. */
+    ESP_GATTC_CANCEL_OPEN_EVT         = 14,       /*!< Deprecated. */
+    ESP_GATTC_SRVC_CHG_EVT            = 15,       /*!< This event is triggered when a service changed indication is received from the Server, indicating that the attribute database on the Server has been modified (e.g., services have been added, removed). */
+    ESP_GATTC_ENC_CMPL_CB_EVT         = 17,       /*!< Deprecated. */
+    ESP_GATTC_CFG_MTU_EVT             = 18,       /*!< This event is triggered upon the completion of the MTU configuration with `esp_ble_gattc_send_mtu_req`. */
+    ESP_GATTC_ADV_DATA_EVT            = 19,       /*!< Deprecated. */
+    ESP_GATTC_MULT_ADV_ENB_EVT        = 20,       /*!< Deprecated. */
+    ESP_GATTC_MULT_ADV_UPD_EVT        = 21,       /*!< Deprecated. */
+    ESP_GATTC_MULT_ADV_DATA_EVT       = 22,       /*!< Deprecated. */
+    ESP_GATTC_MULT_ADV_DIS_EVT        = 23,       /*!< Deprecated. */
+    ESP_GATTC_CONGEST_EVT             = 24,       /*!< This event is triggered when the GATT connection is congested. */
+    ESP_GATTC_BTH_SCAN_ENB_EVT        = 25,       /*!< Deprecated. */
+    ESP_GATTC_BTH_SCAN_CFG_EVT        = 26,       /*!< Deprecated. */
+    ESP_GATTC_BTH_SCAN_RD_EVT         = 27,       /*!< Deprecated. */
+    ESP_GATTC_BTH_SCAN_THR_EVT        = 28,       /*!< Deprecated. */
+    ESP_GATTC_BTH_SCAN_PARAM_EVT      = 29,       /*!< Deprecated. */
+    ESP_GATTC_BTH_SCAN_DIS_EVT        = 30,       /*!< Deprecated. */
+    ESP_GATTC_SCAN_FLT_CFG_EVT        = 31,       /*!< Deprecated. */
+    ESP_GATTC_SCAN_FLT_PARAM_EVT      = 32,       /*!< Deprecated. */
+    ESP_GATTC_SCAN_FLT_STATUS_EVT     = 33,       /*!< Deprecated. */
+    ESP_GATTC_ADV_VSC_EVT             = 34,       /*!< Deprecated. */
+    ESP_GATTC_REG_FOR_NOTIFY_EVT      = 38,       /*!< This event is triggered upon the completion of a service notification registration using `esp_ble_gattc_register_for_notify`. */
+    ESP_GATTC_UNREG_FOR_NOTIFY_EVT    = 39,       /*!< This event is triggered upon the completion of a service notification unregistration using `esp_ble_gattc_unregister_for_notify`. */
+    ESP_GATTC_CONNECT_EVT             = 40,       /*!< This event is triggered when the physical connection is set up. */
+    ESP_GATTC_DISCONNECT_EVT          = 41,       /*!< This event is triggered when the physical connection is terminated. */
+    ESP_GATTC_READ_MULTIPLE_EVT       = 42,       /*!< This event is triggered when the multiple characteristic or descriptor values are retrieved using `esp_ble_gattc_read_multiple`. */
+    ESP_GATTC_QUEUE_FULL_EVT          = 43,       /*!< This event is triggered when the GATTC command queue is full. */
+    ESP_GATTC_SET_ASSOC_EVT           = 44,       /*!< This event is triggered when the association between the source and the remote address is added or deleted using `esp_ble_gattc_cache_assoc`. */
+    ESP_GATTC_GET_ADDR_LIST_EVT       = 45,       /*!< This event is triggered when retrieving the address list from the GATTC cache is completed using `esp_ble_gattc_cache_get_addr_list`. */
+    ESP_GATTC_DIS_SRVC_CMPL_EVT       = 46,       /*!< This event is triggered when the GATT service discovery is completed. */
+    ESP_GATTC_READ_MULTI_VAR_EVT      = 47,       /*!< This event is triggered when multiple variable length characteristic values are retrieved using `esp_ble_gattc_read_multiple`. */
 } esp_gattc_cb_event_t;
 
 
 /**
- * @brief Gatt client callback parameters union
+ * @brief GATT Client callback parameters
  */
 typedef union {
+
     /**
-     * @brief ESP_GATTC_REG_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_REG_EVT`
      */
     struct gattc_reg_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t app_id;                /*!< Application id which input in register API */
-    } reg;                              /*!< Gatt client callback param of ESP_GATTC_REG_EVT */
+        uint16_t app_id;                /*!< Application ID */
+    } reg;                              /*!< Callback parameter for the event `ESP_GATTC_REG_EVT` */
 
     /**
-     * @brief ESP_GATTC_OPEN_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_OPEN_EVT`.
      */
     struct gattc_open_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t conn_id;               /*!< Connection id */
-        esp_bd_addr_t remote_bda;       /*!< Remote bluetooth device address */
+        uint16_t conn_id;               /*!< Connection ID */
+        esp_bd_addr_t remote_bda;       /*!< Remote Bluetooth device address */
         uint16_t mtu;                   /*!< MTU size */
-    } open;                             /*!< Gatt client callback param of ESP_GATTC_OPEN_EVT */
+    } open;                             /*!< Callback parameter for the event `ESP_GATTC_OPEN_EVT` */
 
     /**
-     * @brief ESP_GATTC_CLOSE_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_CLOSE_EVT`
      */
     struct gattc_close_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t conn_id;               /*!< Connection id */
+        uint16_t conn_id;               /*!< Connection ID */
         esp_bd_addr_t remote_bda;       /*!< Remote bluetooth device address */
-        esp_gatt_conn_reason_t reason;  /*!< The reason of gatt connection close */
-    } close;                            /*!< Gatt client callback param of ESP_GATTC_CLOSE_EVT */
+        esp_gatt_conn_reason_t reason;  /*!< The reason of GATT connection close */
+    } close;                            /*!< Callback parameter for the event `ESP_GATTC_CLOSE_EVT` */
 
     /**
-     * @brief ESP_GATTC_CFG_MTU_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_CFG_MTU_EVT`
      */
     struct gattc_cfg_mtu_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t conn_id;               /*!< Connection id */
+        uint16_t conn_id;               /*!< Connection ID */
         uint16_t mtu;                   /*!< MTU size */
-    } cfg_mtu;                          /*!< Gatt client callback param of ESP_GATTC_CFG_MTU_EVT */
+    } cfg_mtu;                          /*!< Callback parameter for the event `ESP_GATTC_CFG_MTU_EVT` */
 
     /**
-     * @brief ESP_GATTC_SEARCH_CMPL_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_SEARCH_CMPL_EVT`
      */
     struct gattc_search_cmpl_evt_param {
         esp_gatt_status_t status;                     /*!< Operation status */
-        uint16_t conn_id;                             /*!< Connection id */
+        uint16_t conn_id;                             /*!< Connection ID */
         esp_service_source_t searched_service_source; /*!< The source of the service information */
-    } search_cmpl;                                    /*!< Gatt client callback param of ESP_GATTC_SEARCH_CMPL_EVT */
+    } search_cmpl;                                    /*!< Callback parameter for the event `ESP_GATTC_SEARCH_CMPL_EVT` */
 
     /**
-     * @brief ESP_GATTC_SEARCH_RES_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_SEARCH_RES_EVT`
      */
     struct gattc_search_res_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
+        uint16_t conn_id;               /*!< Connection ID */
         uint16_t start_handle;          /*!< Service start handle */
         uint16_t end_handle;            /*!< Service end handle */
-        esp_gatt_id_t srvc_id;          /*!< Service id, include service uuid and other information */
-        bool      is_primary;           /*!< True if this is the primary service */
-    } search_res;                       /*!< Gatt client callback param of ESP_GATTC_SEARCH_RES_EVT */
+        esp_gatt_id_t srvc_id;          /*!< Service ID, including service UUID and other information */
+        bool      is_primary;           /*!< True indicates a primary service, false otherwise */
+    } search_res;                       /*!< Callback parameter for the event `ESP_GATTC_SEARCH_RES_EVT` */
 
     /**
-     * @brief ESP_GATTC_READ_CHAR_EVT, ESP_GATTC_READ_DESCR_EVT, ESP_GATTC_READ_MULTIPLE_EVT, ESP_GATTC_READ_MULTI_VAR_EVT
+     * @brief Callback parameter for the events: `ESP_GATTC_READ_CHAR_EVT`, `ESP_GATTC_READ_DESCR_EVT`,
+     *        `ESP_GATTC_READ_MULTIPLE_EVT`, `ESP_GATTC_READ_MULTI_VAR_EVT`
      */
     struct gattc_read_char_evt_param {
 
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t conn_id;               /*!< Connection id */
+        uint16_t conn_id;               /*!< Connection ID */
         uint16_t handle;                /*!< Characteristic handle */
         uint8_t *value;                 /*!< Characteristic value */
         uint16_t value_len;             /*!< Characteristic value length */
-    } read;                             /*!< Gatt client callback param of ESP_GATTC_READ_CHAR_EVT */
+    } read;                             /*!< Callback parameter for events: `ESP_GATTC_READ_CHAR_EVT`, `ESP_GATTC_READ_DESCR_EVT`,
+                                            `ESP_GATTC_READ_MULTIPLE_EVT`, `ESP_GATTC_READ_MULTI_VAR_EVT` */
 
     /**
-     * @brief ESP_GATTC_WRITE_CHAR_EVT, ESP_GATTC_PREP_WRITE_EVT, ESP_GATTC_WRITE_DESCR_EVT
+     * @brief Callback parameter for the events: `ESP_GATTC_WRITE_CHAR_EVT`, `ESP_GATTC_PREP_WRITE_EVT`, `ESP_GATTC_WRITE_DESCR_EVT`.
      */
     struct gattc_write_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t conn_id;               /*!< Connection id */
-        uint16_t handle;                /*!< The Characteristic or descriptor handle */
-        uint16_t offset;                /*!< The prepare write offset, this value is valid only when prepare write */
-    } write;                            /*!< Gatt client callback param of ESP_GATTC_WRITE_DESCR_EVT */
+        uint16_t conn_id;               /*!< Connection ID */
+        uint16_t handle;                /*!< The characteristic or descriptor handle */
+        uint16_t offset;                /*!< The position offset to write. This value is valid only for prepare write operation. */
+    } write;                            /*!< Callback parameter for the events: `ESP_GATTC_WRITE_CHAR_EVT`, `ESP_GATTC_PREP_WRITE_EVT`, `ESP_GATTC_WRITE_DESCR_EVT` */
 
     /**
-     * @brief ESP_GATTC_EXEC_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_EXEC_EVT`
      */
     struct gattc_exec_cmpl_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t conn_id;               /*!< Connection id */
-    } exec_cmpl;                        /*!< Gatt client callback param of ESP_GATTC_EXEC_EVT */
+        uint16_t conn_id;               /*!< Connection ID */
+    } exec_cmpl;                        /*!< Callback parameter for the event `ESP_GATTC_EXEC_EVT` */
 
     /**
-     * @brief ESP_GATTC_NOTIFY_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_NOTIFY_EVT`
      */
     struct gattc_notify_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
-        esp_bd_addr_t remote_bda;       /*!< Remote bluetooth device address */
-        uint16_t handle;                /*!< The Characteristic or descriptor handle */
-        uint16_t value_len;             /*!< Notify attribute value */
+        uint16_t conn_id;               /*!< Connection ID */
+        esp_bd_addr_t remote_bda;       /*!< Remote Bluetooth device address. */
+        uint16_t handle;                /*!< The characteristic or descriptor handle */
+        uint16_t value_len;             /*!< Notify attribute value length in bytes */
         uint8_t *value;                 /*!< Notify attribute value */
-        bool is_notify;                 /*!< True means notify, false means indicate */
-    } notify;                           /*!< Gatt client callback param of ESP_GATTC_NOTIFY_EVT */
+        bool is_notify;                 /*!< True means notification; false means indication */
+    } notify;                           /*!< Callback parameter for the event `ESP_GATTC_NOTIFY_EVT` */
 
     /**
-     * @brief ESP_GATTC_SRVC_CHG_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_SRVC_CHG_EVT`
 	 */
     struct gattc_srvc_chg_evt_param {
-        esp_bd_addr_t remote_bda;       /*!< Remote bluetooth device address */
-    } srvc_chg;                         /*!< Gatt client callback param of ESP_GATTC_SRVC_CHG_EVT */
+        esp_bd_addr_t remote_bda;       /*!< Remote Bluetooth device address */
+    } srvc_chg;                         /*!< Callback parameter for the event `ESP_GATTC_SRVC_CHG_EVT` */
 
     /**
-     * @brief ESP_GATTC_CONGEST_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_CONGEST_EVT`
      */
     struct gattc_congest_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
-        bool congested;                 /*!< Congested or not */
-    } congest;                          /*!< Gatt client callback param of ESP_GATTC_CONGEST_EVT */
+        uint16_t conn_id;               /*!< Connection ID */
+        bool congested;                 /*!< True indicates that the connection is congested, false otherwise */
+    } congest;                          /*!< Callback parameter for the event `ESP_GATTC_CONGEST_EVT` */
     /**
-     * @brief ESP_GATTC_REG_FOR_NOTIFY_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_REG_FOR_NOTIFY_EVT`
      */
     struct gattc_reg_for_notify_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
         uint16_t handle;                /*!< The characteristic or descriptor handle */
-    } reg_for_notify;                   /*!< Gatt client callback param of ESP_GATTC_REG_FOR_NOTIFY_EVT */
+    } reg_for_notify;                   /*!< Callback parameter for the event `ESP_GATTC_REG_FOR_NOTIFY_EVT` */
 
     /**
-     * @brief ESP_GATTC_UNREG_FOR_NOTIFY_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_UNREG_FOR_NOTIFY_EVT`
      */
     struct gattc_unreg_for_notify_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
         uint16_t handle;                /*!< The characteristic or descriptor handle */
-    } unreg_for_notify;                 /*!< Gatt client callback param of ESP_GATTC_UNREG_FOR_NOTIFY_EVT */
+    } unreg_for_notify;                 /*!< Callback parameter for the event `ESP_GATTC_UNREG_FOR_NOTIFY_EVT` */
 
     /**
-     * @brief ESP_GATTC_CONNECT_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_CONNECT_EVT`
      */
     struct gattc_connect_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
-        uint8_t link_role;              /*!< Link role : master role = 0  ; slave role = 1*/
-        esp_bd_addr_t remote_bda;       /*!< Remote bluetooth device address */
-        esp_gatt_conn_params_t conn_params; /*!< current connection parameters */
-        esp_ble_addr_type_t ble_addr_type;  /*!< Remote BLE device address type */
-        uint16_t conn_handle;           /*!< HCI connection handle */
-    } connect;                          /*!< Gatt client callback param of ESP_GATTC_CONNECT_EVT */
+        uint16_t conn_id;                   /*!< Connection ID */
+        uint8_t link_role;                  /*!< Link role : master role = 0; slave role = 1 */
+        esp_bd_addr_t remote_bda;           /*!< Remote device address */
+        esp_gatt_conn_params_t conn_params; /*!< Current connection parameters */
+        esp_ble_addr_type_t ble_addr_type;  /*!< Remote device address type */
+        uint16_t conn_handle;               /*!< HCI connection handle */
+    } connect;                              /*!< Callback parameter for the event `ESP_GATTC_CONNECT_EVT` */
 
     /**
-     * @brief ESP_GATTC_DISCONNECT_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_DISCONNECT_EVT`
      */
     struct gattc_disconnect_evt_param {
-        esp_gatt_conn_reason_t reason;  /*!< disconnection reason */
-        uint16_t conn_id;               /*!< Connection id */
-        esp_bd_addr_t remote_bda;       /*!< Remote bluetooth device address */
-    } disconnect;                       /*!< Gatt client callback param of ESP_GATTC_DISCONNECT_EVT */
+        esp_gatt_conn_reason_t reason;  /*!< Disconnection reason */
+        uint16_t conn_id;               /*!< Connection ID */
+        esp_bd_addr_t remote_bda;       /*!< Remote device address */
+    } disconnect;                       /*!< Callback parameter for the event `ESP_GATTC_DISCONNECT_EVT` */
+
     /**
-     * @brief ESP_GATTC_SET_ASSOC_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_SET_ASSOC_EVT`
      */
     struct gattc_set_assoc_addr_cmp_evt_param {
-        esp_gatt_status_t status;      /*!< Operation status */
-    } set_assoc_cmp;                     /*!< Gatt client callback param of ESP_GATTC_SET_ASSOC_EVT */
+        esp_gatt_status_t status;        /*!< Operation status */
+    } set_assoc_cmp;                     /*!< Callback parameter for the event `ESP_GATTC_SET_ASSOC_EVT` */
+
     /**
-     * @brief ESP_GATTC_GET_ADDR_LIST_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_GET_ADDR_LIST_EVT`
      */
     struct gattc_get_addr_list_evt_param {
         esp_gatt_status_t status;      /*!< Operation status */
-        uint8_t num_addr;              /*!< The number of address in the gattc cache address list */
-        esp_bd_addr_t *addr_list;      /*!< The pointer to the address list which has been get from the gattc cache */
-    } get_addr_list;                   /*!< Gatt client callback param of ESP_GATTC_GET_ADDR_LIST_EVT */
+        uint8_t num_addr;              /*!< The number of addresses in the local GATTC cache address list */
+        esp_bd_addr_t *addr_list;      /*!< The pointer to the address list which has been retrieved from the local GATTC cache */
+    } get_addr_list;                   /*!< Callback parameter for the event `ESP_GATTC_GET_ADDR_LIST_EVT` */
 
     /**
-     * @brief ESP_GATTC_QUEUE_FULL_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_QUEUE_FULL_EVT`
      */
     struct gattc_queue_full_evt_param {
         esp_gatt_status_t status;      /*!< Operation status */
-        uint16_t conn_id;              /*!< Connection id */
-        bool     is_full;              /*!< The gattc command queue is full or not */
-    } queue_full;                      /*!< Gatt client callback param of ESP_GATTC_QUEUE_FULL_EVT */
+        uint16_t conn_id;              /*!< Connection ID */
+        bool     is_full;              /*!< True indicates the GATTC command queue is full; false otherwise. */
+    } queue_full;                      /*!< Callback parameter for the event `ESP_GATTC_QUEUE_FULL_EVT` */
 
     /**
-     * @brief ESP_GATTC_DIS_SRVC_CMPL_EVT
+     * @brief Callback parameter for the event `ESP_GATTC_DIS_SRVC_CMPL_EVT`
      */
     struct gattc_dis_srvc_cmpl_evt_param {
         esp_gatt_status_t status;      /*!< Operation status */
-        uint16_t conn_id;              /*!< Connection id */
-    } dis_srvc_cmpl;                   /*!< Gatt client callback param of ESP_GATTC_DIS_SRVC_CMPL_EVT */
+        uint16_t conn_id;              /*!< Connection ID */
+    } dis_srvc_cmpl;                   /*!< Callback parameter for the event `ESP_GATTC_DIS_SRVC_CMPL_EVT` */
 
-} esp_ble_gattc_cb_param_t;             /*!< GATT client callback parameter union type */
+} esp_ble_gattc_cb_param_t;
 
 /**
  * @brief GATT Client callback function type
- * @param event : Event type
- * @param gattc_if : GATT client access interface, normally
- *                   different gattc_if correspond to different profile
- * @param param : Point to callback parameter, currently is union type
+ *
+ * @param[in] event    Event type
+ * @param[in] gattc_if GATT Client access interface
+ * @param[in] param    The pointer to callback parameter
  */
 typedef void (* esp_gattc_cb_t)(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_if, esp_ble_gattc_cb_param_t *param);
 
 /**
- * @brief           This function is called to register application callbacks
- *                  with GATTC module.
+ * @brief  Register GATT Client application callbacks
  *
- * @param[in]       callback : pointer to the application callback function.
+ * @param[in]      callback The pointer to the application callback function
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note            Avoid performing time-consuming operations within the callback functions.
  *
+ * @return
+ *          - ESP_OK: Success
+ *          - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gattc_register_callback(esp_gattc_cb_t callback);
 
 /**
- * @brief           This function is called to get the current application callbacks
- *                  with BTA GATTC module.
+ * @brief  Get the current application callbacks
  *
  * @return
- *                  - esp_gattC_cb_t : current callback
- *
+ *        - esp_gattc_cb_t: Current callback
  */
 esp_gattc_cb_t esp_ble_gattc_get_callback(void);
 
 /**
- * @brief           This function is called to register application callbacks
- *                  with GATTC module.
+ * @brief  Register a GATT Client application
  *
- * @param[in]       app_id : Application Identify (UUID), for different application
+ * @param[in] app_id  The UUID for different application
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_REG_EVT`.
+ *      2. The maximum number of applications is limited to 4.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_ARG: The input `app_id` exceeds `ESP_APP_ID_MAX` (0x7fff) defined in esp_bt_defs.h
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_app_register(uint16_t app_id);
 
-
 /**
- * @brief           This function is called to unregister an application
- *                  from GATTC module.
+ * @brief  Unregister a GATT Client application
  *
- * @param[in]       gattc_if: Gatt client access interface.
+ * @param[in] gattc_if GATT Client access interface
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note      This function triggers `ESP_GATTC_UNREG_EVT`.
  *
+ * @return
+ *        - ESP_OK: Success
+ *        - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if);
 
-#if (BLE_42_FEATURE_SUPPORT == TRUE)
 /**
- * @brief           Open a direct connection or add a background auto connection
+ * @brief   Create an ACL connection
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       remote_bda: remote device bluetooth device address.
- * @param[in]       remote_addr_type: remote device bluetooth device the address type.
- * @param[in]       is_direct: direct connection or background auto connection(by now, background auto connection is not supported).
+ * @note
+ *      1. Do not enable `BT_BLE_42_FEATURES_SUPPORTED` and `BT_BLE_50_FEATURES_SUPPORTED` in the menuconfig simultaneously.
+ *      1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`.
+ *      2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well.
+ *      3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only.
+
+ *
+ * @param[in]       gattc_if: GATT client access interface.
+ * @param[in]       esp_gatt_create_conn: Pointer to the structure containing connection parameters.
  *
  * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ *                  - ESP_OK: Success
+ *                  - others: Operation failed
  *
  */
+esp_err_t esp_ble_gattc_enh_open(esp_gatt_if_t gattc_if, esp_ble_gatt_creat_conn_params_t *esp_gatt_create_conn);
+
+/**
+ * @brief  Create an ACL connection when `BT_BLE_42_FEATURES_SUPPORTED` is enabled in the menuconfig
+ *
+ * @param[in]       gattc_if         GATT Client access interface
+ * @param[in]       remote_bda       Remote device address
+ * @param[in]       remote_addr_type Remote device address type
+ * @param[in]       is_direct        `True` indicates a direct connection, while `False` indicates a background auto connection. By now, background auto connection is not supported, please always pass True to this parameter.
+ *
+ * @note
+ *      1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`.
+ *      2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well.
+ *      3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only.
+ *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_FAIL: Failure
+ */
+#if (BLE_42_FEATURE_SUPPORT == TRUE)
 esp_err_t esp_ble_gattc_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, esp_ble_addr_type_t remote_addr_type, bool is_direct);
 #endif // #if (BLE_42_FEATURE_SUPPORT == TRUE)
 
+/**
+ * @brief Create an ACL connection when `BT_BLE_50_FEATURES_SUPPORTED` is enabled in the menuconfig
+ *
+ * @param[in]       gattc_if         GATT Client access interface
+ * @param[in]       remote_bda       Remote device address
+ * @param[in]       remote_addr_type Remote device address type
+ * @param[in]       is_direct        `True` indicates a direct connection, while `False` indicates a background auto connection. By now, background auto connection is not supported, please always pass True to this parameter.
+ *
+ * @note
+ *      1. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`.
+ *      2. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well.
+ *      3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Client. If the ACL connection already exists, it will create a virtual connection only.
+ *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_FAIL: Failure
+ */
 #if (BLE_50_FEATURE_SUPPORT == TRUE)
 esp_err_t esp_ble_gattc_aux_open(esp_gatt_if_t gattc_if, esp_bd_addr_t remote_bda, esp_ble_addr_type_t remote_addr_type, bool is_direct);
 #endif // #if (BLE_50_FEATURE_SUPPORT == TRUE)
+
 /**
- * @brief           Close the virtual connection to the GATT server. gattc may have multiple virtual GATT server connections when multiple app_id registered,
- *                  this API only close one virtual GATT server connection. if there exist other virtual GATT server connections,
- *                  it does not disconnect the physical connection.
- *                  if you want to disconnect the physical connection directly, you can use esp_ble_gap_disconnect(esp_bd_addr_t remote_device).
+ * @brief  Close the virtual GATT Client connection
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID to be closed.
+ * @param[in]       gattc_if GATT Client access interface
+ * @param[in]       conn_id  Connection ID to be closed
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_CLOSE_EVT`.
+ *      2. There may be multiple virtual GATT server connections when multiple `app_id` got registered.
+ *      3. This API closes one virtual GATT server connection only, if there exist other virtual GATT server connections. It does not close the physical connection.
+ *      4. The API `esp_ble_gap_disconnect` can be used to disconnect the physical connection directly.
+ *      5. If there is only one virtual GATT connection left, this API will terminate the ACL connection in addition and triggers `ESP_GATTC_DISCONNECT_EVT`. Then there is no need to call `esp_ble_gap_disconnect` anymore.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_FAIL: Failure
  */
-esp_err_t esp_ble_gattc_close (esp_gatt_if_t gattc_if, uint16_t conn_id);
-
+esp_err_t esp_ble_gattc_close(esp_gatt_if_t gattc_if, uint16_t conn_id);
 
 /**
- * @brief           Configure the MTU size in the GATT channel. This can be done
- *                  only once per connection. Before using, use esp_ble_gatt_set_local_mtu()
- *                  to configure the local MTU size.
+ * @brief  Configure the MTU size in the GATT channel
  *
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID.
+ * @param[in]       gattc_if GATT Client access interface
+ * @param[in]       conn_id  Connection ID
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_CFG_MTU_EVT`.
+ *      2. You could call `esp_ble_gatt_set_local_mtu` to set the desired MTU size locally before this API. If not set, the GATT channel uses the default MTU size (23 bytes).
  *
+ * @return
+ *        - ESP_OK: Success
+ *        - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gattc_send_mtu_req (esp_gatt_if_t gattc_if, uint16_t conn_id);
 
-
 /**
- * @brief           This function is called to get service from local cache.
- *                  This function report service search result by a callback
- *                  event, and followed by a service search complete event.
- *                  Note: 128-bit base UUID will automatically be converted to a 16-bit UUID in the search results. Other types of UUID remain unchanged.
+ * @brief  Search services from the local GATTC cache
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID.
- * @param[in]       filter_uuid: a UUID of the service application is interested in.
- *                  If Null, discover for all services.
+ * @param[in]       gattc_if    GATT Client access interface
+ * @param[in]       conn_id     Connection ID
+ * @param[in]       filter_uuid A UUID of the intended service. If NULL is passed, this API will return all services.
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_SEARCH_RES_EVT` each time a service is retrieved.
+ *      2. This function triggers `ESP_GATTC_SEARCH_CMPL_EVT` when the search is completed.
+ *      3. The 128-bit base UUID will be converted to a 16-bit UUID automatically in the search results. Other types of UUID remain unchanged.
  *
+ * @return
+ *       - ESP_OK:   Success
+ *       - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gattc_search_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *filter_uuid);
 
 /**
- * @brief           Find all the service with the given service uuid in the gattc cache, if the svc_uuid is NULL, find all the service.
- *                  Note: It just get service from local cache, won't get from remote devices. If want to get it from remote device, need
- *                  to used the esp_ble_gattc_cache_refresh, then call esp_ble_gattc_get_service again.
+ * @brief  Get the service with the given service UUID in the local GATTC cache
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID which identify the server.
- * @param[in]       svc_uuid: the pointer to the service uuid.
- * @param[out]      result: The pointer to the service which has been found in the gattc cache.
- * @param[inout]   count: input the number of service want to find,
- *                         it will output the number of service has been found in the gattc cache with the given service uuid.
- * @param[in]       offset: Offset of the service position to get.
+ * @param[in]       gattc_if GATT Client access interface
+ * @param[in]       conn_id  Connection ID
+ * @param[in]       svc_uuid The pointer to the service UUID. If NULL is passed, the API will retrieve all services.
+ * @param[out]      result   The pointer to the service which has been found in the local GATTC cache
+ * @param[inout]    count    The number of services to retrieve. It will be updated with the actual number of services found.
+ * @param[in]       offset   The position offset to retrieve
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This API does not trigger any event.
+ *      2. `esp_ble_gattc_cache_refresh` can be used to discover services again.
  *
+ * @return
+ *      - ESP_OK: Success
+ *      - ESP_FAIL: Failure
  */
 esp_gatt_status_t esp_ble_gattc_get_service(esp_gatt_if_t gattc_if, uint16_t conn_id, esp_bt_uuid_t *svc_uuid,
                                             esp_gattc_service_elem_t *result, uint16_t *count, uint16_t offset);
 
 /**
- * @brief           Find all the characteristic with the given service in the gattc cache
- *                  Note: It just get characteristic from local cache, won't get from remote devices.
+ * @brief  Get all characteristics with the given handle range in the local GATTC cache
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID which identify the server.
- * @param[in]       start_handle: the attribute start handle.
- * @param[in]       end_handle: the attribute end handle
- * @param[out]      result: The pointer to the characteristic in the service.
- * @param[inout]   count: input the number of characteristic want to find,
- *                         it will output the number of characteristic has been found in the gattc cache with the given service.
- * @param[in]       offset: Offset of the characteristic position to get.
+ * @param[in]       gattc_if     GATT Client access interface
+ * @param[in]       conn_id      Connection ID
+ * @param[in]       start_handle The attribute start handle
+ * @param[in]       end_handle   The attribute end handle
+ * @param[out]      result       The pointer to the characteristic in the service
+ * @param[inout]    count        The number of characteristics to retrieve. It will be updated with the actual number of characteristics found.
+ * @param[in]       offset       The position offset to retrieve
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This API does not trigger any event.
+ *      2. `start_handle` must be greater than 0, and smaller than `end_handle`.
  *
+ * @return
+ *      - ESP_OK: Success
+ *      - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle` or `end_handle`
+ *      - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0
+ *      - ESP_FAIL: Failure due to other reasons
  */
 esp_gatt_status_t esp_ble_gattc_get_all_char(esp_gatt_if_t gattc_if,
                                              uint16_t conn_id,
@@ -429,21 +483,24 @@ esp_gatt_status_t esp_ble_gattc_get_all_char(esp_gatt_if_t gattc_if,
                                              uint16_t *count, uint16_t offset);
 
 /**
- * @brief           Find all the descriptor with the given characteristic in the gattc cache
- *                  Note: It just get descriptor from local cache, won't get from remote devices.
+ * @brief  Get all descriptors with the given characteristic in the local GATTC cache
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID which identify the server.
- * @param[in]       char_handle: the given characteristic handle
- * @param[out]      result: The pointer to the descriptor in the characteristic.
- * @param[inout]    count: input the number of descriptor want to find,
- *                         it will output the number of descriptor has been found in the gattc cache with the given characteristic.
- * @param[in]       offset: Offset of the descriptor position to get.
+ * @param[in]       gattc_if    GATT Client access interface
+ * @param[in]       conn_id     Connection ID which identifies the server
+ * @param[in]       char_handle The given characteristic handle
+ * @param[out]      result      The pointer to the descriptor in the characteristic
+ * @param[inout]    count       The number of descriptors to retrieve. It will be updated with the actual number of descriptors found.
+ * @param[in]       offset      The position offset to retrieve
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This API does not trigger any event.
+ *      2. `char_handle` must be greater than 0.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_GATT_INVALID_HANDLE: Invalid GATT `char_handle`
+ *       - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_gatt_status_t esp_ble_gattc_get_all_descr(esp_gatt_if_t gattc_if,
                                               uint16_t conn_id,
@@ -451,24 +508,26 @@ esp_gatt_status_t esp_ble_gattc_get_all_descr(esp_gatt_if_t gattc_if,
                                               esp_gattc_descr_elem_t *result,
                                               uint16_t *count, uint16_t offset);
 
-
 /**
- * @brief           Find the characteristic with the given characteristic uuid in the gattc cache
- *                  Note: It just get characteristic from local cache, won't get from remote devices.
+ * @brief  Get the characteristic with the given characteristic UUID in the local GATTC cache
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID which identify the server.
- * @param[in]       start_handle: the attribute start handle
- * @param[in]       end_handle: the attribute end handle
- * @param[in]       char_uuid: the characteristic uuid
- * @param[out]      result: The pointer to the characteristic in the service.
- * @param[inout]   count: input the number of characteristic want to find,
- *                         it will output the number of characteristic has been found in the gattc cache with the given service.
+ * @param[in]       gattc_if      GATT Client access interface
+ * @param[in]       conn_id       Connection ID
+ * @param[in]       start_handle  The attribute start handle
+ * @param[in]       end_handle    The attribute end handle
+ * @param[in]       char_uuid     The characteristic UUID
+ * @param[out]      result        The pointer to the characteristic in the service
+ * @param[inout]    count         The number of characteristics to retrieve. It will be updated with the actual number of characteristics found.
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This API does not trigger any event.
+ *      2. `start_handle` must be greater than 0, and smaller than `end_handle`.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle` or `end_handle`
+ *       - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_gatt_status_t esp_ble_gattc_get_char_by_uuid(esp_gatt_if_t gattc_if,
                                                  uint16_t conn_id,
@@ -479,23 +538,25 @@ esp_gatt_status_t esp_ble_gattc_get_char_by_uuid(esp_gatt_if_t gattc_if,
                                                  uint16_t *count);
 
 /**
- * @brief           Find the descriptor with the given characteristic uuid in the gattc cache
- *                  Note: It just get descriptor from local cache, won't get from remote devices.
+ * @brief  Get the descriptor with the given characteristic UUID in the local GATTC cache
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID which identify the server.
- * @param[in]       start_handle: the attribute start handle
- * @param[in]       end_handle: the attribute end handle
- * @param[in]       char_uuid: the characteristic uuid.
- * @param[in]       descr_uuid: the descriptor uuid.
- * @param[out]      result: The pointer to the descriptor in the given characteristic.
- * @param[inout]   count: input the number of descriptor want to find,
- *                         it will output the number of descriptor has been found in the gattc cache with the given characteristic.
+ * @param[in]       gattc_if     GATT Client access interface
+ * @param[in]       conn_id      Connection ID
+ * @param[in]       start_handle The attribute start handle
+ * @param[in]       end_handle   The attribute end handle
+ * @param[in]       char_uuid    The characteristic UUID
+ * @param[in]       descr_uuid   The descriptor UUID.
+ * @param[out]      result       The pointer to the descriptor in the given characteristic.
+ * @param[inout]    count        The number of descriptors want to retrieve. It will be updated with the actual number of descriptors found.
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This API does not trigger any event.
+ *      2. `start_handle` must be greater than 0, and smaller than `end_handle`.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_gatt_status_t esp_ble_gattc_get_descr_by_uuid(esp_gatt_if_t gattc_if,
                                                   uint16_t conn_id,
@@ -507,21 +568,24 @@ esp_gatt_status_t esp_ble_gattc_get_descr_by_uuid(esp_gatt_if_t gattc_if,
                                                   uint16_t *count);
 
 /**
- * @brief           Find the descriptor with the given characteristic handle in the gattc cache
- *                  Note: It just get descriptor from local cache, won't get from remote devices.
+ * @brief  Get the descriptor with the given characteristic handle in the local GATTC cache
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID which identify the server.
- * @param[in]       char_handle: the characteristic handle.
- * @param[in]       descr_uuid: the descriptor uuid.
- * @param[out]      result: The pointer to the descriptor in the given characteristic.
- * @param[inout]   count: input the number of descriptor want to find,
- *                         it will output the number of descriptor has been found in the gattc cache with the given characteristic.
+ * @param[in]       gattc_if    GATT Client access interface
+ * @param[in]       conn_id     Connection ID which identifies the server
+ * @param[in]       char_handle The characteristic handle
+ * @param[in]       descr_uuid  The descriptor UUID
+ * @param[out]      result      The pointer to the descriptor in the given characteristic
+ * @param[inout]    count       The number of descriptors want to retrieve. It will be updated with the actual number of descriptors found.
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This API does not trigger any event.
+ *      2. `char_handle` must be greater than 0.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_GATT_INVALID_HANDLE: Invalid GATT `char_handle`
+ *       - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_gatt_status_t esp_ble_gattc_get_descr_by_char_handle(esp_gatt_if_t gattc_if,
                                                          uint16_t conn_id,
@@ -531,22 +595,24 @@ esp_gatt_status_t esp_ble_gattc_get_descr_by_char_handle(esp_gatt_if_t gattc_if,
                                                          uint16_t *count);
 
 /**
- * @brief           Find the include service with the given service handle in the gattc cache
- *                  Note: It just get include service from local cache, won't get from remote devices.
+ * @brief  Get the included services with the given service handle in the local GATTC cache.
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID which identify the server.
- * @param[in]       start_handle: the attribute start handle
- * @param[in]       end_handle: the attribute end handle
- * @param[in]       incl_uuid: the include service uuid
- * @param[out]      result: The pointer to the include service in the given service.
- * @param[inout]   count: input the number of include service want to find,
- *                         it will output the number of include service has been found in the gattc cache with the given service.
+ * @param[in]       gattc_if     GATT Client access interface
+ * @param[in]       conn_id      Connection ID which identifies the server
+ * @param[in]       start_handle The attribute start handle
+ * @param[in]       end_handle   The attribute end handle
+ * @param[in]       incl_uuid    The included service UUID
+ * @param[out]      result       The pointer to the included service with the given service handle.
+ * @param[inout]    count        The number of included services to retrieve. It will be updated with the actual number of included services found.
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This API does not trigger any event.
+ *      2. `start_handle` must be greater than 0, and smaller than `end_handle`.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_GATT_INVALID_PDU: NULL pointer to `result` or NULL pointer to `count` or the count value is 0
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_gatt_status_t esp_ble_gattc_get_include_service(esp_gatt_if_t gattc_if,
                                                     uint16_t conn_id,
@@ -556,23 +622,27 @@ esp_gatt_status_t esp_ble_gattc_get_include_service(esp_gatt_if_t gattc_if,
                                                     esp_gattc_incl_svc_elem_t *result,
                                                     uint16_t *count);
 
-
 /**
- * @brief           Find the attribute count with the given service or characteristic in the gattc cache
+ * @brief  Get the attribute count with the given service or characteristic in the local GATTC cache
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id: connection ID which identify the server.
- * @param[in]       type: the attribute type.
- * @param[in]       start_handle: the attribute start handle, if the type is ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore
- * @param[in]       end_handle: the attribute end handle, if the type is ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore
- * @param[in]       char_handle: the characteristic handle, this parameter valid when the type is ESP_GATT_DB_DESCRIPTOR. If the type
- *                               isn't ESP_GATT_DB_DESCRIPTOR, this parameter should be ignore.
- * @param[out]      count: output the number of attribute has been found in the gattc cache with the given attribute type.
+ * @param[in]       gattc_if     GATT Client access interface
+ * @param[in]       conn_id      Connection ID
+ * @param[in]       type         The attribute type
+ * @param[in]       start_handle The attribute start handle. If the type is `ESP_GATT_DB_DESCRIPTOR`, this parameter will be ignored.
+ * @param[in]       end_handle   The attribute end handle. If the type is `ESP_GATT_DB_DESCRIPTOR`, this parameter will be ignored.
+ * @param[in]       char_handle  The characteristic handle. This parameter is valid only if the type is `ESP_GATT_DB_DESCRIPTOR`.
+ * @param[out]      count        The number of attributes found in the local GATTC cache with the given attribute type
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
  *
+ * @note
+ *     1. This API does not trigger any event.
+ *     2. `start_handle` must be greater than 0, and smaller than `end_handle` if the `type` is not `ESP_GATT_DB_DESCRIPTOR`.
+ *
+ * @return
+ *                  - ESP_OK: Success
+ *                  - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle`, `end_handle`
+ *                  - ESP_GATT_INVALID_PDU: NULL pointer to `count`
+ *                  - ESP_FAIL: Failure due to other reasons
  */
 esp_gatt_status_t esp_ble_gattc_get_attr_count(esp_gatt_if_t gattc_if,
                                                uint16_t conn_id,
@@ -583,38 +653,47 @@ esp_gatt_status_t esp_ble_gattc_get_attr_count(esp_gatt_if_t gattc_if,
                                                uint16_t *count);
 
 /**
- * @brief           This function is called to get the GATT database.
- *                  Note: It just get attribute data base from local cache, won't get from remote devices.
+ * @brief  Get the GATT database elements
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       start_handle: the attribute start handle
- * @param[in]       end_handle: the attribute end handle
- * @param[in]       conn_id: connection ID which identify the server.
- * @param[in]       db: output parameter which will contain the GATT database copy.
- *                      Caller is responsible for freeing it.
- * @param[in]       count: number of elements in database.
+ * @param[in]       gattc_if     GATT Client access interface
+ * @param[in]       start_handle The attribute start handle
+ * @param[in]       end_handle   The attribute end handle
+ * @param[in]       conn_id      Connection ID
+ * @param[out]      db           The pointer to GATT database elements
+ * @param[inout]    count        The number of elements in the database to retrieve. It will be updated with the actual number of elements found.
+ *
+ * @note
+ *       1. This API does not trigger any event.
+ *       2. `start_handle` must be greater than 0, and smaller than `end_handle`.
  *
  * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ *       - ESP_OK: Success
+ *       - ESP_GATT_INVALID_HANDLE: Invalid GATT `start_handle`, `end_handle`
+ *       - ESP_GATT_INVALID_PDU: NULL pointer to `db` or NULL pointer to `count` or the count value is 0
+ *       - ESP_FAIL: Failure due to other reasons
  *
  */
 esp_gatt_status_t esp_ble_gattc_get_db(esp_gatt_if_t gattc_if, uint16_t conn_id, uint16_t start_handle, uint16_t end_handle,
                                         esp_gattc_db_elem_t *db, uint16_t *count);
 
 /**
- * @brief           This function is called to read a service's characteristics of
- *                  the given characteristic handle
+ * @brief  Read the characteristics value of the given characteristic handle
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id : connection ID.
- * @param[in]       handle : characteritic handle to read.
- * @param[in]       auth_req : authenticate request type
+ * @param[in]       gattc_if GATT Client access interface
+ * @param[in]       conn_id  Connection ID
+ * @param[in]       handle   Characteristic handle to read
+ * @param[in]       auth_req Authenticate request type
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_READ_CHAR_EVT`.
+ *      2. This function should be called only after the connection has been established.
+ *      3. `handle` must be greater than 0.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_STATE: The connection has not been established.
+ *       - ESP_GATT_INVALID_HANDLE: Invalid `handle`
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_read_char (esp_gatt_if_t gattc_if,
                                    uint16_t conn_id,
@@ -622,20 +701,25 @@ esp_err_t esp_ble_gattc_read_char (esp_gatt_if_t gattc_if,
                                    esp_gatt_auth_req_t auth_req);
 
 /**
- * @brief           This function is called to read a service's characteristics of
- *                  the given characteristic UUID
+ * @brief  Read the characteristics value of the given characteristic UUID.
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id : connection ID.
- * @param[in]       start_handle : the attribute start handle.
- * @param[in]       end_handle : the attribute end handle
- * @param[in]       uuid : The UUID of attribute which will be read.
- * @param[in]       auth_req : authenticate request type
+ * @param[in]       gattc_if     GATT Client access interface.
+ * @param[in]       conn_id      Connection ID
+ * @param[in]       start_handle The attribute start handle
+ * @param[in]       end_handle   The attribute end handle
+ * @param[in]       uuid         The pointer to UUID of attribute to read
+ * @param[in]       auth_req     Authenticate request type
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_READ_CHAR_EVT`.
+ *      2. This function should be called only after the connection has been established.
+ *      3. `start_handle` must be greater than 0, and smaller than `end_handle`.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_GATT_ILLEGAL_PARAMETER: NULL pointer to  `uuid`
+ *       - ESP_ERR_INVALID_STATE: The connection has not been established
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_read_by_type (esp_gatt_if_t gattc_if,
                                       uint16_t conn_id,
@@ -645,75 +729,92 @@ esp_err_t esp_ble_gattc_read_by_type (esp_gatt_if_t gattc_if,
                                       esp_gatt_auth_req_t auth_req);
 
 /**
- * @brief           This function is called to read multiple characteristic or
- *                  characteristic descriptors.
+ * @brief  Read multiple characteristic or descriptor values
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id : connection ID.
- * @param[in]       read_multi : pointer to the read multiple parameter.
- * @param[in]       auth_req : authenticate request type
+ * @param[in]       gattc_if   GATT Client access interface
+ * @param[in]       conn_id    Connection ID which specifies the server
+ * @param[in]       read_multi Pointer to `esp_gattc_multi_t`
+ * @param[in]       auth_req   Authenticate request type
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_READ_MULTIPLE_EVT`.
+ *      2. This function should be called only after the connection has been established.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_STATE: The connection has not been established
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_read_multiple(esp_gatt_if_t gattc_if,
                                       uint16_t conn_id, esp_gattc_multi_t *read_multi,
                                       esp_gatt_auth_req_t auth_req);
 
 /**
- * @brief           This function is called to read multiple variable length characteristic or
- *                  characteristic descriptors.
+ * @brief  Read multiple variable length characteristic values.
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id : connection ID.
- * @param[in]       read_multi : pointer to the read multiple parameter.
- * @param[in]       auth_req : authenticate request type
+ * @param[in]       gattc_if   GATT Client access interface
+ * @param[in]       conn_id    Connection ID
+ * @param[in]       read_multi The pointer to the `esp_gattc_multi_t`
+ * @param[in]       auth_req   Authenticate request type
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_READ_MULTI_VAR_EVT`.
+ *      2. This function should be called only after the connection has been established.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_STATE: The connection has not been established.
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_read_multiple_variable(esp_gatt_if_t gattc_if,
                                       uint16_t conn_id, esp_gattc_multi_t *read_multi,
                                       esp_gatt_auth_req_t auth_req);
 
 /**
- * @brief           This function is called to read a characteristics descriptor.
+ * @brief  Read a characteristics descriptor
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id : connection ID.
- * @param[in]       handle : descriptor handle to read.
- * @param[in]       auth_req : authenticate request type
+ * @param[in]       gattc_if GATT Client access interface
+ * @param[in]       conn_id  Connection ID
+ * @param[in]       handle   Descriptor handle to read
+ * @param[in]       auth_req Authenticate request type
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_READ_DESCR_EVT`.
+ *      2. This function should be called only after the connection has been established.
+ *      3. `handle` must be greater than 0.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_STATE: The connection has not been established.
+ *       - ESP_GATT_INVALID_HANDLE：Invalid `handle`
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_read_char_descr (esp_gatt_if_t gattc_if,
                                          uint16_t conn_id,
                                          uint16_t handle,
                                          esp_gatt_auth_req_t auth_req);
 
-
 /**
- * @brief           This function is called to write characteristic value.
+ * @brief  Write the characteristic value of a given characteristic handle
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id : connection ID.
- * @param[in]       handle : characteristic handle to write.
- * @param[in]       value_len: length of the value to be written.
- * @param[in]       value : the value to be written.
- * @param[in]       write_type : the type of attribute write operation.
- * @param[in]       auth_req : authentication request.
+ * @param[in]       gattc_if   GATT Client access interface
+ * @param[in]       conn_id    Connection ID
+ * @param[in]       handle     The characteristic handle to write
+ * @param[in]       value_len  The length of the value to write in bytes
+ * @param[in]       value      The value to write
+ * @param[in]       write_type The type of Attribute write operation
+ * @param[in]       auth_req   Authentication request type
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_WRITE_CHAR_EVT`.
+ *      2. This function should be called only after the connection has been established.
+ *      3. `handle` must be greater than 0.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_STATE: The connection has not been established.
+ *       - ESP_GATT_INVALID_HANDLE：Invalid `handle`
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_write_char( esp_gatt_if_t gattc_if,
                                     uint16_t conn_id,
@@ -723,22 +824,27 @@ esp_err_t esp_ble_gattc_write_char( esp_gatt_if_t gattc_if,
                                     esp_gatt_write_type_t write_type,
                                     esp_gatt_auth_req_t auth_req);
 
-
 /**
- * @brief           This function is called to write characteristic descriptor value.
+ * @brief  Write Characteristic descriptor value of a given descriptor handle
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id : connection ID
- * @param[in]       handle : descriptor handle to write.
- * @param[in]       value_len: length of the value to be written.
- * @param[in]       value : the value to be written.
- * @param[in]       write_type : the type of attribute write operation.
- * @param[in]       auth_req : authentication request.
+ * @param[in]       gattc_if   GATT Client access interface
+ * @param[in]       conn_id    Connection ID
+ * @param[in]       handle     The descriptor handle to write.
+ * @param[in]       value_len  The length of the value to write in bytes.
+ * @param[in]       value      The value to write
+ * @param[in]       write_type The type of Attribute write operation
+ * @param[in]       auth_req   Authentication request type
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_WRITE_DESCR_EVT`.
+ *      2. This function should be called only after the connection has been established.
+ *      3. `handle` must be greater than 0.
  *
+ * @return
+ *      - ESP_OK: Success
+ *      - ESP_ERR_INVALID_STATE: The connection has not been established.
+ *      - ESP_GATT_INVALID_HANDLE：Invalid `handle`
+ *      - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_write_char_descr (esp_gatt_if_t gattc_if,
                                          uint16_t conn_id,
@@ -748,22 +854,29 @@ esp_err_t esp_ble_gattc_write_char_descr (esp_gatt_if_t gattc_if,
                                          esp_gatt_write_type_t write_type,
                                          esp_gatt_auth_req_t auth_req);
 
-
 /**
- * @brief           This function is called to prepare write a characteristic value.
- *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id : connection ID.
- * @param[in]       handle : characteristic handle to prepare write.
- * @param[in]       offset : offset of the write value.
- * @param[in]       value_len: length of the value to be written.
- * @param[in]       value : the value to be written.
- * @param[in]       auth_req : authentication request.
+ * @brief  Prepare to write a characteristic value which is longer than the MTU size to a specified characteristic handle
+ *
+ * @param[in]       gattc_if  GATT Client access interface
+ * @param[in]       conn_id   Connection ID
+ * @param[in]       handle    Characteristic handle to prepare to write
+ * @param[in]       offset    The position offset to write
+ * @param[in]       value_len The length of the value to write in bytes
+ * @param[in]       value     The value to write
+ * @param[in]       auth_req  Authentication request type
+ *
+ * @note
+ *      1. This function should be called only after the connection has been established.
+ *      2. After using this API, use `esp_ble_gattc_execute_write` to write.
+ *      3. This function triggers `ESP_GATTC_PREP_WRITE_EVT`.
+ *      4. If `value_len` is less than or equal to MTU size, it is recommended to `esp_ble_gattc_write_char` to write directly.
+ *      5. `handle` must be greater than 0.
  *
  * @return
- *                  - ESP_OK: success
- *                  - other: failed
- *
+ *      - ESP_OK: Success
+ *      - ESP_ERR_INVALID_STATE: The connection has not been established.
+ *      - ESP_GATT_INVALID_HANDLE：Invalid `handle`
+ *      - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if,
                                       uint16_t conn_id,
@@ -773,22 +886,27 @@ esp_err_t esp_ble_gattc_prepare_write(esp_gatt_if_t gattc_if,
                                       uint8_t *value,
                                       esp_gatt_auth_req_t auth_req);
 
-
 /**
- * @brief           This function is called to prepare write a characteristic descriptor value.
+ * @brief  Prepare to write a characteristic descriptor value at a given handle
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id : connection ID.
- * @param[in]       handle : characteristic descriptor handle to prepare write.
- * @param[in]       offset : offset of the write value.
- * @param[in]       value_len: length of the value to be written.
- * @param[in]       value : the value to be written.
- * @param[in]       auth_req : authentication request.
+ * @param[in]       gattc_if  GATT Client access interface
+ * @param[in]       conn_id   Connection ID
+ * @param[in]       handle    Characteristic descriptor handle to prepare to write
+ * @param[in]       offset    The position offset to write
+ * @param[in]       value_len The length of the value to write in bytes
+ * @param[in]       value     The value to write
+ * @param[in]       auth_req  Authentication request type
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note
+ *      1. This function triggers `ESP_GATTC_WRITE_CHAR_EVT`.
+ *      2. This function should be called only after the connection has been established.
+ *      3. `handle` must be greater than 0.
  *
+ * @return
+ *      - ESP_OK: Success
+ *      - ESP_ERR_INVALID_STATE: The connection has not been established.
+ *      - ESP_GATT_INVALID_HANDLE：Invalid `handle`
+ *      - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_prepare_write_char_descr(esp_gatt_if_t gattc_if,
                                                  uint16_t conn_id,
@@ -798,112 +916,123 @@ esp_err_t esp_ble_gattc_prepare_write_char_descr(esp_gatt_if_t gattc_if,
                                                  uint8_t *value,
                                                  esp_gatt_auth_req_t auth_req);
 
-
 /**
- * @brief           This function is called to execute write a prepare write sequence.
+ * @brief  Execute a prepared writing sequence
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       conn_id : connection ID.
- * @param[in]       is_execute : execute or cancel.
+ * @param[in]       gattc_if   GATT Client access interface
+ * @param[in]       conn_id    Connection ID
+ * @param[in]       is_execute True if it is to execute the writing sequence; false if it is to cancel the writing sequence.
  *
- * @return
- *                  - ESP_OK: success
- *                  - other: failed
+ * @note            This function triggers `ESP_GATTC_EXEC_EVT`.
  *
+ * @return
+ *        - ESP_OK: Success
+ *        - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gattc_execute_write (esp_gatt_if_t gattc_if, uint16_t conn_id, bool is_execute);
 
-
 /**
- * @brief           This function is called to register for notification of a service.
+ * @brief  Register to receive notification/indication of a characteristic.
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       server_bda : target GATT server.
- * @param[in]       handle : GATT characteristic handle.
+ * @param[in]       gattc_if   GATT Client access interface
+ * @param[in]       server_bda Target GATT server device address
+ * @param[in]       handle     Target GATT characteristic handle
  *
- * @return
- *                  - ESP_OK: registration succeeds
- *                  - other: failed
+ * @note
+ *       1. This function triggers `ESP_GATTC_REG_FOR_NOTIFY_EVT`.
+ *       2. You should call `esp_ble_gattc_write_char_descr()` after this API to write Client Characteristic Configuration (CCC) descriptor to the value of 1 (Enable Notification) or 2 (Enable Indication).
+ *       3. `handle` must be greater than 0.
  *
+ * @return
+ *        - ESP_OK: Success
+ *        - ESP_GATT_INVALID_HANDLE：Invalid `handle`
+ *        - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_register_for_notify (esp_gatt_if_t gattc_if,
                                              esp_bd_addr_t server_bda,
                                              uint16_t handle);
 
-
 /**
- * @brief           This function is called to de-register for notification of a service.
+ * @brief  Unregister the notification of a service.
  *
- * @param[in]       gattc_if: Gatt client access interface.
- * @param[in]       server_bda : target GATT server.
- * @param[in]       handle : GATT characteristic handle.
+ * @param[in]       gattc_if   GATT Client access interface
+ * @param[in]       server_bda Target GATT server device address
+ * @param[in]       handle     Target GATT characteristic handle
  *
+ * @note
+ *      1. This function triggers `ESP_GATTC_UNREG_FOR_NOTIFY_EVT`.
+ *      2. You should call `esp_ble_gattc_write_char_descr()` after this API to write Client Characteristic Configuration (CCC) descriptor value to 0.
+ *      3. `handle` must be greater than 0
  * @return
- *                  - ESP_OK: unregister succeeds
- *                  - other: failed
- *
+ *       - ESP_OK: Success
+ *       - ESP_GATT_INVALID_HANDLE：Invalid `handle`
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gattc_unregister_for_notify (esp_gatt_if_t gattc_if,
                                                esp_bd_addr_t server_bda,
                                                uint16_t handle);
 
-
 /**
-* @brief           Refresh the server cache store in the gattc stack of the remote device. If
-*                  the device is connected, this API will restart the discovery of service information of the remote device
-*
-* @param[in]       remote_bda: remote device BD address.
-*
-* @return
-*                  - ESP_OK: success
-*                  - other: failed
-*
-*/
+ * @brief  Refresh the cache of the remote device
+ *
+ * @param[in]       remote_bda Remote device address
+ *
+ * @note
+ *       1. If the device is connected, this API will restart the discovery of service information of the remote device.
+ *       2. This function triggers `ESP_GATTC_DIS_SRVC_CMPL_EVT` only after the ACL connection is established. Otherwise, no events will be triggered.
+ *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_FAIL: Failure
+ */
 esp_err_t esp_ble_gattc_cache_refresh(esp_bd_addr_t remote_bda);
 
 /**
-* @brief           Add or delete the associated address with the source address.
-*                  Note: The role of this API is mainly when the client side has stored a server-side database,
-*                        when it needs to connect another device, but the device's attribute database is the same
-*                        as the server database stored on the client-side, calling this API can use the database
-*                        that the device has stored used as the peer server database to reduce the attribute
-*                        database search and discovery process and speed up the connection time.
-*                        The associated address mains that device want to used the database has stored in the local cache.
-*                        The source address mains that device want to share the database to the associated address device.
-*
-* @param[in]       gattc_if: Gatt client access interface.
-* @param[in]       src_addr: the source address which provide the attribute table.
-* @param[in]       assoc_addr: the associated device address which went to share the attribute table with the source address.
-* @param[in]       is_assoc: true add the associated device address, false remove the associated device address.
-* @return
-*                  - ESP_OK: success
-*                  - other: failed
-*
-*/
+ * @brief  Add or remove the association between the address in the local GATTC cache with the source address of the remote device
+ *
+ * @param[in]       gattc_if   GATT Client access interface
+ * @param[in]       src_addr   The source address intended to be associated to the `assoc_addr` which has been stored in the local GATTC cache
+ * @param[in]       assoc_addr The associated device address intended to share the attribute table with the source address
+ * @param[in]       is_assoc   True if adding the association; false if removing the association.
+ *
+ * @note
+ *      1. This API is primarily used when the client has a stored server-side database (`assoc_addr`) and needs to connect to
+ *         another device (`src_addr`) with the same attribute database. By invoking this API, the stored database is utilized
+ *         as the peer server database, eliminating the need for attribute database search and discovery. This reduces
+ *         processing time and accelerates the connection process.
+ *      2. The attribute table of a device with `assoc_addr` must be stored in the local GATTC cache first.
+ *         Then, the attribute table of the device with `src_addr` must be the same as the one with `assoc_addr`.
+ *      3. This function triggers `ESP_GATTC_SET_ASSOC_EVT`.
+ *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_FAIL: Failure
+ */
 esp_err_t esp_ble_gattc_cache_assoc(esp_gatt_if_t gattc_if, esp_bd_addr_t src_addr,
                                       esp_bd_addr_t assoc_addr, bool is_assoc);
+
 /**
-* @brief           Get the address list which has store the attribute table in the gattc cache. There will
-*                  callback ESP_GATTC_GET_ADDR_LIST_EVT event when get address list complete.
-*
-* @param[in]       gattc_if: Gatt client access interface.
-* @return
-*                  - ESP_OK: success
-*                  - other: failed
-*
-*/
+ * @brief  Get the address list stored in the local GATTC cache
+ *
+ * @param[in]       gattc_if GATT Client access interface
+ *
+ * @note            This function triggers `ESP_GATTC_GET_ADDR_LIST_EVT`.
+ *
+ * @return
+ *        - ESP_OK: Success
+ *        - ESP_FAIL: Failure
+ */
 esp_err_t esp_ble_gattc_cache_get_addr_list(esp_gatt_if_t gattc_if);
 
 /**
-* @brief           Clean the service cache of this device in the gattc stack,
-*
-* @param[in]       remote_bda: remote device BD address.
-*
-* @return
-*                  - ESP_OK: success
-*                  - other: failed
-*
-*/
+ * @brief  Clean the service cache of the target device in the local GATTC cache
+ *
+ * @param[in]       remote_bda Remote device address
+ *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_FAIL: Failure
+ */
 esp_err_t esp_ble_gattc_cache_clean(esp_bd_addr_t remote_bda);
 
 #ifdef __cplusplus
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_gatts_api.h b/lib/bt/host/bluedroid/api/include/api/esp_gatts_api.h
index 0eb7ddd9..64222210 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_gatts_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_gatts_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -17,579 +17,606 @@ extern "C" {
 
 /// GATT Server callback function events
 typedef enum {
-    ESP_GATTS_REG_EVT                 = 0,       /*!< When register application id, the event comes */
-    ESP_GATTS_READ_EVT                = 1,       /*!< When gatt client request read operation, the event comes */
-    ESP_GATTS_WRITE_EVT               = 2,       /*!< When gatt client request write operation, the event comes */
-    ESP_GATTS_EXEC_WRITE_EVT          = 3,       /*!< When gatt client request execute write, the event comes */
-    ESP_GATTS_MTU_EVT                 = 4,       /*!< When set mtu complete, the event comes */
-    ESP_GATTS_CONF_EVT                = 5,       /*!< When receive confirm, the event comes */
-    ESP_GATTS_UNREG_EVT               = 6,       /*!< When unregister application id, the event comes */
-    ESP_GATTS_CREATE_EVT              = 7,       /*!< When create service complete, the event comes */
-    ESP_GATTS_ADD_INCL_SRVC_EVT       = 8,       /*!< When add included service complete, the event comes */
-    ESP_GATTS_ADD_CHAR_EVT            = 9,       /*!< When add characteristic complete, the event comes */
-    ESP_GATTS_ADD_CHAR_DESCR_EVT      = 10,      /*!< When add descriptor complete, the event comes */
-    ESP_GATTS_DELETE_EVT              = 11,      /*!< When delete service complete, the event comes */
-    ESP_GATTS_START_EVT               = 12,      /*!< When start service complete, the event comes */
-    ESP_GATTS_STOP_EVT                = 13,      /*!< When stop service complete, the event comes */
-    ESP_GATTS_CONNECT_EVT             = 14,      /*!< When gatt client connect, the event comes */
-    ESP_GATTS_DISCONNECT_EVT          = 15,      /*!< When gatt client disconnect, the event comes */
-    ESP_GATTS_OPEN_EVT                = 16,      /*!< When connect to peer, the event comes */
-    ESP_GATTS_CANCEL_OPEN_EVT         = 17,      /*!< When disconnect from peer, the event comes */
-    ESP_GATTS_CLOSE_EVT               = 18,      /*!< When gatt server close, the event comes */
-    ESP_GATTS_LISTEN_EVT              = 19,      /*!< When gatt listen to be connected the event comes */
-    ESP_GATTS_CONGEST_EVT             = 20,      /*!< When congest happen, the event comes */
+    ESP_GATTS_REG_EVT                 = 0,       /*!< This event is triggered when a GATT Server application is registered using `esp_ble_gatts_app_register`. */
+    ESP_GATTS_READ_EVT                = 1,       /*!< This event is triggered when the read request from the Client is received. */
+    ESP_GATTS_WRITE_EVT               = 2,       /*!< This event is triggered when the write request from the Client is received. */
+    ESP_GATTS_EXEC_WRITE_EVT          = 3,       /*!< This event is triggered when the write execution request from the Client is received. */
+    ESP_GATTS_MTU_EVT                 = 4,       /*!< This event is triggered when the MTU configuration request from the Client is received. */
+    ESP_GATTS_CONF_EVT                = 5,       /*!< This event is triggered when the confirmation from the Client is received. */
+    ESP_GATTS_UNREG_EVT               = 6,       /*!< This event is triggered when a GATT Server application is unregistered using `esp_ble_gatts_app_unregister`. */
+    ESP_GATTS_CREATE_EVT              = 7,       /*!< This event is triggered when a GATT Server service is created using `esp_ble_gatts_create_service`. */
+    ESP_GATTS_ADD_INCL_SRVC_EVT       = 8,       /*!< This event is triggered when an included service is added using `esp_ble_gatts_add_included_service`. */
+    ESP_GATTS_ADD_CHAR_EVT            = 9,       /*!< This event is triggered when a characteristic is added to the service using `esp_ble_gatts_add_char`. */
+    ESP_GATTS_ADD_CHAR_DESCR_EVT      = 10,      /*!< This event is triggered when a characteristic descriptor is added to the service using `esp_ble_gatts_add_char_descr`. */
+    ESP_GATTS_DELETE_EVT              = 11,      /*!< This event is triggered when the service is deleted using `esp_ble_gatts_delete_service`. */
+    ESP_GATTS_START_EVT               = 12,      /*!< This event is triggered when the service is started using `esp_ble_gatts_start_service`. */
+    ESP_GATTS_STOP_EVT                = 13,      /*!< This event is triggered when the service is stopped using `esp_ble_gatts_stop_service`.  */
+    ESP_GATTS_CONNECT_EVT             = 14,      /*!< This event is triggered when a physical connection is set up. */
+    ESP_GATTS_DISCONNECT_EVT          = 15,      /*!< This event is triggered when a physical connection is terminated. */
+    ESP_GATTS_OPEN_EVT                = 16,      /*!< This event is triggered when a virtual connection is created using `esp_ble_gatts_open`. */
+    ESP_GATTS_CANCEL_OPEN_EVT         = 17,      /*!< Deprecated. */
+    ESP_GATTS_CLOSE_EVT               = 18,      /*!< This event is triggered when a virtual connection is closed using `esp_ble_gatts_close`. */
+    ESP_GATTS_LISTEN_EVT              = 19,      /*!< Deprecated. */
+    ESP_GATTS_CONGEST_EVT             = 20,      /*!< This event is triggered when the GATT connection is congested. */
     /* following is extra event */
-    ESP_GATTS_RESPONSE_EVT            = 21,      /*!< When gatt send response complete, the event comes */
-    ESP_GATTS_CREAT_ATTR_TAB_EVT      = 22,      /*!< When gatt create table complete, the event comes */
-    ESP_GATTS_SET_ATTR_VAL_EVT        = 23,      /*!< When gatt set attr value complete, the event comes */
-    ESP_GATTS_SEND_SERVICE_CHANGE_EVT = 24,      /*!< When gatt send service change indication complete, the event comes */
+    ESP_GATTS_RESPONSE_EVT            = 21,      /*!< This event is triggered when a response is sent to the request using `esp_ble_gatts_send_response`. */
+    ESP_GATTS_CREAT_ATTR_TAB_EVT      = 22,      /*!< This event is triggered when a service attribute table is created using `esp_ble_gatts_create_attr_tab`. */
+    ESP_GATTS_SET_ATTR_VAL_EVT        = 23,      /*!< This event is triggered when an attribute value is set using `esp_ble_gatts_set_attr_value`. */
+    ESP_GATTS_SEND_SERVICE_CHANGE_EVT = 24,      /*!< This event is triggered when a service change indication is sent using `esp_ble_gatts_send_service_change_indication`. */
 } esp_gatts_cb_event_t;
 
 /**
- * @brief Gatt server callback parameters union
+ * @brief GATT Server callback parameters
  */
 typedef union {
     /**
-     * @brief ESP_GATTS_REG_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_REG_EVT`
      */
     struct gatts_reg_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t app_id;                /*!< Application id which input in register API */
-    } reg;                              /*!< Gatt server callback param of ESP_GATTS_REG_EVT */
+        uint16_t app_id;                /*!< Application ID */
+    } reg;                              /*!< Callback parameter for the event `ESP_GATTS_REG_EVT` */
 
     /**
-     * @brief ESP_GATTS_READ_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_READ_EVT`
      */
     struct gatts_read_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
-        uint32_t trans_id;              /*!< Transfer id */
-        esp_bd_addr_t bda;              /*!< The bluetooth device address which been read */
+        uint16_t conn_id;               /*!< Connection ID */
+        uint32_t trans_id;              /*!< Transfer ID */
+        esp_bd_addr_t bda;              /*!< The device address to read */
         uint16_t handle;                /*!< The attribute handle */
-        uint16_t offset;                /*!< Offset of the value, if the value is too long */
-        bool is_long;                   /*!< The value is too long or not */
-        bool need_rsp;                  /*!< The read operation need to do response */
-    } read;                             /*!< Gatt server callback param of ESP_GATTS_READ_EVT */
+        uint16_t offset;                /*!< The position offset to read. If the length of value is less than or equal to the MTU size, this value is 0. */
+        bool is_long;                   /*!< True indicates that the length of value is greater than the MTU size; false otherwise. */
+        bool need_rsp;                  /*!< True indicates that the `esp_ble_gatts_send_response` is required in the following step; false otherwise. */
+    } read;                             /*!< Callback parameter for the event `ESP_GATTS_READ_EVT` */
 
 
     /**
-     * @brief ESP_GATTS_WRITE_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_WRITE_EVT`
      */
     struct gatts_write_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
-        uint32_t trans_id;              /*!< Transfer id */
-        esp_bd_addr_t bda;              /*!< The bluetooth device address which been written */
+        uint16_t conn_id;               /*!< Connection ID */
+        uint32_t trans_id;              /*!< Transfer ID */
+        esp_bd_addr_t bda;              /*!< The device address to write */
         uint16_t handle;                /*!< The attribute handle */
-        uint16_t offset;                /*!< Offset of the value, if the value is too long */
-        bool need_rsp;                  /*!< The write operation need to do response */
-        bool is_prep;                   /*!< This write operation is prepare write */
-        uint16_t len;                   /*!< The write attribute value length */
+        uint16_t offset;                /*!< The position offset to write. If the length of value is less than or equal to the MTU size, this value is 0.*/
+        bool need_rsp;                  /*!< True indicates that the `esp_ble_gatts_send_response` is required in the following step; false otherwise. */
+        bool is_prep;                   /*!< True indicates the write operation is a prepared write operation */
+        uint16_t len;                   /*!< The length of the write attribute value in bytes */
         uint8_t *value;                 /*!< The write attribute value */
-    } write;                            /*!< Gatt server callback param of ESP_GATTS_WRITE_EVT */
+    } write;                            /*!< Callback parameter for the event `ESP_GATTS_WRITE_EVT` */
 
     /**
-     * @brief ESP_GATTS_EXEC_WRITE_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_EXEC_WRITE_EVT`
      */
     struct gatts_exec_write_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
-        uint32_t trans_id;              /*!< Transfer id */
-        esp_bd_addr_t bda;              /*!< The bluetooth device address which been written */
-#define ESP_GATT_PREP_WRITE_CANCEL 0x00 /*!< Prepare write flag to indicate cancel prepare write */
-#define ESP_GATT_PREP_WRITE_EXEC   0x01 /*!< Prepare write flag to indicate execute prepare write */
-        uint8_t exec_write_flag;        /*!< Execute write flag */
-    } exec_write;                       /*!< Gatt server callback param of ESP_GATTS_EXEC_WRITE_EVT */
+        uint16_t conn_id;               /*!< Connection ID */
+        uint32_t trans_id;              /*!< Transfer ID */
+        esp_bd_addr_t bda;              /*!< The bluetooth device address to write */
+        #define ESP_GATT_PREP_WRITE_CANCEL 0x00 /*!< Flag to indicate the cancellation of a prepare write operation */
+        #define ESP_GATT_PREP_WRITE_EXEC   0x01 /*!< Flag to indicate the execution of a prepare write operation */
+        uint8_t exec_write_flag;        /*!< Execute write flag: `ESP_GATT_PREP_WRITE_CANCEL` or `ESP_GATT_PREP_WRITE_EXEC` */
+    } exec_write;                       /*!< Callback parameter for the event `ESP_GATTS_EXEC_WRITE_EVT` */
 
     /**
-     * @brief ESP_GATTS_MTU_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_MTU_EVT`
      */
     struct gatts_mtu_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
+        uint16_t conn_id;               /*!< Connection ID */
         uint16_t mtu;                   /*!< MTU size */
-    } mtu;                              /*!< Gatt server callback param of ESP_GATTS_MTU_EVT */
+    } mtu;                              /*!< Callback parameter for the event `ESP_GATTS_MTU_EVT` */
 
     /**
-     * @brief ESP_GATTS_CONF_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_CONF_EVT`
      */
     struct gatts_conf_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t conn_id;               /*!< Connection id */
-        uint16_t handle;                /*!< attribute handle */
-        uint16_t len;                   /*!< The indication or notification value length, len is valid when send notification or indication failed */
-        uint8_t *value;                 /*!< The indication or notification value , value is valid when send notification or indication failed */
-    } conf;                             /*!< Gatt server callback param of ESP_GATTS_CONF_EVT (confirm) */
+        uint16_t conn_id;               /*!< Connection ID */
+        uint16_t handle;                /*!< Attribute handle */
+        uint16_t len;                   /*!< The length of indication or notification value in bytes. The length is invalid if the notification or indication failed. */
+        uint8_t *value;                 /*!< The indication or notification value. The value is invalid if the notification or indication failed. */
+    } conf;                             /*!< Callback parameter for the event `ESP_GATTS_CONF_EVT` */
 
     /**
-     * @brief ESP_GATTS_UNREG_EVT
-     */
-
-    /**
-     * @brief ESP_GATTS_CREATE_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_CREATE_EVT`
      */
     struct gatts_create_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
         uint16_t service_handle;        /*!< Service attribute handle */
-        esp_gatt_srvc_id_t service_id;  /*!< Service id, include service uuid and other information */
-    } create;                           /*!< Gatt server callback param of ESP_GATTS_CREATE_EVT */
+        esp_gatt_srvc_id_t service_id;  /*!< Service ID, including service UUID and other information */
+    } create;                           /*!< Callback parameter for the event `ESP_GATTS_CREATE_EVT` */
 
     /**
-     * @brief ESP_GATTS_ADD_INCL_SRVC_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_ADD_INCL_SRVC_EVT`
      */
     struct gatts_add_incl_srvc_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
         uint16_t attr_handle;           /*!< Included service attribute handle */
         uint16_t service_handle;        /*!< Service attribute handle */
-    } add_incl_srvc;                    /*!< Gatt server callback param of ESP_GATTS_ADD_INCL_SRVC_EVT */
+    } add_incl_srvc;                    /*!< Callback parameter for the event `ESP_GATTS_ADD_INCL_SRVC_EVT` */
 
     /**
-     * @brief ESP_GATTS_ADD_CHAR_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_ADD_CHAR_EVT`
      */
     struct gatts_add_char_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
         uint16_t attr_handle;           /*!< Characteristic attribute handle */
         uint16_t service_handle;        /*!< Service attribute handle */
-        esp_bt_uuid_t char_uuid;        /*!< Characteristic uuid */
-    } add_char;                         /*!< Gatt server callback param of ESP_GATTS_ADD_CHAR_EVT */
+        esp_bt_uuid_t char_uuid;        /*!< Characteristic UUID */
+    } add_char;                         /*!< Callback parameter for the event `ESP_GATTS_ADD_CHAR_EVT` */
 
     /**
-     * @brief ESP_GATTS_ADD_CHAR_DESCR_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_ADD_CHAR_DESCR_EVT`
      */
     struct gatts_add_char_descr_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
         uint16_t attr_handle;           /*!< Descriptor attribute handle */
         uint16_t service_handle;        /*!< Service attribute handle */
-        esp_bt_uuid_t descr_uuid;       /*!< Characteristic descriptor uuid */
-    } add_char_descr;                   /*!< Gatt server callback param of ESP_GATTS_ADD_CHAR_DESCR_EVT */
+        esp_bt_uuid_t descr_uuid;       /*!< Characteristic descriptor UUID */
+    } add_char_descr;                   /*!< Callback parameter for the event `ESP_GATTS_ADD_CHAR_DESCR_EVT` */
 
     /**
-     * @brief ESP_GATTS_DELETE_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_DELETE_EVT`
      */
     struct gatts_delete_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
         uint16_t service_handle;        /*!< Service attribute handle */
-    } del;                              /*!< Gatt server callback param of ESP_GATTS_DELETE_EVT */
+    } del;                              /*!< Callback parameter for the event `ESP_GATTS_DELETE_EVT` */
 
     /**
-     * @brief ESP_GATTS_START_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_START_EVT`
      */
     struct gatts_start_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
         uint16_t service_handle;        /*!< Service attribute handle */
-    } start;                            /*!< Gatt server callback param of ESP_GATTS_START_EVT */
+    } start;                            /*!< Callback parameter for the event `ESP_GATTS_START_EVT` */
 
     /**
-     * @brief ESP_GATTS_STOP_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_STOP_EVT`
      */
     struct gatts_stop_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
         uint16_t service_handle;        /*!< Service attribute handle */
-    } stop;                             /*!< Gatt server callback param of ESP_GATTS_STOP_EVT */
+    } stop;                             /*!< Callback parameter for the event `ESP_GATTS_STOP_EVT` */
 
     /**
-     * @brief ESP_GATTS_CONNECT_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_CONNECT_EVT`
      */
     struct gatts_connect_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
-        uint8_t link_role;              /*!< Link role : master role = 0  ; slave role = 1*/
-        esp_bd_addr_t remote_bda;       /*!< Remote bluetooth device address */
-        esp_gatt_conn_params_t conn_params; /*!< current Connection parameters */
-        esp_ble_addr_type_t ble_addr_type;  /*!< Remote BLE device address type */
-        uint16_t conn_handle;           /*!< HCI connection handle */
-    } connect;                          /*!< Gatt server callback param of ESP_GATTS_CONNECT_EVT */
+        uint16_t conn_id;                   /*!< Connection ID */
+        uint8_t link_role;                  /*!< Link role: master role = 0; slave role = 1 */
+        esp_bd_addr_t remote_bda;           /*!< Remote device address */
+        esp_gatt_conn_params_t conn_params; /*!< Current connection parameters */
+        esp_ble_addr_type_t ble_addr_type;  /*!< Remote device address type */
+        uint16_t conn_handle;               /*!< HCI connection handle */
+    } connect;                              /*!< Callback parameter for the event `ESP_GATTS_CONNECT_EVT` */
 
     /**
-     * @brief ESP_GATTS_DISCONNECT_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_DISCONNECT_EVT`
      */
     struct gatts_disconnect_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
-        esp_bd_addr_t remote_bda;       /*!< Remote bluetooth device address */
-        esp_gatt_conn_reason_t reason;  /*!< Indicate the reason of disconnection */
-    } disconnect;                       /*!< Gatt server callback param of ESP_GATTS_DISCONNECT_EVT */
+        uint16_t conn_id;               /*!< Connection ID */
+        esp_bd_addr_t remote_bda;       /*!< Remote device address */
+        esp_gatt_conn_reason_t reason;  /*!< The reason of disconnection */
+    } disconnect;                       /*!< Callback parameter for the event `ESP_GATTS_DISCONNECT_EVT` */
 
     /**
-     * @brief ESP_GATTS_OPEN_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_OPEN_EVT`
      */
     struct gatts_open_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-    } open;                             /*!< Gatt server callback param of ESP_GATTS_OPEN_EVT */
+    } open;                             /*!< Callback parameter for the event `ESP_GATTS_OPEN_EVT` */
 
     /**
-     * @brief ESP_GATTS_CANCEL_OPEN_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_CANCEL_OPEN_EVT`
      */
     struct gatts_cancel_open_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-    } cancel_open;                      /*!< Gatt server callback param of ESP_GATTS_CANCEL_OPEN_EVT */
+    } cancel_open;                      /*!< Callback parameter for the event `ESP_GATTS_CANCEL_OPEN_EVT` */
 
     /**
-     * @brief ESP_GATTS_CLOSE_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_CLOSE_EVT`
      */
     struct gatts_close_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t conn_id;               /*!< Connection id */
-    } close;                            /*!< Gatt server callback param of ESP_GATTS_CLOSE_EVT */
+        uint16_t conn_id;               /*!< Connection ID */
+    } close;                            /*!< Callback parameter for the event `ESP_GATTS_CLOSE_EVT` */
 
     /**
-     * @brief ESP_GATTS_LISTEN_EVT
-     */
-    /**
-     * @brief ESP_GATTS_CONGEST_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_CONGEST_EVT`
      */
     struct gatts_congest_evt_param {
-        uint16_t conn_id;               /*!< Connection id */
-        bool congested;                 /*!< Congested or not */
-    } congest;                          /*!< Gatt server callback param of ESP_GATTS_CONGEST_EVT */
+        uint16_t conn_id;               /*!< Connection ID */
+        bool congested;                 /*!< True indicates the connection is congested; false otherwise. */
+    } congest;                          /*!< Callback parameter for the event `ESP_GATTS_CONGEST_EVT` */
 
     /**
-     * @brief ESP_GATTS_RESPONSE_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_RESPONSE_EVT`
      */
     struct gatts_rsp_evt_param {
         esp_gatt_status_t status;       /*!< Operation status */
-        uint16_t handle;                /*!< Attribute handle which send response */
-    } rsp;                              /*!< Gatt server callback param of ESP_GATTS_RESPONSE_EVT */
+        uint16_t conn_id;               /*!< Connection ID */
+        uint16_t handle;                /*!< Attribute handle which sends the response */
+    } rsp;                              /*!< Callback parameter for the event `ESP_GATTS_RESPONSE_EVT` */
 
     /**
-     * @brief ESP_GATTS_CREAT_ATTR_TAB_EVT
+     * @brief Callback parameter for the event `ESP_GATTS_CREAT_ATTR_TAB_EVT`
      */
     struct gatts_add_attr_tab_evt_param{
         esp_gatt_status_t status;       /*!< Operation status */
-        esp_bt_uuid_t svc_uuid;         /*!< Service uuid type */
-        uint8_t svc_inst_id;            /*!< Service id */
-        uint16_t num_handle;            /*!< The number of the attribute handle to be added to the gatts database */
-        uint16_t *handles;              /*!< The number to the handles */
-    } add_attr_tab;                     /*!< Gatt server callback param of ESP_GATTS_CREAT_ATTR_TAB_EVT */
+        esp_bt_uuid_t svc_uuid;         /*!< Service UUID type */
+        uint8_t svc_inst_id;            /*!< Service ID */
+        uint16_t num_handle;            /*!< The number of the attribute handles which have been added to the GATT Service table */
+        uint16_t *handles;              /*!< The handles which have been added to the table */
+    } add_attr_tab;                     /*!< Callback parameter for the event `ESP_GATTS_CREAT_ATTR_TAB_EVT` */
 
 
    /**
-    * @brief ESP_GATTS_SET_ATTR_VAL_EVT
+    * @brief Callback parameter for the event `ESP_GATTS_SET_ATTR_VAL_EVT`
     */
     struct gatts_set_attr_val_evt_param{
         uint16_t srvc_handle;           /*!< The service handle */
-        uint16_t attr_handle;           /*!< The attribute  handle */
-        esp_gatt_status_t status;       /*!< Operation status*/
-    } set_attr_val;                     /*!< Gatt server callback param of ESP_GATTS_SET_ATTR_VAL_EVT */
+        uint16_t attr_handle;           /*!< The attribute handle */
+        esp_gatt_status_t status;       /*!< Operation status */
+    } set_attr_val;                     /*!< Callback parameter for the event `ESP_GATTS_SET_ATTR_VAL_EVT` */
 
     /**
-    * @brief ESP_GATTS_SEND_SERVICE_CHANGE_EVT
+    * @brief Callback parameter for the event `ESP_GATTS_SEND_SERVICE_CHANGE_EVT`
     */
     struct gatts_send_service_change_evt_param{
-        esp_gatt_status_t status;       /*!< Operation status*/
-    } service_change;                    /*!< Gatt server callback param of ESP_GATTS_SEND_SERVICE_CHANGE_EVT */
+        esp_gatt_status_t status;        /*!< Operation status */
+    } service_change;                    /*!< Callback parameter for the event `ESP_GATTS_SEND_SERVICE_CHANGE_EVT` */
 
 } esp_ble_gatts_cb_param_t;
 
 /**
  * @brief GATT Server callback function type
- * @param event : Event type
- * @param gatts_if : GATT server access interface, normally
- *                   different gatts_if correspond to different profile
- * @param param : Point to callback parameter, currently is union type
+ *
+ * @param[in] event    Event type
+ * @param[in] gatts_if GATT Server access interface. Typically, different `gatts_if` values correspond to different profiles.
+ * @param[in] param    The pointer to the callback parameter, which is of a union type.
  */
 typedef void (* esp_gatts_cb_t)(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_if, esp_ble_gatts_cb_param_t *param);
 
 /**
- * @brief           This function is called to register application callbacks
- *                  with BTA GATTS module.
+ * @brief  Register GATT Server application callbacks
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @param[in] callback The pointer to the application callback function
+ *
+ * @note            Avoid performing time-consuming operations within the callback functions.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_register_callback(esp_gatts_cb_t callback);
 
 /**
- * @brief           This function is called to get the current application callbacks
- *                  with BTA GATTS module.
+ * @brief  Get the current GATT Server application callback
  *
  * @return
- *                  - esp_gatts_cb_t : current callback
- *
+ *        - esp_gatts_cb_t: Current callback
  */
 esp_gatts_cb_t esp_ble_gatts_get_callback(void);
 
 /**
- * @brief           This function is called to register application identifier
+ * @brief  Register GATT Server application
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @param[in] app_id: The UUID for different application
  *
+ * @note
+ *      1. This function triggers `ESP_GATTS_REG_EVT`.
+ *      2. The maximum number of applications is limited to 6.
+ *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_ARG: The input `app_id` exceeds `ESP_APP_ID_MAX` (0x7fff) defined in esp_bt_defs.h.
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gatts_app_register(uint16_t app_id);
 
-
-
 /**
- * @brief           unregister with GATT Server.
+ * @brief  Unregister an GATT Server application
  *
- * @param[in]       gatts_if: GATT server access interface
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @param[in]  gatts_if GATT Server access interface.
+ *
+ * @note
+ *      1. This function triggers `ESP_GATTS_UNREG_EVT`.
+ *      2. The maximum number of applications is limited to 6.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_app_unregister(esp_gatt_if_t gatts_if);
 
-
 /**
- * @brief           Create a service. When service creation is done, a callback
- *                  event ESP_GATTS_CREATE_EVT is called to report status
- *                  and service ID to the profile. The service ID obtained in
- *                  the callback function needs to be used when adding included
- *                  service and characteristics/descriptors into the service.
+ * @brief  Create a GATT Server service
  *
- * @param[in]       gatts_if: GATT server access interface
- * @param[in]       service_id: service ID.
- * @param[in]       num_handle: number of handle requested for this service.
+ * @param[in]       gatts_if   GATT Server access interface
+ * @param[in]       service_id The pointer to the Service ID
+ * @param[in]       num_handle The number of handles requested for this service.
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note
+ *       1. This function triggers `ESP_GATTS_CREATE_EVT`.
+ *       2. `num_handle` should not be greater than CONFIG_BT_GATT_MAX_SR_ATTRIBUTES.
  *
+ * @return
+ *        - ESP_OK: Success
+ *        - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_create_service(esp_gatt_if_t gatts_if,
                                        esp_gatt_srvc_id_t *service_id, uint16_t num_handle);
 
 
 /**
- * @brief               Create a service attribute tab.
- * @param[in]       gatts_attr_db: the pointer to the service attr tab
- * @param[in]       gatts_if: GATT server access interface
- * @param[in]       max_nb_attr: the number of attribute to be added to the service database.
- * @param[in]       srvc_inst_id: the instance id of the service
+ * @brief  Create a service attribute table
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @param[in]       gatts_attr_db The pointer to the service attribute table
+ * @param[in]       gatts_if      GATT Server access interface
+ * @param[in]       max_nb_attr   The number of attributes to be added to the service database
+ * @param[in]       srvc_inst_id  The instance ID of the service
  *
+ * @note
+ *      1. This function triggers `ESP_GATTS_CREAT_ATTR_TAB_EVT`.
+ *      2. `max_nb_attr` should not be greater than CONFIG_BT_GATT_MAX_SR_ATTRIBUTES.
+ *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_ARG: Invalid `max_nb_attr`
+ *       - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_create_attr_tab(const esp_gatts_attr_db_t *gatts_attr_db,
                                             esp_gatt_if_t gatts_if,
                                             uint16_t max_nb_attr,
                                             uint8_t srvc_inst_id);
 /**
- * @brief           This function is called to add an included service. This function have to be called between
- *                  'esp_ble_gatts_create_service' and 'esp_ble_gatts_add_char'.  After included
- *                  service is included, a callback event ESP_GATTS_ADD_INCL_SRVC_EVT
- *                  is reported the included service ID.
+ * @brief  Add an included service
  *
- * @param[in]       service_handle: service handle to which this included service is to
- *                  be added.
- * @param[in]       included_service_handle: the service ID to be included.
+ * @param[in]       service_handle  Target service handle to add
+ * @param[in]       included_service_handle The handle of included service to be added
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note
+ *       1. This function triggers `ESP_GATTS_ADD_INCL_SRVC_EVT`.
+ *       2. This function has to be called between `esp_ble_gatts_create_service` and `esp_ble_gatts_add_char`.
  *
+ * @return
+ *        - ESP_OK: Success
+ *        - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_add_included_service(uint16_t service_handle, uint16_t included_service_handle);
 
-
-
 /**
- * @brief           This function is called to add a characteristic into a service.
+ * @brief  Add a characteristic into a service.
  *
- * @param[in]       service_handle: service handle to which this included service is to
- *                  be added.
- * @param[in]       char_uuid : Characteristic UUID.
- * @param[in]       perm      : Characteristic value declaration attribute permission.
- * @param[in]       property  : Characteristic Properties
- * @param[in]       char_val    : Characteristic value
- * @param[in]       control : attribute response control byte
+ * @param[in]       service_handle  Target service handle to add the characteristic
+ * @param[in]       char_uuid       The pointer to the characteristic UUID
+ * @param[in]       perm            Characteristic value declaration attribute permission
+ * @param[in]       property        Characteristic Properties
+ * @param[in]       char_val        The pointer to the characteristic value
+ * @param[in]       control         The pointer to the attribute response control byte
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note
+ *      1. This function triggers `ESP_GATTS_ADD_CHAR_EVT`.
+ *      2. `control->auto_rsp` should be set to `ESP_GATT_AUTO_RSP` or `ESP_GATT_RSP_BY_APP`.
+ *      3. For stack respond attribute (`ESP_GATT_AUTO_RSP`), `char_val` should not be NULL and `char_val->attr_max_len` must be greater than 0.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_ARG: Invalid arguments
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gatts_add_char(uint16_t service_handle,  esp_bt_uuid_t  *char_uuid,
                                  esp_gatt_perm_t perm, esp_gatt_char_prop_t property, esp_attr_value_t *char_val,
                                  esp_attr_control_t *control);
 
-
 /**
- * @brief           This function is called to add characteristic descriptor. When
- *                  it's done, a callback event ESP_GATTS_ADD_DESCR_EVT is called
- *                  to report the status and an ID number for this descriptor.
- *
- * @param[in]       service_handle: service handle to which this characteristic descriptor is to
- *                              be added.
- * @param[in]       perm: descriptor access permission.
- * @param[in]       descr_uuid: descriptor UUID.
- * @param[in]       char_descr_val  : Characteristic descriptor value
- * @param[in]       control : attribute response control byte
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @brief  Add a characteristic descriptor
+ *
+ * @param[in]       service_handle Target service handle to add the characteristic descriptor
+ * @param[in]       descr_uuid     The pointer to the descriptor UUID
+ * @param[in]       perm           Descriptor access permission
+ * @param[in]       char_descr_val The pointer to the characteristic descriptor value
+ * @param[in]       control        The pointer to the attribute response control byte
  *
+ * @note
+ *      1. This function triggers `ESP_GATTS_ADD_CHAR_DESCR_EVT`.
+ *      2. `control->auto_rsp` should be set to `ESP_GATT_AUTO_RSP` or `ESP_GATT_RSP_BY_APP`.
+ *      3. For stack respond attribute (`ESP_GATT_AUTO_RSP`), `char_val` should not be NULL and `char_val->attr_max_len` must be greater than 0.
+ *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_ARG: Invalid arguments
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gatts_add_char_descr (uint16_t service_handle,
                                         esp_bt_uuid_t   *descr_uuid,
                                         esp_gatt_perm_t perm, esp_attr_value_t *char_descr_val,
                                         esp_attr_control_t *control);
 
-
-
 /**
- * @brief           This function is called to delete a service. When this is done,
- *                  a callback event ESP_GATTS_DELETE_EVT is report with the status.
+ * @brief  Delete a service
  *
- * @param[in]       service_handle: service_handle to be deleted.
+ * @param[in]       service_handle Target service handle to delete
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note    This function triggers `ESP_GATTS_DELETE_EVT`.
  *
+ * @return
+ *         - ESP_OK: Success
+ *         - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_delete_service(uint16_t service_handle);
 
-
-
 /**
- * @brief           This function is called to start a service.
+ * @brief  Start a service
  *
- * @param[in]       service_handle: the service handle to be started.
+ * @param[in]       service_handle Target service handle to start
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note      This function triggers `ESP_GATTS_START_EVT`.
  *
+ * @return
+ *         - ESP_OK: Success
+ *         - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_start_service(uint16_t service_handle);
 
-
-
 /**
- * @brief           This function is called to stop a service.
+ * @brief  Stop a service.
  *
- * @param[in]       service_handle - service to be topped.
+ * @param[in]       service_handle Target service handle to stop
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note            This function triggers `ESP_GATTS_STOP_EVT`.
  *
+ * @return
+ *          - ESP_OK: Success
+ *          - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_stop_service(uint16_t service_handle);
 
-
-
 /**
- * @brief           Send indicate or notify to GATT client.
- *                  Set param need_confirm as false will send notification, otherwise indication.
- *                  Note: the size of indicate or notify data need less than MTU size,see "esp_ble_gattc_send_mtu_req".
- *
- * @param[in]       gatts_if: GATT server access interface
- * @param[in]       conn_id - connection id to indicate.
- * @param[in]       attr_handle - attribute handle to indicate.
- * @param[in]       value_len - indicate value length.
- * @param[in]       value: value to indicate.
- * @param[in]       need_confirm - Whether a confirmation is required.
- *                  false sends a GATT notification, true sends a GATT indication.
+ * @brief  Send indication or notification to a GATT Client
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @param[in]       gatts_if    GATT Server access interface
+ * @param[in]       conn_id     Connection ID
+ * @param[in]       attr_handle Attribute handle to indicate
+ * @param[in]       value_len   Indication value length in bytes
+ * @param[in]       value       Value to indicate
+ * @param[in]       need_confirm True if a confirmation is required, which is a GATT indication; false if the confirmation is not required, which is a GATT notification.
+ *
+ * @note
+ *       1. This function triggers `ESP_GATTS_CONF_EVT`.
+ *       2. The size of indication or notification data must be less than or equal to MTU size, see `esp_ble_gattc_send_mtu_req`.
+ *       3. This function should be called only after the connection has been established.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_ERR_INVALID_STATE: The connection has not been established.
+ *       - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gatts_send_indicate(esp_gatt_if_t gatts_if, uint16_t conn_id, uint16_t attr_handle,
                                       uint16_t value_len, uint8_t *value, bool need_confirm);
 
-
 /**
- * @brief           This function is called to send a response to a request.
+ * @brief  Send a response to a request
  *
- * @param[in]       gatts_if: GATT server access interface
- * @param[in]       conn_id - connection identifier.
- * @param[in]       trans_id - transfer id
- * @param[in]       status - response status
- * @param[in]       rsp - response data.
+ * @param[in]       gatts_if GATT Server access interface
+ * @param[in]       conn_id  Connection ID
+ * @param[in]       trans_id Transfer ID
+ * @param[in]       status   Response status
+ * @param[in]       rsp      The pointer to the response data
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note
+ *      1. This function triggers `ESP_GATTS_RESPONSE_EVT`.
+ *      2. This function should be called only after the connection has been established.
  *
+ * @return
+ *        - ESP_OK: Success
+ *        - ESP_ERR_INVALID_STATE: The connection has not been established.
+ *        - ESP_FAIL: Failure due to other reasons
  */
 esp_err_t esp_ble_gatts_send_response(esp_gatt_if_t gatts_if, uint16_t conn_id, uint32_t trans_id,
                                       esp_gatt_status_t status, esp_gatt_rsp_t *rsp);
 
-
 /**
- * @brief           This function is called to set the attribute value by the application
+ * @brief  Set the attribute value
  *
- * @param[in]       attr_handle: the attribute handle which to be set
- * @param[in]       length: the value length
- * @param[in]       value: the pointer to the attribute value
+ * @param[in]       attr_handle Target attribute handle to set the value
+ * @param[in]       length      The value length in bytes
+ * @param[in]       value       The pointer to the attribute value
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note    This function triggers `ESP_GATTS_SET_ATTR_VAL_EVT`.
  *
+ * @return
+ *          - ESP_OK: Success
+ *          - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_set_attr_value(uint16_t attr_handle, uint16_t length, const uint8_t *value);
 
 /**
- * @brief       Retrieve attribute value
+ * @brief  Retrieve attribute value
  *
- * @param[in]   attr_handle: Attribute handle.
- * @param[out]  length: pointer to the attribute value length
- * @param[out]  value:  Pointer to attribute value payload, the value cannot be modified by user
+ * @param[in]   attr_handle Attribute handle
+ * @param[out]  length      The pointer to the attribute value length in bytes
+ * @param[out]  value       The pointer to attribute value payload. This value cannot be modified by user.
  *
- * @return
- *                  - ESP_GATT_OK : success
- *                  - other  : failed
+ * @note
+ *      1. This function does not trigger any event.
+ *      2. `attr_handle` must be greater than 0.
  *
+ * @return
+ *        - ESP_OK: Success
+ *        - ESP_GATT_INVALID_HANDLE: Invalid `attr_handle`
+ *        - ESP_FAIL: Failure due to other reasons
  */
 esp_gatt_status_t esp_ble_gatts_get_attr_value(uint16_t attr_handle, uint16_t *length, const uint8_t **value);
 
-
 /**
- * @brief           Open a direct open connection or add a background auto connection
+ * @brief  Create an ACL connection when `BT_BLE_42_FEATURES_SUPPORTED` is enabled in the menuconfig
  *
- * @param[in]       gatts_if: GATT server access interface
- * @param[in]       remote_bda: remote device bluetooth device address.
- * @param[in]       is_direct: direct connection or background auto connection
+ * @param[in]       gatts_if   GATT Server access interface
+ * @param[in]       remote_bda Remote  device address
+ * @param[in]       is_direct `True` indicates a direct connection, while `False` indicates a background auto connection. Currently, background auto connection is not supported, so please always set this parameter to True.
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note
+ *      1. The function always triggers `ESP_GATTS_CONNECT_EVT` and `ESP_GATTS_OPEN_EVT`.
+ *      2. When the device acts as GATT Server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well.
+ *      3. This function will establish an ACL connection as a Central and a virtual connection as a GATT Server. If the ACL connection already exists, it will create a virtual connection only.
  *
+ * @return
+ *      - ESP_OK: Success
+ *      - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_open(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda, bool is_direct);
 
 /**
- * @brief           Close a connection  a remote device.
+ * @brief  Close a connection with a remote device
  *
- * @param[in]       gatts_if: GATT server access interface
- * @param[in]       conn_id: connection ID to be closed.
+ * @param[in]       gatts_if GATT Server access interface
+ * @param[in]       conn_id  Connection ID to be closed
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note
+ *      1. This function triggers `ESP_GATTS_CLOSE_EVT`.
+ *      2. There may be multiple virtual GATT server connections when multiple `app_id` got registered.
+ *      3. This API closes one virtual GATT server connection only, if there exist other virtual GATT server connections. It does not close the physical connection.
+ *      4. The API `esp_ble_gap_disconnect` can be used to disconnect the physical connection directly.
+ *      5. If there is only one virtual GATT connection left, this API will terminate the ACL connection in addition, and trigger `ESP_GATTS_DISCONNECT_EVT`. Then there is no need to call `esp_ble_gap_disconnect` anymore.
  *
+ * @return
+ *      - ESP_OK: Success
+ *      - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_close(esp_gatt_if_t gatts_if, uint16_t conn_id);
 
 /**
- * @brief           Send service change indication
+ * @brief  Send service change indication
  *
- * @param[in]       gatts_if: GATT server access interface
- * @param[in]       remote_bda: remote device bluetooth device address.
+ * @param[in]       gatts_if   GATT Server access interface
+ * @param[in]       remote_bda Remote device address.
  *                  If remote_bda is NULL then it will send service change
  *                  indication to all the connected devices and if not then
- *                  to a specific device
+ *                  to a specific device.
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * @note This function triggers `ESP_GATTS_SEND_SERVICE_CHANGE_EVT`.
  *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_send_service_change_indication(esp_gatt_if_t gatts_if, esp_bd_addr_t remote_bda);
 
 /**
- * @brief           Print local database (GATT service table)
+ * @brief   Display the Server's local attribute database.
  *
- * @return
- *                  - ESP_OK : success
- *                  - other  : failed
+ * This API prints the local attribute database of the BLE server, including details
+ * of all services, characteristics, and descriptors.
  *
+ * @note
+ *    1. This function does not trigger any event.
+ *    2. It is primarily intended for debugging purposes to verify the server's current configuration.
+ *
+ * @return
+ *       - ESP_OK: Success
+ *       - ESP_FAIL: Failure
  */
 esp_err_t esp_ble_gatts_show_local_database(void);
 
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h b/lib/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h
index 84086118..f34c52c4 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_hf_ag_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -10,6 +10,7 @@
 #include "esp_err.h"
 #include "esp_bt_defs.h"
 #include "esp_hf_defs.h"
+#include "esp_hf_ag_legacy_api.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -63,6 +64,7 @@ typedef enum
     ESP_HF_WBS_RESPONSE_EVT,                  /*!< Codec Status */
     ESP_HF_BCS_RESPONSE_EVT,                  /*!< Final Codec Choice */
     ESP_HF_PKT_STAT_NUMS_GET_EVT,             /*!< Request number of packet different status */
+    ESP_HF_PROF_STATE_EVT,                    /*!< Indicate HF init or deinit complete */
 } esp_hf_cb_event_t;
 
 /// Dial type of ESP_HF_DIAL_EVT
@@ -73,6 +75,14 @@ typedef enum
     ESP_HF_DIAL_MEM,                          /*!< Dial with a memory position */
 } esp_hf_dial_type_t;
 
+
+/// HFP AG profile status parameters
+typedef struct {
+    bool hfp_ag_inited;                        /*!< hfp ag initialization */
+    uint8_t slc_conn_num;                      /*!< Number of Service Level Connections */
+    uint8_t sync_conn_num;                     /*!< Number of (e)SCO Connections */
+} esp_hf_profile_status_t;
+
 /// HFP AG callback parameters
 typedef union
 {
@@ -92,7 +102,8 @@ typedef union
     struct hf_audio_stat_param {
         esp_bd_addr_t remote_addr;                /*!< Remote bluetooth device address */
         esp_hf_audio_state_t state;               /*!< Audio connection state */
-        uint16_t sync_conn_handle;                /*!< (e)SCO connection handle */
+        esp_hf_sync_conn_hdl_t sync_conn_handle;    /*!< (e)SCO connection handle */
+        uint16_t preferred_frame_size;            /*!< Valid only when Voice Over HCI is enabled, recommended frame size to send */
     } audio_stat;                                 /*!< AG callback param of ESP_HF_AUDIO_STATE_EVT */
 
     /**
@@ -223,45 +234,37 @@ typedef union
         uint32_t tx_discarded;    /*!< the total number of packets send lost */
     } pkt_nums;                   /*!< AG callback param of ESP_HF_PKT_STAT_NUMS_GET_EVT */
 
+    /**
+     * @brief ESP_HF_PROF_STATE_EVT
+     */
+    struct ag_prof_stat_param {
+        esp_hf_prof_state_t state;                /*!< hf profile state param */
+    } prof_stat;                                  /*!< status to indicate hf prof init or deinit */
+
 } esp_hf_cb_param_t;                              /*!< HFP AG callback param compound*/
 
 /**
- * @brief           AG incoming data callback function, the callback is useful in case of
- *                  Voice Over HCI.
+ * @brief           HF AG callback function type
  *
- * @param[in]       buf : pointer to incoming data(payload of HCI synchronous data packet), the
- *                  buffer is allocated inside bluetooth protocol stack and will be released after
- *                  invoke of the callback is finished.
+ * @param           event : Event type
  *
- * @param[in]       len : size(in bytes) in buf
+ * @param           param : Pointer to callback parameter
  */
-typedef void (* esp_hf_incoming_data_cb_t)(const uint8_t *buf, uint32_t len);
+typedef void (* esp_hf_cb_t) (esp_hf_cb_event_t event, esp_hf_cb_param_t *param);
 
 /**
- * @brief           AG outgoing data callback function, the callback is useful in case of
- *                  Voice Over HCI. Once audio connection is set up and the application layer has
- *                  prepared data to send, the lower layer will call this function to read data
- *                  and then send. This callback is supposed to be implemented as non-blocking,
- *                  and if data is not enough, return value 0 is supposed.
+ * @brief           HFP AG incoming audio data callback function, user should copy audio_buf struct
+ *                  to other place before return. This callback is used in case of Voice Over HCI.
  *
- * @param[in]       buf : pointer to incoming data(payload of HCI synchronous data packet), the
- *                  buffer is allocated inside bluetooth protocol stack and will be released after
- *                  invoke of the callback is finished.
+ * @param[in]       sync_conn_hdl: (e)SCO connection handle
  *
- * @param[in]       len : size(in bytes) in buf
+ * @param[in]       audio_buf: pointer to incoming data(payload of HCI synchronous data packet), user
+ *                  should free audio buffer by calling esp_hf_ag_audio_buff_free
  *
- * @return          length of data successfully read
- */
-typedef uint32_t (* esp_hf_outgoing_data_cb_t) (uint8_t *buf, uint32_t len);
-
-/**
- * @brief           HF AG callback function type
- *
- * @param           event : Event type
+ * @param[in]       is_bad_frame: whether this packet is marked as bad frame by baseband
  *
- * @param           param : Pointer to callback parameter
  */
-typedef void (* esp_hf_cb_t) (esp_hf_cb_event_t event, esp_hf_cb_param_t *param);
+typedef void (* esp_hf_ag_audio_data_cb_t)(esp_hf_sync_conn_hdl_t sync_conn_hdl, esp_hf_audio_buff_t *audio_buf, bool is_bad_frame);
 
 /************************************************************************************
 **  ESP HF API
@@ -284,6 +287,7 @@ esp_err_t esp_hf_ag_register_callback(esp_hf_cb_t callback);
  *
  * @brief           Initialize the bluetooth HF AG module.
  *                  This function should be called after esp_bluedroid_enable() completes successfully.
+ *                  ESP_HF_PROF_STATE_EVT with ESP_HF_INIT_SUCCESS will reported to the APP layer.
  *
  * @return
  *                  - ESP_OK: if the initialization request is sent successfully
@@ -297,6 +301,7 @@ esp_err_t esp_hf_ag_init(void);
  *
  * @brief           De-initialize for HF AG module.
  *                  This function should be called only after esp_bluedroid_enable() completes successfully.
+ *                  ESP_HF_PROF_STATE_EVT with ESP_HF_DEINIT_SUCCESS will reported to the APP layer.
  *
  * @return
  *                  - ESP_OK: success
@@ -504,13 +509,13 @@ esp_err_t esp_hf_ag_cind_response(esp_bd_addr_t remote_addr,
 
 /**
  *
- * @brief           Reponse for AT+COPS command from HF Client.
+ * @brief           Response for AT+COPS command from HF Client.
  *                  As a precondition to use this API, Service Level Connection shall exist with HFP client.
  *
  * @param[in]       remote_addr: remote bluetooth device address
  * @param[in]       name: current operator name
  * @return
- *                  - ESP_OK: reponse for AT+COPS command is sent to lower layer
+ *                  - ESP_OK: response for AT+COPS command is sent to lower layer
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
  *                  - ESP_FAIL: others
  *
@@ -529,7 +534,7 @@ esp_err_t esp_hf_ag_cops_response(esp_bd_addr_t remote_addr, char *name);
  * @param[in]       mode: current call mode (voice/data/fax)
  * @param[in]       mpty: single or multi type
  * @param[in]       number: current call number
- * @param[in]       type: international type or unknow
+ * @param[in]       type: international type or unknown
  * @return
  *                  - ESP_OK: response to AT+CLCC command is sent to lower layer
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
@@ -668,19 +673,58 @@ esp_err_t esp_hf_ag_end_call(esp_bd_addr_t remote_addr, int num_active, int num_
                             char *number, esp_hf_call_addr_type_t call_addr_type);
 
 /**
- * @brief           Register AG data output function.
- *                  The callback is only used in the case that Voice Over HCI is enabled.
+ * @brief           Register HFP AG audio data output function; the callback is only used in
+ *                  the case that Voice Over HCI is enabled.
  *
- * @param[in]       recv: HFP client incoming data callback function
- * @param[in]       send: HFP client outgoing data callback function
+ * @param[in]       callback: HFP AG incoming audio data callback function
  *
  * @return
  *                  - ESP_OK: success
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
- *                  - ESP_FAIL: if callback is a NULL function pointer
+ *                  - ESP_FAIL: others
  *
  */
-esp_err_t esp_hf_ag_register_data_callback(esp_hf_incoming_data_cb_t recv, esp_hf_outgoing_data_cb_t send);
+esp_err_t esp_hf_ag_register_audio_data_callback(esp_hf_ag_audio_data_cb_t callback);
+
+/**
+ * @brief           Allocate a audio buffer to store and send audio data. This function is only
+ *                  used in the case that Voice Over HCI is enabled.
+ *
+ * @param[in]       size: buffer size to allocate
+ *
+ * @return          allocated audio buffer, if Bluedroid is not enabled, no memory, or size is
+ *                  zeros, will return NULL
+ *
+ */
+esp_hf_audio_buff_t *esp_hf_ag_audio_buff_alloc(uint16_t size);
+
+/**
+ * @brief           Free a audio buffer allocated by esp_hf_ag_audio_buff_alloc. This function
+ *                  is only used in the case that Voice Over HCI is enabled.
+ *
+ * @param[in]       audio_buf: audio buffer to free
+ *
+ */
+void esp_hf_ag_audio_buff_free(esp_hf_audio_buff_t *audio_buf);
+
+/**
+ * @brief           Send audio data, the audio buffer should by allocated by esp_hf_ag_audio_buff_alloc.
+ *                  If the length of the audio data is equal to preferred_frame_size indicated by
+ *                  ESP_HF_AUDIO_STATE_EVT, then we can reduce one memory copy inside the Bluedroid stack.
+ *                  This function is only used in the case that Voice Over HCI is enabled.
+ *
+ * @param[in]       sync_conn_hdl: (e)SCO connection handle
+ *
+ * @param[in]       audio_buf: audio buffer that audio data stored
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
+ *                  - ESP_ERR_INVALID_ARG: invalid parameter
+ *                  - ESP_FAIL: others
+ *
+ */
+esp_err_t esp_hf_ag_audio_data_send(esp_hf_sync_conn_hdl_t sync_conn_hdl, esp_hf_audio_buff_t *audio_buf);
 
 /**
  *
@@ -700,14 +744,15 @@ esp_err_t esp_hf_ag_register_data_callback(esp_hf_incoming_data_cb_t recv, esp_h
 esp_err_t esp_hf_ag_pkt_stat_nums_get(uint16_t sync_conn_handle);
 
 /**
- * @brief           Trigger the lower-layer to fetch and send audio data.
+ * @brief       This function is used to get the status of hfp ag
  *
- *                  This function is only used in the case that Voice Over HCI is enabled.
- *                  As a precondition to use this API, Service Level Connection shall exist with HFP client.
- *                  After this function is called, lower layer will invoke esp_hf_client_outgoing_data_cb_t to fetch data
+ * @param[out]  profile_status - hfp ag status
  *
+ * @return
+ *              - ESP_OK: success
+ *              - other: failed
  */
-void esp_hf_ag_outgoing_data_ready(void);
+esp_err_t esp_hf_ag_get_profile_status(esp_hf_profile_status_t *profile_status);
 
 #ifdef __cplusplus
 }
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_hf_ag_legacy_api.h b/lib/bt/host/bluedroid/api/include/api/esp_hf_ag_legacy_api.h
new file mode 100644
index 00000000..7cd0769b
--- /dev/null
+++ b/lib/bt/host/bluedroid/api/include/api/esp_hf_ag_legacy_api.h
@@ -0,0 +1,77 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ *  Some legacy APIs of HFP AG, will be removed in the future
+ */
+
+#pragma once
+
+#include "esp_err.h"
+#include "esp_bt_defs.h"
+#include "esp_hf_defs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief           AG incoming data callback function, the callback is useful in case of
+ *                  Voice Over HCI.
+ *
+ * @param[in]       buf : pointer to incoming data(payload of HCI synchronous data packet), the
+ *                  buffer is allocated inside bluetooth protocol stack and will be released after
+ *                  invoke of the callback is finished.
+ *
+ * @param[in]       len : size(in bytes) in buf
+ */
+typedef void (* esp_hf_incoming_data_cb_t)(const uint8_t *buf, uint32_t len);
+
+/**
+ * @brief           AG outgoing data callback function, the callback is useful in case of
+ *                  Voice Over HCI. Once audio connection is set up and the application layer has
+ *                  prepared data to send, the lower layer will call this function to read data
+ *                  and then send. This callback is supposed to be implemented as non-blocking,
+ *                  and if data is not enough, return value 0 is supposed.
+ *
+ * @param[in]       buf : pointer to incoming data(payload of HCI synchronous data packet), the
+ *                  buffer is allocated inside bluetooth protocol stack and will be released after
+ *                  invoke of the callback is finished.
+ *
+ * @param[in]       len : size(in bytes) in buf
+ *
+ * @return          length of data successfully read
+ */
+typedef uint32_t (* esp_hf_outgoing_data_cb_t) (uint8_t *buf, uint32_t len);
+
+/**
+ * @brief           Register AG data output function.
+ *                  The callback is only used in the case that Voice Over HCI is enabled.
+ *
+ * @param[in]       recv: HFP client incoming data callback function
+ * @param[in]       send: HFP client outgoing data callback function
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
+ *                  - ESP_FAIL: if callback is a NULL function pointer
+ *
+ */
+esp_err_t esp_hf_ag_register_data_callback(esp_hf_incoming_data_cb_t recv, esp_hf_outgoing_data_cb_t send);
+
+/**
+ * @brief           Trigger the lower-layer to fetch and send audio data.
+ *
+ *                  This function is only used in the case that Voice Over HCI is enabled.
+ *                  As a precondition to use this API, Service Level Connection shall exist with HFP client.
+ *                  After this function is called, lower layer will invoke esp_hf_ag_outgoing_data_cb_t to fetch data
+ *
+ */
+void esp_hf_ag_outgoing_data_ready(void);
+
+#ifdef __cplusplus
+}
+#endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_hf_client_api.h b/lib/bt/host/bluedroid/api/include/api/esp_hf_client_api.h
index 9353fc03..53bf0396 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_hf_client_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_hf_client_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -10,6 +10,7 @@
 #include "esp_err.h"
 #include "esp_bt_defs.h"
 #include "esp_hf_defs.h"
+#include "esp_hf_client_legacy_api.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -42,6 +43,15 @@ typedef enum {
     ESP_HF_CLIENT_IN_BAND_RINGTONE_PROVIDED,
 } esp_hf_client_in_band_ring_state_t;
 
+/**
+ * @brief HF client profile status parameters
+ */
+typedef struct {
+    bool hf_client_inited;                             /*!< hf client initialization */
+    uint8_t slc_conn_num;                              /*!< Number of Service Level Connections */
+    uint8_t sync_conn_num;                             /*!< Number of (e)SCO Connections */
+} esp_hf_client_profile_status_t;
+
 /* features masks of AG */
 #define ESP_HF_CLIENT_PEER_FEAT_3WAY       0x01        /* Three-way calling */
 #define ESP_HF_CLIENT_PEER_FEAT_ECNR       0x02        /* Echo cancellation and/or noise reduction */
@@ -97,6 +107,7 @@ typedef enum {
     ESP_HF_CLIENT_BINP_EVT,                          /*!< requested number of last voice tag from AG */
     ESP_HF_CLIENT_RING_IND_EVT,                      /*!< ring indication event */
     ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT,             /*!< requested number of packet different status */
+    ESP_HF_CLIENT_PROF_STATE_EVT,                    /*!< Indicate HF CLIENT init or deinit complete */
 } esp_hf_client_cb_event_t;
 
 /// HFP client callback parameters
@@ -117,7 +128,8 @@ typedef union {
     struct hf_client_audio_stat_param {
         esp_hf_client_audio_state_t state;       /*!< audio connection state */
         esp_bd_addr_t remote_bda;                /*!< remote bluetooth device address */
-        uint16_t  sync_conn_handle;              /*!< (e)SCO connection handle */
+        esp_hf_sync_conn_hdl_t  sync_conn_handle;  /*!< (e)SCO connection handle */
+        uint16_t preferred_frame_size;           /*!< valid only when Voice Over HCI is enabled, recommended frame size to send */
     } audio_stat;                                /*!< HF callback param of ESP_HF_CLIENT_AUDIO_STATE_EVT */
 
     /**
@@ -266,35 +278,28 @@ typedef union {
         uint32_t tx_discarded;    /*!< the total number of packets send lost */
     } pkt_nums;                   /*!< HF callback param of ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT */
 
-} esp_hf_client_cb_param_t;                      /*!< HFP client callback parameters */
+    /**
+     * @brief ESP_HF_CLIENT_PROF_STATE_EVT
+     */
+    struct hf_client_prof_stat_param {
+        esp_hf_prof_state_t state;               /*!< hf client profile state param */
+    } prof_stat;                                 /*!< status to indicate hf client prof init or deinit */
 
-/**
- * @brief           HFP client incoming data callback function, the callback is useful in case of
- *                  Voice Over HCI.
- * @param[in]       buf : pointer to incoming data(payload of HCI synchronous data packet), the
- *                  buffer is allocated inside bluetooth protocol stack and will be released after
- *                  invoke of the callback is finished.
- * @param[in]       len : size(in bytes) in buf
- */
-typedef void (* esp_hf_client_incoming_data_cb_t)(const uint8_t *buf, uint32_t len);
+} esp_hf_client_cb_param_t;                      /*!< HFP client callback parameters */
 
 /**
- * @brief           HFP client outgoing data callback function, the callback is useful in case of
- *                  Voice Over HCI. Once audio connection is set up and the application layer has
- *                  prepared data to send, the lower layer will call this function to read data
- *                  and then send. This callback is supposed to be implemented as non-blocking,
- *                  and if data is not enough, return value 0 is supposed.
+ * @brief           HFP client incoming audio data callback function, user should copy audio_buf struct
+ *                  to other place before return. This callback is used in case of Voice Over HCI.
  *
- * @param[in]       buf : pointer to incoming data(payload of HCI synchronous data packet), the
- *                  buffer is allocated inside bluetooth protocol stack and will be released after
- *                  invoke of the callback is finished.
+ * @param[in]       sync_conn_hdl: (e)SCO connection handle
  *
- * @param[in]       len : size(in bytes) in buf
+ * @param[in]       audio_buf: pointer to incoming data(payload of HCI synchronous data packet), user
+ *                  should free audio buffer by calling esp_hf_client_audio_buff_free
  *
- * @return          length of data successfully read
+ * @param[in]       is_bad_frame: whether this packet is marked as bad frame by baseband
  *
  */
-typedef uint32_t (* esp_hf_client_outgoing_data_cb_t)(uint8_t *buf, uint32_t len);
+typedef void (* esp_hf_client_audio_data_cb_t)(esp_hf_sync_conn_hdl_t sync_conn_hdl, esp_hf_audio_buff_t *audio_buf, bool is_bad_frame);
 
 /**
  * @brief           HFP client callback function type
@@ -323,6 +328,7 @@ esp_err_t esp_hf_client_register_callback(esp_hf_client_cb_t callback);
  *
  * @brief           Initialize the bluetooth HFP client module.
  *                  This function should be called after esp_bluedroid_enable() completes successfully.
+ *                  ESP_HF_CLIENT_PROF_STATE_EVT with ESP_HF_INIT_SUCCESS will reported to the APP layer.
  *
  * @return
  *                  - ESP_OK: if the initialization request is sent successfully
@@ -336,6 +342,7 @@ esp_err_t esp_hf_client_init(void);
  *
  * @brief           De-initialize for HFP client module.
  *                  This function should be called only after esp_bluedroid_enable() completes successfully.
+ *                  ESP_HF_CLIENT_PROF_STATE_EVT with ESP_HF_DEINIT_SUCCESS will reported to the APP layer.
  *
  * @return
  *                  - ESP_OK: success
@@ -422,7 +429,7 @@ esp_err_t esp_hf_client_start_voice_recognition(void);
  *                  As a precondition to use this API, Service Level Connection shall exist with AG.
  *
  * @return
- *                  - ESP_OK: stoping voice recognition is sent to lower layer
+ *                  - ESP_OK: stopping voice recognition is sent to lower layer
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
  *                  - ESP_FAIL: others
  *
@@ -652,50 +659,74 @@ esp_err_t esp_hf_client_request_last_voice_tag_number(void);
  */
 esp_err_t esp_hf_client_send_nrec(void);
 
-
 /**
- * @brief           Register HFP client data output function; the callback is only used in
- *                  the case that Voice Over HCI is enabled.
  *
- * @param[in]       recv: HFP client incoming data callback function
+ * @brief           Get the number of packets received and sent
+ *                  This function is only used in the case that Voice Over HCI is enabled and the audio state is connected.
+ *                  When the operation is completed, the callback function will be called with ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT.
  *
- * @param[in]       send: HFP client outgoing data callback function
+ * @param[in]       sync_conn_handle: the (e)SCO connection handle
  *
  * @return
- *                  - ESP_OK: success
+ *                  - ESP_OK: if the request is sent successfully
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
- *                  - ESP_FAIL: if callback is a NULL function pointer
+ *                  - ESP_FAIL: others
  *
  */
-esp_err_t esp_hf_client_register_data_callback(esp_hf_client_incoming_data_cb_t recv,
-                                               esp_hf_client_outgoing_data_cb_t send);
+esp_err_t esp_hf_client_pkt_stat_nums_get(uint16_t sync_conn_handle);
 
 /**
+ * @brief           Register HFP client audio data output function; the callback is only used in
+ *                  the case that Voice Over HCI is enabled.
  *
- * @brief           Get the number of packets received and sent
- *                  This function is only used in the case that Voice Over HCI is enabled and the audio state is connected.
- *                  When the operation is completed, the callback function will be called with ESP_HF_CLIENT_PKT_STAT_NUMS_GET_EVT.
- *
- * @param[in]       sync_conn_handle: the (e)SCO connection handle
+ * @param[in]       callback: HFP client incoming audio data callback function
  *
  * @return
- *                  - ESP_OK: if the request is sent successfully
+ *                  - ESP_OK: success
  *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
  *                  - ESP_FAIL: others
  *
  */
-esp_err_t esp_hf_client_pkt_stat_nums_get(uint16_t sync_conn_handle);
+esp_err_t esp_hf_client_register_audio_data_callback(esp_hf_client_audio_data_cb_t callback);
 
 /**
- * @brief           Trigger the lower-layer to fetch and send audio data.
- *                  This function is only only used in the case that Voice Over HCI is enabled. After this
- *                  function is called, lower layer will invoke esp_hf_client_outgoing_data_cb_t to fetch data.
+ * @brief           Allocate a audio buffer to store and send audio data. This function is only
+ *                  used in the case that Voice Over HCI is enabled.
  *
- *                  As a precondition to use this API, Service Level Connection shall exist with AG.
+ * @param[in]       size: buffer size to allocate
+ *
+ * @return          allocated audio buffer, if Bluedroid is not enabled, no memory, or size is
+ *                  zeros, will return NULL
  *
  */
-void esp_hf_client_outgoing_data_ready(void);
+esp_hf_audio_buff_t *esp_hf_client_audio_buff_alloc(uint16_t size);
 
+/**
+ * @brief           Free a audio buffer allocated by esp_hf_client_audio_buff_alloc. This function
+ *                  is only used in the case that Voice Over HCI is enabled.
+ *
+ * @param[in]       audio_buf: audio buffer to free
+ *
+ */
+void esp_hf_client_audio_buff_free(esp_hf_audio_buff_t *audio_buf);
+
+/**
+ * @brief           Send audio data, the audio buffer should by allocated by esp_hf_client_audio_buff_alloc.
+ *                  If the length of the audio data is equal to preferred_frame_size indicated by
+ *                  ESP_HF_CLIENT_AUDIO_STATE_EVT, then we can reduce one memory copy inside the Bluedroid stack.
+ *                  This function is only used in the case that Voice Over HCI is enabled.
+ *
+ * @param[in]       sync_conn_hdl: (e)SCO connection handle
+ *
+ * @param[in]       audio_buf: audio buffer that audio data stored
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
+ *                  - ESP_ERR_INVALID_ARG: invalid parameter
+ *
+ */
+esp_err_t esp_hf_client_audio_data_send(esp_hf_sync_conn_hdl_t sync_conn_hdl, esp_hf_audio_buff_t *audio_buf);
 
 /**
  * @brief           Initialize the down sampling converter. This is a utility function that can
@@ -728,6 +759,17 @@ void esp_hf_client_pcm_resample_deinit(void);
  */
 int32_t esp_hf_client_pcm_resample(void *src, uint32_t in_bytes, void *dst);
 
+/**
+ * @brief       This function is used to get the status of hf client
+ *
+ * @param[out]  profile_status - hf client status
+ *
+ * @return
+ *              - ESP_OK: success
+ *              - other: failed
+ */
+esp_err_t esp_hf_client_get_profile_status(esp_hf_client_profile_status_t *profile_status);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_hf_client_legacy_api.h b/lib/bt/host/bluedroid/api/include/api/esp_hf_client_legacy_api.h
new file mode 100644
index 00000000..6441bfc4
--- /dev/null
+++ b/lib/bt/host/bluedroid/api/include/api/esp_hf_client_legacy_api.h
@@ -0,0 +1,78 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ *  Some legacy APIs of HFP HF, will be removed in the future
+ */
+
+#pragma once
+
+#include "esp_err.h"
+#include "esp_bt_defs.h"
+#include "esp_hf_defs.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief           HFP client incoming data callback function, the callback is useful in case of
+ *                  Voice Over HCI.
+ * @param[in]       buf : pointer to incoming data(payload of HCI synchronous data packet), the
+ *                  buffer is allocated inside bluetooth protocol stack and will be released after
+ *                  invoke of the callback is finished.
+ * @param[in]       len : size(in bytes) in buf
+ */
+typedef void (* esp_hf_client_incoming_data_cb_t)(const uint8_t *buf, uint32_t len);
+
+/**
+ * @brief           HFP client outgoing data callback function, the callback is useful in case of
+ *                  Voice Over HCI. Once audio connection is set up and the application layer has
+ *                  prepared data to send, the lower layer will call this function to read data
+ *                  and then send. This callback is supposed to be implemented as non-blocking,
+ *                  and if data is not enough, return value 0 is supposed.
+ *
+ * @param[in]       buf : pointer to incoming data(payload of HCI synchronous data packet), the
+ *                  buffer is allocated inside bluetooth protocol stack and will be released after
+ *                  invoke of the callback is finished.
+ *
+ * @param[in]       len : size(in bytes) in buf
+ *
+ * @return          length of data successfully read
+ *
+ */
+typedef uint32_t (* esp_hf_client_outgoing_data_cb_t)(uint8_t *buf, uint32_t len);
+
+/**
+ * @brief           Register HFP client data output function; the callback is only used in
+ *                  the case that Voice Over HCI is enabled.
+ *
+ * @param[in]       recv: HFP client incoming data callback function
+ *
+ * @param[in]       send: HFP client outgoing data callback function
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - ESP_ERR_INVALID_STATE: if bluetooth stack is not yet enabled
+ *                  - ESP_FAIL: if callback is a NULL function pointer
+ *
+ */
+esp_err_t esp_hf_client_register_data_callback(esp_hf_client_incoming_data_cb_t recv,
+                                               esp_hf_client_outgoing_data_cb_t send);
+
+/**
+ * @brief           Trigger the lower-layer to fetch and send audio data.
+ *                  This function is only only used in the case that Voice Over HCI is enabled. After this
+ *                  function is called, lower layer will invoke esp_hf_client_outgoing_data_cb_t to fetch data.
+ *
+ *                  As a precondition to use this API, Service Level Connection shall exist with AG.
+ *
+ */
+void esp_hf_client_outgoing_data_ready(void);
+
+#ifdef __cplusplus
+}
+#endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_hf_defs.h b/lib/bt/host/bluedroid/api/include/api/esp_hf_defs.h
index b7671ff1..e6ca2e70 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_hf_defs.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_hf_defs.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -13,6 +13,18 @@
 extern "C" {
 #endif
 
+typedef uint16_t esp_hf_sync_conn_hdl_t;
+
+/// profile states
+typedef enum {
+    ESP_HF_INIT_SUCCESS = 0,                /*!< Indicate init successful */
+    ESP_HF_INIT_ALREADY,                    /*!< Indicate init repeated */
+    ESP_HF_INIT_FAIL,                       /*!< Indicate init fail */
+    ESP_HF_DEINIT_SUCCESS,                  /*!< Indicate deinit successful */
+    ESP_HF_DEINIT_ALREADY,                  /*!< Indicate deinit repeated */
+    ESP_HF_DEINIT_FAIL,                     /*!< Indicate deinit fail */
+} esp_hf_prof_state_t;
+
 /// in-band ring tone state
 typedef enum {
     ESP_HF_IN_BAND_RINGTONE_NOT_PROVIDED = 0,
@@ -128,7 +140,7 @@ typedef enum {
 
 /// +CLCC address type
 typedef enum {
-    ESP_HF_CALL_ADDR_TYPE_UNKNOWN = 0x81,            /*!< unkown address type */
+    ESP_HF_CALL_ADDR_TYPE_UNKNOWN = 0x81,            /*!< unknown address type */
     ESP_HF_CALL_ADDR_TYPE_INTERNATIONAL = 0x91,      /*!< international address */
 } esp_hf_call_addr_type_t;
 
@@ -160,7 +172,7 @@ typedef enum
     ESP_HF_NREC_START
 } esp_hf_nrec_t;
 
-///+CCWA resposne status
+///+CCWA response status
 typedef enum {
     ESP_HF_CALL_WAITING_INACTIVE,
     ESP_HF_CALL_WAITING_ACTIVE,
@@ -239,6 +251,25 @@ typedef enum {
     ESP_HF_CME_NETWORK_NOT_ALLOWED = 32,          /*!< network not allowed --emergency calls only */
 } esp_hf_cme_err_t;
 
+/* Since HFP uses a fixed set of mSBC codec parameters, define it here */
+#define ESP_HF_MSBC_CHANNEL_MODE                "Mono"              /*!< mSBC channel mode */
+#define ESP_HF_MSBC_SAMPLING_RATE               "16 kHz"            /*!< mSBC sampling rate */
+#define ESP_HF_MSBC_ALLOCATION_METHOD           "Loudness"          /*!< mSBC allocation method */
+#define ESP_HF_MSBC_SUBBANDS                    8                   /*!< mSBC subbands */
+#define ESP_HF_MSBC_BLOCK_LENGTH                15                  /*!< mSBC block length */
+#define ESP_HF_MSBC_BITPOOL                     26                  /*!< mSBC bitpool */
+/* frame size after mSBC encoded */
+#define ESP_HF_MSBC_ENCODED_FRAME_SIZE          57                  /*!< mSBC frame size */
+
+/**
+ * @brief HFP audio buffer
+ */
+typedef struct {
+    uint16_t    buff_size;                  /*!< buffer size */
+    uint16_t    data_len;                   /*!< audio data length, data length should not greater than buffer size */
+    uint8_t    *data;                       /*!< pointer to audio data start */
+} esp_hf_audio_buff_t;                      /*!< struct to store audio data */
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_hidd_api.h b/lib/bt/host/bluedroid/api/include/api/esp_hidd_api.h
index a2af1659..f16bbcb0 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_hidd_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_hidd_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -146,6 +146,16 @@ typedef enum {
 } esp_hidd_status_t;
 
 /**
+ * @brief HID device profile status parameters
+ */
+typedef struct {
+    bool hidd_inited;                      /*!< HID device initialization */
+    uint8_t conn_num;                      /*!< Number of connections */
+    uint8_t plug_vc_dev_num;               /*!< Number of plugged virtual cable devices */
+    uint8_t reg_app_num;                   /*!< Number of HID device application registrations */
+} esp_hidd_profile_status_t;
+
+/**
  * @brief HID device callback parameters union
  */
 typedef union {
@@ -335,6 +345,11 @@ esp_err_t esp_bt_hid_device_unregister_app(void);
  *                  called after esp_bt_hid_device_init(). When the operation is complete, the callback function will
  *                  be called with ESP_HIDD_OPEN_EVT.
  *
+ * @note            The connection between the HID Host and the HID Device is established as a virtual cable by default.
+ *                  A new HID Host connection request will only be accepted after the previous HID Host has been
+ *                  explicitly unplugged. For details on disconnection and virtual cable unplugging, please refer to API
+ *                  `esp_bt_hid_device_disconnect` and `esp_bt_hid_device_virtual_cable_unplug`.
+ *
  * @param[in]       bd_addr: Remote host bluetooth device address.
  *
  * @return
@@ -406,6 +421,17 @@ esp_err_t esp_bt_hid_device_report_error(esp_hidd_handshake_error_t error);
  */
 esp_err_t esp_bt_hid_device_virtual_cable_unplug(void);
 
+/**
+ * @brief       This function is used to get the status of hid device
+ *
+ * @param[out]  profile_status - HID device status
+ *
+ * @return
+ *              - ESP_OK: success
+ *              - other: failed
+ */
+esp_err_t esp_bt_hid_device_get_profile_status(esp_hidd_profile_status_t *profile_status);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_hidh_api.h b/lib/bt/host/bluedroid/api/include/api/esp_hidh_api.h
index 46f8a15b..51a0d43f 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_hidh_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_hidh_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  *
@@ -104,7 +104,7 @@ typedef enum {
 typedef enum {
     ESP_HIDH_DEV_ATTR_VIRTUAL_CABLE = 0x0001,           /*!< whether Virtual Cables is supported */
     ESP_HIDH_DEV_ATTR_NORMALLY_CONNECTABLE = 0x0002,    /*!< whether device is in Page Scan mode when there is no active connection */
-    ESP_HIDH_DEV_ATTR_RECONNECT_INITIATE = 0x0004,      /*!< whether the HID device inititates the reconnection process */
+    ESP_HIDH_DEV_ATTR_RECONNECT_INITIATE = 0x0004,      /*!< whether the HID device initiates the reconnection process */
 } esp_hidh_dev_attr_t;
 
 /**
@@ -128,12 +128,21 @@ typedef struct {
     int vendor_id;                            /*!< Device ID information: vendor ID */
     int product_id;                           /*!< Device ID information: product ID */
     int version;                              /*!< Device ID information: version */
-    uint8_t ctry_code;                        /*!< SDP attrbutes of HID devices: HID country code (https://www.usb.org/sites/default/files/hid1_11.pdf) */
-    int dl_len;                               /*!< SDP attrbutes of HID devices: HID device descriptor length */
-    uint8_t dsc_list[BTHH_MAX_DSC_LEN];       /*!< SDP attrbutes of HID devices: HID device descriptor definition */
+    uint8_t ctry_code;                        /*!< SDP attributes of HID devices: HID country code (https://www.usb.org/sites/default/files/hid1_11.pdf) */
+    int dl_len;                               /*!< SDP attributes of HID devices: HID device descriptor length */
+    uint8_t dsc_list[BTHH_MAX_DSC_LEN];       /*!< SDP attributes of HID devices: HID device descriptor definition */
 } esp_hidh_hid_info_t;
 
 /**
+ * @brief HID host profile status parameters
+ */
+typedef struct {
+    bool hidh_inited;                         /*!< HID host initialization */
+    uint8_t conn_num;                         /*!< Number of connections */
+    uint8_t plug_vc_dev_num;                  /*!< Number of plugged virtual cable devices*/
+} esp_hidh_profile_status_t;
+
+/**
  * @brief HID host callback parameters union
  */
 typedef union {
@@ -157,7 +166,7 @@ typedef union {
     struct hidh_open_evt_param {
         esp_hidh_status_t status;                /*!< operation status         */
         esp_hidh_connection_state_t conn_status; /*!< connection status        */
-        bool is_orig;                            /*!< indicate if host intiate the connection        */
+        bool is_orig;                            /*!< indicate if host initiate the connection        */
         uint8_t handle;                          /*!< device handle            */
         esp_bd_addr_t bd_addr;                   /*!< device address           */
     } open;                                      /*!< HIDH callback param of ESP_HIDH_OPEN_EVT */
@@ -475,6 +484,17 @@ esp_err_t esp_bt_hid_host_set_report(esp_bd_addr_t bd_addr, esp_hidh_report_type
  */
 esp_err_t esp_bt_hid_host_send_data(esp_bd_addr_t bd_addr, uint8_t *data, size_t len);
 
+/**
+ * @brief       This function is used to get the status of hid host
+ *
+ * @param[out]  profile_status - HID host status
+ *
+ * @return
+ *              - ESP_OK: success
+ *              - other: failed
+ */
+esp_err_t esp_bt_hid_host_get_profile_status(esp_hidh_profile_status_t *profile_status);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_l2cap_bt_api.h b/lib/bt/host/bluedroid/api/include/api/esp_l2cap_bt_api.h
index f11c932f..982cbdaa 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_l2cap_bt_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_l2cap_bt_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -41,6 +41,14 @@ typedef enum {
 typedef uint32_t esp_bt_l2cap_cntl_flags_t;
 
 /**
+ * @brief L2CAP status parameters
+ */
+typedef struct {
+    bool l2cap_inited;                   /*!< l2cap initialization */
+    uint8_t conn_num;                    /*!< Number of connections */
+} esp_bt_l2cap_protocol_status_t;
+
+/**
  * @brief L2CAP callback function events
  */
 typedef enum {
@@ -51,6 +59,8 @@ typedef enum {
     ESP_BT_L2CAP_START_EVT                = 18,     /*!< When L2CAP server started, the event comes */
     ESP_BT_L2CAP_CL_INIT_EVT              = 19,     /*!< When L2CAP client initiated a connection, the event comes */
     ESP_BT_L2CAP_SRV_STOP_EVT             = 36,     /*!< When L2CAP server stopped, the event comes */
+    ESP_BT_L2CAP_VFS_REGISTER_EVT         = 38,     /*!< When L2CAP VFS register, the event comes */
+    ESP_BT_L2CAP_VFS_UNREGISTER_EVT       = 39,     /*!< When L2CAP VFS unregister, the event comes */
 } esp_bt_l2cap_cb_event_t;
 
 /**
@@ -114,9 +124,23 @@ typedef union {
      */
     struct l2cap_srv_stop_evt_param {
         esp_bt_l2cap_status_t  status;         /*!< status */
-        uint8_t                psm;            /*!< local psm */
+        uint16_t               psm;            /*!< local psm */
     } srv_stop;                                /*!< L2CAP callback param of ESP_BT_L2CAP_SRV_STOP_EVT */
 
+    /**
+     * @brief ESP_BT_L2CAP_VFS_REGISTER_EVT
+     */
+    struct l2cap_vfs_register_evt_param {
+        esp_bt_l2cap_status_t    status;       /*!< status */
+    } vfs_register;                            /*!< L2CAP callback param of ESP_BT_L2CAP_VFS_REGISTER_EVT */
+
+    /**
+     * @brief ESP_BT_L2CAP_VFS_UNREGISTER_EVT
+     */
+    struct l2cap_vfs_unregister_evt_param {
+        esp_bt_l2cap_status_t    status;        /*!< status */
+    } vfs_unregister;                           /*!< L2CAP callback param of ESP_BT_L2CAP_VFS_UNREGISTER_EVT */
+
 } esp_bt_l2cap_cb_param_t;
 
 /**
@@ -226,6 +250,7 @@ esp_err_t esp_bt_l2cap_stop_srv(uint16_t local_psm);
 /**
  * @brief       This function is used to register VFS.
  *              Only supports write, read and close.
+ *              When the operation is completed, the callback function will be called with ESP_BT_L2CAP_VFS_REGISTER_EVT.
  *              This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().
  *
  * @return
@@ -236,6 +261,7 @@ esp_err_t esp_bt_l2cap_vfs_register(void);
 
 /**
  * @brief       This function is used to unregister VFS.
+ *              When the operation is completed, the callback function will be called with ESP_BT_L2CAP_VFS_UNREGISTER_EVT.
  *              This function must be called after esp_bt_l2cap_init() successful and before esp_bt_l2cap_deinit().
  *
  * @return
@@ -244,6 +270,17 @@ esp_err_t esp_bt_l2cap_vfs_register(void);
  */
 esp_err_t esp_bt_l2cap_vfs_unregister(void);
 
+/**
+ * @brief       This function is used to get the status of L2CAP
+ *
+ * @param[out]  status - l2cap status
+ *
+ * @return
+ *              - ESP_OK: success
+ *              - other: failed
+ */
+esp_err_t esp_bt_l2cap_get_protocol_status(esp_bt_l2cap_protocol_status_t *status);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_pba_defs.h b/lib/bt/host/bluedroid/api/include/api/esp_pba_defs.h
new file mode 100644
index 00000000..c3a6f510
--- /dev/null
+++ b/lib/bt/host/bluedroid/api/include/api/esp_pba_defs.h
@@ -0,0 +1,27 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_bt_defs.h"
+
+/* Supported repositories bit mask */
+#define ESP_PBA_SUPPORTED_REPO_LOCAL_PHONE_BOOK             0x01
+#define ESP_PBA_SUPPORTED_REPO_SIM_CARD                     0x02
+#define ESP_PBA_SUPPORTED_REPO_SPEED_DIAL                   0x04
+#define ESP_PBA_SUPPORTED_REPO_FAVORITES                    0x08
+
+/* Supported features bit mask */
+#define ESP_PBA_SUPPORTED_FEAT_DOWNLOAD                     0x0001
+#define ESP_PBA_SUPPORTED_FEAT_BROWSING                     0x0002
+#define ESP_PBA_SUPPORTED_FEAT_DATABASE_IDENTIFIER          0x0004
+#define ESP_PBA_SUPPORTED_FEAT_FOLDER_VERSION_COUNTERS      0x0008
+#define ESP_PBA_SUPPORTED_FEAT_VCARD_SELECTING              0x0010
+#define ESP_PBA_SUPPORTED_FEAT_ENHANCED_MISSED_CALLS        0x0020
+#define ESP_PBA_SUPPORTED_FEAT_X_BT_UCI_VCARD_PROPERTY      0x0040
+#define ESP_PBA_SUPPORTED_FEAT_X_BT_UID_VCARD_PROPERTY      0x0080
+#define ESP_PBA_SUPPORTED_FEAT_CONTACT_REFERENCING          0x0100
+#define ESP_PBA_SUPPORTED_FEAT_DEFAULT_CONTACT_IMAGE_FORMAT 0x0200
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_pbac_api.h b/lib/bt/host/bluedroid/api/include/api/esp_pbac_api.h
new file mode 100644
index 00000000..131d53f8
--- /dev/null
+++ b/lib/bt/host/bluedroid/api/include/api/esp_pbac_api.h
@@ -0,0 +1,340 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_err.h"
+#include "esp_bt_defs.h"
+#include "esp_pba_defs.h"
+
+#define ESP_PBAC_INVALID_HANDLE     0               /*!< invalid handle value */
+
+typedef uint16_t esp_pbac_conn_hdl_t;
+
+/**
+ * @brief PBA client callback events
+ */
+typedef enum {
+    ESP_PBAC_INIT_EVT,                              /*!< PBA client initialized event */
+    ESP_PBAC_DEINIT_EVT,                            /*!< PBA client de-initialized event */
+    ESP_PBAC_CONNECTION_STATE_EVT,                  /*!< PBA client connection state changed event */
+    ESP_PBAC_PULL_PHONE_BOOK_RESPONSE_EVT,          /*!< Response of pull phone book */
+    ESP_PBAC_SET_PHONE_BOOK_RESPONSE_EVT,           /*!< Response of set phone book */
+    ESP_PBAC_PULL_VCARD_LISTING_RESPONSE_EVT,       /*!< Response of pull vCard listing */
+    ESP_PBAC_PULL_VCARD_ENTRY_RESPONSE_EVT,         /*!< Response of pull vCard entry */
+} esp_pbac_event_t;
+
+/**
+ * @brief PBA client status code
+ */
+typedef enum {
+    ESP_PBAC_SUCCESS = 0,                           /*!< Operation success */
+    ESP_PBAC_FAILURE,                               /*!< Generic failure */
+    ESP_PBAC_ALREADY_CONN,                          /*!< Connection to peer device already exist */
+    ESP_PBAC_NO_RESOURCE,                           /*!< No more resource */
+    ESP_PBAC_SDP_FAIL,                              /*!< Connection failed in SDP */
+    ESP_PBAC_GOEP_FAIL,                             /*!< Operation failed in GOEP */
+    ESP_PBAC_AUTH_FAIL,                             /*!< Connection failed in OBEX authentication */
+    ESP_PBAC_DEINIT,                                /*!< Connection closed due to pba client is deinit */
+
+    /* these error code is related to OBEX */
+    ESP_PBAC_BAD_REQUEST            = 0xC0,         /*!< Server couldn't understand request */
+    ESP_PBAC_UNAUTHORIZED           = 0xC1,         /*!< Unauthorized */
+    ESP_PBAC_FORBIDDEN              = 0xC3,         /*!< Operation is understood but refused */
+    ESP_PBAC_NOT_FOUND              = 0xC4,         /*!< Not found */
+    ESP_PBAC_NOT_ACCEPTABLE         = 0xC6,         /*!< Not Acceptable */
+    ESP_PBAC_PRECONDITION_FAILED    = 0xCC,         /*!< Precondition failed */
+    ESP_PBAC_NOT_IMPLEMENTED        = 0xD1,         /*!< Not implemented */
+    ESP_PBAC_SERVICE_UNAVAILABLE    = 0xD3,         /*!< Service unavailable */
+} esp_pbac_status_t;
+
+/**
+ * @brief PBA client set phone book flags
+ */
+typedef enum {
+    ESP_PBAC_SET_PHONE_BOOK_FLAGS_ROOT = 0x02,          /*!< Go back to root, name should set to empty string, not NULL */
+    ESP_PBAC_SET_PHONE_BOOK_FLAGS_DOWN = 0x02,          /*!< Go down 1 level, name should set to child folder */
+    ESP_PBAC_SET_PHONE_BOOK_FLAGS_UP = 0x03,            /*!< Go up 1 level, name is optional */
+} esp_pbac_set_phone_book_flags_t;
+
+/**
+ * @brief PBA client pull phone book optional application parameter
+ */
+typedef struct {
+    uint8_t include_property_selector       : 1;        /*!< 1 if app param include property_selector */
+    uint8_t include_format                  : 1;        /*!< 1 if app param include format */
+    uint8_t include_max_list_count          : 1;        /*!< 1 if app param include max_list_count */
+    uint8_t include_list_start_offset       : 1;        /*!< 1 if app param include list_start_offset */
+    uint8_t include_reset_new_missed_calls  : 1;        /*!< 1 if app param include reset_new_missed_calls */
+    uint8_t include_vcard_selector          : 1;        /*!< 1 if app param include vcard_selector */
+    uint8_t include_vcard_selector_operator : 1;        /*!< 1 if app param include vcard_selector_operator */
+    uint8_t format;                                     /*!< 0x00 = 2.1, 0x01 = 3.0 */
+    uint8_t reset_new_missed_calls;                     /*!< 0x01 = Reset */
+    uint8_t vcard_selector_operator;                    /*!< 0x00 = OR, 0x01 = AND */
+    uint16_t max_list_count;                            /*!< 0x0000 to 0xFFFF */
+    uint16_t list_start_offset;                         /*!< 0x0000 to 0xFFFF */
+    uint64_t property_selector;                         /*!< 64 bits mask */
+    uint64_t vcard_selector;                            /*!< 64 bits mask */
+} esp_pbac_pull_phone_book_app_param_t;
+
+/**
+ * @brief PBA client pull vCard listing optional application parameter
+ */
+typedef struct {
+    uint8_t include_order                   : 1;        /*!< 1 if app param include order */
+    uint8_t include_search_value            : 1;        /*!< 1 if app param include search_value */
+    uint8_t include_search_property         : 1;        /*!< 1 if app param include search_property */
+    uint8_t include_max_list_count          : 1;        /*!< 1 if app param include max_list_count */
+    uint8_t include_list_start_offset       : 1;        /*!< 1 if app param include list_start_offset */
+    uint8_t include_reset_new_missed_calls  : 1;        /*!< 1 if app param include reset_new_missed_calls */
+    uint8_t include_vcard_selector          : 1;        /*!< 1 if app param include vcard_selector */
+    uint8_t include_vcard_selector_operator : 1;        /*!< 1 if app param include vcard_selector_operator */
+    uint8_t order;                                      /*!< 0x00 = indexed, 0x01 = alphanumeric */
+    uint8_t search_property;                            /*!< 0x00 = Name, 0x01 = Number, 0x02 = Sound */
+    uint8_t reset_new_missed_calls;                     /*!< 0x01 = Reset */
+    uint8_t vcard_selector_operator;                    /*!< 0x00 = OR, 0x01 = AND */
+    uint16_t max_list_count;                            /*!< 0x0000 to 0xFFFF */
+    uint16_t list_start_offset;                         /*!< 0x0000 to 0xFFFF */
+    char *search_value;                                 /*!< Text */
+    uint64_t vcard_selector;                            /*!< 64 bits mask */
+} esp_pbac_pull_vcard_listing_app_param_t;
+
+/**
+ * @brief PBA client pull vCard entry optional application parameter
+ */
+typedef struct {
+    uint8_t include_property_selector : 1;              /*!< 1 if app param include property_selector */
+    uint8_t include_format            : 1;              /*!< 1 if app param include format */
+    uint8_t format;                                     /*!< 0x00 = 2.1, 0x01 = 3.0 */
+    uint64_t property_selector;                         /*!< 64 bits mask */
+} esp_pbac_pull_vcard_entry_app_param_t;
+
+/**
+ * @brief PBA client callback parameters
+ */
+typedef union {
+    /**
+     * @brief  ESP_PBAC_CONNECTION_STATE_EVT
+     */
+    struct pbac_conn_stat_param {
+        bool connected;                                 /*!< whether pba client is connected to server */
+        esp_pbac_conn_hdl_t handle;                     /*!< connection handle, non zeros if exist */
+        uint8_t peer_supported_repo;                    /*!< peer supported repositories */
+        uint32_t peer_supported_feat;                   /*!< peer supported features */
+        esp_bd_addr_t remote_bda;                       /*!< remote bluetooth device address */
+        esp_pbac_status_t reason;                       /*!< reason if disconnect */
+    } conn_stat;                                        /*!< PBA client connection status */
+
+    /**
+     * @brief  ESP_PBAC_PULL_PHONE_BOOK_RESPONSE_EVT
+     */
+    struct pbac_pull_phone_book_rsp_param {
+        esp_pbac_conn_hdl_t handle;                                 /*!< PBA client connection handle */
+        esp_pbac_status_t result;                                   /*!< operation result, ESP_PBAC_SUCCESS if success */
+        bool final;                                                 /*!< whether this is the final response packet */
+        uint8_t *data;                                              /*!< response data */
+        uint16_t data_len;                                          /*!< response data len */
+        /* The following are the application parameters */
+        uint8_t include_phone_book_size          : 1;               /*!< 1 if app param include phone_book_size */
+        uint8_t include_new_missed_calls         : 1;               /*!< 1 if app param include new_missed_calls */
+        uint8_t include_primary_folder_version   : 1;               /*!< 1 if app param include primary_folder_version */
+        uint8_t include_secondary_folder_version : 1;               /*!< 1 if app param include secondary_folder_version */
+        uint8_t include_database_identifier      : 1;               /*!< 1 if app param include database_identifier */
+        uint8_t new_missed_calls;                                   /*!< 0x00 to 0xFF */
+        uint16_t phone_book_size;                                   /*!< 0x0000 to 0xFFFF */
+        uint8_t *primary_folder_version;                            /*!< 0 to (2^128 -1) */
+        uint8_t *secondary_folder_version;                          /*!< 0 to (2^128 -1) */
+        uint8_t *database_identifier;                               /*!< 0 to (2^128 -1) */
+    } pull_phone_book_rsp;                                          /*!< pull phone book response */
+
+    /**
+     * @brief  ESP_PBAC_SET_PHONE_BOOK_RESPONSE_EVT
+     */
+    struct pbac_set_phone_book_rsp_param {
+        esp_pbac_conn_hdl_t handle;                                 /*!< PBA client connection handle */
+        esp_pbac_status_t result;                                   /*!< operation result, ESP_PBAC_SUCCESS if success */
+    } set_phone_book_rsp;                                           /*!< set phone book response, always the final response */
+
+    /**
+     * @brief  ESP_PBAC_PULL_VCARD_LISTING_RESPONSE_EVT
+     */
+    struct pbac_pull_vcard_listing_rsp_param {
+        esp_pbac_conn_hdl_t handle;                                     /*!< PBA client connection handle */
+        esp_pbac_status_t result;                                       /*!< operation result, ESP_PBAC_SUCCESS if success */
+        bool final;                                                     /*!< whether this is the final response packet */
+        uint8_t *data;                                                  /*!< response data */
+        uint16_t data_len;                                              /*!< response data len */
+        /* The following are the application parameters */
+        uint8_t include_phone_book_size          : 1;                   /*!< 1 if app param include phone_book_size */
+        uint8_t include_new_missed_calls         : 1;                   /*!< 1 if app param include new_missed_calls */
+        uint8_t include_primary_folder_version   : 1;                   /*!< 1 if app param include primary_folder_version */
+        uint8_t include_secondary_folder_version : 1;                   /*!< 1 if app param include secondary_folder_version */
+        uint8_t include_database_identifier      : 1;                   /*!< 1 if app param include database_identifier */
+        uint8_t new_missed_calls;                                       /*!< 0x00 to 0xFF */
+        uint16_t phone_book_size;                                       /*!< 0x0000 to 0xFFFF */
+        uint8_t *primary_folder_version;                                /*!< 0 to (2^128 -1) */
+        uint8_t *secondary_folder_version;                              /*!< 0 to (2^128 -1) */
+        uint8_t *database_identifier;                                   /*!< 0 to (2^128 -1) */
+    } pull_vcard_listing_rsp;                                           /*!< pull vcard listing response */
+
+    /**
+     * @brief  ESP_PBAC_PULL_VCARD_ENTRY_RESPONSE_EVT
+     */
+    struct pbac_pull_vcard_entry_rsp_param {
+        esp_pbac_conn_hdl_t handle;                                     /*!< PBA client connection handle */
+        esp_pbac_status_t result;                                       /*!< operation result, ESP_PBAC_SUCCESS if success */
+        bool final;                                                     /*!< whether this is the final response packet */
+        uint8_t *data;                                                  /*!< response data */
+        uint16_t data_len;                                              /*!< response data len */
+        /* The following are the application parameters */
+        uint8_t include_database_identifier : 1;                        /*!< 1 if app param include database_identifier */
+        uint8_t *database_identifier;                                   /*!< 0 to (2^128 -1) */
+    } pull_vcard_entry_rsp;                                             /*!< pull vcard listing response */
+} esp_pbac_param_t;
+
+/**
+ * @brief           PBA client callback function type
+ *
+ * @param           event : Event type
+ *
+ * @param           param : Pointer to callback parameter
+ */
+typedef void (*esp_pbac_callback_t)(esp_pbac_event_t event, esp_pbac_param_t *param);
+
+
+/**
+ * @brief           This function is called to register a user callbacks in PBA client.
+ *
+ * @param[in]       callback: pointer to the user callback function.
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - other: failed
+ */
+esp_err_t esp_pbac_register_callback(esp_pbac_callback_t callback);
+
+/**
+ * @brief           Initializes PBA client interface. This function should be called after bluedroid
+ *                  enable successfully, and should be called after esp_pbac_register_callback.
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - other: failed
+ */
+esp_err_t esp_pbac_init(void);
+
+/**
+ * @brief           De-initializes PBA client interface. This will close all PBA client connection.
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - other: failed
+ */
+esp_err_t esp_pbac_deinit(void);
+
+/**
+ * @brief           Start the process to establish a connection to PBA server.
+ *
+ * @param[in]       bd_addr: peer bluetooth device address
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - other: failed
+ */
+esp_err_t esp_pbac_connect(esp_bd_addr_t bd_addr);
+
+/**
+ * @brief           Disconnects from the current connected PBA server.
+ *
+ * @param[in]       handle: connection handle retrieved from ESP_PBAC_CONNECTION_STATE_EVT
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - other: failed
+ */
+esp_err_t esp_pbac_disconnect(esp_pbac_conn_hdl_t handle);
+
+/**
+ * @brief           Send a request to pull phone book.
+ *
+ * @param[in]       handle: connection handle retrieved from ESP_PBAC_CONNECTION_STATE_EVT
+ *
+ * @param[in]       name: phone book object path and name, shall contain the absolute path
+ *                        in the virtual folder architecture
+ *
+ * @param[in]       app_param: optional application parameter
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - other: failed
+ */
+esp_err_t esp_pbac_pull_phone_book(esp_pbac_conn_hdl_t handle, const char *name, esp_pbac_pull_phone_book_app_param_t *app_param);
+
+/**
+ * @brief           Send a request to set the current folder in the virtual folder architecture.
+ *
+ * @param[in]       handle: connection handle retrieved from ESP_PBAC_CONNECTION_STATE_EVT
+ *
+ * @param[in]       flags: operation flags, one of ESP_PBAC_SET_PHONE_BOOK_FLAGS_XXX
+ *
+ * @param[in]       name: folder name, if flags is set to ROOT, name should be empty string (""),
+ *                        if flags is set to UP, name is optional, if flags is set to DOWN, name
+ *                        is mandatory
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - other: failed
+ */
+esp_err_t esp_pbac_set_phone_book(esp_pbac_conn_hdl_t handle, esp_pbac_set_phone_book_flags_t flags, const char *name);
+
+/**
+ * @brief           Set the current folder in the virtual folder architecture, use absolute path.
+ *
+ * @param[in]       handle: connection handle retrieved from ESP_PBAC_CONNECTION_STATE_EVT
+ *
+ * @param[in]       path: absolute path of the folder intend to set. NULL or empty string will
+ *                  set to ROOT
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - other: failed
+ */
+esp_err_t esp_pbac_set_phone_book2(esp_pbac_conn_hdl_t handle, const char *path);
+
+/**
+ * @brief           Send a request to pull vCard listing.
+ *
+ * @param[in]       handle: connection handle retrieved from ESP_PBAC_CONNECTION_STATE_EVT
+ *
+ * @param[in]       name: specifies the name of the folder to be retrieved, uses relative paths,
+ *                        shall not include any path information. An empty name (empty string "")
+ *                        may be sent to retrieve the vCard Listing object of the current folder.
+ *                        However, it is illegal to issue a pull vCard listing request with an
+ *                        empty name header from the ‘telecom/’ folder
+ *
+ * @param[in]       app_param: optional application parameter
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - other: failed
+ */
+esp_err_t esp_pbac_pull_vcard_listing(esp_pbac_conn_hdl_t handle, const char *name, esp_pbac_pull_vcard_listing_app_param_t *app_param);
+
+/**
+ * @brief           Send a request to pull vCard entry.
+ *
+ * @param[in]       handle: connection handle retrieved from ESP_PBAC_CONNECTION_STATE_EVT
+ *
+ * @param[in]       name: vCard name or, if supported, the X-BT-UID of the object to be retrieved.
+ *                        uses relative paths,shall not include any path information
+ *
+ * @param[in]       app_param: optional application parameter
+ *
+ * @return
+ *                  - ESP_OK: success
+ *                  - other: failed
+ */
+esp_err_t esp_pbac_pull_vcard_entry(esp_pbac_conn_hdl_t handle, const char *name, esp_pbac_pull_vcard_entry_app_param_t *app_param);
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_sdp_api.h b/lib/bt/host/bluedroid/api/include/api/esp_sdp_api.h
index 14741e74..956af037 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_sdp_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_sdp_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2022 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -14,123 +14,173 @@
 extern "C" {
 #endif
 
-#define ESP_SDP_SERVER_NAME_MAX 32                 /*!< Service name max length */
-#define SDP_OPP_SUPPORTED_FORMATS_MAX_LENGTH 15    /*!< OPP supported format list maximum length */
+#define ESP_SDP_SERVER_NAME_MAX              32  /*!< Service name max length */
+#define SDP_OPP_SUPPORTED_FORMATS_MAX_LENGTH 15  /*!< OPP supported format list maximum length */
+
+#define ESP_SDP_UUID_MAP_MAS  0x1132 /*!< Message Access Service UUID */
+#define ESP_SDP_UUID_MAP_MNS  0x1133 /*!< Message Notification Service UUID */
+#define ESP_SDP_UUID_PBAP_PSE 0x112F /*!< Phone Book Server Equipment UUID */
+#define ESP_SDP_UUID_PBAP_PCE 0x112E /*!< Phone Book Client Equipment UUID */
+#define ESP_SDP_UUID_OPP      0x1105 /*!< Object Push Profile UUID */
+#define ESP_SDP_UUID_SAP      0x112D /*!< SIM Access Profile UUID */
+#define ESP_SDP_UUID_DIP      0x1200 /*!< Device Identification Profile UUID */
+
+#define ESP_SDP_BUILD_BT_UUID16(uuid16_val)                                                                                \
+    (esp_bt_uuid_t) { .len = ESP_UUID_LEN_16, .uuid = {.uuid16 = (uint16_t)(uuid16_val),}, }
 
 typedef enum {
-    ESP_SDP_SUCCESS   = 0,          /*!< Successful operation. */
-    ESP_SDP_FAILURE,                /*!< Generic failure. */
-    ESP_SDP_NO_RESOURCE,            /*!< No more resource */
-    ESP_SDP_NEED_INIT,              /*!< SDP module shall init first */
-    ESP_SDP_NEED_DEINIT,            /*!< SDP module shall deinit first */
-    ESP_SDP_NO_CREATE_RECORD,       /*!< No record created */
+    ESP_SDP_SUCCESS = 0,      /*!< Successful operation. */
+    ESP_SDP_FAILURE,          /*!< Generic failure. */
+    ESP_SDP_NO_RESOURCE,      /*!< No more resource */
+    ESP_SDP_NEED_INIT,        /*!< SDP module shall init first */
+    ESP_SDP_NEED_DEINIT,      /*!< SDP module shall deinit first */
+    ESP_SDP_NO_CREATE_RECORD, /*!< No record created */
 } esp_sdp_status_t;
 
 /**
+ * @brief SDP protocol status parameters
+ */
+typedef struct {
+    bool sdp_inited;                   /*!< SDP initialization */
+    uint8_t records_num;               /*!< Number of created records */
+} esp_sdp_protocol_status_t;
+
+/**
  * @brief SDP callback function events
  */
 typedef enum {
-    ESP_SDP_INIT_EVT                    = 0,                /*!< When SDP is initialized, the event comes */
-    ESP_SDP_DEINIT_EVT                  = 1,                /*!< When SDP is deinitialized, the event comes */
-    ESP_SDP_SEARCH_COMP_EVT             = 2,                /*!< When SDP search complete, the event comes */
-    ESP_SDP_CREATE_RECORD_COMP_EVT      = 3,                /*!< When create SDP records complete, the event comes */
-    ESP_SDP_REMOVE_RECORD_COMP_EVT      = 4,                /*!< When remove a SDP record complete, the event comes */
+    ESP_SDP_INIT_EVT               = 0, /*!< When SDP is initialized, the event comes */
+    ESP_SDP_DEINIT_EVT             = 1, /*!< When SDP is de-initialized, the event comes */
+    ESP_SDP_SEARCH_COMP_EVT        = 2, /*!< When SDP search complete, the event comes */
+    ESP_SDP_CREATE_RECORD_COMP_EVT = 3, /*!< When create SDP records complete, the event comes */
+    ESP_SDP_REMOVE_RECORD_COMP_EVT = 4, /*!< When remove a SDP record complete, the event comes */
 } esp_sdp_cb_event_t;
 
 /**
  * @brief SDP record type
  */
 typedef enum {
-    ESP_SDP_TYPE_RAW,          /*!< Used to carry raw SDP search data for unknown UUIDs */
-    ESP_SDP_TYPE_MAP_MAS,      /*!< Message Access Profile - Server */
-    ESP_SDP_TYPE_MAP_MNS,      /*!< Message Access Profile - Client (Notification Server) */
-    ESP_SDP_TYPE_PBAP_PSE,     /*!< Phone Book Profile - Server */
-    ESP_SDP_TYPE_PBAP_PCE,     /*!< Phone Book Profile - Client */
-    ESP_SDP_TYPE_OPP_SERVER,   /*!< Object Push Profile */
-    ESP_SDP_TYPE_SAP_SERVER    /*!< SIM Access Profile */
+    ESP_SDP_TYPE_RAW,        /*!< Used to carry raw SDP search data for unknown UUIDs */
+    ESP_SDP_TYPE_MAP_MAS,    /*!< Message Access Profile - Server */
+    ESP_SDP_TYPE_MAP_MNS,    /*!< Message Access Profile - Client (Notification Server) */
+    ESP_SDP_TYPE_PBAP_PSE,   /*!< Phone Book Profile - Server */
+    ESP_SDP_TYPE_PBAP_PCE,   /*!< Phone Book Profile - Client */
+    ESP_SDP_TYPE_OPP_SERVER, /*!< Object Push Profile */
+    ESP_SDP_TYPE_SAP_SERVER, /*!< SIM Access Profile */
+    ESP_SDP_TYPE_DIP_SERVER, /*!< Device Identification Profile */
 } esp_bluetooth_sdp_types_t;
 
 /**
- * @brief Some signals need additional pointers, hence we introduce a
- *        generic way to handle these pointers.
+ * @brief SDP header structure
  */
 typedef struct bluetooth_sdp_hdr_overlay {
-    esp_bluetooth_sdp_types_t type;            /*!< SDP type */
-    esp_bt_uuid_t  uuid;                       /*!< UUID type， include uuid and uuid length */
-    uint32_t       service_name_length;        /*!< Service name length */
-    char          *service_name;               /*!< service name */
-    int32_t        rfcomm_channel_number;      /*!< rfcomm channel number, if not used set to -1*/
-    int32_t        l2cap_psm;                  /*!< l2cap psm, if not used set to -1 */
-    int32_t        profile_version;            /*!< profile version */
-
-    // User pointers, only used for some signals - see esp_bluetooth_sdp_ops_record_t
-    int            user1_ptr_len;              /*!< see esp_bluetooth_sdp_ops_record_t */
-    uint8_t       *user1_ptr;                  /*!< see esp_bluetooth_sdp_ops_record_t */
-    int            user2_ptr_len;              /*!< see esp_bluetooth_sdp_ops_record_t */
-    uint8_t       *user2_ptr;                  /*!< see esp_bluetooth_sdp_ops_record_t */
+    esp_bluetooth_sdp_types_t type;                 /*!< SDP type */
+    esp_bt_uuid_t uuid;                             /*!< UUID type, include uuid and uuid length, only needed to be set for RAW record creation */
+    uint32_t service_name_length;                   /*!< Service name length */
+    char *service_name;                             /*!< Service name */
+    int32_t rfcomm_channel_number;                  /*!< RFCOMM channel number, if not used set to -1*/
+    int32_t l2cap_psm;                              /*!< L2CAP psm, if not used set to -1 */
+    int32_t profile_version;                        /*!< Profile version */
+    int user1_ptr_len;                              /*!< User data1 length, only used for searching RAW record */
+    uint8_t *user1_ptr;                             /*!< User data1 pointer to the raw SDP response data, only used for searching RAW record */
+    int user2_ptr_len __attribute__((deprecated));  /*!< User data2 length, only used for searching RAW record */
+    uint8_t *user2_ptr __attribute__((deprecated)); /*!< User data2 pointer, only used for searching RAW record */
 } esp_bluetooth_sdp_hdr_overlay_t;
 
 /**
+ * @brief Raw SDP record
+ */
+typedef struct bluetooth_sdp_raw_record {
+    esp_bluetooth_sdp_hdr_overlay_t hdr; /*!< General info */
+} esp_bluetooth_sdp_raw_record_t;
+
+/**
  * @brief Message Access Profile - Server parameters
  */
 typedef struct bluetooth_sdp_mas_record {
-    esp_bluetooth_sdp_hdr_overlay_t hdr;       /*!< General info */
-    uint32_t    mas_instance_id;               /*!< MAS Instance ID */
-    uint32_t    supported_features;            /*!< Map supported features */
-    uint32_t    supported_message_types;       /*!< Supported message types */
+    esp_bluetooth_sdp_hdr_overlay_t hdr; /*!< General info */
+    uint32_t mas_instance_id;            /*!< MAS Instance ID */
+    uint32_t supported_features;         /*!< Map supported features */
+    uint32_t supported_message_types;    /*!< Supported message types */
 } esp_bluetooth_sdp_mas_record_t;
 
 /**
  * @brief Message Access Profile - Client (Notification Server) parameters
  */
 typedef struct bluetooth_sdp_mns_record {
-    esp_bluetooth_sdp_hdr_overlay_t hdr;       /*!< General info */
-    uint32_t    supported_features;            /*!< Supported features */
+    esp_bluetooth_sdp_hdr_overlay_t hdr; /*!< General info */
+    uint32_t supported_features;         /*!< Supported features */
 } esp_bluetooth_sdp_mns_record_t;
 
 /**
  * @brief Phone Book Profile - Server parameters
  */
 typedef struct bluetooth_sdp_pse_record {
-    esp_bluetooth_sdp_hdr_overlay_t hdr;       /*!< General info */
-    uint32_t    supported_features;            /*!< Pbap Supported Features */
-    uint32_t    supported_repositories;        /*!< Supported Repositories */
+    esp_bluetooth_sdp_hdr_overlay_t hdr; /*!< General info */
+    uint32_t supported_features;         /*!< PBAP Supported Features */
+    uint32_t supported_repositories;     /*!< Supported Repositories */
 } esp_bluetooth_sdp_pse_record_t;
 
 /**
  * @brief Phone Book Profile - Client parameters
  */
 typedef struct bluetooth_sdp_pce_record {
-    esp_bluetooth_sdp_hdr_overlay_t hdr;       /*!< General info */
+    esp_bluetooth_sdp_hdr_overlay_t hdr; /*!< General info */
 } esp_bluetooth_sdp_pce_record_t;
 
 /**
  * @brief Object Push Profile parameters
  */
 typedef struct bluetooth_sdp_ops_record {
-    esp_bluetooth_sdp_hdr_overlay_t hdr;       /*!< General info */
-    int         supported_formats_list_len;    /*!< Supported formats list length */
-    uint8_t     supported_formats_list[SDP_OPP_SUPPORTED_FORMATS_MAX_LENGTH];  /*!< Supported formats list */
+    esp_bluetooth_sdp_hdr_overlay_t hdr;                                  /*!< General info */
+    int supported_formats_list_len;                                       /*!< Supported formats list length */
+    uint8_t supported_formats_list[SDP_OPP_SUPPORTED_FORMATS_MAX_LENGTH]; /*!< Supported formats list */
 } esp_bluetooth_sdp_ops_record_t;
 
 /**
  * @brief SIM Access Profile parameters
  */
 typedef struct bluetooth_sdp_sap_record {
-    esp_bluetooth_sdp_hdr_overlay_t hdr;       /*!< General info */
+    esp_bluetooth_sdp_hdr_overlay_t hdr; /*!< General info */
 } esp_bluetooth_sdp_sap_record_t;
 
 /**
+ * @brief Vendor ID source
+ */
+typedef enum {
+    ESP_SDP_VENDOR_ID_SRC_BT  = 1, /*!< Bluetooth assigned vendor id source */
+    ESP_SDP_VENDOR_ID_SRC_USB = 2, /*!< USB assigned vendor id source */
+} esp_sdp_vendor_id_source_t;
+
+/**
+ * @brief Device Identification Profile parameters
+ *
+ * @note Only one primary Device Identification service record can be added in the SDP database. If primary
+ * Device Identification service is created multiple times, only the last one will take effect.
+ */
+typedef struct bluetooth_sdp_dip_record {
+    esp_bluetooth_sdp_hdr_overlay_t hdr; /*!< General info */
+    uint16_t vendor;                     /*!< Vendor ID */
+    uint16_t vendor_id_source;           /*!< Vendor ID source, 0x0001 for Bluetooth, 0x0002 for USB, other values reserved, see `esp_sdp_vendor_id_source_t` */
+    uint16_t product;                    /*!< Product ID */
+    uint16_t version;                    /*!< Release version in format 0xJJMN(JJ – major number, M – minor number, N – sub-minor number) */
+    bool primary_record;                 /*!< Indicate if the record is primary, shall set to true if there is a only single device
+                                            record, others shall be set to false */
+} esp_bluetooth_sdp_dip_record_t;
+
+/**
  * @brief SDP record parameters union
  */
 typedef union {
-    esp_bluetooth_sdp_hdr_overlay_t   hdr;     /*!< General info */
-    esp_bluetooth_sdp_mas_record_t    mas;     /*!< Message Access Profile - Server */
-    esp_bluetooth_sdp_mns_record_t    mns;     /*!< Message Access Profile - Client (Notification Server) */
-    esp_bluetooth_sdp_pse_record_t    pse;     /*!< Phone Book Profile - Server */
-    esp_bluetooth_sdp_pce_record_t    pce;     /*!< Phone Book Profile - Client */
-    esp_bluetooth_sdp_ops_record_t    ops;     /*!< Object Push Profile */
-    esp_bluetooth_sdp_sap_record_t    sap;     /*!< SIM Access Profile */
+    esp_bluetooth_sdp_hdr_overlay_t hdr; /*!< General info */
+    esp_bluetooth_sdp_raw_record_t raw;  /*!< Raw SDP search data for unknown UUIDs */
+    esp_bluetooth_sdp_mas_record_t mas;  /*!< Message Access Profile - Server */
+    esp_bluetooth_sdp_mns_record_t mns;  /*!< Message Access Profile - Client (Notification Server) */
+    esp_bluetooth_sdp_pse_record_t pse;  /*!< Phone Book Profile - Server */
+    esp_bluetooth_sdp_pce_record_t pce;  /*!< Phone Book Profile - Client */
+    esp_bluetooth_sdp_ops_record_t ops;  /*!< Object Push Profile */
+    esp_bluetooth_sdp_sap_record_t sap;  /*!< SIM Access Profile */
+    esp_bluetooth_sdp_dip_record_t dip;  /*!< Device Identification Profile */
 } esp_bluetooth_sdp_record_t;
 
 /**
@@ -141,44 +191,43 @@ typedef union {
      * @brief ESP_SDP_INIT_EVT
      */
     struct sdp_init_evt_param {
-        esp_sdp_status_t    status;         /*!< status */
-    } init;                                 /*!< SDP callback param of ESP_SDP_INIT_EVT */
+        esp_sdp_status_t status; /*!< Status */
+    } init;                      /*!< SDP callback param of ESP_SDP_INIT_EVT */
 
     /**
      * @brief ESP_SDP_DEINIT_EVT
      */
     struct sdp_deinit_evt_param {
-        esp_sdp_status_t    status;         /*!< status */
-    } deinit;                               /*!< SDP callback param of ESP_SDP_DEINIT_EVT */
+        esp_sdp_status_t status; /*!< Status */
+    } deinit;                    /*!< SDP callback param of ESP_SDP_DEINIT_EVT */
 
     /**
      * @brief ESP_SDP_SEARCH_COMP_EVT
      */
     struct sdp_search_evt_param {
-        esp_sdp_status_t    status;         /*!< status */
-        esp_bd_addr_t       remote_addr;    /*!< remote device address */
-        esp_bt_uuid_t       sdp_uuid;       /*!< service uuid */
-        int                 record_count;   /*!< Number of SDP records */
-        esp_bluetooth_sdp_record_t *records;/*!< SDP records */
-    } search;                               /*!< SDP callback param of ESP_SDP_SEARCH_COMP_EVT */
+        esp_sdp_status_t status;             /*!< Status */
+        esp_bd_addr_t remote_addr;           /*!< Remote device address */
+        esp_bt_uuid_t sdp_uuid;              /*!< Service uuid */
+        int record_count;                    /*!< Number of SDP records */
+        esp_bluetooth_sdp_record_t *records; /*!< SDP records */
+    } search;                                /*!< SDP callback param of ESP_SDP_SEARCH_COMP_EVT */
 
     /**
      * @brief ESP_SDP_CREATE_RECORD_COMP_EVT
      */
-    struct sdp_crate_record_evt_param {
-        esp_sdp_status_t    status;         /*!< status */
-        int                 record_handle;  /*!< SDP record handle */
-    } create_record;                        /*!< SDP callback param of ESP_SDP_CREATE_RECORD_COMP_EVT */
+    struct sdp_create_record_evt_param {
+        esp_sdp_status_t status; /*!< Status */
+        int record_handle;       /*!< SDP record handle */
+    } create_record;             /*!< SDP callback param of ESP_SDP_CREATE_RECORD_COMP_EVT */
 
     /**
      * @brief ESP_SDP_REMOVE_RECORD_COMP_EVT
      */
     struct sdp_remove_record_evt_param {
-        esp_sdp_status_t    status;         /*!< status */
-    } remove_record;                        /*!< SDP callback param of ESP_SDP_REMOVE_RECORD_COMP_EVT */
-
-} esp_sdp_cb_param_t;                       /*!< SDP callback parameter union type */
+        esp_sdp_status_t status; /*!< Status */
+    } remove_record;             /*!< SDP callback param of ESP_SDP_REMOVE_RECORD_COMP_EVT */
 
+} esp_sdp_cb_param_t;
 
 /**
  * @brief       SDP callback function type.
@@ -264,6 +313,17 @@ esp_err_t esp_sdp_create_record(esp_bluetooth_sdp_record_t *record);
  */
 esp_err_t esp_sdp_remove_record(int record_handle);
 
+/**
+ * @brief       This function is used to get the status of SDP
+ *
+ * @param[out]  status - sdp status
+ *
+ * @return
+ *              - ESP_OK: success
+ *              - other: failed
+ */
+esp_err_t esp_sdp_get_protocol_status(esp_sdp_protocol_status_t *status);
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/lib/bt/host/bluedroid/api/include/api/esp_spp_api.h b/lib/bt/host/bluedroid/api/include/api/esp_spp_api.h
index d2a0e090..40788667 100644
--- a/lib/bt/host/bluedroid/api/include/api/esp_spp_api.h
+++ b/lib/bt/host/bluedroid/api/include/api/esp_spp_api.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2015-2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -102,6 +102,13 @@ typedef enum {
     ESP_SPP_VFS_UNREGISTER_EVT          = 37,               /*!< When SPP VFS unregister, the event comes */
 } esp_spp_cb_event_t;
 
+/**
+ * @brief SPP profile status parameters
+ */
+typedef struct {
+    bool spp_inited;                     /*!< spp initialization */
+    uint8_t conn_num;                    /*!< Number of connections */
+} esp_spp_profile_status_t;
 
 /**
  * @brief SPP callback parameters union
@@ -432,6 +439,17 @@ esp_err_t esp_spp_vfs_register(void);
  */
 esp_err_t esp_spp_vfs_unregister(void);
 
+/**
+ * @brief       This function is used to get the status of SPP
+ *
+ * @param[out]  profile_status - SPP status
+ *
+ * @return
+ *              - ESP_OK: success
+ *              - other: failed
+ */
+esp_err_t esp_spp_get_profile_status(esp_spp_profile_status_t *profile_status);
+
 #ifdef __cplusplus
 }
 #endif