espressif/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2026-04-27 19:13:21 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'feature/doc_time_src' into 'master'

Browse Source 
feat(docs): Adds clarifications on RTC clock source selection

Closes IDF-14264

See merge request espressif/esp-idf!44829
This commit is contained in:
Konstantin Kondrashov
2026-01-19 19:43:43 +08:00
parent 326342db45 b944d7d0d8
commit 33ebe15253
2 changed files with 64 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/en/api-reference/system/system_time.rst
+30
View File
@@ -43,6 +43,36 @@ The choice depends on your requirements for system time accuracy and power consu
More details about the wiring requirements for the external crystal or external oscillator, please refer to the `Hardware Design Guidelines <https://docs.espressif.com/projects/esp-hardware-design-guidelines/en/latest/{IDF_TARGET_PATH_NAME}>`_.
Selecting RTC Timer Clock Source
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Use the default **internal RC oscillator** when:
- Minimizing sleep current consumption is critical for battery-powered or energy-constrained devices.
- High time accuracy during sleep modes is not required. Time drifting in the range of several seconds per day is acceptable.
- Minimizing external components and hardware complexity is a priority.
- The operating temperature is relatively stable (reducing frequency variation).
- Bluetooth LE with power saving is not used, or only used for legacy advertising/scanning without connections.
Use an **external 32 kHz crystal** or **external 32 kHz oscillator** when:
- Accurate time-keeping during Deep-sleep and Light-sleep modes is required.
- A small increase in sleep current (typically a few μA) fits within the power budget.
- Adding external components is acceptable for the design.
- Operating temperature may vary significantly.
- Bluetooth LE with power saving is enabled and connections are required.
Some chips may provide the **internal oscillator** option, which is a trade-off between the internal RC oscillator and external 32 kHz crystal/oscillator options. It does not require external components while providing better frequency stability than the internal RC oscillator but at the cost of higher sleep current consumption. If Bluetooth LE is used please verify the internal oscillator meets Bluetooth LE sleep clock accuracy requirements (see below).
In most designs, the additional sleep current is a reasonable trade-off for significantly improved RTC Timer frequency stability and reduced time drift during sleep.
**Bluetooth LE** requires sleep clock accuracy within 500 PPM. The RTC clock source may not meet this requirement, leading to connection establishment failures, unexpected timeouts, or incompatibility with non-Espressif peer devices.
.. only:: SOC_BLE_SUPPORTED
For a detailed comparison of Bluetooth LE clock configurations and power consumption, refer to :doc:`Low Power Mode in Bluetooth LE </api-guides/low-power-mode/low-power-mode-ble>`.
Get Current Time
----------------
docs/zh_CN/api-reference/system/system_time.rst
+34 -4
View File
@@ -31,17 +31,47 @@ RTC 定时器有以下时钟源：
.. list::
- ``内置 90～150 kHz（频率取决于芯片型号） 振荡器`` （默认）：Deep-sleep 模式下电流消耗最低，不依赖任何外部元件。但由于温度波动会影响该时钟源的频率稳定性，在 Deep-sleep 和 Light-sleep 模式下都有可能发生时间偏移。
- ``内置 90～150 kHz（频率取决于芯片型号）RC 振荡器`` （默认）：Deep-sleep 模式下电流消耗最低，不依赖任何外部元件。但由于温度波动会影响该时钟源的频率稳定性，在 Deep-sleep 和 Light-sleep 模式下都有可能发生时间偏移。
:not esp32c2: - ``外置 32 kHz 晶振``：需要将一个 32 kHz 晶振连接到外置晶振管脚。频率稳定性更高，但在 Deep-sleep 模式下电流消耗略高（比默认模式高 1 μA）。管脚连接的相关信息请参考 `技术规格书 <{IDF_TARGET_DATASHEET_CN_URL}>`__。
:not esp32c2: - ``外部 32 kHz 无源晶振``：需要将一个 32 kHz 晶振连接到外部晶振管脚。频率稳定性更高，但在 Deep-sleep 模式下电流消耗略高（比默认模式高 1 μA）。管脚连接的相关信息请参考 `技术规格书 <{IDF_TARGET_DATASHEET_CN_URL}>`__。
- ``外置 32 kHz 振荡器``：允许使用由外部电路产生的 32 kHz 时钟。外部时钟信号必须连接到外置振荡器管脚。输入振幅必须保证数字电路能够正确识别电平高低。测试结果表明，1.7 V 为高低电平的分界点，因此需确保输入波形的峰值大于 1.7 V，谷值小于 1.7 V。管脚连接的相关信息请参考 `技术规格书 <{IDF_TARGET_DATASHEET_CN_URL}>`__。
- ``外部 32 kHz 有源晶振``：允许使用由外部电路产生的 32 kHz 时钟。外部时钟信号必须连接到外部振荡器管脚。输入振幅必须保证数字电路能够正确识别电平高低。测试结果表明，1.7 V 为高低电平的分界点，因此需确保输入波形的峰值大于 1.7 V，谷值小于 1.7 V。管脚连接的相关信息请参考 `技术规格书 <{IDF_TARGET_DATASHEET_CN_URL}>`__。
:esp32 or esp32s2 or esp32s3 or esp32c2 or esp32c3: - ``内置 8.5～17.5 MHz 振荡器（频率取决于芯片型号）的 256 分频时钟``：频率稳定性优于 ``内置 90～150 kHz RC 振荡器``，同样无需外部元件，但 Deep-sleep 模式下电流消耗更高（比默认模式高 5 μA）。
时钟源的选择取决于系统时间精度要求和睡眠模式下的功耗要求。要修改 RTC 时钟源，请在项目配置中设置 :ref:`CONFIG_RTC_CLK_SRC`。
想要了解外置晶振或外置振荡器的更多布线要求，请参考 `硬件设计指南 <https://docs.espressif.com/projects/esp-hardware-design-guidelines/zh_CN/latest/{IDF_TARGET_PATH_NAME}>`_。
想要了解外部无源晶振和有源晶振的更多布线要求，请参考 `硬件设计指南 <https://docs.espressif.com/projects/esp-hardware-design-guidelines/zh_CN/latest/{IDF_TARGET_PATH_NAME}>`_。
选择 RTC 定时器时钟源
^^^^^^^^^^^^^^^^^^^^^
在以下情况下使用默认的 **内部 RC 振荡器**：
- 对于电池供电设备或能量受限的设备，最小化睡眠电流消耗。
- 睡眠模式下不需要高时间精度，并且可以接受每天几秒的时间漂移。
- 优先考虑最小化外部元件和硬件复杂度。
- 工作温度相对稳定（减少频率变化）。
- 未使用低功耗蓝牙的节能模式，或仅用于传统广播/扫描而不建立连接。
在以下情况下使用 **外部 32 kHz 有源晶振** 或 **外部 32 kHz 无源晶振**：
- 需要在 Deep-sleep 和 Light-sleep 模式下保持准确的时间。
- 睡眠电流略有增加（通常为几微安）仍在功耗预算范围内。
- 设计可以接受添加外部元件。
- 工作温度可能变化较大。
- 启用低功耗蓝牙的节能模式，且需要建立连接。
某些芯片可能提供 **内部振荡器** 选项，这是内部 RC 振荡器和外部 32 kHz 有源晶振/无源晶振选项之间的折中方案。它不需要外部元件，同时提供比内部 RC 振荡器更好的频率稳定性，但代价是睡眠电流消耗更高。如果使用低功耗蓝牙，请确认内部振荡器是否满足低功耗蓝牙睡眠时钟精度要求（见下文）。
在大多数设计中，睡眠电流的略微增加是换取 RTC 定时器频率稳定性显著提升和睡眠期间时间漂移减少的合理权衡。
**低功耗蓝牙** 要求睡眠时钟精度在 500 PPM 以内。RTC 时钟源可能无法满足此要求，导致连接建立失败、意外超时或与非乐鑫设备不兼容。
.. only:: SOC_BLE_SUPPORTED
有关低功耗蓝牙时钟配置和功耗的详细比较，请参考 :doc:`低功耗蓝牙的低功耗模式 </api-guides/low-power-mode/low-power-mode-ble>`。
获取当前时间
--------------