ESP Timer (High Resolution Timer)

[中文]

This document covers the ESP-IDF feature called ESP Timer. The contents are as follows:

Overview

The ESP Timer feature allows for creating software timers and invoking their callback functions (dispatching callbacks) on timeout. ESP Timer is useful when user software needs to perform delayed or periodic actions, such as delayed device start/stop or periodic sampling of sensor data.

ESP Timer hides the complexity associated with managing multiple timers, dispatching callbacks, accounting for clock frequency changes (if dynamic frequency scaling is enabled), and maintaining correct time after light sleep.

For application scenarios that require better real-time performance (such as generating waveforms) or configurable timer resolution, it is recommended that GPTimer be used instead. Also, GPTimer has features not available in ESP Timer, such as event capture.

Finally, FreeRTOS has its own software timers. As explained in FreeRTOS Timers, they have much lower resolution compared to ESP Timer, but FreeRTOS timers are portable (non-dependent on ESP-IDF) which might be an advantage in some cases.

Features and Concepts

The ESP Timer API provides:

• One-shot and periodic timers

• Multiple callback dispatch methods

• Handling overdue callbacks

• Bit range: 52 bits

• Time resolution: 1 microsecond

One-Shot and Periodic Timers

A one-shot timer invokes its callback function only once upon expiration and then stops operation. One-shot timers are useful for single delayed actions, such as turning off a device or reading a sensor after a specified time interval.

A periodic timer invokes its callback function upon expiration and restarts itself automatically, resulting in the callback function being invoked at a defined interval until the periodic timer is manually stopped. Periodic timers are useful for repeated actions, such as sampling sensor data, updating display information, or generating a waveform.

Callback Dispatch Methods

Timer callbacks can be dispatched using the following methods:

• Task Dispatch method (default):

  • Dispatches timer callbacks from a single high-priority ESP Timer task (esp_timer task (notified by ISR) > callback)

  • Suitable for handling timer callbacks that are not time-critical

• Interrupt Dispatch method (ESP_TIMER_ISR):

  • Dispatches timer callbacks directly from an interrupt handler (ISR > callback)

  • Suitable for simple, low-latency timer callbacks which take a few microseconds to run

  • Ensures shorter delay between the event and the callback execution

  • Not affected by other active tasks

Task Dispatch Specifics

The execution of callbacks in the ESP Timer task is serialized. Thus, when multiple timeouts occur simultaneously, the execution time of one callback will delay the execution of subsequent callbacks. For this reason, it is recommended to keep the callbacks short. If the callback needs to perform more work, the work should be deferred to a lower-priority task using FreeRTOS primitives, such as queues and semaphores.

If other FreeRTOS tasks with higher priority are running, such as an SPI Flash operation, callback dispatching will be delayed until the ESP Timer task has a chance to run.

To maintain predictable and timely execution of tasks, callbacks should never attempt block (waiting for resources) or yield (give up control) operations, because such operations disrupt the serialized execution of callbacks.

Interrupt Dispatch Specifics

Timers using the Interrupt Dispatch method have their callbacks executed from an interrupt handler. As interrupts can preempt all tasks, the Interrupt Dispatch method offers lower latency. Interrupt dispatched timer callbacks should never attempt to block and should not attempt to trigger a context switch via portYIELD_FROM_ISR(). Instead, the function esp_timer_isr_dispatch_need_yield() should be used. The context switch will happen after all ISR dispatch timers are processed.

While using interrupt dispatched timers, the standard logging or debugging methods, such as printf should be avoided. To debug an application or display certain information in the console, the ESP-IDF logging macros should be used, such as ESP_DRAM_LOGI, ESP_EARLY_LOGI, etc. These macros are specifically designed to work in various contexts, including interrupt service routines.

Obtaining Current Time

The time passed since the initialization of ESP Timer can be obtained using the convenience function esp_timer_get_time(). The initialization happens shortly before the app_main function is called. This function is fast and has no locking mechanisms that could potentially introduce delays or conflicts. As a result, it can be useful for fine-grained timing, with the accuracy of 1 us, in tasks as well as in ISR routines.

Unlike the gettimeofday() function, esp_timer_get_time() has the following specifics:

