# 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

- Relative and absolute timing

- Multiple callback dispatch methods

- Handling overdue callbacks

- Bit range: 64 bits

- Time resolution: one 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 or timed actions, such as turning off a device or reading a sensor after a specified time interval or at a specified time point.

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 timers using the ISR dispatch method 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 μs, 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 μs

  > - 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 μs

  > - 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:

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 invoke the callback after a specified timeout duration, or `esp_timer_start_once_at()` to invoke it at a specific absolute time.

   > - To start the timer in periodic mode, call `esp_timer_start_periodic()` to invoke the callback repeatedly at regular intervals, or `esp_timer_start_periodic_at()` to start the first invocation at a specific absolute time and then repeat at regular intervals; 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()` / `esp_timer_restart_at()` 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()`. But it does not guarantee that after this call, the callback will not be running one or more times. To check if the callback is not running after stopping the timer, you can use `esp_timer_is_active()`. Another approach is to use a blocking stop API.

   > - To block the timer stop operation until any in-flight callback completes, use `esp_timer_stop_blocking()`.

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 dispatch 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

   > 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 Interrupt Dispatch method.

- Use the Kconfig option CONFIG_ESP_TIMER_TASK_AFFINITY to run the ESP Timer task on any of the available cores.

### Significant Delays while 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_once_at(esp_timer_handle_t timer, uint64_t alarm_us)

  Start a one-shot timer with absolute alarm time.

  This function starts a one-shot timer that will trigger once at the specified absolute time. To start a timer relative to the current time, see esp_timer_start_once(). Timer represented by `timer` should not be running when this function is called.

  Parameters:

    - timer -- timer handle created using esp_timer_create()

    - alarm_us -- timer alarm time, in absolute microseconds (as returned by esp_timer_get_time())

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if the handle is invalid or alarm_us is in the past

    - 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_start_periodic_at(esp_timer_handle_t timer, uint64_t period_us, uint64_t first_alarm_us)

  Start a periodic timer with absolute alarm time.

  Timer represented by `timer` should not be running when this function is called. This function starts the timer which will trigger every `period` microseconds. The first alarm will be triggered at `first_alarm_us` time. To start a periodic timer relative to the current time, see esp_timer_start_periodic().

  Parameters:

    - timer -- timer handle created using esp_timer_create()

    - period_us -- timer period, in microseconds

    - first_alarm_us -- timer first alarm time, in absolute microseconds (as returned by esp_timer_get_time())

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if the handle is invalid or first_alarm_us is in the past

    - 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_restart_at(esp_timer_handle_t timer, uint64_t period_us, uint64_t first_alarm_us)

  Restart a currently running timer with absolute alarm time.

  Type of `timer` | Action
  --- | ---
  One-shot timer | Restarted immediately and times out once at `alarm_us` microseconds
  Periodic timer | Restarted immediately with a new period of `period_us` microseconds. Next alarm is at `first_alarm_us` microseconds

  Parameters:

    - timer -- timer handle created using esp_timer_create()

    - period_us -- In case of a periodic timer, represents the new period.

    - first_alarm_us -- timer alarm time, in absolute microseconds (as returned by esp_timer_get_time())

  Returns:

    - ESP_OK on success

    - ESP_ERR_INVALID_ARG if the handle is invalid or first_alarm_us is in the past

    - 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().

  This function disarms the timer (prevents future callbacks) but does NOT preempt an already-dispatched or currently-running callback.

  For a hard guarantee that no callback is running or will run after stop, use esp_timer_stop_blocking() or poll esp_timer_is_active() until it returns false.

  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_stop_blocking(esp_timer_handle_t timer, uint32_t timeout_ticks)

  Stop a running timer and wait for any in-flight callback to complete.

  This function disarms the timer (prevents future callbacks). If the timer callback is currently executing, it waits for the callback to finish, taking into account the specified waiting time.

  If this function returns ESP_OK, the caller is guaranteed that the timer is disarmed and no callback is executing after the function returns (see the calling-context rules below).

  If ESP_ERR_NOT_FINISHED is returned, it means that the timer is disarmed, but its callback may still be running or will run soon. In this case, you can poll esp_timer_is_active() until it returns false to ensure the callback has completed.

  Note

  Behavior depends on calling context:

  - User task context (normal case): Disarms the timer and waits up to timeout_ticks for any in-flight callback to complete. Returns ESP_OK when no callback is running, or ESP_ERR_TIMEOUT if the callback didn't finish in time.

  - ISR context: Never blocks. Disarms the timer and returns immediately. If the timer callback may still be running, returns ESP_ERR_NOT_FINISHED.

  - Callback context: Disarms the timer and returns immediately. Blocking from a callback would delay the esp_timer task and distort timing of other TASK-dispatch timers. Return value depends on the stopped timer state and the currently running callback:

    - Returns ESP_OK when the stop request is issued from the stopped timer’s own callback (the callback will complete naturally after it returns).

    - Returns ESP_ERR_NOT_FINISHED when stopping an ISR-dispatch timer from a foreign callback (i.e., the currently running callback belongs to another timer). In this case the caller cannot safely wait for ISR context to complete, so it is informed that the callback may still be running.

  Parameters:

    - timer -- Timer handle created using esp_timer_create()

    - timeout_ticks -- Maximum time to wait for callback completion, in FreeRTOS ticks. Use portMAX_DELAY to wait indefinitely.

  Returns:

    - ESP_OK on success (timer is disarmed, no callback is running or will run)

    - ESP_ERR_TIMEOUT if the callback didn't complete within timeout_ticks

    - ESP_ERR_INVALID_ARG if the timer handle is invalid

    - ESP_ERR_INVALID_STATE if esp_timer is not initialized

    - ESP_ERR_NOT_FINISHED if the callback may still be running (e.g., ISR context, or TIMER_TASK while an ISR callback is in-flight)

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 when the next timer will expire.

  This function returns the alarm time of the timer that will expire soonest across all dispatch methods (TASK and ISR).

  Returns:

    Timestamp of the nearest timer event, in microseconds since boot. Returns INT64_MAX if no timers are currently armed. 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 when the next timer that should wake from light sleep will expire.

  This function returns the alarm time of the timer that will expire soonest, excluding timers that have esp_timer_create_args_t::skip_unhandled_events enabled. Used by the power management system to determine when to wake from light sleep.

  Returns:

    Timestamp of the nearest timer event that should wake the system, in microseconds since boot. Returns INT64_MAX if no wake-capable timers are currently armed. 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 period of a timer. For a one-shot timer, the period will be 0. For a periodic timer, returns the interval between successive callback invocations.

  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.

  This function prints statistics about timers. Without CONFIG_ESP_TIMER_PROFILING, it prints only the active (armed) timers. With CONFIG_ESP_TIMER_PROFILING enabled, it prints all created timers (both armed and disarmed).

  Output format without CONFIG_ESP_TIMER_PROFILING:

  Name | Period | Alarm
  --- | --- | ---
  timer@0x3ffb1234 | 1000000 | 12345678

  - Name — timer pointer (or timer name if CONFIG_ESP_TIMER_PROFILING is enabled)

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

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

  Output format with CONFIG_ESP_TIMER_PROFILING:

  Name | Period | Alarm | Times_armed | Times_trigg | Times_skip | Cb_exec_time
  --- | --- | --- | --- | --- | --- | ---
  my_timer | 1000000 | 12345678 | 42 | 40 | 2 | 1234

  - Name — timer name (from esp_timer_create_args_t::name)

  - Period — same as above

  - Alarm — same as above

  - Times_armed — number of times the timer was armed via esp_timer_start_*

  - Times_trigg — number of times the callback was invoked

  - Times_skip — number of times the callback was skipped (periodic timers with skip_unhandled_events)

  - Cb_exec_time — total time spent executing the callback, in microseconds

  Parameters:

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

  Returns:

    - ESP_OK on success

    - ESP_ERR_NO_MEM if cannot 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)

  Check if a timer is active.

  A timer is considered active if it is armed (will expire in the future) or if its callback is currently executing. After calling esp_timer_stop(), the timer is disarmed but its callback may still be running, so this function may still return true.

  Parameters:

    timer -- timer handle created using esp_timer_create()

  Returns:

    - true if timer is armed or its callback is currently running

    - false if timer is disarmed and callback is not running

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 (ESP_TIMER_TASK, default) or.

  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.

Was this page helpful?

- Thank you! We received your feedback.
- If you have any comments, fill in Espressif Documentation Feedback Form.

- We value your feedback.
- Let us know how we can improve this page by filling in Espressif Documentation Feedback Form.