Espressif ESP32-S2 User Manual

Chapter 2. API Reference
• Timer callbacks are dispatched from a low-priority task
Hardware timers are free from both of the limitations, but often they are less convenient to use. For example,
application components may need timer events to fire at certain times in the future, but the hardware timer only
contains one “compare”value used for interrupt generation. This means that some facility needs to be built on top
of the hardware timer to manage the list of pending events can dispatch the callbacks for these events as corresponding
hardware interrupts happen.
An interrupt level of the handler depends on the CONFIG_ESP_TIMER_INTERRUPT_LEVEL option. It allows to set
this: 1, 2 or 3 level (by default 1). Raising the level, the interrupt handler can reduce the timer processing delay.
esp_timer set of APIs provides one-shot and periodic timers, microsecond time resolution, and 64-bit range.
Internally, esp_timer uses a 64-bit hardware timer, where the implemention depends on CON-
FIG_ESP_TIMER_IMPL. Available options are:
• SYSTIMER
Timer callbacks can dispatched by two methods:
• ESP_TIMER_TASK
• ESP_TIMER_ISR. Available only if CONFIG_ESP_TIMER_SUPPORTS_ISR_DISPATCH_METHOD is en-
abled (by default disabled).
ESP_TIMER_TASK. Timer callbacks are dispatched from a high-priority esp_timer task. Because all the call-
backs are dispatched from the same task, it is recommended to only do the minimal possible amount of work from
the callback itself, posting an event to a lower priority task using a queue instead.
If other tasks with priority higher than esp_timer are running, callback dispatching will be delayed until
esp_timer task has a chance to run. For example, this will happen if a SPI Flash operation is in progress.
ESP_TIMER_ISR. Timer callbacks are dispatched directly from the timer interrupt handler. This method is useful
for some simple callbacks which aim for lower latency.
Creating and starting a timer, and dispatching the callback takes some time. Therefore there is a lower limit to the
timeout value of one-shot esp_timer. If esp_timer_start_once() is called with a timeout value less than
20us, the callback will be dispatched only after approximately 20us.
Periodic esp_timer also imposes a 50us restriction on the minimal timer period. Periodic software timers with
period of less than 50us are not practical since they would consume most of the CPU time. Consider using dedicated
hardware peripherals or DMA features if you find that a timer with small period is required.
Using esp_timer APIs
Single timer is represented by esp_timer_handle_t type. Timer has a callback function associated with it.
This callback function is called from the esp_timer task each time the timer elapses.
• To create a timer, call esp_timer_create().
• To delete the timer when it is no longer needed, call esp_timer_delete().
The timer can be started in one-shot mode or in periodic mode.
• To start the timer in one-shot mode, call esp_timer_start_once(), passing the time interval after
which the callback should be called. When the callback gets called, the timer is considered to be stopped.
• To start the timer in periodic mode, call esp_timer_start_periodic(), passing the period with which
the callback should be called. The timer keeps running until esp_timer_stop() is called.
Note that the timer must not be running when esp_timer_start_once() or
esp_timer_start_periodic() is called. To restart a running timer, call esp_timer_stop()
first, then call one of the start functions.
Callback functions
Timer callbacks which are processed by ESP_TIMER_ISR method should not call the
context switch call - portYIELD_FROM_ISR(), instead of this you should use the
Espressif Systems 994
Submit Document Feedback
Release v4.4

Espressif ESP32-S2 Specifications

General

Brand	Espressif
Model	ESP32-S2
Category	Single board computers
Language	English