• Upon wakeup from deep sleep, the initialization timer restarts from zero

• The returned value has no timezone settings or daylight saving time adjustments

System Integration

This section mainly covers some aspects of how to optimize the operation of ESP Timer and integrate it with other ESP-IDF features.

Timeout Value Limits

As callback dispatching can never be instantaneous, the one-shot and periodic timers created with ESP Timer also have timeout value limits. These limits cannot be estimated precisely, because they depend on multiple factors.

For reference, the ESP32 running at 240 MHz and using the Task Dispatch method has the approximate minimum timeout values as follows:

• One-shot timers: ~20 us

  • If esp_timer_start_once() is called, this is the earliest time after which the system will be able to dispatch a callback.

• Periodic timers: ~50 us

  • Periodic software timers with a smaller timeout value would simply consume most of the CPU time, which is impractical.

The lower the CPU frequency, the higher the minimum timeout values will be. The general guideline is if the required timeout values are in the order of tens of microseconds, the user application needs to undergo thorough testing to ensure stable operation.

If the minimum timeout values slightly exceed the requirements, the Interrupt Dispatch method might offer an improvement.

For even smaller timeout values, for example, to generate or receive waveforms or do bit banging, the resolution of ESP Timer may be insufficient. In this case, it is recommended to use dedicated peripherals, such as Parallel IO, and their DMA features if available.

Sleep Mode Considerations

If a timer is started, and there are no other tasks being executed during the wait time, the chip can be put into sleep to optimize power consumption.

Sleep can be induced in the following ways:

• Automatic sleep provided by Power Management APIs: If no tasks are being executed, the chip can automatically enter light sleep and automatically wake up at the appropriate time for ESP Timer to dispatch a pending callback.

• Manual sleep provided by Sleep Mode APIs: The chip can be put into sleep regardless of whether other tasks are being executed.

For manually induced sleep, the following sleep modes exist:

• Deep-sleep mode: ESP Timer is deactivated

  The user application restarts from scratch upon wakeup from deep sleep. This makes deep sleep unsuitable for continuous ESP Timer operation. However, deep sleep can be used if the running timers are not expected to persist across wakeups.

• Light-sleep mode: ESP Timer is suspended

  While in light sleep, ESP Timer counter and callbacks are suspended. Timekeeping is done by the RTC timer. Once the chip is woken up, the counter of ESP Timer is automatically advanced by the amount of time spent in sleep, then timekeeping and callback execution is resumed.

  At this point, ESP Timer will attempt to dispatch all unhandled callbacks if there are any. It can potentially lead to the overflow of ESP Timer callback execution queue. This behavior may be undesirable for certain applications, and the ways to avoid it are covered in Handling Callbacks in Light-sleep Mode.

FreeRTOS Timers

Although FreeRTOS provides software timers, they have limitations:

• FreeRTOS timer resolution is bound by the tick frequency, which is typically in the range of 100 to 1000 Hz.

• Timer callbacks are dispatched from a low-priority timer task that can be preempted by other tasks, leading to decreased timer precision and accuracy.

However, FreeRTOS timers are portable (non-dependent on ESP-IDF) and are written to be deterministic as they do not dispatch callbacks from ISRs.

ETM Events

ESP Timer has connection to the Event Task Matrix (ETM) module. This module allows notifying a number of peripherals about events without involving CPU interrupts. Direct notifications reduce latency and decrease CPU workload. The function esp_timer_new_etm_alarm_event() can be called to get the corresponding ETM event handle.

Usage

While setting up your ESP-IDF project, make sure to:

• Add required component dependencies to your CMakeLists.txt.

• Include required header files in your .c files.

• (Optional) Set Kconfig options. For this, see Kconfig Options > ESP Timer (High Resolution Timer)

General Procedure

The general procedure to create, start, stop, and delete a timer is as follows:

1. Create a timer

   • Define a timer handle using the type esp_timer_handle_t

   • Set the timer configuration parameters by defining the structure esp_timer_create_args_t which also includes the callback function

     Note

     It is recommended to keep callbacks as short as possible to avoid delaying other callbacks.

   • To create a timer, call the function esp_timer_create()

