diff options
Diffstat (limited to 'lib/bt/host/bluedroid/api/include')
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 |