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: 64 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 GPTimer or RMT, 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.
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:
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 functionNote
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()
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 usingesp_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 usingesp_timer_stop()
and then call one of the start functions.Stop the timer
To stop the running timer, call the function
esp_timer_stop()
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:
Set Kconfig options
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:
Set Kconfig options for more detailed output:
Enable CONFIG_ESP_TIMER_PROFILING
Note that enabling this option increases code size and heap memory usage.
Wherever required in your code, call the function
esp_timer_dump()
to print the information and use it to debug your timers.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
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 onesp_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 toNO_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 everyperiod
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
microsecondsPeriodic 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.
-
esp_timer_cb_t callback
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