From 6bbb58401f0018c1df70e2b3cdcb3d7c53df1805 Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Thu, 30 Oct 2025 14:24:11 +0800 Subject: [PATCH 1/6] Added BLE Low Power Mode Introduction (cherry picked from commit 1e84dea7d0fc2a3cb6de8f86c9c0199aecd0130f) Co-authored-by: weiyuhan --- docs/conf_common.py | 1 + docs/en/api-guides/ble/index.rst | 1 + docs/en/api-guides/low-power-mode/index.rst | 1 + .../low-power-mode/low-power-mode-ble.rst | 210 ++++++++++++++++++ docs/zh_CN/api-guides/ble/index.rst | 1 + .../zh_CN/api-guides/low-power-mode/index.rst | 1 + .../low-power-mode/low-power-mode-ble.rst | 210 ++++++++++++++++++ 7 files changed, 425 insertions(+) create mode 100644 docs/en/api-guides/low-power-mode/low-power-mode-ble.rst create mode 100644 docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst diff --git a/docs/conf_common.py b/docs/conf_common.py index 3b7275ee562..427f7032232 100644 --- a/docs/conf_common.py +++ b/docs/conf_common.py @@ -39,6 +39,7 @@ BLE_DOCS = [ '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', diff --git a/docs/en/api-guides/ble/index.rst b/docs/en/api-guides/ble/index.rst index 80530e8262a..e9deeee59fe 100644 --- a/docs/en/api-guides/ble/index.rst +++ b/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 diff --git a/docs/en/api-guides/low-power-mode/index.rst b/docs/en/api-guides/low-power-mode/index.rst index c8d4734efb1..6b216535646 100644 --- a/docs/en/api-guides/low-power-mode/index.rst +++ b/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 diff --git a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst new file mode 100644 index 00000000000..636c3076f4d --- /dev/null +++ b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst @@ -0,0 +1,210 @@ +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 (BLE), 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, so make sure the clock source selected for BLE low power mode should meet that requirement. Otherwise BLE may not perform normally and cause a series of problem such as ACL connection establishment failure or ACL connection timeout, etc. + + +Selecting Main XTAL +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To select the main XTAL as the BLE internal clock source, configure the following option: + +.. only:: esp32 or esp32c3 or esp32s3 + + **Configuration Path:** + + ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` + + **Configuration Option:** + + - \ (X) Main crystal + +.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61 + + **Configuration Path:** + + ``Component config → Bluetooth → Controller Options → BLE low power clock source`` + + **Configuration Option:** + + - \ (X) Use main XTAL as RTC clock source + +When this is selected, the main XTAL remains powered on during light-sleep, resulting in higher current consumption. The current reference for light-sleep using XTAL versus a 32kHz external crystal is shown below: + +.. list-table:: Current Reference Values for Different Clock Sources in Light-sleep Mode + :widths: auto + :header-rows: 1 + + * - Clock Source + - Typical Light-sleep Current + * - Main XTAL + - 3.3 mA + * - 32kHz External Crystal / 136 kHz RC + - 34 uA + + +Selecting 32kHz External Crystal +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To use a 32kHz external crystal as the BLE internal clock source, configure the following options: + +.. only:: esp32 or esp32c3 or esp32s3 + + **Configuration Path:** + + ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` + + **Configuration Option:** + + - \ (X) External 32kHz crystal/oscillator + +.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61 + + **Configuration Path 1:** + + ``Component config → Bluetooth → Controller Options → BLE low power clock source`` + + **Configuration Option:** + + - \ (X) Use system RTC slow clock source + + **Configuration Path 2:** + + ``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` + + **Configuration Option:** + + - \ (X) External 32 kHz crystal + +**Note:** Even if 32kHz is selected in menuconfig, the system will fall back to the main XTAL if the external crystal is not detected during BLE 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 BLE internal clock source, configure the following option: + + **Configuration Path:** ` + + `Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` + + **Configuration Option:** + + - \ (X) Internal 136kHz RC oscillator + + Generally, the 136 kHz RC oscillator cannot meet the accuracy requirement of BLE. It is only suitable for scenarios with low clock accuracy requirements, such as legacy advertising (ADV) or scanning. + + However, for testing purposes, if the peer device also uses 136 kHz RC as the clock source, BLE can function under a 136 kHz RC clock through the following configuration: + + **Configuration Path:** + + ``Component config → Bluetooth → Controller Options`` + + **Configuration Options:** + + - \ [*] Enable to set constant peer SCA + - \ (3000) Constant peer sleep clock accuracy value + + **Note:** Using the 136 kHz RC oscillator may cause rare issues like connection drops or failures to establish a connection. + +.. only:: esp32 + + **Note:** ESP32 does not support using 136 kHz RC oscillator as the BLE clock source. + +.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61 + + To use a 136 kHz internal RC oscillator as the BLE internal clock source, configure the following options: + + **Configuration Path 1:** + + ``Component config → Bluetooth → Controller Options → BLE low power clock source`` + + **Configuration Option:** + + - \ (X) Use system RTC slow clock source + + **Configuration Path 2:** + + ``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` + + **Configuration Option:** + + - \ (X) Internal 136 kHz RC oscillator + + Generally, the 136 kHz RC oscillator cannot meet the accuracy requirement of BLE. It is only suitable for scenarios with low clock accuracy requirements, such as legacy advertising (ADV) or scanning. + + If low curent consumption is required but have no access to the External 32kHz Crystal, then this clock source is recommended. However, selecting this clock source will have the sleep clock accuracy larger than 500 PPM, which is supported if the peer device is also an ESP chip. If the peer device is not an ESP chip, here's some BLE event 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:** + + ``Component config → Bluetooth → Controller Options`` + + **Configuration Options:** + + - \ [*] Enable to set constant peer SCA + - \ (3000) Constant peer sleep clock accuracy value + + **Note:** Using the 136 kHz RC oscillator may cause rare issues like connection establishment failure or connection timeout. + + +**How to Check the Current Clock Source Used by BLE** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can determine the BLE clock source from the logs during BLE initialization: + +.. list-table:: BLE Initialization Log Messages and Clock Source Correspondence + :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. BLE 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 BLE accuracy requirements. + + +**2. Measured light-sleep Current Is Higher Than Expected** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +As introduced in the clock source selection section above, if the main XTAL is used as the clock source, it will remain powered on during light-sleep, resulting in higher current consumption than other clock sources. + +Also, BLE operates in Auto Light-sleep mode, meaning the system decides whether to enter sleep after entering IDLE. During advertising or scanning, current will be significantly higher than during light-sleep. + +Thus, the average current in low power mode is somewhere between light-sleep current and peak current (usually TX current). + +The average current can be application specific, and depends on the BLE configuration and the period of time in light-sleep mode. Some application may have larger average currrent because it has BLE taking a larger ratio of time transmitting and receiving. + +**3. Unable to Enter light-sleep Mode** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +When Auto light-sleep is enabled but the device fails to enter light-sleep, it's often due to insufficient IDLE duration, which prevents meeting the automatic light-sleep entry conditions. + +This could be caused by excessive logging or BLE configuration that prevents sufficient IDLE time, such as continuous scan mode. diff --git a/docs/zh_CN/api-guides/ble/index.rst b/docs/zh_CN/api-guides/ble/index.rst index 287977cea2a..201911777f2 100644 --- a/docs/zh_CN/api-guides/ble/index.rst +++ b/docs/zh_CN/api-guides/ble/index.rst @@ -13,6 +13,7 @@ overview ble-feature-support-status ble-qualification + 低功耗模式介绍 <../low-power-mode/low-power-mode-ble> ********** 快速入门 diff --git a/docs/zh_CN/api-guides/low-power-mode/index.rst b/docs/zh_CN/api-guides/low-power-mode/index.rst index 8c1d526cfe4..efa345c3bec 100644 --- a/docs/zh_CN/api-guides/low-power-mode/index.rst +++ b/docs/zh_CN/api-guides/low-power-mode/index.rst @@ -13,3 +13,4 @@ low-power-mode-soc :SOC_WIFI_SUPPORTED: low-power-mode-wifi + :SOC_BLE_SUPPORTED: low-power-mode-ble diff --git a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst new file mode 100644 index 00000000000..9e2c8f7d25c --- /dev/null +++ b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst @@ -0,0 +1,210 @@ +低功耗蓝牙\ :sup:`®` 场景下低功耗模式介绍 +======================================================================== + +:link_to_translation:`en:[English]` + +本节介绍低功耗蓝牙 (Bluetooth LE) 在低功耗模式下的时钟源选择，以及常见相关问题。 + +低功耗模式下的时钟源选择 +-------------------------------------------- + +在低功耗蓝牙应用场景中，由于协议要求休眠时钟精度需在 500 PPM 以内，light-sleep 和 modem-sleep 模式下所用的时钟源必须满足该要求。如果时钟精度不足，可能会出现 ACL 连接失败或超时断开等问题。**因此在使用前请确保所选时钟源及其精度满足 BLE 要求。** + + +选择主晶振 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +要选择主晶振作为 BLE 内部时钟源，请配置以下选项： + +.. only:: esp32 or esp32c3 or esp32s3 + + **配置路径：** + + ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` + + **配置选项：** + + - \ (X) Main crystal + +.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61 + + **配置路径：** + + ``Component config → Bluetooth → Controller Options → BLE low power clock source`` + + **配置选项：** + + - \ (X) Use main XTAL as RTC clock source + +选择主晶振后，light-sleep 模式下主晶振电源不会关闭，因此电流消耗更高。使用 XTAL 和 32kHz 外部晶振时 light-sleep 电流参考如下： + +.. list-table:: light-sleep 模式下不同时钟源的电流参考值 + :widths: auto + :header-rows: 1 + + * - 时钟源 + - 典型 light-sleep 电流 + * - 主晶振 + - 3.3 mA + * - 32kHz 外部晶振 / 136 kHz RC + - 34 uA + + +选择 32kHz 外部晶振 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +要使用 32kHz 外部晶振作为 BLE 内部时钟源，请配置以下选项： + +.. only:: esp32 or esp32c3 or esp32s3 + + **配置路径：** + + ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` + + **配置选项：** + + - \ (X) External 32kHz crystal/oscillator + +.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61 + + **配置路径 1：** + + ``Component config → Bluetooth → Controller Options → BLE low power clock source`` + + **配置选项：** + + - \ (X) Use system RTC slow clock source + + **配置路径 2：** + + ``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` + + **配置选项：** + + - \ (X) External 32 kHz crystal + +**注意：** 即使在 menuconfig 中选择了 32kHz 外部晶振，如果 BLE 初始化时未检测到外部晶振，系统会自动切换为主晶振，可能导致 light-sleep 电流高于预期。 + + +选择 136 kHz RC 振荡器 +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. only:: esp32c3 or esp32s3 + + 要使用 136 kHz 内部 RC 振荡器作为 BLE 内部时钟源，请配置以下选项： + + **配置路径：** + + ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` + + **配置选项：** + + - \ (X) Internal 136kHz RC oscillator + + 一般来说，136 kHz RC 振荡器难以满足 BLE 的精度要求，仅适用于对时钟精度要求不高的场景，如传统广播 (ADV) 或扫描 (SCAN)。 + + 但测试时，如果对端设备也用 136 kHz RC 作为时钟源，可通过如下配置实现 BLE 在 136 kHz RC 下运行： + + **配置路径：** + + ``Component config → Bluetooth → Controller Options`` + + **配置选项：** + + - \ [*] Enable to set constant peer SCA + - \ (3000) Constant peer sleep clock accuracy value + + **注意：** 使用 136 kHz RC 振荡器可能偶发连接断开或连接失败。 + +.. only:: esp32 + + **注意：** ESP32 不支持 136 kHz RC 振荡器作为 BLE 时钟源。 + +.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61 + + 要使用 136 kHz 内部 RC 振荡器作为 BLE 内部时钟源，请配置以下选项： + + **配置路径 1：** + + ``Component config → Bluetooth → Controller Options → BLE low power clock source`` + + **配置选项：** + + - \ (X) Use system RTC slow clock source + + **配置路径 2：** + + ``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` + + **配置选项：** + + - \ (X) Internal 136 kHz RC oscillator + + 一般来说，136 kHz RC 振荡器难以满足 BLE 的精度要求，仅适用于对时钟精度要求不高的场景，如传统广播 (ADV) 或扫描 (SCAN)。 + + 对于需要低功耗且没有32kHz外部晶振的场景下，可以选择136 kHz RC振荡器。然而这个时钟无法满足BLE的500PPM的休眠时钟精度需求。不过如果对端设备使用的是ESP芯片，仍能支持BLE行为。但是如果对端设备并非使用ESP芯片，则使用下面BLE行为将无法支持： + + 1. 作为连接的Central方 + 2. 作为Periodic Advertising的广播方 + + 如果对端设备也用 136 kHz RC 作为时钟源，需要如下配置: + + **配置路径：** + + ``Component config → Bluetooth → Controller Options`` + + **配置选项：** + + - \ [*] Enable to set constant peer SCA + - \ (3000) Constant peer sleep clock accuracy value + + **注意：** 使用 136 kHz RC 振荡器可能偶发连接断开或连接失败。 + + +**如何确认当前 BLE 使用的时钟源** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +可通过 BLE 初始化时的日志判断当前时钟源： + +.. list-table:: BLE 初始化日志与时钟源对应关系 + :widths: 50 50 + :header-rows: 1 + + * - 日志内容 + - 时钟源 + * - Using main XTAL as clock source + - 主晶振 (Main XTAL) + * - Using 136 kHz RC as clock source + - 内部 136 kHz RC 振荡器 (Internal 136 kHz RC oscillator) + * - Using external 32.768 kHz crystal as clock source + - 外部 32 kHz 晶振 (External 32 kHz crystal) + * - Using external 32.768 kHz oscillator at 32K_XP pin as clock source + - 外部 32 kHz 振荡器 (32K_XP 引脚) (External 32 kHz oscillator at 32K_XP pin) + + +常见问题 +-------------------------------------- + +**1. BLE ACL 连接在低功耗模式下建立失败或断开** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +如时钟源选择部分所述，ACL 连接建立失败或断开时，请首先检查当前时钟源是否满足 BLE 精度要求。 + + +**2. 实测 light-sleep 电流高于预期** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +如时钟源选择部分所述，若主晶振为时钟源，light-sleep 模式下主晶振持续供电，电流消耗高于其他时钟源。 + +此外，BLE 运行在 Auto Light-sleep 模式下，系统在进入 IDLE 后自动决定是否休眠。广播或扫描时电流远高于 light-sleep。 + +因此，低功耗模式下的平均电流介于 light-sleep 电流与峰值电流（通常为 TX 电流）之间。 + +一个应用程序的平均电流一般取决于在light-sleep模式下的时间，以及蓝牙的配置。如果一个应用中蓝牙收发包的时间更长，这个应用的平均电流也会更高 + +**3. 无法进入 light-sleep 模式** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +启用 Auto light-sleep 后，若设备无法进入 light-sleep，通常是 IDLE 时间不足，未满足自动进入条件。 + +这可能由日志过多或 BLE 配置导致 IDLE 时间过短（如连续扫描）引起。 From ca78edce54c5c56e43988d47e4ec56e74f4ac5c1 Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Thu, 30 Oct 2025 14:24:12 +0800 Subject: [PATCH 2/6] docs(ble): Revisied BLE Low Power Giude (cherry picked from commit 19fc7319c6751128b9cddbf8a27d38d55fb28a69) Co-authored-by: Wei Yuhan --- .../low-power-mode/low-power-mode-ble.rst | 25 ++-------------- .../low-power-mode/low-power-mode-ble.rst | 29 ++++--------------- 2 files changed, 8 insertions(+), 46 deletions(-) diff --git a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst index 636c3076f4d..7e8cd97f7af 100644 --- a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst +++ b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst @@ -101,20 +101,7 @@ Selecting 136 kHz RC Oscillator - \ (X) Internal 136kHz RC oscillator - Generally, the 136 kHz RC oscillator cannot meet the accuracy requirement of BLE. It is only suitable for scenarios with low clock accuracy requirements, such as legacy advertising (ADV) or scanning. - - However, for testing purposes, if the peer device also uses 136 kHz RC as the clock source, BLE can function under a 136 kHz RC clock through the following configuration: - - **Configuration Path:** - - ``Component config → Bluetooth → Controller Options`` - - **Configuration Options:** - - - \ [*] Enable to set constant peer SCA - - \ (3000) Constant peer sleep clock accuracy value - - **Note:** Using the 136 kHz RC oscillator may cause rare issues like connection drops or failures to establish a connection. + Generally, the 136 kHz RC oscillator cannot meet the accuracy requirement of BLE. 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 @@ -140,9 +127,7 @@ Selecting 136 kHz RC Oscillator - \ (X) Internal 136 kHz RC oscillator - Generally, the 136 kHz RC oscillator cannot meet the accuracy requirement of BLE. It is only suitable for scenarios with low clock accuracy requirements, such as legacy advertising (ADV) or scanning. - - If low curent consumption is required but have no access to the External 32kHz Crystal, then this clock source is recommended. However, selecting this clock source will have the sleep clock accuracy larger than 500 PPM, which is supported if the peer device is also an ESP chip. If the peer device is not an ESP chip, here's some BLE event not supported: + If low current consumption is required but have no access to the External 32kHz Crystal, then this clock source is recommended. However, selecting this clock source will have the sleep clock accuracy larger than 500 PPM, which is supported if the peer device is also an ESP chip. If the peer device is not an ESP chip, here's some BLE event not supported: 1. Central role of Connection 2. Advertiser of Periodic Advertising @@ -196,11 +181,7 @@ As explained in the clock source selection section above, when ACL connections f As introduced in the clock source selection section above, if the main XTAL is used as the clock source, it will remain powered on during light-sleep, resulting in higher current consumption than other clock sources. -Also, BLE operates in Auto Light-sleep mode, meaning the system decides whether to enter sleep after entering IDLE. During advertising or scanning, current will be significantly higher than during light-sleep. - -Thus, the average current in low power mode is somewhere between light-sleep current and peak current (usually TX current). - -The average current can be application specific, and depends on the BLE configuration and the period of time in light-sleep mode. Some application may have larger average currrent because it has BLE taking a larger ratio of time transmitting and receiving. +The average current can be application specific, and depends on the BLE configuration and the period of time in light-sleep mode. Some application may have larger average current because it has BLE taking a larger ratio of time transmitting and receiving. **3. Unable to Enter light-sleep Mode** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst index 9e2c8f7d25c..2e0be9b4076 100644 --- a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst +++ b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst @@ -101,20 +101,7 @@ - \ (X) Internal 136kHz RC oscillator - 一般来说，136 kHz RC 振荡器难以满足 BLE 的精度要求，仅适用于对时钟精度要求不高的场景，如传统广播 (ADV) 或扫描 (SCAN)。 - - 但测试时，如果对端设备也用 136 kHz RC 作为时钟源，可通过如下配置实现 BLE 在 136 kHz RC 下运行： - - **配置路径：** - - ``Component config → Bluetooth → Controller Options`` - - **配置选项：** - - - \ [*] Enable to set constant peer SCA - - \ (3000) Constant peer sleep clock accuracy value - - **注意：** 使用 136 kHz RC 振荡器可能偶发连接断开或连接失败。 + 一般来说，136 kHz RC 振荡器难以满足 BLE 的精度要求，仅适用于对时钟精度要求不高的场景，如传统广播 (ADV) 或扫描 (SCAN)。它不支持以中心角色或外设角色建立连接。 .. only:: esp32 @@ -140,12 +127,10 @@ - \ (X) Internal 136 kHz RC oscillator - 一般来说，136 kHz RC 振荡器难以满足 BLE 的精度要求，仅适用于对时钟精度要求不高的场景，如传统广播 (ADV) 或扫描 (SCAN)。 + 对于需要低功耗且没有 32kHz 外部晶振的场景下，可以选择 136 kHz R C振荡器。然而这个时钟无法满足 BLE 的 500PPM 的休眠时钟精度需求。不过如果对端设备使用的是 ESP 芯片，仍能支持 BLE 行为。但是如果对端设备并非使用 ESP 芯片，则使用下面 BLE 行为将无法支持： - 对于需要低功耗且没有32kHz外部晶振的场景下，可以选择136 kHz RC振荡器。然而这个时钟无法满足BLE的500PPM的休眠时钟精度需求。不过如果对端设备使用的是ESP芯片，仍能支持BLE行为。但是如果对端设备并非使用ESP芯片，则使用下面BLE行为将无法支持： - - 1. 作为连接的Central方 - 2. 作为Periodic Advertising的广播方 + 1. 作为连接的 Central 方 + 2. 作为 Periodic Advertising 的广播方 如果对端设备也用 136 kHz RC 作为时钟源，需要如下配置: @@ -196,11 +181,7 @@ 如时钟源选择部分所述，若主晶振为时钟源，light-sleep 模式下主晶振持续供电，电流消耗高于其他时钟源。 -此外，BLE 运行在 Auto Light-sleep 模式下，系统在进入 IDLE 后自动决定是否休眠。广播或扫描时电流远高于 light-sleep。 - -因此，低功耗模式下的平均电流介于 light-sleep 电流与峰值电流（通常为 TX 电流）之间。 - -一个应用程序的平均电流一般取决于在light-sleep模式下的时间，以及蓝牙的配置。如果一个应用中蓝牙收发包的时间更长，这个应用的平均电流也会更高 +平均电流可能会因具体应用而异，并取决于 BLE 的配置以及处于 light-sleep 模式的时间周期。某些应用的平均电流可能会更大，这是因为 BLE 在其中花费了更高比例的时间进行发射和接收。 **3. 无法进入 light-sleep 模式** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From 398c09a1a8d47203ded064fa4ede16dc06b0cc0d Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Thu, 30 Oct 2025 14:24:12 +0800 Subject: [PATCH 3/6] docs(ble): Replaced BLE with Bluetooth LE (cherry picked from commit acc8a99aae0b3e95fac09f8a940f3d09ade70bdb) Co-authored-by: Wei Yuhan --- .../ble/ble-feature-support-status.rst | 2 +- .../ble/get-started/ble-data-exchange.rst | 2 +- .../ble/host-feature-support-status.rst | 2 +- .../low-power-mode/low-power-mode-ble.rst | 40 +++++++++---------- docs/en/api-reference/protocols/mbedtls.rst | 2 +- docs/zh_CN/api-guides/ble/blufi.rst | 4 +- .../ble/get-started/ble-data-exchange.rst | 2 +- .../low-power-mode/low-power-mode-ble.rst | 32 +++++++-------- .../api-reference/bluetooth/esp_gap_ble.rst | 4 +- .../zh_CN/api-reference/protocols/mbedtls.rst | 2 +- 10 files changed, 46 insertions(+), 46 deletions(-) diff --git a/docs/en/api-guides/ble/ble-feature-support-status.rst b/docs/en/api-guides/ble/ble-feature-support-status.rst index 8cbe9ed1e25..706d1bb04a6 100644 --- a/docs/en/api-guides/ble/ble-feature-support-status.rst +++ b/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 `__. 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 ` . It is important to clarify that this document is not a binding commitment to our customers. diff --git a/docs/en/api-guides/ble/get-started/ble-data-exchange.rst b/docs/en/api-guides/ble/get-started/ble-data-exchange.rst index e8a00f57ef1..069074a6c76 100644 --- a/docs/en/api-guides/ble/get-started/ble-data-exchange.rst +++ b/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 ` 。 +Please refer to :ref:`Bluetooth LE Introduction Try It Out ` 。 Code Explanation diff --git a/docs/en/api-guides/ble/host-feature-support-status.rst b/docs/en/api-guides/ble/host-feature-support-status.rst index 4855371bda6..d17a95bbf9b 100644 --- a/docs/en/api-guides/ble/host-feature-support-status.rst +++ b/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 ` . |supported_def| **This feature has completed development and internal testing.** [1]_ diff --git a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst index 7e8cd97f7af..07e7c5ed5c0 100644 --- a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst +++ b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst @@ -3,18 +3,18 @@ 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 (BLE), along with common related issues. +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, so make sure the clock source selected for BLE low power mode should meet that requirement. Otherwise BLE may not perform normally and cause a series of problem such as ACL connection establishment failure or ACL connection timeout, etc. +According to the Bluetooth specification, the sleep clock accuracy must be within 500 PPM, so make sure the clock source selected for Bluetooth LE low power mode should meet that requirement. Otherwise Bluetooth LE may not perform normally and cause a series of problem such as ACL connection establishment failure or ACL connection timeout, etc. Selecting Main XTAL ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To select the main XTAL as the BLE internal clock source, configure the following option: +To select the main XTAL as the Bluetooth LE internal clock source, configure the following option: .. only:: esp32 or esp32c3 or esp32s3 @@ -53,7 +53,7 @@ When this is selected, the main XTAL remains powered on during light-sleep, resu Selecting 32kHz External Crystal ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To use a 32kHz external crystal as the BLE internal clock source, configure the following options: +To use a 32kHz external crystal as the Bluetooth LE internal clock source, configure the following options: .. only:: esp32 or esp32c3 or esp32s3 @@ -83,7 +83,7 @@ To use a 32kHz external crystal as the BLE internal clock source, configure the - \ (X) External 32 kHz crystal -**Note:** Even if 32kHz is selected in menuconfig, the system will fall back to the main XTAL if the external crystal is not detected during BLE initialization. This may lead to unexpected current consumption in light-sleep mode. +**Note:** Even if 32kHz 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 @@ -91,7 +91,7 @@ Selecting 136 kHz RC Oscillator .. only:: esp32c3 or esp32s3 - To use a 136 kHz internal RC oscillator as the BLE internal clock source, configure the following option: + To use a 136 kHz internal RC oscillator as the Bluetooth LE internal clock source, configure the following option: **Configuration Path:** ` @@ -101,15 +101,15 @@ Selecting 136 kHz RC Oscillator - \ (X) Internal 136kHz RC oscillator - Generally, the 136 kHz RC oscillator cannot meet the accuracy requirement of BLE. 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. + 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 BLE clock source. + **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 BLE internal clock source, configure the following options: + To use a 136 kHz internal RC oscillator as the Bluetooth LE internal clock source, configure the following options: **Configuration Path 1:** @@ -127,7 +127,7 @@ Selecting 136 kHz RC Oscillator - \ (X) Internal 136 kHz RC oscillator - If low current consumption is required but have no access to the External 32kHz Crystal, then this clock source is recommended. However, selecting this clock source will have the sleep clock accuracy larger than 500 PPM, which is supported if the peer device is also an ESP chip. If the peer device is not an ESP chip, here's some BLE event not supported: + If low current consumption is required but have no access to the External 32kHz Crystal, then this clock source is recommended. However, selecting this clock source will have the sleep clock accuracy larger than 500 PPM, which is supported if the peer device is also an ESP chip. If the peer device is not an ESP chip, here's some Bluetooth LE event not supported: 1. Central role of Connection 2. Advertiser of Periodic Advertising @@ -146,12 +146,12 @@ Selecting 136 kHz RC Oscillator **Note:** Using the 136 kHz RC oscillator may cause rare issues like connection establishment failure or connection timeout. -**How to Check the Current Clock Source Used by BLE** -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**How to Check the Current Clock Source Used by Bluetooth LE** +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You can determine the BLE clock source from the logs during BLE initialization: +You can determine the Bluetooth LE clock source from the logs during Bluetooth LE initialization: -.. list-table:: BLE Initialization Log Messages and Clock Source Correspondence +.. list-table:: Bluetooth LE Initialization Log Messages and Clock Source Correspondence :widths: 50 50 :header-rows: 1 @@ -170,22 +170,22 @@ You can determine the BLE clock source from the logs during BLE initialization: FAQ -------------------------------------- -**1. BLE ACL Connection Fails or Disconnects in Low Power Mode** -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +**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 BLE accuracy requirements. +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 Is Higher Than Expected** -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ As introduced in the clock source selection section above, if the main XTAL is used as the clock source, it will remain powered on during light-sleep, resulting in higher current consumption than other clock sources. -The average current can be application specific, and depends on the BLE configuration and the period of time in light-sleep mode. Some application may have larger average current because it has BLE taking a larger ratio of time transmitting and receiving. +The average current can be application specific, and depends on the Bluetooth LE configuration and the period of time in light-sleep mode. Some application may have larger average current because it has Bluetooth LE taking a larger ratio of time transmitting and receiving. **3. Unable to Enter light-sleep Mode** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When Auto light-sleep is enabled but the device fails to enter light-sleep, it's often due to insufficient IDLE duration, which prevents meeting the automatic light-sleep entry conditions. -This could be caused by excessive logging or BLE configuration that prevents sufficient IDLE time, such as continuous scan mode. +This could be caused by excessive logging or Bluetooth LE configuration that prevents sufficient IDLE time, such as continuous scan mode. diff --git a/docs/en/api-reference/protocols/mbedtls.rst b/docs/en/api-reference/protocols/mbedtls.rst index 86e79a9b846..cd33f9b82f3 100644 --- a/docs/en/api-reference/protocols/mbedtls.rst +++ b/docs/en/api-reference/protocols/mbedtls.rst @@ -66,7 +66,7 @@ ESP-IDF provides a preset-based configuration system for Mbed TLS to simplify se • Basic X.509 parsing * - **Bluetooth (BT)** - Bluetooth applications - - • Optimized for BLE security + - • Optimized for Bluetooth LE security • ECC P-256 curve support • Minimal TLS overhead • Bluetooth-specific algorithms diff --git a/docs/zh_CN/api-guides/ble/blufi.rst b/docs/zh_CN/api-guides/ble/blufi.rst index ab562967078..efed5748826 100644 --- a/docs/zh_CN/api-guides/ble/blufi.rst +++ b/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 列表。 diff --git a/docs/zh_CN/api-guides/ble/get-started/ble-data-exchange.rst b/docs/zh_CN/api-guides/ble/get-started/ble-data-exchange.rst index e40863f6db5..021518aabc3 100644 --- a/docs/zh_CN/api-guides/ble/get-started/ble-data-exchange.rst +++ b/docs/zh_CN/api-guides/ble/get-started/ble-data-exchange.rst @@ -296,7 +296,7 @@ GATT 数据操作 动手试试 ^^^^^^^^^^^^^^^^^^ -请参考 :ref:`BLE 介绍 动手试试 ` 。 +请参考 :ref:`低功耗蓝牙介绍 动手试试 ` 。 代码详解 diff --git a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst index 2e0be9b4076..121f19fe654 100644 --- a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst +++ b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst @@ -8,13 +8,13 @@ 低功耗模式下的时钟源选择 -------------------------------------------- -在低功耗蓝牙应用场景中，由于协议要求休眠时钟精度需在 500 PPM 以内，light-sleep 和 modem-sleep 模式下所用的时钟源必须满足该要求。如果时钟精度不足，可能会出现 ACL 连接失败或超时断开等问题。**因此在使用前请确保所选时钟源及其精度满足 BLE 要求。** +在低功耗蓝牙应用场景中，由于协议要求休眠时钟精度需在 500 PPM 以内，light-sleep 和 modem-sleep 模式下所用的时钟源必须满足该要求。如果时钟精度不足，可能会出现 ACL 连接失败或超时断开等问题。**因此在使用前请确保所选时钟源及其精度满 要求。** 选择主晶振 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -要选择主晶振作为 BLE 内部时钟源，请配置以下选项： +要选择主晶振作为低功耗蓝牙内部时钟源，请配置以下选项： .. only:: esp32 or esp32c3 or esp32s3 @@ -53,7 +53,7 @@ 选择 32kHz 外部晶振 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -要使用 32kHz 外部晶振作为 BLE 内部时钟源，请配置以下选项： +要使用 32kHz 外部晶振作为低功耗蓝牙内部时钟源，请配置以下选项： .. only:: esp32 or esp32c3 or esp32s3 @@ -83,7 +83,7 @@ - \ (X) External 32 kHz crystal -**注意：** 即使在 menuconfig 中选择了 32kHz 外部晶振，如果 BLE 初始化时未检测到外部晶振，系统会自动切换为主晶振，可能导致 light-sleep 电流高于预期。 +**注意：** 即使在 menuconfig 中选择了 32kHz 外部晶振，如果低功耗蓝牙初始化时未检测到外部晶振，系统会自动切换为主晶振，可能导致 light-sleep 电流高于预期。 选择 136 kHz RC 振荡器 @@ -91,7 +91,7 @@ .. only:: esp32c3 or esp32s3 - 要使用 136 kHz 内部 RC 振荡器作为 BLE 内部时钟源，请配置以下选项： + 要使用 136 kHz 内部 RC 振荡器作为低功耗蓝牙内部时钟源，请配置以下选项： **配置路径：** @@ -101,15 +101,15 @@ - \ (X) Internal 136kHz RC oscillator - 一般来说，136 kHz RC 振荡器难以满足 BLE 的精度要求，仅适用于对时钟精度要求不高的场景，如传统广播 (ADV) 或扫描 (SCAN)。它不支持以中心角色或外设角色建立连接。 + 一般来说，136 kHz RC 振荡器难以满足低功耗蓝牙的精度要求，仅适用于对时钟精度要求不高的场景，如传统广播 (ADV) 或扫描 (SCAN)。它不支持以中心角色或外设角色建立连接。 .. only:: esp32 - **注意：** ESP32 不支持 136 kHz RC 振荡器作为 BLE 时钟源。 + **注意：** ESP32 不支持 136 kHz RC 振荡器作为低功耗蓝牙时钟源。 .. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61 - 要使用 136 kHz 内部 RC 振荡器作为 BLE 内部时钟源，请配置以下选项： + 要使用 136 kHz 内部 RC 振荡器作为低功耗蓝牙内部时钟源，请配置以下选项： **配置路径 1：** @@ -127,7 +127,7 @@ - \ (X) Internal 136 kHz RC oscillator - 对于需要低功耗且没有 32kHz 外部晶振的场景下，可以选择 136 kHz R C振荡器。然而这个时钟无法满足 BLE 的 500PPM 的休眠时钟精度需求。不过如果对端设备使用的是 ESP 芯片，仍能支持 BLE 行为。但是如果对端设备并非使用 ESP 芯片，则使用下面 BLE 行为将无法支持： + 对于需要低功耗且没有 32kHz 外部晶振的场景下，可以选择 136 kHz R C振荡器。然而这个时钟无法满足低功耗蓝牙的 500PPM 的休眠时钟精度需求。不过如果对端设备使用的是 ESP 芯片，仍能支持低功耗蓝牙行为。但是如果对端设备并非使用 ESP 芯片，则使用下面低功耗蓝牙行为将无法支持： 1. 作为连接的 Central 方 2. 作为 Periodic Advertising 的广播方 @@ -146,12 +146,12 @@ **注意：** 使用 136 kHz RC 振荡器可能偶发连接断开或连接失败。 -**如何确认当前 BLE 使用的时钟源** +**如何确认当前低功耗蓝牙使用的时钟源** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -可通过 BLE 初始化时的日志判断当前时钟源： +可通过低功耗蓝牙初始化时的日志判断当前时钟源： -.. list-table:: BLE 初始化日志与时钟源对应关系 +.. list-table:: 低功耗蓝牙初始化日志与时钟源对应关系 :widths: 50 50 :header-rows: 1 @@ -170,10 +170,10 @@ 常见问题 -------------------------------------- -**1. BLE ACL 连接在低功耗模式下建立失败或断开** +**1. 低功耗蓝牙 ACL 连接在低功耗模式下建立失败或断开** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -如时钟源选择部分所述，ACL 连接建立失败或断开时，请首先检查当前时钟源是否满足 BLE 精度要求。 +如时钟源选择部分所述，ACL 连接建立失败或断开时，请首先检查当前时钟源是否满足低功耗蓝牙精度要求。 **2. 实测 light-sleep 电流高于预期** @@ -181,11 +181,11 @@ 如时钟源选择部分所述，若主晶振为时钟源，light-sleep 模式下主晶振持续供电，电流消耗高于其他时钟源。 -平均电流可能会因具体应用而异，并取决于 BLE 的配置以及处于 light-sleep 模式的时间周期。某些应用的平均电流可能会更大，这是因为 BLE 在其中花费了更高比例的时间进行发射和接收。 +平均电流可能会因具体应用而异，并取决于低功耗蓝牙的配置以及处于 light-sleep 模式的时间周期。某些应用的平均电流可能会更大，这是因为低功耗蓝牙在其中花费了更高比例的时间进行发射和接收。 **3. 无法进入 light-sleep 模式** ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 启用 Auto light-sleep 后，若设备无法进入 light-sleep，通常是 IDLE 时间不足，未满足自动进入条件。 -这可能由日志过多或 BLE 配置导致 IDLE 时间过短（如连续扫描）引起。 +这可能由日志过多或低功耗蓝牙配置导致 IDLE 时间过短（如连续扫描）引起。 diff --git a/docs/zh_CN/api-reference/bluetooth/esp_gap_ble.rst b/docs/zh_CN/api-reference/bluetooth/esp_gap_ble.rst index a215413f16c..53a0e24718d 100644 --- a/docs/zh_CN/api-reference/bluetooth/esp_gap_ble.rst +++ b/docs/zh_CN/api-reference/bluetooth/esp_gap_ble.rst @@ -6,9 +6,9 @@ GAP API 应用示例 ------------------- -- :example:`bluetooth/bluedroid/ble/gatt_security_client` 演示使用 ESP BLE security API，{IDF_TARGET_NAME} 作为 GATT 客户端时如何建立安全连接并加密与对等设备的通信。 +- :example:`bluetooth/bluedroid/ble/gatt_security_client` 演示使用 ESP 低功耗蓝牙 security API，{IDF_TARGET_NAME} 作为 GATT 客户端时如何建立安全连接并加密与对等设备的通信。 -- :example:`bluetooth/bluedroid/ble/gatt_security_server` 演示使用 ESP BLE security API，{IDF_TARGET_NAME} 作为 GATT 服务器时如何建立安全连接并加密与对等设备的通信。 +- :example:`bluetooth/bluedroid/ble/gatt_security_server` 演示使用 ESP 低功耗蓝牙 security API，{IDF_TARGET_NAME} 作为 GATT 服务器时如何建立安全连接并加密与对等设备的通信。 API 参考 ------------- diff --git a/docs/zh_CN/api-reference/protocols/mbedtls.rst b/docs/zh_CN/api-reference/protocols/mbedtls.rst index 53b0a0cd185..3f06d882844 100644 --- a/docs/zh_CN/api-reference/protocols/mbedtls.rst +++ b/docs/zh_CN/api-reference/protocols/mbedtls.rst @@ -66,7 +66,7 @@ ESP-IDF 为 Mbed TLS 提供了基于预设的配置系统，用于简化设置 • 基本的 X.509 解析 * - **蓝牙 (BT)** - 蓝牙应用 - - • 针对 BLE 安全性需求进行优化 + - • 针对低功耗蓝牙安全性需求进行优化 • 支持 ECC P-256 曲线 • 最小的 TLS 开销 • 蓝牙特定算法 From 1ed76f53ecfaa458a1ab3123747bb9ffc8ebcb79 Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Thu, 30 Oct 2025 14:24:13 +0800 Subject: [PATCH 4/6] docs(ble): Fixed the common operation path for all chips (cherry picked from commit c55a1180ebeb720252f70f573b6a25d2679a94e4) Co-authored-by: Wei Yuhan --- .../low-power-mode/low-power-mode-ble.rst | 16 ++++++++++------ .../low-power-mode/low-power-mode-ble.rst | 18 +++++++++++------- 2 files changed, 21 insertions(+), 13 deletions(-) diff --git a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst index 07e7c5ed5c0..42738b65475 100644 --- a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst +++ b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst @@ -57,7 +57,7 @@ To use a 32kHz external crystal as the Bluetooth LE internal clock source, confi .. only:: esp32 or esp32c3 or esp32s3 - **Configuration Path:** + **Configuration Path 1:** ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` @@ -75,13 +75,13 @@ To use a 32kHz external crystal as the Bluetooth LE internal clock source, confi - \ (X) Use system RTC slow clock source - **Configuration Path 2:** +**Configuration Path 2:** - ``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` +``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` - **Configuration Option:** +**Configuration Option:** - - \ (X) External 32 kHz crystal + - \ (X) External 32 kHz crystal **Note:** Even if 32kHz 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. @@ -93,7 +93,7 @@ Selecting 136 kHz RC Oscillator To use a 136 kHz internal RC oscillator as the Bluetooth LE internal clock source, configure the following option: - **Configuration Path:** ` + **Configuration Path 1:** `Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` @@ -119,6 +119,8 @@ Selecting 136 kHz RC Oscillator - \ (X) Use system RTC slow clock source +.. only:: not esp32 + **Configuration Path 2:** ``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` @@ -127,6 +129,8 @@ Selecting 136 kHz RC Oscillator - \ (X) Internal 136 kHz RC oscillator +.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61 + If low current consumption is required but have no access to the External 32kHz Crystal, then this clock source is recommended. However, selecting this clock source will have the sleep clock accuracy larger than 500 PPM, which is supported if the peer device is also an ESP chip. If the peer device is not an ESP chip, here's some Bluetooth LE event not supported: 1. Central role of Connection diff --git a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst index 121f19fe654..8fa171dfb60 100644 --- a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst +++ b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst @@ -8,7 +8,7 @@ 低功耗模式下的时钟源选择 -------------------------------------------- -在低功耗蓝牙应用场景中，由于协议要求休眠时钟精度需在 500 PPM 以内，light-sleep 和 modem-sleep 模式下所用的时钟源必须满足该要求。如果时钟精度不足，可能会出现 ACL 连接失败或超时断开等问题。**因此在使用前请确保所选时钟源及其精度满 要求。** +在低功耗蓝牙应用场景中，由于协议要求休眠时钟精度需在 500 PPM 以内，light-sleep 和 modem-sleep 模式下所用的时钟源必须满足该要求。如果时钟精度不足，可能会出现 ACL 连接失败或超时断开等问题。**因此在使用前请确保所选时钟源及其精度满足要求。** 选择主晶振 @@ -57,7 +57,7 @@ .. only:: esp32 or esp32c3 or esp32s3 - **配置路径：** + **配置路径 1：** ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` @@ -75,13 +75,13 @@ - \ (X) Use system RTC slow clock source - **配置路径 2：** +**配置路径 2：** - ``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` +``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` - **配置选项：** +**配置选项：** - - \ (X) External 32 kHz crystal +- \ (X) External 32 kHz crystal **注意：** 即使在 menuconfig 中选择了 32kHz 外部晶振，如果低功耗蓝牙初始化时未检测到外部晶振，系统会自动切换为主晶振，可能导致 light-sleep 电流高于预期。 @@ -93,7 +93,7 @@ 要使用 136 kHz 内部 RC 振荡器作为低功耗蓝牙内部时钟源，请配置以下选项： - **配置路径：** + **配置路径 1：** ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` @@ -119,6 +119,8 @@ - \ (X) Use system RTC slow clock source +.. only:: not esp32 + **配置路径 2：** ``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` @@ -127,6 +129,8 @@ - \ (X) Internal 136 kHz RC oscillator +.. only:: esp32c2 or esp32c6 or esp32h2 or esp32c5 or esp32c61 + 对于需要低功耗且没有 32kHz 外部晶振的场景下，可以选择 136 kHz R C振荡器。然而这个时钟无法满足低功耗蓝牙的 500PPM 的休眠时钟精度需求。不过如果对端设备使用的是 ESP 芯片，仍能支持低功耗蓝牙行为。但是如果对端设备并非使用 ESP 芯片，则使用下面低功耗蓝牙行为将无法支持： 1. 作为连接的 Central 方 From b6e0ab8ca56094b26b586497251ec3cf8f792eee Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Thu, 30 Oct 2025 14:24:13 +0800 Subject: [PATCH 5/6] docs(ble): Replaced the current table with the link to the Power Save README (cherry picked from commit 13b04ab89eafebcec225bc95aa821ef86d46fd4b) Co-authored-by: Wei Yuhan --- .../low-power-mode/low-power-mode-ble.rst | 15 ++------------- .../low-power-mode/low-power-mode-ble.rst | 15 ++------------- 2 files changed, 4 insertions(+), 26 deletions(-) diff --git a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst index 42738b65475..1d3ee25923c 100644 --- a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst +++ b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst @@ -36,19 +36,8 @@ To select the main XTAL as the Bluetooth LE internal clock source, configure the - \ (X) Use main XTAL as RTC clock source -When this is selected, the main XTAL remains powered on during light-sleep, resulting in higher current consumption. The current reference for light-sleep using XTAL versus a 32kHz external crystal is shown below: - -.. list-table:: Current Reference Values for Different Clock Sources in Light-sleep Mode - :widths: auto - :header-rows: 1 - - * - Clock Source - - Typical Light-sleep Current - * - Main XTAL - - 3.3 mA - * - 32kHz External Crystal / 136 kHz RC - - 34 uA - +When this is selected, the main XTAL remains powered on during light-sleep, resulting in higher current consumption. +Please refer :example_file:`Power Save README ` for the typical current consumption in light-sleep using XTAL versus a 32kHz external crystal. Selecting 32kHz External Crystal ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst index 8fa171dfb60..345ec179ad4 100644 --- a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst +++ b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst @@ -36,19 +36,8 @@ - \ (X) Use main XTAL as RTC clock source -选择主晶振后，light-sleep 模式下主晶振电源不会关闭，因此电流消耗更高。使用 XTAL 和 32kHz 外部晶振时 light-sleep 电流参考如下： - -.. list-table:: light-sleep 模式下不同时钟源的电流参考值 - :widths: auto - :header-rows: 1 - - * - 时钟源 - - 典型 light-sleep 电流 - * - 主晶振 - - 3.3 mA - * - 32kHz 外部晶振 / 136 kHz RC - - 34 uA - +选择主晶振后，light-sleep 模式下主晶振电源不会关闭，因此电流消耗更高。 +有关使用主晶振与 32kHz 外部晶振在 light-sleep 模式下的典型电流消耗，请参考 :example_file:`Power Save README ` 。 选择 32kHz 外部晶振 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ From f8538218a896f9ff97ee0ce7b179cb9b18499caa Mon Sep 17 00:00:00 2001 From: Wei Yu Han Date: Thu, 30 Oct 2025 14:24:13 +0800 Subject: [PATCH 6/6] docs(ble): Optimized the BLE low power guide (cherry picked from commit 8c90e65db64414b3cd66a6f18ec5138483b2df51) Co-authored-by: Wei Yu Han --- .../ble/get-started/ble-data-exchange.rst | 2 +- .../low-power-mode/low-power-mode-ble.rst | 107 ++++++------------ .../api-reference/system/power_management.rst | 2 +- .../low-power-mode/low-power-mode-ble.rst | 97 +++++----------- 4 files changed, 63 insertions(+), 145 deletions(-) diff --git a/docs/en/api-guides/ble/get-started/ble-data-exchange.rst b/docs/en/api-guides/ble/get-started/ble-data-exchange.rst index 069074a6c76..006c134438f 100644 --- a/docs/en/api-guides/ble/get-started/ble-data-exchange.rst +++ b/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:`Bluetooth LE Introduction Try It Out ` 。 +Please refer to :ref:`Bluetooth LE Introduction Try It Out `. Code Explanation diff --git a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst index 1d3ee25923c..6a2760507f6 100644 --- a/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst +++ b/docs/en/api-guides/low-power-mode/low-power-mode-ble.rst @@ -8,72 +8,51 @@ This section introduces clock source selection in low power modes for Bluetooth Clock Source Selection in Low Power Mode -------------------------------------------- -According to the Bluetooth specification, the sleep clock accuracy must be within 500 PPM, so make sure the clock source selected for Bluetooth LE low power mode should meet that requirement. Otherwise Bluetooth LE may not perform normally and cause a series of problem such as ACL connection establishment failure or ACL connection timeout, etc. - +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 or esp32c3 or esp32s3 +.. only:: esp32 - **Configuration Path:** + :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` = Main crystal (`CONFIG_BTDM_CTRL_LPCLK_SEL_MAIN_XTAL`) - ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` +.. only:: esp32c3 or esp32s3 - **Configuration Option:** - - - \ (X) Main crystal + :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 - **Configuration Path:** + :ref:`CONFIG_BT_LE_LP_CLK_SRC` = Use main XTAL as RTC clock source (`CONFIG_BT_LE_LP_CLK_SRC_MAIN_XTAL`) - ``Component config → Bluetooth → Controller Options → BLE low power clock source`` +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 ` for the typical current consumption in light-sleep using XTAL versus a 32 kHz external crystal. - **Configuration Option:** - - - \ (X) Use main XTAL as RTC clock source - -When this is selected, the main XTAL remains powered on during light-sleep, resulting in higher current consumption. -Please refer :example_file:`Power Save README ` for the typical current consumption in light-sleep using XTAL versus a 32kHz external crystal. - -Selecting 32kHz External Crystal +Selecting 32 kHz External Crystal ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -To use a 32kHz external crystal as the Bluetooth LE internal clock source, configure the following options: +To use a 32 kHz external crystal as the Bluetooth LE internal clock source, configure the following options: -.. only:: esp32 or esp32c3 or esp32s3 +**Configuration Path 1:** - **Configuration Path 1:** +.. only:: esp32 - ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` + :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` = External 32 kHz crystal/oscillator (`CONFIG_BTDM_CTRL_LPCLK_SEL_EXT_32K_XTAL`) - **Configuration Option:** +.. only:: esp32c3 or esp32s3 - - \ (X) External 32kHz crystal/oscillator + :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 - **Configuration Path 1:** - - ``Component config → Bluetooth → Controller Options → BLE low power clock source`` - - **Configuration Option:** - - - \ (X) Use system RTC slow clock source + :ref:`CONFIG_BT_LE_LP_CLK_SRC` = Use system RTC slow clock source (`CONFIG_BT_LE_LP_CLK_SRC_DEFAULT`) **Configuration Path 2:** -``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` - -**Configuration Option:** - - - \ (X) External 32 kHz crystal - -**Note:** Even if 32kHz 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. +: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 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -84,11 +63,7 @@ Selecting 136 kHz RC Oscillator **Configuration Path 1:** - `Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` - - **Configuration Option:** - - - \ (X) Internal 136kHz RC oscillator + :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. @@ -102,25 +77,17 @@ Selecting 136 kHz RC Oscillator **Configuration Path 1:** - ``Component config → Bluetooth → Controller Options → BLE low power clock source`` - - **Configuration Option:** - - - \ (X) Use system RTC slow clock source + :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:** - ``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` - - **Configuration Option:** - - - \ (X) Internal 136 kHz RC oscillator + :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 have no access to the External 32kHz Crystal, then this clock source is recommended. However, selecting this clock source will have the sleep clock accuracy larger than 500 PPM, which is supported if the peer device is also an ESP chip. If the peer device is not an ESP chip, here's some Bluetooth LE event not supported: + 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 @@ -129,22 +96,18 @@ Selecting 136 kHz RC Oscillator **Configuration Path:** - ``Component config → Bluetooth → Controller Options`` + - :ref:`CONFIG_BT_LE_LL_PEER_SCA_SET_ENABLE` = y + - :ref:`CONFIG_BT_LE_LL_PEER_SCA` = 3000 - **Configuration Options:** - - - \ [*] Enable to set constant peer SCA - - \ (3000) Constant peer sleep clock accuracy value - - **Note:** Using the 136 kHz RC oscillator may cause rare issues like connection establishment failure or connection timeout. + **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** +How to Check the Current Clock Source Used by Bluetooth LE ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -You can determine the Bluetooth LE clock source from the logs during Bluetooth LE initialization: +You can check the current Bluetooth LE clock source from the initialization logs: -.. list-table:: Bluetooth LE Initialization Log Messages and Clock Source Correspondence +.. list-table:: Bluetooth LE Initialization Logs and Clock Sources :widths: 50 50 :header-rows: 1 @@ -163,22 +126,18 @@ You can determine the Bluetooth LE clock source from the logs during Bluetooth L FAQ -------------------------------------- -**1. Bluetooth LE ACL Connection Fails or Disconnects in Low Power Mode** +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 Is Higher Than Expected** -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +2. Measured light-sleep Current Higher Than Expected +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -As introduced in the clock source selection section above, if the main XTAL is used as the clock source, it will remain powered on during light-sleep, resulting in higher current consumption than other clock sources. +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. -The average current can be application specific, and depends on the Bluetooth LE configuration and the period of time in light-sleep mode. Some application may have larger average current because it has Bluetooth LE taking a larger ratio of time transmitting and receiving. - -**3. Unable to Enter light-sleep Mode** +3. Unable to Enter light-sleep Mode ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When Auto light-sleep is enabled but the device fails to enter light-sleep, it's often due to insufficient IDLE duration, which prevents meeting the automatic light-sleep entry conditions. - -This could be caused by excessive logging or Bluetooth LE configuration that prevents sufficient IDLE time, such as continuous scan 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. diff --git a/docs/en/api-reference/system/power_management.rst b/docs/en/api-reference/system/power_management.rst index 7d96d7f8d9b..a8c164ee9f8 100644 --- a/docs/en/api-reference/system/power_management.rst +++ b/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`. diff --git a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst index 345ec179ad4..0f2aabe1ef5 100644 --- a/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst +++ b/docs/zh_CN/api-guides/low-power-mode/low-power-mode-ble.rst @@ -10,70 +10,49 @@ 在低功耗蓝牙应用场景中，由于协议要求休眠时钟精度需在 500 PPM 以内，light-sleep 和 modem-sleep 模式下所用的时钟源必须满足该要求。如果时钟精度不足，可能会出现 ACL 连接失败或超时断开等问题。**因此在使用前请确保所选时钟源及其精度满足要求。** - 选择主晶振 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 要选择主晶振作为低功耗蓝牙内部时钟源，请配置以下选项： -.. only:: esp32 or esp32c3 or esp32s3 +.. only:: esp32 - **配置路径：** + :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` = Main crystal (`CONFIG_BTDM_CTRL_LPCLK_SEL_MAIN_XTAL`) - ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` +.. only:: esp32c3 or esp32s3 - **配置选项：** - - - \ (X) Main crystal + :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`) - ``Component config → Bluetooth → Controller Options → BLE low power clock source`` +选择主晶振后，light-sleep 模式下主晶振电源不会关闭，因此电流消耗更高。有关使用主晶振与 32 kHz 外部晶振在 light-sleep 模式下的典型电流消耗，请参考 :example_file:`Power Save README ` 。 - **配置选项：** - - - \ (X) Use main XTAL as RTC clock source - -选择主晶振后，light-sleep 模式下主晶振电源不会关闭，因此电流消耗更高。 -有关使用主晶振与 32kHz 外部晶振在 light-sleep 模式下的典型电流消耗，请参考 :example_file:`Power Save README ` 。 - -选择 32kHz 外部晶振 +选择 32 kHz 外部晶振 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -要使用 32kHz 外部晶振作为低功耗蓝牙内部时钟源，请配置以下选项： +要使用 32 kHz 外部晶振作为低功耗蓝牙内部时钟源，请配置以下选项： -.. only:: esp32 or esp32c3 or esp32s3 +**配置路径 1：** - **配置路径 1：** +.. only:: esp32 - ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` + :ref:`CONFIG_BTDM_CTRL_LOW_POWER_CLOCK` = External 32 kHz crystal/oscillator (`CONFIG_BTDM_CTRL_LPCLK_SEL_EXT_32K_XTAL`) - **配置选项：** +.. only:: esp32c3 or esp32s3 - - \ (X) External 32kHz crystal/oscillator + :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 - **配置路径 1：** - - ``Component config → Bluetooth → Controller Options → BLE low power clock source`` - - **配置选项：** - - - \ (X) Use system RTC slow clock source + :ref:`CONFIG_BT_LE_LP_CLK_SRC` = Use system RTC slow clock source (`CONFIG_BT_LE_LP_CLK_SRC_DEFAULT`) **配置路径 2：** -``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` - -**配置选项：** - -- \ (X) External 32 kHz crystal - -**注意：** 即使在 menuconfig 中选择了 32kHz 外部晶振，如果低功耗蓝牙初始化时未检测到外部晶振，系统会自动切换为主晶振，可能导致 light-sleep 电流高于预期。 +:ref:`CONFIG_RTC_CLK_SRC` = External 32 kHz crystal (`CONFIG_RTC_CLK_SRC_EXT_CRYS`) +**注意：** 即使在 menuconfig 中选择了 32 kHz 外部晶振，如果低功耗蓝牙初始化时未检测到外部晶振，系统会自动切换为主晶振，可能导致 light-sleep 电流高于预期。 选择 136 kHz RC 振荡器 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -84,11 +63,7 @@ **配置路径 1：** - ``Component config → Bluetooth → Controller Options → MODEM SLEEP Options → Bluetooth modem sleep → Bluetooth Modem sleep Mode 1 → Bluetooth low power clock`` - - **配置选项：** - - - \ (X) Internal 136kHz RC oscillator + :ref:`CONFIG_BT_CTRL_LOW_POWER_CLOCK` = Internal 136kHz RC oscillator (`CONFIG_BT_CTRL_LPCLK_SEL_RTC_SLOW`) 一般来说，136 kHz RC 振荡器难以满足低功耗蓝牙的精度要求，仅适用于对时钟精度要求不高的场景，如传统广播 (ADV) 或扫描 (SCAN)。它不支持以中心角色或外设角色建立连接。 @@ -102,25 +77,17 @@ **配置路径 1：** - ``Component config → Bluetooth → Controller Options → BLE low power clock source`` - - **配置选项：** - - - \ (X) Use system RTC slow clock source + :ref:`CONFIG_BT_LE_LP_CLK_SRC` = Use system RTC slow clock source (`CONFIG_BT_LE_LP_CLK_SRC_DEFAULT`) .. only:: not esp32 **配置路径 2：** - ``Component config → Hardware Settings → RTC Clock Config → RTC clock source`` - - **配置选项：** - - - \ (X) Internal 136 kHz RC oscillator + :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 - 对于需要低功耗且没有 32kHz 外部晶振的场景下，可以选择 136 kHz R C振荡器。然而这个时钟无法满足低功耗蓝牙的 500PPM 的休眠时钟精度需求。不过如果对端设备使用的是 ESP 芯片，仍能支持低功耗蓝牙行为。但是如果对端设备并非使用 ESP 芯片，则使用下面低功耗蓝牙行为将无法支持： + 对于需要低功耗且没有 32 kHz 外部晶振的场景，可以选择 136 kHz RC 振荡器。然而，该时钟无法满足低功耗蓝牙的 500 PPM 的休眠时钟精度需求。如果对端设备使用 ESP 芯片，低功耗蓝牙功能仍可正常工作；但如果对端设备不是 ESP 芯片，则以下低功耗蓝牙行为将无法支持： 1. 作为连接的 Central 方 2. 作为 Periodic Advertising 的广播方 @@ -129,17 +96,13 @@ **配置路径：** - ``Component config → Bluetooth → Controller Options`` - - **配置选项：** - - - \ [*] Enable to set constant peer SCA - - \ (3000) Constant peer sleep clock accuracy value + - :ref:`CONFIG_BT_LE_LL_PEER_SCA_SET_ENABLE` = y + - :ref:`CONFIG_BT_LE_LL_PEER_SCA` = 3000 **注意：** 使用 136 kHz RC 振荡器可能偶发连接断开或连接失败。 -**如何确认当前低功耗蓝牙使用的时钟源** +如何确认当前低功耗蓝牙使用的时钟源 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 可通过低功耗蓝牙初始化时的日志判断当前时钟源： @@ -163,22 +126,18 @@ 常见问题 -------------------------------------- -**1. 低功耗蓝牙 ACL 连接在低功耗模式下建立失败或断开** +1. 低功耗蓝牙 ACL 连接在低功耗模式下建立失败或断开 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 如时钟源选择部分所述，ACL 连接建立失败或断开时，请首先检查当前时钟源是否满足低功耗蓝牙精度要求。 -**2. 实测 light-sleep 电流高于预期** +2. 实测 light-sleep 电流高于预期 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -如时钟源选择部分所述，若主晶振为时钟源，light-sleep 模式下主晶振持续供电，电流消耗高于其他时钟源。 +如时钟源选择部分所述，若主晶振为时钟源，light-sleep 模式下主晶振持续供电，电流消耗高于其他时钟源。平均电流可能会因具体应用而异，并取决于低功耗蓝牙的配置以及处于 light-sleep 模式的时间周期。某些应用的平均电流可能会更大，这是因为低功耗蓝牙在其中花费了更高比例的时间进行发射和接收。 -平均电流可能会因具体应用而异，并取决于低功耗蓝牙的配置以及处于 light-sleep 模式的时间周期。某些应用的平均电流可能会更大，这是因为低功耗蓝牙在其中花费了更高比例的时间进行发射和接收。 - -**3. 无法进入 light-sleep 模式** +3. 无法进入 light-sleep 模式 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -启用 Auto light-sleep 后，若设备无法进入 light-sleep，通常是 IDLE 时间不足，未满足自动进入条件。 - -这可能由日志过多或低功耗蓝牙配置导致 IDLE 时间过短（如连续扫描）引起。 +启用 Auto light-sleep 后，若设备无法进入 light-sleep，通常是 IDLE 时间不足，未满足自动进入条件。这可能由日志过多或低功耗蓝牙配置导致 IDLE 时间过短（如连续扫描）引起。