From 1692cf9f7201cc11f397a22a0d4800f79b37faec Mon Sep 17 00:00:00 2001 From: Zhang Hai Peng Date: Tue, 2 Jun 2026 10:23:27 +0800 Subject: [PATCH] docs(bt): clarify BLE TX power priority and granularity (cherry picked from commit 4ab49f267b5cd6905b3536d21b1e9cededea7ed4) Co-authored-by: zhanghaipeng --- .../api/include/api/esp_gap_ble_api.h | 10 ++++++- .../bt/include/esp32c3/include/esp_bt.h | 28 +++++++++++++++++-- 2 files changed, 35 insertions(+), 3 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 11ba3d63cc3..c1ceb1e021e 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 6dfb46d83ba..d66c114cb12 100644 --- a/components/bt/include/esp32c3/include/esp_bt.h +++ b/components/bt/include/esp32c3/include/esp_bt.h @@ -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