Mirrors/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-08-18 06:35:35 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'opt/optimize_ble_document' into 'master'

Browse Source 
Opt/optimize ble document

Closes BLERP-2844

See merge request espressif/esp-idf!48819
This commit is contained in:
Island
2026-06-01 19:23:27 +08:00
parent 240a16bd20 4ab49f267b
commit f17466af04
9 changed files with 115 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
components/bt/host/bluedroid/api/esp_gatt_common_api.c
View File

@@ -64,6 +64,9 @@ uint16_t esp_ble_get_sendable_packets_num (void)
/**
* @brief This function is used to query the number of available buffers for the current connection.
* When you need to query the current available buffer number, it is recommended to use this API.
*
* @note This API can only be called when a direct connection exists.
*
* @param[in] conn_id: current connection id.
*
* @return

2
components/bt/host/bluedroid/api/esp_gattc_api.c
View File

@@ -93,7 +93,7 @@ esp_err_t esp_ble_gattc_enh_open(esp_gatt_if_t gattc_if, esp_ble_gatt_creat_conn
memcpy(arg.open.remote_bda, creat_conn_params->remote_bda, ESP_BD_ADDR_LEN);
arg.open.remote_addr_type = creat_conn_params->remote_addr_type;
arg.open.is_direct = creat_conn_params->is_direct;
arg.open.is_aux= creat_conn_params->is_aux;
arg.open.is_aux = creat_conn_params->is_aux;
#if (BT_BLE_FEAT_PAWR_EN == TRUE)
arg.open.is_pawr_synced = false;
arg.open.adv_handle = 0xFF;

2
components/bt/host/bluedroid/api/include/api/esp_bt_defs.h
View File

@@ -210,7 +210,7 @@ typedef uint8_t esp_link_key[ESP_BT_OCTET16_LEN]; /* Link Key */
/// Default GATT interface id
#define ESP_DEFAULT_GATT_IF 0xff
#if BLE_HIGH_DUTY_ADV_INTERVAL
#if CONFIG_BT_BLE_HIGH_DUTY_ADV_INTERVAL
#define ESP_BLE_PRIM_ADV_INT_MIN 0x000008 /*!< Minimum advertising interval for undirected and low duty cycle directed advertising */
#else
#define ESP_BLE_PRIM_ADV_INT_MIN 0x000020 /*!< Minimum advertising interval for undirected and low duty cycle directed advertising */

16
components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h
View File

