From 82c5c1fef3818bee736efb5b8f5b98bb1a693b24 Mon Sep 17 00:00:00 2001 From: zhanghaipeng Date: Fri, 6 Feb 2026 16:22:35 +0800 Subject: [PATCH 1/6] fix(ble/bluedroid): Ensure HIGH_DUTY_ADV_INTERVAL config is applied in stack --- components/bt/host/bluedroid/api/include/api/esp_bt_defs.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h b/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h index bd4b2c7e763..b6573c4de65 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h +++ b/components/bt/host/bluedroid/api/include/api/esp_bt_defs.h @@ -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 */ From 4590b4bb34d897360049ad7cf4f8150805c878e0 Mon Sep 17 00:00:00 2001 From: zhanghaipeng Date: Thu, 29 Jan 2026 20:43:55 +0800 Subject: [PATCH 2/6] doc(ble/bluedroid): clarify callback notes to avoid time-consuming ops --- .../bt/host/bluedroid/api/include/api/esp_gap_ble_api.h | 6 +++++- .../bt/host/bluedroid/api/include/api/esp_gattc_api.h | 6 +++++- .../bt/host/bluedroid/api/include/api/esp_gatts_api.h | 8 ++++++-- 3 files changed, 16 insertions(+), 4 deletions(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h index da5df368a1a..4fc217c36c4 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h @@ -2902,7 +2902,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 diff --git a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h index 70953609ee6..9129edb6f4d 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h @@ -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 diff --git a/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h b/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h index 642222104ad..875ddbc9a11 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gatts_api.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2015-2024 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -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 From 1a9f2af505465cffac57343c6e75244409d6d868 Mon Sep 17 00:00:00 2001 From: zhanghaipeng Date: Wed, 14 Jan 2026 11:59:20 +0800 Subject: [PATCH 3/6] feat(ble/bluedroid): add auto-setting for is_aux parameter in esp_ble_gattc_enh_open --- .../bt/host/bluedroid/api/esp_gattc_api.c | 2 +- .../bluedroid/api/include/api/esp_gatt_defs.h | 12 +++++++++- .../bluedroid/api/include/api/esp_gattc_api.h | 20 +++++++++++++---- .../bt/host/bluedroid/stack/l2cap/l2c_ble.c | 22 ++++++++++++++++++- 4 files changed, 49 insertions(+), 7 deletions(-) diff --git a/components/bt/host/bluedroid/api/esp_gattc_api.c b/components/bt/host/bluedroid/api/esp_gattc_api.c index 0e2befd18d7..2a61abeb053 100644 --- a/components/bt/host/bluedroid/api/esp_gattc_api.c +++ b/components/bt/host/bluedroid/api/esp_gattc_api.c @@ -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; diff --git a/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h b/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h index 688366a9b0c..b8051625eef 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h @@ -687,7 +687,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 */ diff --git a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h index 9129edb6f4d..9f662b6c97c 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h @@ -334,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. diff --git a/components/bt/host/bluedroid/stack/l2cap/l2c_ble.c b/components/bt/host/bluedroid/stack/l2cap/l2c_ble.c index 65d4e643b06..d4acd714ae8 100644 --- a/components/bt/host/bluedroid/stack/l2cap/l2c_ble.c +++ b/components/bt/host/bluedroid/stack/l2cap/l2c_ble.c @@ -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 */ From 27fc241384784d9bc124c4a6b7e102506636edbe Mon Sep 17 00:00:00 2001 From: zhanghaipeng Date: Thu, 22 Jan 2026 14:35:00 +0800 Subject: [PATCH 4/6] docs(bt/bluedroid): add usage note for esp_ble_get_cur_sendable_packets_num --- components/bt/host/bluedroid/api/esp_gatt_common_api.c | 3 +++ 1 file changed, 3 insertions(+) diff --git a/components/bt/host/bluedroid/api/esp_gatt_common_api.c b/components/bt/host/bluedroid/api/esp_gatt_common_api.c index 9254b8d87af..d3348d5a450 100644 --- a/components/bt/host/bluedroid/api/esp_gatt_common_api.c +++ b/components/bt/host/bluedroid/api/esp_gatt_common_api.c @@ -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 From 43734e7d7be22328135918edf2e8075c1fb717c6 Mon Sep 17 00:00:00 2001 From: zhanghaipeng Date: Fri, 22 May 2026 14:18:10 +0800 Subject: [PATCH 5/6] docs(bt): clarify GATT client auth_req may trigger SMP --- .../host/bluedroid/api/include/api/esp_gatt_defs.h | 13 +++++++++---- .../host/bluedroid/api/include/api/esp_gattc_api.h | 4 +++- 2 files changed, 12 insertions(+), 5 deletions(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h b/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h index b8051625eef..03ba9a01624 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h @@ -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. */ diff --git a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h index 9f662b6c97c..65979ba4abf 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h @@ -874,12 +874,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 From 4ab49f267b5cd6905b3536d21b1e9cededea7ed4 Mon Sep 17 00:00:00 2001 From: zhanghaipeng Date: Mon, 1 Jun 2026 11:20:27 +0800 Subject: [PATCH 6/6] docs(bt): clarify BLE TX power priority and granularity --- .../api/include/api/esp_gap_ble_api.h | 10 ++++++- .../bt/include/esp32c3/include/esp_bt.h | 30 +++++++++++++++++-- 2 files changed, 36 insertions(+), 4 deletions(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h index 4fc217c36c4..4e2711324ad 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gap_ble_api.h @@ -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. diff --git a/components/bt/include/esp32c3/include/esp_bt.h b/components/bt/include/esp32c3/include/esp_bt.h index 48e939be06b..4ce1410d6bb 100644 --- a/components/bt/include/esp32c3/include/esp_bt.h +++ b/components/bt/include/esp32c3/include/esp_bt.h @@ -1,5 +1,5 @@ /* - * SPDX-FileCopyrightText: 2015-2025 Espressif Systems (Shanghai) CO LTD + * SPDX-FileCopyrightText: 2015-2026 Espressif Systems (Shanghai) CO LTD * * SPDX-License-Identifier: Apache-2.0 */ @@ -525,7 +525,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 */ @@ -788,7 +789,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) @@ -828,6 +841,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