2. Start the timer in one-shot mode or periodic mode depending on your requirements

   • To start the timer in one-shot mode, call esp_timer_start_once()

   • To start the timer in periodic mode, call esp_timer_start_periodic(); the timer will continue running until you explicitly stop it using esp_timer_stop()

   Note

   When executing a start function, ensure that the timer is not running. If a timer is running, either call esp_timer_restart() or stop it first using esp_timer_stop() and then call one of the start functions.

3. Stop the timer

   • To stop the running timer, call the function esp_timer_stop()

4. Delete the timer

   • When the timer is no longer needed, delete it to free up memory using the function esp_timer_delete()

Using the Interrupt Dispatch Method

Out of the available callback methods, if you choose the Interrupt Dispatch method, follow these steps:

1. Set Kconfig options

   • Enable CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD

2. Create a timer

   • Set the timer configuration parameters by defining the structure esp_timer_create_args_t

     const esp_timer_create_args_t timer = {
       ... ,
       .dispatch_method = ESP_TIMER_ISR,
       ...
     };
     

   • To create a timer, call the function esp_timer_create()

For further steps, refer to General Procedure.

Handling Callbacks in Light-sleep Mode

Light sleep allows you to save power while maintaining the ability to quickly wake up for specific actions. To use ESP Timer in conjunction with Light-sleep mode, see Sleep Mode APIs.

During light sleep, to keep unhandled callbacks under control and avoid potential overflow of ESP Timer callback execution queue on wakeup, do one of the following:

• Prevent the invocation of callbacks in the first place: stop the timer before entering light sleep by using esp_timer_stop().

• If calling the stop function is not desirable for any reason, use the option esp_timer_create_args_t::skip_unhandled_events. In this case, if a periodic timer expires one or more times during light sleep, then only one callback is executed on wakeup.

Debugging Timers

The function esp_timer_dump() allows dumping information about either all or only running timers: the parameters for timers, the number of times the timers were started, triggered, skipped, and time taken by timer callbacks to execute. This information can be helpful in debugging.

To debug timers, use the following procedure:

1. Set Kconfig options for more detailed output:

   • Enable CONFIG_ESP_TIMER_PROFILING

   Note that enabling this option increases code size and heap memory usage.

2. Wherever required in your code, call the function esp_timer_dump() to print the information and use it to debug your timers.

3. Once debugging is complete, consider disabling CONFIG_ESP_TIMER_PROFILING.

Troubleshooting

Unstable Callback Dispatch Time

While dispatching the same callback function repeatedly, if the response time varies considerably, try to stabilize it by doing the following:

• Use the ESP_TIMER_ISR callback method

• Use the Kconfig option CONFIG_ESP_TIMER_TASK_AFFINITY to run the ESP Timer task on both cores

Significant Delays Dispatching Callbacks

If dispatching a callback function takes a considerable amount of time, the problem can lie in the callback function itself. More precisely, as all callback functions are processed one by one in a single esp_timer task, the delays might be caused by other callback functions earlier in the queue.

For this reason, make sure that all callback functions in your application can execute on their own quickly and without any blocking operations.

Repeated Callback Dispatches After Sleep

If the callback functions are executed repeatedly upon wakeup from sleep, see Handling Callbacks in Light-sleep Mode.

Stack Overflow While Dispatching Callbacks

If you see a stack overflow error when executing a callback function, consider reducing the stack usage within your callback function. Alternatively, try increasing the size of the ESP Timer task stack by adjusting CONFIG_ESP_TIMER_TASK_STACK_SIZE.

Application Examples

• system/esp_timer creates and starts one-shot and periodic software timers, shows how they work with Light-sleep mode, and then stops and deletes the timers

API Reference

Header File

• components/esp_timer/include/esp_timer.h

• This header file can be included with:

  #include "esp_timer.h"
  

• This header file is a part of the API provided by the esp_timer component. To declare that your component depends on esp_timer, add the following to your CMakeLists.txt:

  REQUIRES esp_timer
  

  or

  PRIV_REQUIRES esp_timer
  

Functions

esp_err_t esp_timer_early_init(void)

Minimal initialization of esp_timer.

This function can be called very early in startup process, after this call only esp_timer_get_time() function can be used.

Note

This function is called from startup code. Applications do not need to call this function before using other esp_timer APIs.

