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

docs(bt): clarify BLE TX power priority and granularity

Browse Source 
(cherry picked from commit 4ab49f267b)

Co-authored-by: zhanghaipeng <zhanghaipeng@espressif.com>
This commit is contained in:
Zhang Hai Peng
2026-06-02 10:23:27 +08:00
parent e4bb039f41
commit 1692cf9f72
2 changed files with 35 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
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.

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