Merge branch 'docs/ble_add_low_power_intro_v5.5' into 'release/v5.5'

Added BLE Low Power Mode Introduction (v5.5)

See merge request espressif/esp-idf!42995

Author: Isl2017

docs/conf_common.py

@@ -39,6 +39,7 @@
     'api-guides/ble/get-started/ble-connection.rst',
     'api-guides/ble/get-started/ble-data-exchange.rst',
     'api-guides/ble/smp.rst',
+    'api-guides/low-power-mode/low-power-mode-ble.rst',
     'api-reference/bluetooth/bt_le.rst',
     'api-reference/bluetooth/esp_gap_ble.rst',
     'api-reference/bluetooth/esp_gatt_defs.rst',

docs/en/api-guides/ble/ble-feature-support-status.rst

@@ -407,7 +407,7 @@ If none of our chip series meet your needs, please contact `customer support tea
    please consult `SIG Bluetooth Product Database <https://qualification.bluetooth.com/Listings/Search>`__.
 
 For certain features, if the majority of the development is completed on the Controller, the Host's support status will be limited by the Controller's support status.
-If you want BLE Controller and Host to run on different Espressif chips, the functionality of the Host will not be limited by the Controller's support status on the chip running the Host,
+If you want Bluetooth LE Controller and Host to run on different Espressif chips, the functionality of the Host will not be limited by the Controller's support status on the chip running the Host,
 please check the :doc:`ESP Host Feature Support Status Table <host-feature-support-status>` .
 
 It is important to clarify that this document is not a binding commitment to our customers.

docs/en/api-guides/ble/get-started/ble-data-exchange.rst

@@ -296,7 +296,7 @@ If you have not completed the ESP-IDF development environment setup, please refe
 Try It Out
 ^^^^^^^^^^^^^^^^^^
 
-Please refer to :ref:`BLE Introduction Try It Out <nimble_gatt_server_practice>` 。
+Please refer to :ref:`Bluetooth LE Introduction Try It Out <nimble_gatt_server_practice>`.
 
 
 Code Explanation

docs/en/api-guides/ble/host-feature-support-status.rst

@@ -6,7 +6,7 @@ ESP Host Major Feature Support Status
 :link_to_translation:`zh_CN:[中文]`
 
 The table below shows the support status of major features on ESP-Bluedroid and ESP-NimBLE Host.
-If you plan to run the BLE Controller and Host on {IDF_TARGET_NAME} together, the functionality of the Host may be limited by the support status of the Controller,
+If you plan to run the Bluetooth LE Controller and Host on {IDF_TARGET_NAME} together, the functionality of the Host may be limited by the support status of the Controller,
 please check the :doc:`{IDF_TARGET_NAME} Major Feature Support Status Table <ble-feature-support-status>` .
 
 |supported_def| **This feature has completed development and internal testing.** [1]_

docs/en/api-guides/ble/index.rst

@@ -13,6 +13,7 @@ Overview
    overview
    ble-feature-support-status
    ble-qualification
+   Low Power Mode Introduction <../low-power-mode/low-power-mode-ble>
 
 ***************
 Get Started

docs/en/api-guides/low-power-mode/index.rst

@@ -13,3 +13,4 @@ The standby power consumption plays an important role in embedded IoT applicatio
 
    low-power-mode-soc
    :SOC_WIFI_SUPPORTED: low-power-mode-wifi
+   :SOC_BLE_SUPPORTED: low-power-mode-ble

docs/en/api-guides/low-power-mode/low-power-mode-ble.rst