@@ -984,7 +984,15 @@ typedef struct {
esp_ble_addr_type_t peer_addr_type; /*!< ext adv peer address type */
esp_bd_addr_t peer_addr; /*!< ext adv peer address */
esp_ble_adv_filter_t filter_policy; /*!< ext adv filter policy */
int8_t tx_power; /*!< ext adv tx power */
int8_t tx_power; /*!< ext adv tx power.
For this advertising set, priority is higher than
`esp_ble_tx_power_set()`, `esp_ble_tx_power_set_enhanced()`,
and menuconfig default TX power (`CONFIG_BT_CTRL_DFT_TX_POWER_LEVEL`).
The actual applied TX power may be different from the requested value,
depending on the Controller TX power granularity/level mechanism.
(for example ESP32-C3/ESP32-S3 with 3 dBm step), the actual
applied TX power may be rounded down and be 0 to 2 dBm lower
than the requested value.) */
esp_ble_gap_pri_phy_t primary_phy; /*!< ext adv primary phy */
uint8_t max_skip; /*!< ext adv maximum skip */
esp_ble_gap_phy_t secondary_phy; /*!< ext adv secondary phy.
@@ -2901,7 +2909,11 @@ 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.
* @note Do NOT perform time-consuming operations in the callback. Time-consuming operations
* include: taking semaphores that may block for a long time (e.g. xSemaphoreTake with
* long timeout or portMAX_DELAY), blocking delays (e.g. vTaskDelay), and flash
* read/write/erase. Such operations may block the Bluetooth stack and lead to
* instability or deadlock. Defer heavy work to a separate task if needed.
*
* @return
* - ESP_OK : success

25
components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h
View File

@@ -361,10 +361,15 @@ typedef struct {
/**
* @brief Defines the GATT authentication request types.
*
* This enumeration lists the types of authentication requests that can be made.
* It corresponds to the `BTA_GATT_AUTH_REQ_xxx` values defined in `bta/bta_gatt_api.h`.
* The types include options for no authentication, unauthenticated encryption, authenticated encryption,
* and both signed versions with and without MITM (Man-In-The-Middle) protection.
* Used as the `auth_req` argument in GATT client read/write APIs. It specifies the
* link security level required before the ATT request is sent, and is independent
* of server-side attribute permission flags (`ESP_GATT_PERM_xxx`).
*
* @note If `auth_req` is not `ESP_GATT_AUTH_REQ_NONE`, the stack may start link
* encryption or SMP pairing before the GATT operation. Handle
* `ESP_GAP_BLE_PASSKEY_REQ_EVT` and call `esp_ble_passkey_reply()` if needed.
*
* Corresponds to the `BTA_GATT_AUTH_REQ_xxx` values defined in `bta/bta_gatt_api.h`.
*/
typedef enum {
ESP_GATT_AUTH_REQ_NONE = 0, /*!< No authentication required. Corresponds to BTA_GATT_AUTH_REQ_NONE. */
@@ -687,7 +692,17 @@ 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. */
bool is_aux; /*!< Determines whether to use BLE 5.0 or BLE 4.2 create connection interface.
- If set to true, the BLE 5.0 interface (extended connection) will be used.
- If set to false, the BLE 4.2 interface (legacy connection) will be used.
- Note: When connecting to a legacy advertising device using BLE 5.0 interface, is_aux should be set to true.
- Auto-setting (handled in L2CAP layer): The system will automatically set this parameter based on the enabled BLE features:
* If only BLE 4.2 feature is enabled, is_aux will be automatically set to false.
* If only BLE 5.0 feature is enabled, is_aux will be automatically set to true.
* If both BLE 4.2 and BLE 5.0 features are enabled (not recommended), the stack will automatically
infer whether to use BLE 5.0 or BLE 4.2 interface based on previously used APIs.
Otherwise, the user-specified value will be used.
- Note: It is strongly recommended NOT to enable both BLE 4.2 and BLE 5.0 features simultaneously. */
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 */

30
components/bt/host/bluedroid/api/include/api/esp_gattc_api.h
View File

@@ -280,7 +280,11 @@ typedef void (* esp_gattc_cb_t)(esp_gattc_cb_event_t event, esp_gatt_if_t gattc_
*
* @param[in] callback The pointer to the application callback function
*
* @note Avoid performing time-consuming operations within the callback functions.
* @note Do NOT perform time-consuming operations in the callback. Time-consuming operations
* include: taking semaphores that may block for a long time (e.g. xSemaphoreTake with
* long timeout or portMAX_DELAY), blocking delays (e.g. vTaskDelay), and flash
* read/write/erase. Such operations may block the Bluetooth stack and lead to
* instability or deadlock. Defer heavy work to a separate task if needed.
*
* @return
* - ESP_OK: Success
@@ -330,10 +334,22 @@ esp_err_t esp_ble_gattc_app_unregister(esp_gatt_if_t gattc_if);
*
* @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.
* 2. The function always triggers `ESP_GATTC_CONNECT_EVT` and `ESP_GATTC_OPEN_EVT`.
* 3. When the device acts as GATT server, besides the above two events, this function triggers `ESP_GATTS_CONNECT_EVT` as well.
* 4. 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.
* 5. The `is_aux` parameter in `esp_gatt_creat_conn_params_t` determines which connection interface to use:
* - If `is_aux` is true, the BLE 5.0 extended connection interface will be used.
* - If `is_aux` is false, the BLE 4.2 interface (legacy connection) will be used.
* - When connecting to a legacy advertising device using BLE 5.0 interface, `is_aux` should be set to true.
* 6. Auto-setting of `is_aux` parameter (handled in L2CAP layer):
* - If only BLE 4.2 feature is enabled, `is_aux` will be automatically set to false.
* - If only BLE 5.0 feature is enabled, `is_aux` will be automatically set to true.
* - If both BLE 4.2 and BLE 5.0 features are enabled (not recommended):
* * The stack will automatically infer whether to use BLE 5.0 or BLE 4.2 interface
* based on previously used APIs.
* * Otherwise, the user-specified value will be used.
* - Note: It is strongly recommended NOT to enable both BLE 4.2 and BLE 5.0 features
* simultaneously in menuconfig.
*
* @param[in] gattc_if: GATT client access interface.
* @param[in] esp_gatt_create_conn: Pointer to the structure containing connection parameters.
@@ -887,12 +903,14 @@ esp_err_t esp_ble_gattc_read_char_descr (esp_gatt_if_t gattc_if,
* @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
* @param[in] auth_req Authenticate request type
*
* @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.
* 4. If `auth_req` is not `ESP_GATT_AUTH_REQ_NONE`, the stack may start encryption
* or SMP pairing before sending the ATT write.
*
* @return
* - ESP_OK: Success

6
components/bt/host/bluedroid/api/include/api/esp_gatts_api.h
View File

@@ -283,7 +283,11 @@ typedef void (* esp_gatts_cb_t)(esp_gatts_cb_event_t event, esp_gatt_if_t gatts_
*
* @param[in] callback The pointer to the application callback function
*
* @note Avoid performing time-consuming operations within the callback functions.
* @note Do NOT perform time-consuming operations in the callback. Time-consuming operations
* include: taking semaphores that may block for a long time (e.g. xSemaphoreTake with
* long timeout or portMAX_DELAY), blocking delays (e.g. vTaskDelay), and flash
* read/write/erase. Such operations may block the Bluetooth stack and lead to
* instability or deadlock. Defer heavy work to a separate task if needed.
*
* @return
* - ESP_OK: Success

22
components/bt/host/bluedroid/stack/l2cap/l2c_ble.c
View File

@@ -1034,7 +1034,27 @@ BOOLEAN l2cble_init_direct_conn (tL2C_LCB *p_lcb)
}
}
if (!p_lcb->is_aux) {
// Auto-set is_aux based on BLE feature support
bool is_aux = p_lcb->is_aux;
#if (BLE_42_FEATURE_SUPPORT == TRUE) && (BLE_50_FEATURE_SUPPORT == FALSE)
if (is_aux) {
L2CAP_TRACE_WARNING("is_aux auto-set to false (BLE 4.2 only)");
is_aux = false;
}
#elif (BLE_42_FEATURE_SUPPORT == FALSE) && (BLE_50_FEATURE_SUPPORT == TRUE)
if (!is_aux) {
L2CAP_TRACE_WARNING("is_aux auto-set to true (BLE 5.0 only)");
is_aux = true;
}
#else
extern bool btm_ble_inter_get(void);
if (btm_ble_inter_get() && (!is_aux)) {
L2CAP_TRACE_WARNING("is_aux auto-set to true (BLE 5.0 API used)");
is_aux = true;
}
#endif
if (!is_aux) {
if (!btsnd_hcic_ble_create_ll_conn (scan_int, /* UINT16 scan_int */
scan_win, /* UINT16 scan_win */
FALSE, /* UINT8 white_list */

28
components/bt/include/esp32c3/include/esp_bt.h
View File

@@ -539,7 +539,8 @@ typedef enum {
* After disconnecting, the corresponding TX power will not be affected.
* 2. `ESP_BLE_PWR_TYPE_DEFAULT` can be used to set the TX power for power types that have not been set before.
* It will not affect the TX power values which have been set for the ADV/SCAN/CONN0-8 power types.
* 3. If none of power type is set, the system will use `ESP_PWR_LVL_P3` as default for all power types.
* 3. If no runtime TX power is configured, the system uses the menuconfig default
* TX power (`CONFIG_BT_CTRL_DFT_TX_POWER_LEVEL`) for all power types.
*/
typedef enum {
ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, /*!< TX power for Connection state handle 0 */
@@ -802,7 +803,19 @@ void esp_bt_controller_wakeup_request(void);
*
* It is recommended to use `esp_ble_tx_power_set_enhanced` to set TX power for individual advertising and connection handle.
*
* @note Connection TX power should only be set after the connection is established.
* @note
* 1. Connection TX power should only be set after the connection is established.
* 2. Priority from high to low:
* - ADV TX power in `esp_ble_gap_ext_adv_set_params()`.
* - TX power configured by `esp_ble_tx_power_set_enhanced()` / `esp_ble_tx_power_set()`.
* - Menuconfig default TX power (`CONFIG_BT_CTRL_DFT_TX_POWER_LEVEL`).
* 3. If TX power is not configured through `esp_ble_gap_ext_adv_set_params()`,
* `esp_ble_tx_power_set_enhanced()`, or `esp_ble_tx_power_set()`,
* the menuconfig default TX power is applied globally.
* 4. On ESP32-C3/ESP32-S3, Controller TX power resolution is 3 dBm per step.
* The actual applied TX power may be 0 to 2 dBm lower than requested.
* For example, request 0 dBm -> apply 0 dBm; request 1/2 dBm -> apply 0 dBm;
* request 3 dBm -> apply 3 dBm.
*
* @param[in] power_type The type of TX power. It could be Advertising, Connection, or Default.
* @param[in] power_level Power level (index) corresponding to the absolute value (dBm)
@@ -842,6 +855,17 @@ esp_power_level_t esp_ble_tx_power_get(esp_ble_power_type_t power_type);
*
* @note
* 1. Connection TX power should only be set after connection created.
* 2. Priority from high to low:
* - ADV TX power in `esp_ble_gap_ext_adv_set_params()`.
* - TX power configured by `esp_ble_tx_power_set_enhanced()` / `esp_ble_tx_power_set()`.
* - Menuconfig default TX power (`CONFIG_BT_CTRL_DFT_TX_POWER_LEVEL`).
* 3. If TX power is not configured through `esp_ble_gap_ext_adv_set_params()`,
* `esp_ble_tx_power_set_enhanced()`, or `esp_ble_tx_power_set()`,
* the menuconfig default TX power is applied globally.
* 4. On ESP32-C3/ESP32-S3, Controller TX power resolution is 3 dBm per step.
* The actual applied TX power may be 0 to 2 dBm lower than requested.
* For example, request 0 dBm -> apply 0 dBm; request 1/2 dBm -> apply 0 dBm;
* request 3 dBm -> apply 3 dBm.
*
* @param[in] power_type The type of TX power
* @param[in] handle The handle of Advertising or Connection