From 075bb4831dc7dfd42c81d04da740764602dc9338 Mon Sep 17 00:00:00 2001 From: Yuhan Wei Date: Wed, 10 Jul 2024 09:31:44 +0800 Subject: [PATCH 01/10] docs(ble): Added more explanations for memory release related API --- components/bt/include/esp32/include/esp_bt.h | 46 ++++++++++---------- 1 file changed, 24 insertions(+), 22 deletions(-) diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index 379cb00eac..9793b68397 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -272,22 +272,22 @@ typedef enum { /** * @brief BLE TX power type * @note - * 1. The connection TX power can only be set after the connection is established. + * 1. Please use `ESP_BLE_PWR_TYPE_DEFAULT` to set connection TX power before establishing the connection. * 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 following CONN0-8/ADV/SCAN power types. - * 3. If none of power type is set, the system will use `ESP_PWR_LVL_P3` as default for ADV/SCAN/CONN0-8. + * It will not affect the TX power values which have been set for the ADV/SCAN power types. + * 3. If none of power type is set, the system will use `ESP_PWR_LVL_P3` as default for all power types. */ typedef enum { - ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, /*!< TX power for connection handle 0 */ - ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, /*!< TX power for connection handle 1 */ - ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, /*!< TX power for connection handle 2 */ - ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, /*!< TX power for connection handle 3 */ - ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, /*!< TX power for connection handle 4 */ - ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, /*!< TX power for connection handle 5 */ - ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, /*!< TX power for connection handle 6 */ - ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, /*!< TX power for connection handle 7 */ - ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, /*!< TX power for connection handle 8 */ + ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, /*!< TX power for connection handle 0. Currently not effective */ + ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, /*!< TX power for connection handle 1. Currently not effective */ + ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, /*!< TX power for connection handle 2. Currently not effective */ + ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, /*!< TX power for connection handle 3. Currently not effective */ + ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, /*!< TX power for connection handle 4. Currently not effective */ + ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, /*!< TX power for connection handle 5. Currently not effective */ + ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, /*!< TX power for connection handle 6. Currently not effective */ + ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, /*!< TX power for connection handle 7. Currently not effective */ + ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, /*!< TX power for connection handle 8. Currently not effective */ ESP_BLE_PWR_TYPE_ADV = 9, /*!< TX power for advertising */ ESP_BLE_PWR_TYPE_SCAN = 10, /*!< TX power for scan */ ESP_BLE_PWR_TYPE_DEFAULT = 11, /*!< Default TX power type, which can be used to set the TX power for power types that have not been set before.*/ @@ -514,6 +514,12 @@ esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callba * * This function releases the BSS, data and other sections of the Controller to heap. The total size is about 70 KB. * + * @note + * 1. This function is optional and should be called only if you want to free up memory for other components. + * 2. This function should be called only before `esp_bt_controller_init()` or after `esp_bt_controller_deinit()`. + * 3. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. + * 4. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. + * * If the app calls `esp_bt_controller_enable(ESP_BT_MODE_BLE)` to use BLE only, * then it is safe to call `esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT)` at initialization time to free unused Classic Bluetooth memory. * @@ -521,11 +527,6 @@ esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callba * which internally calls `esp_bt_controller_mem_release(ESP_BT_MODE_BTDM)` and additionally releases the BSS and data * consumed by the Classic Bluetooth/BLE Host stack to heap. For more details about usage please refer to the documentation of `esp_bt_mem_release()` function. * - * @note - * 1. This function should be called only before `esp_bt_controller_init()` or after `esp_bt_controller_deinit()`. - * 2. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. - * 3. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. - * * @param[in] mode The Bluetooth Controller mode * * @return @@ -536,6 +537,12 @@ esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callba esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode); /** @brief Release the Controller memory, BSS and data section of the Classic Bluetooth/BLE Host stack as per the mode + * + * @note + * 1. This function is optional and should be called only if you want to free up memory for other components. + * 2. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. + * 3. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. + * 4. In case of NimBLE Host, to release BSS and data memory to heap, the mode needs to be set to `ESP_BT_MODE_BTDM` as the Controller is in Dual mode. * * This function first releases Controller memory by internally calling `esp_bt_controller_mem_release()`. * Additionally, if the mode is set to `ESP_BT_MODE_BTDM`, it also releases the BSS and data consumed by the Classic Bluetooth and BLE Host stack to heap. @@ -553,11 +560,6 @@ esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode); * esp_bt_controller_deinit(); * esp_bt_mem_release(ESP_BT_MODE_BTDM); * - * @note - * 1. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. - * 2. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. - * 3. In case of NimBLE Host, to release BSS and data memory to heap, the mode needs to be set to `ESP_BT_MODE_BTDM` as the Controller is in Dual mode. - * * @param[in] mode The Bluetooth Controller mode * * @return From 40c454bb40792d8b5e164bee1f7875986e379606 Mon Sep 17 00:00:00 2001 From: Yuhan Wei Date: Wed, 10 Jul 2024 09:55:55 +0800 Subject: [PATCH 02/10] docs(ble): Removed a period --- components/bt/include/esp32/include/esp_bt.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index 9793b68397..62c18ca896 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -53,7 +53,7 @@ extern "C" { /** * @brief Internal use only * -* @note Please do not modify this value. +* @note Please do not modify this value */ #define ESP_BT_CONTROLLER_CONFIG_MAGIC_VAL 0x20240315 @@ -539,7 +539,7 @@ esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode); /** @brief Release the Controller memory, BSS and data section of the Classic Bluetooth/BLE Host stack as per the mode * * @note - * 1. This function is optional and should be called only if you want to free up memory for other components. + * 1. This function is optional and should be called only if you want to free up memory for other components. * 2. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. * 3. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. * 4. In case of NimBLE Host, to release BSS and data memory to heap, the mode needs to be set to `ESP_BT_MODE_BTDM` as the Controller is in Dual mode. From e9f0ca3631a7076241a50765eb11e75907eb685f Mon Sep 17 00:00:00 2001 From: Yuhan Wei Date: Wed, 10 Jul 2024 10:01:01 +0800 Subject: [PATCH 03/10] docs(ble): Reformat the code --- components/bt/include/esp32/include/esp_bt.h | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index 62c18ca896..92bbf42fd8 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -477,11 +477,11 @@ typedef struct esp_vhci_host_callback { /** * @brief Check whether the Controller is ready to receive the packet * - * If the return value is True, the Host can send the packet to the Controller. + * If the return value is True, the Host can send the packet to the Controller. * - * @note This function should be called before each `esp_vhci_host_send_packet()`. + * @note This function should be called before each `esp_vhci_host_send_packet()`. * - * @return + * @return * True if the Controller is ready to receive packets; false otherwise */ bool esp_vhci_host_check_send_available(void); From 28da1bc4bca9357cc2f1db9a049dcb096a68b3dc Mon Sep 17 00:00:00 2001 From: Yuhan Wei Date: Wed, 10 Jul 2024 16:29:00 +0800 Subject: [PATCH 04/10] docs(ble): Revised the explanations for memory release related APIs --- components/bt/include/esp32/include/esp_bt.h | 45 +++++++++++--------- 1 file changed, 26 insertions(+), 19 deletions(-) diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index 92bbf42fd8..101a46f64f 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -272,8 +272,8 @@ typedef enum { /** * @brief BLE TX power type * @note - * 1. Please use `ESP_BLE_PWR_TYPE_DEFAULT` to set connection TX power before establishing the connection. - * After disconnecting, the corresponding TX power will not be affected. + * 1. `ESP_BLE_PWR_CONN_HDL0` - `ESP_BLE_PWR_CONN_HDL8` are not effective currently. Please use `ESP_BLE_PWR_TYPE_DEFAULT` + * to set / get BLE TX power for all connection handles. * 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 power types. * 3. If none of power type is set, the system will use `ESP_PWR_LVL_P3` as default for all power types. @@ -327,7 +327,9 @@ typedef enum { /** * @brief Set BLE TX power * - * @note Connection TX power should only be set after the connection is established. + * @note + * 1. Please use `ESP_BLE_PWR_TYPE_DEFAULT` to set BLE TX power for all connection handles. + * 2. Connection TX power should only be set after the connection is established. * * @param[in] power_type The type of TX power. It could be Advertising, Connection, Default, etc. * @param[in] power_level Power level (index) corresponding to the absolute value (dBm) @@ -341,7 +343,9 @@ esp_err_t esp_ble_tx_power_set(esp_ble_power_type_t power_type, esp_power_level_ /** * @brief Get BLE TX power * - * @note Connection TX power should only be retrieved after the connection is established. + * @note + * 1. Please use `ESP_BLE_PWR_TYPE_DEFAULT` to get BLE TX power for all connection handles. + * 2. Connection TX power should only be retrieved after the connection is established. * * @param[in] power_type The type of TX power. It could be Advertising/Connection/Default and etc. * @@ -516,16 +520,17 @@ esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callba * * @note * 1. This function is optional and should be called only if you want to free up memory for other components. - * 2. This function should be called only before `esp_bt_controller_init()` or after `esp_bt_controller_deinit()`. - * 3. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. - * 4. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. + * 2. This function should only be called when the controller is in `ESP_BT_CONTROLLER_STATUS_IDLE` status. + * 3. This function should be called only before `esp_bt_controller_init()` or after `esp_bt_controller_deinit()`. + * 4. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. + * 5. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. * - * If the app calls `esp_bt_controller_enable(ESP_BT_MODE_BLE)` to use BLE only, - * then it is safe to call `esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT)` at initialization time to free unused Classic Bluetooth memory. + * If you never intend to use Bluetooth in a current boot-up cycle, calling `esp_bt_controller_mem_release(ESP_BT_MODE_BTDM)` could release the BSS and data consumed by both Classic Bluetooth and BLE Controller to heap. + * + * If you intend to use BLE only, calling `esp_bt_controller_mem_release(ESP_BT_MODE_CLASSIC_BT)` could release the BSS and data consumed by Classic Bluetooth Controller. You can then continue using BLE. + * + * If you intend to use Classic Bluetooth only, calling `esp_bt_controller_mem_release(ESP_BT_MODE_BLE)` could release the BSS and data consumed by BLE Controller. You can then continue using Classic Bluetooth. * - * If the mode is `ESP_BT_MODE_BTDM`, then it may be useful to call API `esp_bt_mem_release(ESP_BT_MODE_BTDM)` instead, - * which internally calls `esp_bt_controller_mem_release(ESP_BT_MODE_BTDM)` and additionally releases the BSS and data - * consumed by the Classic Bluetooth/BLE Host stack to heap. For more details about usage please refer to the documentation of `esp_bt_mem_release()` function. * * @param[in] mode The Bluetooth Controller mode * @@ -540,15 +545,17 @@ esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode); * * @note * 1. This function is optional and should be called only if you want to free up memory for other components. - * 2. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. - * 3. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. - * 4. In case of NimBLE Host, to release BSS and data memory to heap, the mode needs to be set to `ESP_BT_MODE_BTDM` as the Controller is in Dual mode. + * 2. This function should only be called when the controller is in `ESP_BT_CONTROLLER_STATUS_IDLE` status. + * 3. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. + * 4. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. * - * This function first releases Controller memory by internally calling `esp_bt_controller_mem_release()`. - * Additionally, if the mode is set to `ESP_BT_MODE_BTDM`, it also releases the BSS and data consumed by the Classic Bluetooth and BLE Host stack to heap. + * This function first releases Controller memory by internally calling `esp_bt_controller_mem_release()`, then release Host memory. * - * If you never intend to use Bluetooth in a current boot-up cycle, you can call `esp_bt_mem_release(ESP_BT_MODE_BTDM)` - * before `esp_bt_controller_init()` or after `esp_bt_controller_deinit()`. + * If you never intend to use Bluetooth in a current boot-up cycle, calling `esp_bt_mem_release(ESP_BT_MODE_BTDM)` could release the BSS and data consumed by both Classic Bluetooth and BLE stack to heap. + * + * If you intend to use BLE only, calling `esp_bt_mem_release(ESP_BT_MODE_CLASSIC_BT)` could release the BSS and data consumed by Classic Bluetooth. You can then continue using BLE. + * + * If you intend to use Classic Bluetooth only, calling `esp_bt_mem_release(ESP_BT_MODE_BLE)` could release the BSS and data consumed by BLE. You can then continue using Classic Bluetooth. * * For example, if you only use Bluetooth for setting the Wi-Fi configuration, and do not use Bluetooth in the rest of the product operation, * after receiving the Wi-Fi configuration, you can disable/de-init Bluetooth and release its memory. From 4bfdf5ecb3a8b6eedc5dc4c5aa0fa7ff357eb033 Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Wed, 10 Jul 2024 17:53:04 +0800 Subject: [PATCH 05/10] docs(ble): Remove one note in esp_bt_controller_mem_release --- components/bt/include/esp32/include/esp_bt.h | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index 101a46f64f..9355772140 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -521,9 +521,8 @@ esp_err_t esp_vhci_host_register_callback(const esp_vhci_host_callback_t *callba * @note * 1. This function is optional and should be called only if you want to free up memory for other components. * 2. This function should only be called when the controller is in `ESP_BT_CONTROLLER_STATUS_IDLE` status. - * 3. This function should be called only before `esp_bt_controller_init()` or after `esp_bt_controller_deinit()`. - * 4. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. - * 5. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. + * 3. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. + * 4. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. * * If you never intend to use Bluetooth in a current boot-up cycle, calling `esp_bt_controller_mem_release(ESP_BT_MODE_BTDM)` could release the BSS and data consumed by both Classic Bluetooth and BLE Controller to heap. * From 213c05db4b2f4d4ea8b1e413b7922b6b8fa58ea0 Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Thu, 11 Jul 2024 10:10:37 +0800 Subject: [PATCH 06/10] docs(ble): Fixed a typo in esp_bt_mem_release comment --- components/bt/include/esp32/include/esp_bt.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index 9355772140..ce731e2ca7 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -548,7 +548,7 @@ esp_err_t esp_bt_controller_mem_release(esp_bt_mode_t mode); * 3. Once Bluetooth Controller memory is released, the process cannot be reversed. This means you cannot use the Bluetooth Controller mode that you have released using this function. * 4. If your firmware will upgrade the Bluetooth Controller mode later (such as switching from BLE to Classic Bluetooth or from disabled to enabled), then do not call this function. * - * This function first releases Controller memory by internally calling `esp_bt_controller_mem_release()`, then release Host memory. + * This function first releases Controller memory by internally calling `esp_bt_controller_mem_release()`, then releases Host memory. * * If you never intend to use Bluetooth in a current boot-up cycle, calling `esp_bt_mem_release(ESP_BT_MODE_BTDM)` could release the BSS and data consumed by both Classic Bluetooth and BLE stack to heap. * From 73b647f2928abc2270792078dce9f87fe7e9c1a9 Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Thu, 11 Jul 2024 18:35:42 +0800 Subject: [PATCH 07/10] docs(ble): Removed the 'not effective' for CONN_HDL0 - CONN_HDL8 --- components/bt/include/esp32/include/esp_bt.h | 28 +++++++++----------- 1 file changed, 13 insertions(+), 15 deletions(-) diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index ce731e2ca7..61f65232d4 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -272,22 +272,22 @@ typedef enum { /** * @brief BLE TX power type * @note - * 1. `ESP_BLE_PWR_CONN_HDL0` - `ESP_BLE_PWR_CONN_HDL8` are not effective currently. Please use `ESP_BLE_PWR_TYPE_DEFAULT` - * to set / get BLE TX power for all connection handles. + * 1. The connection TX power can only be set after the connection is established. + * 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 power types. * 3. If none of power type is set, the system will use `ESP_PWR_LVL_P3` as default for all power types. */ typedef enum { - ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, /*!< TX power for connection handle 0. Currently not effective */ - ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, /*!< TX power for connection handle 1. Currently not effective */ - ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, /*!< TX power for connection handle 2. Currently not effective */ - ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, /*!< TX power for connection handle 3. Currently not effective */ - ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, /*!< TX power for connection handle 4. Currently not effective */ - ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, /*!< TX power for connection handle 5. Currently not effective */ - ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, /*!< TX power for connection handle 6. Currently not effective */ - ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, /*!< TX power for connection handle 7. Currently not effective */ - ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, /*!< TX power for connection handle 8. Currently not effective */ + ESP_BLE_PWR_TYPE_CONN_HDL0 = 0, /*!< TX power for connection handle 0 */ + ESP_BLE_PWR_TYPE_CONN_HDL1 = 1, /*!< TX power for connection handle 1 */ + ESP_BLE_PWR_TYPE_CONN_HDL2 = 2, /*!< TX power for connection handle 2 */ + ESP_BLE_PWR_TYPE_CONN_HDL3 = 3, /*!< TX power for connection handle 3 */ + ESP_BLE_PWR_TYPE_CONN_HDL4 = 4, /*!< TX power for connection handle 4 */ + ESP_BLE_PWR_TYPE_CONN_HDL5 = 5, /*!< TX power for connection handle 5 */ + ESP_BLE_PWR_TYPE_CONN_HDL6 = 6, /*!< TX power for connection handle 6 */ + ESP_BLE_PWR_TYPE_CONN_HDL7 = 7, /*!< TX power for connection handle 7 */ + ESP_BLE_PWR_TYPE_CONN_HDL8 = 8, /*!< TX power for connection handle 8 */ ESP_BLE_PWR_TYPE_ADV = 9, /*!< TX power for advertising */ ESP_BLE_PWR_TYPE_SCAN = 10, /*!< TX power for scan */ ESP_BLE_PWR_TYPE_DEFAULT = 11, /*!< Default TX power type, which can be used to set the TX power for power types that have not been set before.*/ @@ -328,8 +328,7 @@ typedef enum { * @brief Set BLE TX power * * @note - * 1. Please use `ESP_BLE_PWR_TYPE_DEFAULT` to set BLE TX power for all connection handles. - * 2. Connection TX power should only be set after the connection is established. + * 1. Connection TX power should only be set after the connection is established. * * @param[in] power_type The type of TX power. It could be Advertising, Connection, Default, etc. * @param[in] power_level Power level (index) corresponding to the absolute value (dBm) @@ -344,8 +343,7 @@ esp_err_t esp_ble_tx_power_set(esp_ble_power_type_t power_type, esp_power_level_ * @brief Get BLE TX power * * @note - * 1. Please use `ESP_BLE_PWR_TYPE_DEFAULT` to get BLE TX power for all connection handles. - * 2. Connection TX power should only be retrieved after the connection is established. + * 1. Connection TX power should only be retrieved after the connection is established. * * @param[in] power_type The type of TX power. It could be Advertising/Connection/Default and etc. * From e8e66a84ededc60178260e799ec656ef99103441 Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Thu, 11 Jul 2024 18:38:15 +0800 Subject: [PATCH 08/10] docs(ble): added CONN0-8 back to the second note of esp_power_level_t --- components/bt/include/esp32/include/esp_bt.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index 61f65232d4..b0779ce883 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -275,7 +275,7 @@ typedef enum { * 1. The connection TX power can only be set after the connection is established. * 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 power types. + * 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. */ typedef enum { From 3df1e43d09119770108edc83994fc92a0b7fe246 Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Fri, 12 Jul 2024 08:01:40 +0800 Subject: [PATCH 09/10] docs(ble): Removed a trailing whitespace --- components/bt/include/esp32/include/esp_bt.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index b0779ce883..5d32f2adc3 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -272,7 +272,7 @@ typedef enum { /** * @brief BLE TX power type * @note - * 1. The connection TX power can only be set after the connection is established. + * 1. The connection TX power can only be set after the connection is established. * 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. From ae3f27bafdce5711967d1ace759d6bc22d52d469 Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Fri, 12 Jul 2024 08:22:16 +0800 Subject: [PATCH 10/10] docs(ble): Removed the index of the note for esp_ble_power_type_set/get --- components/bt/include/esp32/include/esp_bt.h | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/components/bt/include/esp32/include/esp_bt.h b/components/bt/include/esp32/include/esp_bt.h index 5d32f2adc3..eb7b16cb25 100644 --- a/components/bt/include/esp32/include/esp_bt.h +++ b/components/bt/include/esp32/include/esp_bt.h @@ -327,8 +327,7 @@ typedef enum { /** * @brief Set BLE TX power * - * @note - * 1. Connection TX power should only be set after the connection is established. + * @note Connection TX power should only be set after the connection is established. * * @param[in] power_type The type of TX power. It could be Advertising, Connection, Default, etc. * @param[in] power_level Power level (index) corresponding to the absolute value (dBm) @@ -342,8 +341,7 @@ esp_err_t esp_ble_tx_power_set(esp_ble_power_type_t power_type, esp_power_level_ /** * @brief Get BLE TX power * - * @note - * 1. Connection TX power should only be retrieved after the connection is established. + * @note Connection TX power should only be retrieved after the connection is established. * * @param[in] power_type The type of TX power. It could be Advertising/Connection/Default and etc. *