@@ -0,0 +1,143 @@
+Introduction to Low Power Mode in Bluetooth\ :sup:`®` Low Energy Scenarios
+================================================================================
+
+:link_to_translation:`zh_CN:[中文]`
+
+This section introduces clock source selection in low power modes for Bluetooth Low Energy (Bluetooth LE), along with common related issues.
+
+Clock Source Selection in Low Power Mode
+--------------------------------------------
+
+According to the Bluetooth specification, the sleep clock accuracy must be within 500 PPM. Make sure the clock source selected for Bluetooth LE low power mode meets this requirement. Otherwise, Bluetooth LE may not perform normally and can cause a series of problems, such as ACL connection establishment failure or ACL connection timeout.
+
+Selecting Main XTAL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To select the main XTAL as the Bluetooth LE internal clock source, configure the following option:
+
+.. only:: esp32
+
+    :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` = Main crystal (`CONFIG_BTDM_CTRL_LPCLK_SEL_MAIN_XTAL`)
+
+.. only:: esp32c3 or esp32s3
+
+    :ref:`CONFIG_BT_CTRL_LOW_POWER_CLOCK` = Main crystal (`CONFIG_BT_CTRL_LPCLK_SEL_MAIN_XTAL`)
+
+.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61
+
+    :ref:`CONFIG_BT_LE_LP_CLK_SRC` = Use main XTAL as RTC clock source (`CONFIG_BT_LE_LP_CLK_SRC_MAIN_XTAL`)
+
+When this is selected, the main XTAL remains powered on during light-sleep, resulting in higher current consumption. Please refer to :example_file:`Power Save README <bluetooth/nimble/power_save/README.md>` for the typical current consumption in light-sleep using XTAL versus a 32 kHz external crystal.
+
+Selecting 32 kHz External Crystal
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To use a 32 kHz external crystal as the Bluetooth LE internal clock source, configure the following options:
+
+**Configuration Path 1:**
+
+.. only:: esp32
+
+    :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` = External 32 kHz crystal/oscillator (`CONFIG_BTDM_CTRL_LPCLK_SEL_EXT_32K_XTAL`)
+
+.. only:: esp32c3 or esp32s3
+
+    :ref:`CONFIG_BT_CTRL_LOW_POWER_CLOCK` = External 32 kHz crystal/oscillator (`CONFIG_BT_CTRL_LPCLK_SEL_EXT_32K_XTAL`)
+
+.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61
+
+    :ref:`CONFIG_BT_LE_LP_CLK_SRC` = Use system RTC slow clock source (`CONFIG_BT_LE_LP_CLK_SRC_DEFAULT`)
+
+**Configuration Path 2:**
+
+:ref:`CONFIG_RTC_CLK_SRC` = External 32 kHz crystal (`CONFIG_RTC_CLK_SRC_EXT_CRYS`)
+
+**Note:** Even if 32 kHz is selected in menuconfig, the system will fall back to the main XTAL if the external crystal is not detected during Bluetooth LE initialization. This may lead to unexpected current consumption in light-sleep mode.
+
+Selecting 136 kHz RC Oscillator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. only:: esp32c3 or esp32s3
+
+    To use a 136 kHz internal RC oscillator as the Bluetooth LE internal clock source, configure the following option:
+
+    **Configuration Path 1:**
+
+    :ref:`CONFIG_BT_CTRL_LOW_POWER_CLOCK` = Internal 136kHz RC oscillator (`CONFIG_BT_CTRL_LPCLK_SEL_RTC_SLOW`)
+
+    Generally, the 136 kHz RC oscillator cannot meet the accuracy requirement of Bluetooth LE. It is only suitable for scenarios with low clock accuracy requirements, such as legacy advertising (ADV) or scanning. It does not support connections in central or peripheral roles.
+
+.. only:: esp32
+
+    **Note:** ESP32 does not support using 136 kHz RC oscillator as the Bluetooth LE clock source.
+
+.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61
+
+    To use a 136 kHz internal RC oscillator as the Bluetooth LE internal clock source, configure the following options:
+
+    **Configuration Path 1:**
+
+    :ref:`CONFIG_BT_LE_LP_CLK_SRC` = Use system RTC slow clock source (`CONFIG_BT_LE_LP_CLK_SRC_DEFAULT`)
+
+.. only:: not esp32
+
+    **Configuration Path 2:**
+
+    :ref:`CONFIG_RTC_CLK_SRC` = Internal 136 kHz RC oscillator (`CONFIG_RTC_CLK_SRC_INT_RC`)
+
+.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61
+
+    If low current consumption is required but there is no access to the External 32 kHz Crystal, this clock source is recommended. However, this clock source has a sleep clock accuracy exceeding 500 PPM, which is only supported when pairing with another ESP chip. For non-ESP peer devices, the following Bluetooth LE features are not supported:
+
+    1. Central role of Connection
+    2. Advertiser of Periodic Advertising
+
+    If the peer device also uses 136 kHz RC as the clock source, the following configuration should be set:
+
+    **Configuration Path:**
+
+      - :ref:`CONFIG_BT_LE_LL_PEER_SCA_SET_ENABLE` = y
+      - :ref:`CONFIG_BT_LE_LL_PEER_SCA` = 3000
+
+    **Note:** Using the 136 kHz RC oscillator may occasionally cause issues such as connection establishment failures or connection timeouts.
+
+
+How to Check the Current Clock Source Used by Bluetooth LE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+You can check the current Bluetooth LE clock source from the initialization logs:
+
+.. list-table:: Bluetooth LE Initialization Logs and Clock Sources
+    :widths: 50 50
+    :header-rows: 1
+
+    * - Log Message
+      - Clock Source
+    * - Using main XTAL as clock source
+      - Main XTAL
+    * - Using 136 kHz RC as clock source
+      - Internal 136 kHz RC oscillator
+    * - Using external 32.768 kHz crystal as clock source
+      - External 32 kHz crystal
+    * - Using external 32.768 kHz oscillator at 32K_XP pin as clock source
+      - External 32 kHz oscillator at 32K_XP pin
+
+
+FAQ
+--------------------------------------
+
+1. Bluetooth LE ACL Connection Fails or Disconnects in Low Power Mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As explained in the clock source selection section above, when ACL connections fail to establish or unexpectedly disconnect in low power mode, first verify whether the current clock source meets Bluetooth LE accuracy requirements.
+
+
+2. Measured light-sleep Current Higher Than Expected
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+As described in the clock source selection section above, if the main XTAL is used as the clock source, it remains powered on during light-sleep, resulting in higher current consumption than other clock sources. The average current may vary depending on the specific application, Bluetooth LE configuration, and the duration spent in light-sleep. Some applications may have higher average current because Bluetooth LE is active for a larger proportion of the time transmitting and receiving.
+
+3. Unable to Enter light-sleep Mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+If Auto light-sleep is enabled but the device fails to enter light-sleep, it's usually due to insufficient IDLE time, which prevents the automatic entry conditions from being met. This can be caused by excessive logging or Bluetooth LE configurations that reduce IDLE time, such as continuous scanning.

