ESP 定时器（高分辨率定时器） ============================ :link_to_translation:`en:[English]` {IDF_TARGET_HR_TIMER:default = "SYSTIMER", esp32 = "LAC 定时器"} {IDF_TARGET_HR_TIMER_Resolution:default = "52", esp32 = "64", esp32s2 = "64"} .. only:: html 本文介绍了 ESP-IDF 的 ESP 定时器功能，章节目录如下： .. contents:: :local: :depth: 2 概述 ---- 使用 ESP 定时器可以创建软件定时器并在超时时调用其回调函数（分发回调函数）。尤其适用于当软件需要执行延迟操作或周期性操作的场景，例如：延迟启动设备或停止设备、周期性采样传感器数据等。 ESP 定时器可以简化一些操作，例如：管理多个定时器、分发回调函数、处理时钟频率变化（如果启用了动态调频），以及从浅睡眠中唤醒后保持准确的时间。 如果应用场景对实时性能要求较高（例如需要生成波形），或要求定时器分辨率可配置，建议使用 :doc:`GPTimer `。此外，GPTimer 还提供一些其他功能，例如事件捕获。 FreeRTOS 有其单独的软件定时器，但分辨率比 ESP 定时器低得多，优势在于 FreeRTOS 定时器有更好的移植性，因为它不依赖于 ESP-IDF。详情请参阅 :ref:`FreeRTOS Timers`。 功能与概念 ---------- ESP 定时器 API 提供： - 一次性和周期性定时器 - 多种分发回调函数的方法 - 处理过期回调函数 - 计数器位宽：{IDF_TARGET_HR_TIMER_Resolution} 位 - 时间分辨率：1 us 一次性和周期性定时器 ^^^^^^^^^^^^^^^^^^^^ 一次性定时器到期时仅调用一次回调函数便停止运行。一次性定时器适用于单次延迟操作，例如在指定时间间隔后关闭设备或读取传感器。 周期性定时器在到期时会调用回调函数并自动重启，回调函数会在指定时间间隔内被反复调用，直至手动暂停周期性定时器。周期性定时器适用于重复操作，例如采样传感器数据、更新显示信息或生成波形。 .. _Callback Methods: 分发回调函数的方法 ^^^^^^^^^^^^^^^^^^ 定时器回调函数可以使用以下方法进行分发： - 任务分发法（默认）： - 从单个高优先级 ESP 定时器任务中分发定时器回调函数（esp_timer 任务（由 ISR 通知）> 回调）。 - 适用于对时序要求不高的定时器回调函数。 - 中断分发法 (:cpp:enumerator:`ESP_TIMER_ISR `)： - 直接从中断处理程序分发定时器回调函数（ISR > 回调）。 - 适合运行时间仅为几微秒的简单、低延迟定时器回调函数。 - 能确保事件和执行回调之间的延迟较短。 - 不受其他活动任务影响。 任务分发细节 ~~~~~~~~~~~~ 在 ESP 定时器任务中，回调函数是串行执行的，若多个超时同时发生，执行前一项回调函数会延迟后续回调函数的执行。因此，建议尽量保持回调函数简短。如果需要回调函数执行更多工作，应使用 FreeRTOS 原语（如队列和信号量）将工作推迟到低优先级任务中执行。 如果有其他更高优先级的 FreeRTOS 任务正在运行（例如 SPI flash 操作），则回调函数的分发将被延迟，直到 ESP 定时器任务有机会再次运行。 为了确保任务的可预测性和及时执行，回调函数不应进行阻塞（等待资源）或让步（放弃控制）操作，否则将中断回调函数的串行执行。 中断分发细节 ~~~~~~~~~~~~ 使用中断分发法的定时器，其回调由中断处理程序执行。由于中断可以抢占所有任务，中断分发法带来的延迟较低。中断分发的定时器回调函数不应尝试阻塞，也不应尝试通过 ``portYIELD_FROM_ISR()`` 触发上下文切换，而应使用 :cpp:func:`esp_timer_isr_dispatch_need_yield` 函数。上下文切换将在处理完所有使用 ISR 分发法的定时器后进行。 使用中断分发的定时器时，应避免使用标准的日志记录或调试方法（例如 ``printf``）。若想调试应用程序或在控制台中显示某些信息，应使用 ESP-IDF 日志宏，例如 :c:macro:`ESP_DRAM_LOGI` 和 :c:macro:`ESP_EARLY_LOGI` 等。这些宏专为在各种上下文（包括中断服务程序）中工作而设计。 获取当前时间 ^^^^^^^^^^^^ 可以使用便捷函数 :cpp:func:`esp_timer_get_time` 获取自 ESP 定时器初始化以来经过的时间。在调用 ``app_main`` 函数之前不久，ESP 定时器会开始初始化。该便捷函数速度极快，没有能引入延迟或冲突的锁机制，因此可用于细粒度定时，在任务和 ISR 例程中的精度为 1 μs。 与 ``gettimeofday()`` 函数不同，:cpp:func:`esp_timer_get_time` 具有以下特点： - 从深睡眠状态中唤醒后，初始化定时器将从零开始。 - 返回值没有时区设置或夏令时调整。 系统集成 -------- 本节主要介绍如何优化 ESP 定时器的操作并将其与其他 ESP-IDF 功能进行集成。 超时值限制 ^^^^^^^^^^ 分发回调不可能是瞬时的，使用 ESP 定时器创建的一次性和周期性定时器具有超时值限制。由于这些限制取决于多个因素，所以无法进行精确估计。 例如，ESP32 以 240 MHz 的频率运行并使用任务分发法，其最小超时值大约如下： * 一次性定时器：~20 μs * 如果调用 :cpp:func:`esp_timer_start_once`，这是系统能够分发回调函数的最小超时值。 * 周期性定时器：~50 μs * 具有较小超时值的周期性软件定时器将消耗大部分 CPU 时间，因此不实用。 CPU 频率越低，最小超时值就越高。一般来说，如果所需的超时值在几十微秒的范围内，则应用程序需要经过彻底测试才能确保稳定运行。 如果最小超时值稍稍超过要求，可以考虑使用中断分发法。 .. only:: not SOC_PARLIO_SUPPORTED and SOC_RMT_SUPPORTED 若需要更小的超时值，例如生成或接收波形、进行位操作时，ESP 定时器的分辨率可能不能满足要求。此时建议使用专用外设，例如 :doc:`GPTimer ` 或 :doc:`RMT `，以及使用它们的 DMA 功能（如果可用）。 .. only:: SOC_PARLIO_SUPPORTED 若需要更小的超时值，例如生成或接收波形、进行位操作时，ESP 定时器的分辨率可能不能满足要求。此时建议使用专用外设，例如 :doc:`并行 IO `，以及使用它们的 DMA 功能（如果可用）。 睡眠模式注意事项 ^^^^^^^^^^^^^^^^ 如果启动了定时器，并且在等待时间内没有执行其他任务，则可以将芯片置于睡眠状态以优化功耗。 可以通过以下方式进入不同睡眠模式： * **自动睡眠** 由 :doc:`电源管理 API ` 提供：如果没有正在执行的任务，芯片会自动进入浅睡眠状态，并在适当时间自动唤醒，以便 ESP 定时器分发待处理的回调函数。 * **手动睡眠** 由 :doc:`睡眠模式 API ` 提供：无论是否正在执行其他任务，都可以将芯片置于睡眠状态。 若手动设置睡眠状态，则可以选择以下睡眠模式： * Deep-sleep 模式：ESP 定时器停用 从深睡眠状态中唤醒时，应用程序即刻重新启动，因此该模式不适用于连续的 ESP 定时器操作。但如果不需要定时器在唤醒后持续运行，则可进入深睡眠状态。 * Light-sleep 模式：ESP 定时器暂停 在浅睡眠状态下，ESP 定时器的计数器和回调函数会被暂停。RTC 定时器可保持系统时间。一旦芯片被唤醒，ESP 定时器的计数器会自动为系统增加睡眠期间的时长，之后时间保持和回调函数执行将恢复。 此时，ESP 定时器将尝试分发所有未处理的回调函数（如果有的话），可能会导致 ESP 定时器回调执行队列的溢出。某些应用中不应出现此类行为，为避免这种情况，可参阅 :ref:`Handling Callbacks in Light Sleep`。 .. _FreeRTOS Timers: FreeRTOS 定时器 ^^^^^^^^^^^^^^^ 尽管 FreeRTOS 提供了 `软件定时器 `_，但它们有以下限制： - FreeRTOS 定时器的分辨率受 `tick 频率 `_ 的限制，该频率通常在 100 到 1000 Hz 之间。 - 定时器回调函数由低优先级定时器任务分发，该任务可能会被其他任务抢占，导致定时器精度和准确度下降。 但 FreeRTOS 定时器是可移植的（不依赖于 ESP-IDF），且不会从 ISR 中分发，因此具有确定性。 .. only:: SOC_ETM_SUPPORTED and SOC_SYSTIMER_SUPPORT_ETM ETM 事件 ^^^^^^^^ ESP 定时器连接到 :doc:`事件任务矩阵 ` (ETM) 模块。该模块能够在不涉及 CPU 中断的情况下通知多个外设。直接通知可以减少延迟并降低 CPU 负载。可以调用函数 :cpp:func:`esp_timer_new_etm_alarm_event` 获取相应的 ETM 事件句柄。 使用方法 -------- 在设置 ESP-IDF 项目时，请确保： - 在 ``CMakeLists.txt`` 中添加所需的组件依赖项 ``esp_timer``。 - 在 ``.c`` 文件中包含所需的头文件 ``esp_timer.h``。 - （可选）设置 Kconfig 选项。详见 :ref:`Kconfig 选项 ` > *ESP 定时器（高分辨率定时器）* .. _General Procedure: 一般程序 ^^^^^^^^ 创建、启动、暂停和删除定时器的一般程序如下： 1. 创建定时器 - 使用类型 :cpp:type:`esp_timer_handle_t` 定义定时器句柄 - 通过定义结构体 :cpp:struct:`esp_timer_create_args_t` （包括回调函数）来设置定时器配置参数。 .. note:: 建议尽量使回调函数保持简短，避免延迟其他回调函数的执行。 - 调用函数 :cpp:func:`esp_timer_create` 来创建定时器。 2. 根据需求启动一次性或周期性的定时器 - 调用函数 :cpp:func:`esp_timer_start_once`，启动一次性定时器。 - 调用函数 :cpp:func:`esp_timer_start_periodic`，启动周期性定时器。在调用函数 :cpp:func:`esp_timer_stop` 显式暂停定时器前，该周期性定时器将持续运行。 .. note:: 执行启动函数前，请确保定时器未在运行。如果定时器正在运行，请先调用 :cpp:func:`esp_timer_restart`，或是调用 :cpp:func:`esp_timer_stop` 暂停定时器，然后再使用上述启动函数。 3. 暂停定时器 - 调用函数 :cpp:func:`esp_timer_stop`，可暂停运行中的定时器。 4. 删除定时器 - 使用函数 :cpp:func:`esp_timer_delete`，可删除不需要的定时器以释放内存。 .. _Using ESP_TIMER_ISR Callback Method: 使用中断分发法 ^^^^^^^^^^^^^^ 在可用的 :ref:`分发回调函数的方法 ` 中，如果选择中断分发法，请按以下步骤操作： 1. 设置 Kconfig 选项 - 启用 :ref:`CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD`。 2. 创建定时器 - 通过定义结构体 :cpp:struct:`esp_timer_create_args_t` 来设置定时器配置参数： .. code-block:: c const esp_timer_create_args_t timer = { ... , .dispatch_method = ESP_TIMER_ISR, ... }; - 调用函数 :cpp:func:`esp_timer_create` 来创建定时器。 更多步骤请参阅 :ref:`General Procedure`。 .. _Handling Callbacks in Light Sleep: 在 Light-sleep 模式下处理回调函数 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 浅睡眠状态下，既能快速唤醒以执行特定操作，又能节省功耗。要想结合 Light-sleep 模式使用 ESP 定时器，请参阅 :doc:`睡眠模式 API `。 在浅睡眠状态下，为控制未处理的回调函数，并且避免唤醒时 ESP 定时器回调执行队列的溢出，请执行以下任一操作： - 首先要防止调用回调函数：在进入浅睡眠状态前，请使用函数 :cpp:func:`esp_timer_stop` 暂停定时器。 - 若出于某种原因不希望调用停止函数，请使用选项 :cpp:member:`esp_timer_create_args_t::skip_unhandled_events`。此时，若周期性定时器在浅睡眠状态下到期一次或多次，则唤醒时只执行一次回调函数。 调试定时器 ^^^^^^^^^^ 使用函数 :cpp:func:`esp_timer_dump`，可转储所有定时器或仅运行中的定时器的相关信息：如定时器的参数、定时器启动次数、触发次数、跳过次数以及执行定时器回调函数所需的时间，这些信息能够帮助调试定时器。 请按照以下步骤调试定时器： 1. 设置 Kconfig 选项以获取更详细的输出： - 启用 :ref:`CONFIG_ESP_TIMER_PROFILING`。 .. note:: 启用此选项会增加代码大小和堆内存使用量。 2. 调用函数 :cpp:func:`esp_timer_dump`，在代码中必要的位置打印信息并用于调试定时器。 3. 结束调试后，考虑禁用 :ref:`CONFIG_ESP_TIMER_PROFILING`。 故障排除 -------- 回调函数分发时间不稳定 ^^^^^^^^^^^^^^^^^^^^^^ 如果多次分发相同的回调函数时响应时间变化较大，请尝试下列方法，使分发时间趋于稳定： .. list:: - :ref:`使用中断分发法 `。 :SOC_HP_CPU_HAS_MULTIPLE_CORES: - 使用 Kconfig 选项 :ref:`CONFIG_ESP_TIMER_TASK_AFFINITY`，将 esp_timer 安装到负载较轻的 CPU 核上运行。 分发回调函数时延迟显著 ^^^^^^^^^^^^^^^^^^^^^^ 若分发回调函数需要相当长的时间，问题可能出在回调函数本身。更准确地说，由于所有回调函数都在单个 esp_timer 任务中逐个处理，延迟可能是由队列中较早的其他回调函数引起的。 因此，要确保应用程序中的所有回调函数都能快速独立地执行，并且没有任何阻塞操作。 唤醒后重复分发回调函数 ^^^^^^^^^^^^^^^^^^^^^^ 从睡眠模式中唤醒后，若回调函数重复执行，请参阅 :ref:`Handling Callbacks in Light Sleep`。 在分发回调函数时栈溢出 ^^^^^^^^^^^^^^^^^^^^^^ 如果在执行回调函数时遇到栈溢出的错误，请考虑减少回调函数内的栈使用量；或者，尝试通过调整 :ref:`CONFIG_ESP_TIMER_TASK_STACK_SIZE` 来增加 ESP 定时器任务栈的大小。 应用示例 -------- * :example:`system/esp_timer` 创建并启动一次性及周期性的软件定时器，展示了如何结合 Light-sleep 模式使用定时器，然后停止并删除定时器。 API 参考 -------- .. include-build-file:: inc/esp_timer.inc