Returns

• ESP_OK on success

esp_err_t esp_timer_init(void)

Initialize esp_timer library.

This function will be called from startup code on every core. If Kconfig option CONFIG_ESP_TIMER_ISR_AFFINITY is set to NO_AFFINITY, it allocates the timer ISR on MULTIPLE cores and creates the timer task which can be run on any core.

Note

This function is called from startup code. Applications do not need to call this function before using other esp_timer APIs. Before calling this function, esp_timer_early_init() must be called by the startup code.

Returns

• ESP_OK on success

• ESP_ERR_NO_MEM if allocation has failed

• ESP_ERR_INVALID_STATE if already initialized

• other errors from interrupt allocator

esp_err_t esp_timer_deinit(void)

De-initialize esp_timer library.

Note

Normally this function should not be called from applications

Returns

• ESP_OK on success

• ESP_ERR_INVALID_STATE if not yet initialized

esp_err_t esp_timer_create(const esp_timer_create_args_t *create_args, esp_timer_handle_t *out_handle)

Create an esp_timer instance.

Note

When timer no longer needed, delete it using esp_timer_delete().

Parameters

• create_args -- Pointer to a structure with timer creation arguments. Not saved by the library, can be allocated on the stack.

• out_handle -- [out] Output, pointer to esp_timer_handle_t variable that holds the created timer handle.

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG if some of the create_args are not valid

• ESP_ERR_INVALID_STATE if esp_timer library is not initialized yet

• ESP_ERR_NO_MEM if memory allocation fails

esp_err_t esp_timer_start_once(esp_timer_handle_t timer, uint64_t timeout_us)

Start a one-shot timer.

Timer represented by timer should not be running when this function is called.

Parameters

• timer -- timer handle created using esp_timer_create()

• timeout_us -- timer timeout, in microseconds relative to the current moment

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG if the handle is invalid

• ESP_ERR_INVALID_STATE if the timer is already running

esp_err_t esp_timer_start_periodic(esp_timer_handle_t timer, uint64_t period)

Start a periodic timer.

Timer represented by timer should not be running when this function is called. This function starts the timer which will trigger every period microseconds.

Parameters

• timer -- timer handle created using esp_timer_create()

• period -- timer period, in microseconds

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG if the handle is invalid

• ESP_ERR_INVALID_STATE if the timer is already running

esp_err_t esp_timer_restart(esp_timer_handle_t timer, uint64_t timeout_us)

Restart a currently running timer.

Type of timer	Action
One-shot timer	Restarted immediately and times out once in timeout_us microseconds
Periodic timer	Restarted immediately with a new period of timeout_us microseconds

Parameters

• timer -- timer handle created using esp_timer_create()

• timeout_us -- Timeout in microseconds relative to the current time. In case of a periodic timer, also represents the new period.

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG if the handle is invalid

• ESP_ERR_INVALID_STATE if the timer is not running

esp_err_t esp_timer_stop(esp_timer_handle_t timer)

Stop a running timer.

This function stops the timer previously started using esp_timer_start_once() or esp_timer_start_periodic().

Parameters

timer -- timer handle created using esp_timer_create()

Returns

• ESP_OK on success

• ESP_ERR_INVALID_STATE if the timer is not running

esp_err_t esp_timer_delete(esp_timer_handle_t timer)

Delete an esp_timer instance.

The timer must be stopped before deleting. A one-shot timer which has expired does not need to be stopped.

Parameters

timer -- timer handle created using esp_timer_create()

Returns

• ESP_OK on success

• ESP_ERR_INVALID_STATE if the timer is running

int64_t esp_timer_get_time(void)

Get time in microseconds since boot.

Returns

Number of microseconds since the initialization of ESP Timer

int64_t esp_timer_get_next_alarm(void)

Get the timestamp of the next expected timeout.

Returns

Timestamp of the nearest timer event, in microseconds. The timebase is the same as for the values returned by esp_timer_get_time().

int64_t esp_timer_get_next_alarm_for_wake_up(void)

Get the timestamp of the next expected timeout excluding those timers that should not interrupt light sleep (such timers have esp_timer_create_args_t::skip_unhandled_events enabled)

Returns