docs/en/api-reference/system/power_management.rst

@@ -116,7 +116,7 @@ The following drivers hold the ``ESP_PM_APB_FREQ_MAX`` lock while the driver is
     - **Ethernet**: between calls to :cpp:func:`esp_eth_driver_install` and :cpp:func:`esp_eth_driver_uninstall`.
     :SOC_WIFI_SUPPORTED: - **WiFi**: between calls to :cpp:func:`esp_wifi_start` and :cpp:func:`esp_wifi_stop`. If modem sleep is enabled, the lock will be released for the periods of time when radio is disabled.
     :SOC_TWAI_SUPPORTED: - **TWAI**: between calls to :cpp:func:`twai_driver_install` and :cpp:func:`twai_driver_uninstall` (only when the clock source is set to :cpp:enumerator:`TWAI_CLK_SRC_APB`).
-    :SOC_BT_SUPPORTED and esp32: - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth Modem-sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` option is set to "External 32kHz crystal".
+    :SOC_BT_SUPPORTED and esp32: - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth Modem-sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held, unless :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` option is set to "External 32 kHz crystal".
     :SOC_BT_SUPPORTED and not esp32: - **Bluetooth**: between calls to :cpp:func:`esp_bt_controller_enable` and :cpp:func:`esp_bt_controller_disable`. If Bluetooth Modem-sleep is enabled, the ``ESP_PM_APB_FREQ_MAX`` lock will be released for the periods of time when radio is disabled. However the ``ESP_PM_NO_LIGHT_SLEEP`` lock will still be held.
     :SOC_PCNT_SUPPORTED: - **PCNT**: between calls to :cpp:func:`pcnt_unit_enable` and :cpp:func:`pcnt_unit_disable`.
     :SOC_SDM_SUPPORTED: - **Sigma-delta**: between calls to :cpp:func:`sdm_channel_enable` and :cpp:func:`sdm_channel_disable`.

docs/zh_CN/api-guides/ble/blufi.rst

@@ -435,9 +435,9 @@ ACK 帧格式 (8 bit)：
      -
 
    * - 0x8 (b’001000)
-     - 断开 BLE GATT 连接。
+     - 断开低功耗蓝牙 GATT 连接。
      -
-     - ESP 设备收到该指令后主动断开 BLE GATT 连接。
+     - ESP 设备收到该指令后主动断开低功耗蓝牙 GATT 连接。
 
    * - 0x9 (b’001001)
      - 获取 Wi-Fi 列表。

docs/zh_CN/api-guides/ble/get-started/ble-data-exchange.rst

@@ -296,7 +296,7 @@ GATT 数据操作
 动手试试
 ^^^^^^^^^^^^^^^^^^
 
-请参考 :ref:`BLE 介绍 动手试试 <nimble_gatt_server_practice>` 。
+请参考 :ref:`低功耗蓝牙介绍 动手试试 <nimble_gatt_server_practice>` 。
 
 
 代码详解