1| Supported Targets | ESP32 |
2| ----------------- | ----- |
3
4# High Resolution Timer Example (`esp_timer`)
5
6(See the README.md file in the upper level 'examples' directory for more information about examples.)
7
8The [High Resolution Timer (`esp_timer`)](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html) APIs allow an application to create multiple timers using a single hardware timer, and hides complexity associated with managing multiple timers, invoking callbacks, accounting for APB frequency changes (if dynamic frequency scaling is enabled), and maintaining correct time after light sleep.
9
10This example illustrates the usage of the [`esp_timer` API](https://docs.espressif.com/projects/esp-idf/en/latest/api-reference/system/esp_timer.html#api-reference) to create one-shot and periodic software timers.
11
12The `esp_timer` API also provides the `esp_timer_get_time()` function which returns the time since boot in microseconds. This can be useful for fine-grained timing in tasks and ISRs thus is also demonstrated in this example.
13
14## How to use example
15
16### Hardware Required
17
18This example should be able to run on any commonly available ESP32 development board.
19
20### Configure the project
21
22```
23idf.py menuconfig
24```
25
26Under `Component config > Common ESP-related` are the following `esp_timer` related configurations
27
28* `High-resolution timer task stack size` can be increased if timer callbacks require a larger stack
29* `Enable esp_timer profiling features` will cause `esp_timer_dump()` to include more information.
30
31### Build and Flash
32
33Build the project and flash it to the board, then run monitor tool to view serial output:
34
35```
36idf.py -p PORT flash monitor
37```
38
39(Replace PORT with the name of the serial port to use.)
40
41(To exit the serial monitor, type ``Ctrl-]``.)
42
43See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
44
45## Example Output
46
47The example should have the following log output:
48
49```
50...
51I (294) example: Started timers, time since boot: 9662 us
52periodic            500000        509644          1          0          0             0
53one-shot                 0       5009654          1          0          0             0
54I (794) example: Periodic timer called, time since boot: 509694 us
55I (1294) example: Periodic timer called, time since boot: 1009671 us
56I (1794) example: Periodic timer called, time since boot: 1509671 us
57I (2294) example: Periodic timer called, time since boot: 2009671 us
58periodic            500000       2509644          1          4          0           542
59one-shot                 0       5009654          1          0          0             0
60I (2794) example: Periodic timer called, time since boot: 2509671 us
61I (3294) example: Periodic timer called, time since boot: 3009671 us
62I (3794) example: Periodic timer called, time since boot: 3509671 us
63I (4294) example: Periodic timer called, time since boot: 4009671 us
64periodic            500000       4509644          1          8          0          1026
65one-shot                 0       5009654          1          0          0             0
66I (4794) example: Periodic timer called, time since boot: 4509671 us
67I (5294) example: Periodic timer called, time since boot: 5009669 us
68I (5294) example: One-shot timer called, time since boot: 5009788 us
69I (5294) example: Restarted periodic timer with 1s period, time since boot: 5012675 us
70I (6294) example: Periodic timer called, time since boot: 6012692 us
71periodic           1000000       7012666          2         11          0          1391
72one-shot                 0             0          1          1          0         11472
73I (7294) example: Periodic timer called, time since boot: 7012692 us
74I (8294) example: Periodic timer called, time since boot: 8012692 us
75periodic           1000000       9012666          2         13          0          1639
76one-shot                 0             0          1          1          0         11472
77I (9294) example: Periodic timer called, time since boot: 9012692 us
78I (10294) example: Periodic timer called, time since boot: 10012692 us
79I (10314) example: Entering light sleep for 0.5s, time since boot: 10024351 us
80I (10314) example: Woke up from light sleep, time since boot: 10525143 us
81...
82```
83
84## Example Breakdown
85
86### 1. Creating and starting timers
87
88The example starts by creating a periodic and a one shot timer using the `esp_timer_create()` function. Once created, the two timers are started using the `esp_timer_start_periodic()` and `esp_timer_start_once()` functions.
89
90```
91I (265) example: Starting timers, time since boot: 2479 us
92```
93
94### 2. Getting initial timer dump
95
96These two repeating lines are the output of `esp_timer_dump()` function. There is one line for each of the timers created. This function can be useful for debugging purposes. Note that such debugging information is available because the example sets `CONFIG_ESP_TIMER_PROFILING` option in sdkconfig. Without this option, less information will be available. See documentation of `esp_timer_dump()` in ESP-IDF programming guide for more details.
97
98```
99timer               period     next time      times        times       times        callback
100name                            to fire      started       fired      skipped      run time (us)
101-------------------------------------------------------------------------------------------------
102
103periodic            500000        502455          1          0           0              0
104one-shot                 0       5002469          1          0           0              0
105```
106
107### 3. Periodic timer keeps running at 500ms period:
108
109```
110I (765) example: Periodic timer called, time since boot: 502506 us
111I (1265) example: Periodic timer called, time since boot: 1002478 us
112I (1765) example: Periodic timer called, time since boot: 1502478 us
113I (2265) example: Periodic timer called, time since boot: 2002478 us
114periodic            500000       2502455          1          4          0          511
115one-shot                 0       5002469          1          0          0            0
116I (2765) example: Periodic timer called, time since boot: 2502478 us
117I (3265) example: Periodic timer called, time since boot: 3002478 us
118I (3765) example: Periodic timer called, time since boot: 3502478 us
119I (4265) example: Periodic timer called, time since boot: 4002478 us
120periodic            500000       4502455          1          8          0          971
121one-shot                 0       5002469          1          0          0            0
122I (4765) example: Periodic timer called, time since boot: 4502478 us
123I (5265) example: Periodic timer called, time since boot: 5002476 us
124```
125
126### 4. One-shot timer runs
127
128The one-shot timer runs and changes the period of the periodic timer. Now the periodic timer runs with a period of 1 second:
129
130```
131I (5265) example: One-shot timer called, time since boot: 5002586 us
132I (5265) example: Restarted periodic timer with 1s period, time since boot: 5005475 us
133I (6265) example: Periodic timer called, time since boot: 6005492 us
134periodic           1000000       7005469          2         11          0          1316
135one-shot                 0             0          1          1          0         11474
136I (7265) example: Periodic timer called, time since boot: 7005492 us
137I (8265) example: Periodic timer called, time since boot: 8005492 us
138periodic           1000000       9005469          2         13          0          1550
139one-shot                 0             0          1          1          0         11474
140I (9265) example: Periodic timer called, time since boot: 9005492 us
141I (10265) example: Periodic timer called, time since boot: 10005492 us
142```
143
144### 5. Continuation through light sleep
145
146To illustrate that timekeeping continues correctly after light sleep, the example enters light sleep for 0.5 seconds. This sleep does not impact timer period, and the timer is executed 1 second after the previous iteration. Note that the timers can not execute during light sleep, since the CPU is not running at that time. Such timers would execute immediately after light sleep, and then continue running with their normal period.
147
148```
149I (10275) example: Entering light sleep for 0.5s, time since boot: 10011559 us
150I (10275) example: Woke up from light sleep, time since boot: 10512007 us
151I (10765) example: Periodic timer called, time since boot: 11005492 us
152I (11765) example: Periodic timer called, time since boot: 12005492 us
153```
154
155### 6. Finally, timers are deleted.
156
157```
158I (12275) example: Stopped and deleted timers
159```