Timestamp of the nearest timer event, in microseconds. The timebase is the same as for the values returned by esp_timer_get_time().

esp_err_t esp_timer_get_period(esp_timer_handle_t timer, uint64_t *period)

Get the period of a timer.

This function fetches the timeout period of a timer. For a one-shot timer, the timeout period will be 0.

Parameters

• timer -- timer handle created using esp_timer_create()

• period -- memory to store the timer period value in microseconds

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG if the arguments are invalid

esp_err_t esp_timer_get_expiry_time(esp_timer_handle_t timer, uint64_t *expiry)

Get the expiry time of a one-shot timer.

This function fetches the expiry time of a one-shot timer.

Note

Passing the timer handle of a periodic timer will result in an error.

Parameters

• timer -- timer handle created using esp_timer_create()

• expiry -- memory to store the timeout value in microseconds

Returns

• ESP_OK on success

• ESP_ERR_INVALID_ARG if the arguments are invalid

• ESP_ERR_NOT_SUPPORTED if the timer type is periodic

esp_err_t esp_timer_dump(FILE *stream)

Dump the list of timers to a stream.

By default, this function prints the list of active (running) timers. The output format is:

| Name | Period | Alarm |

• Name — timer pointer

• Period — period of timer in microseconds, or 0 for one-shot timer

• Alarm - time of the next alarm in microseconds since boot, or 0 if the timer is not started

To print the list of all created timers, enable Kconfig option CONFIG_ESP_TIMER_PROFILING. In this case, the output format is:

| Name | Period | Alarm | Times_armed | Times_trigg | Times_skip | Cb_exec_time |

• Name — timer name

• Period — same as above

• Alarm — same as above

• Times_armed — number of times the timer was armed via esp_timer_start_X

• Times_triggered - number of times the callback was triggered

• Times_skipped - number of times the callback was skipped

• Callback_exec_time - total time taken by callback to execute, across all calls

Parameters

stream -- stream (such as stdout) to which to dump the information

Returns

• ESP_OK on success

• ESP_ERR_NO_MEM if can not allocate temporary buffer for the output

void esp_timer_isr_dispatch_need_yield(void)

Requests a context switch from a timer callback function.

This only works for a timer that has an ISR dispatch method. The context switch will be called after all ISR dispatch timers have been processed.

bool esp_timer_is_active(esp_timer_handle_t timer)

Returns status of a timer, active or not.

This function is used to identify if the timer is still active (running) or not.

Parameters

timer -- timer handle created using esp_timer_create()

Returns

• 1 if timer is still active (running)

• 0 if timer is not active

esp_err_t esp_timer_new_etm_alarm_event(esp_etm_event_handle_t *out_event)

Get the ETM event handle of esp_timer underlying alarm event.

Note

The created ETM event object can be deleted later using esp_etm_del_event()

Note

The ETM event is generated by the underlying hardware - systimer; therefore, if the esp_timer is not clocked by systimer, then no ETM event will be generated.

Parameters

out_event -- [out] Returned ETM event handle

Returns

• ESP_OK Success

• ESP_ERR_INVALID_ARG Parameter error

Structures

struct esp_timer_create_args_t

Timer configuration passed to esp_timer_create()

Public Members

esp_timer_cb_t callback

Callback function to execute when timer expires.

void *arg

Argument to pass to callback.

esp_timer_dispatch_t dispatch_method

Dispatch callback from task or ISR; if not specified, esp_timer task.

const char *name

Timer name, used in esp_timer_dump() function.

bool skip_unhandled_events

Setting to skip unhandled events in light sleep for periodic timers.

Type Definitions

typedef struct esp_timer *esp_timer_handle_t

Opaque type representing a single timer handle.

typedef void (*esp_timer_cb_t)(void *arg)

Timer callback function type.

Param arg

pointer to opaque user-specific data

Enumerations

enum esp_timer_dispatch_t

Method to dispatch timer callback.

Values:

enumerator ESP_TIMER_TASK

Callback is dispatched from esp_timer task.

enumerator ESP_TIMER_ISR

Callback is dispatched from interrupt handler.

enumerator ESP_TIMER_MAX

Sentinel value for the number of callback dispatch methods.

Provide feedback about this document