1 // Copyright 2020 Espressif Systems (Shanghai) PTE LTD
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 #pragma once
16
17 #ifdef __cpp_exceptions
18
19 #include <chrono>
20 #include <functional>
21 #include <string>
22 #include "esp_exception.hpp"
23 #include "esp_timer.h"
24
25 namespace idf {
26
27 namespace esp_timer {
28
29 /**
30 * @brief Get time since boot
31 * @return time since \c esp_timer_init() was called (this normally happens early during application startup).
32 */
get_time()33 static inline std::chrono::microseconds get_time()
34 {
35 return std::chrono::microseconds(esp_timer_get_time());
36 }
37
38 /**
39 * @brief Get the timestamp when the next timeout is expected to occur
40 * @return Timestamp of the nearest timer event.
41 * The timebase is the same as for the values returned by \c get_time().
42 */
get_next_alarm()43 static inline std::chrono::microseconds get_next_alarm()
44 {
45 return std::chrono::microseconds(esp_timer_get_next_alarm());
46 }
47
48
49 /**
50 * @brief
51 * A timer using the esp_timer component which can be started either as one-shot timer or periodically.
52 */
53 class ESPTimer {
54 public:
55 /**
56 * @param timeout_cb The timeout callback.
57 * @param timer_name The name of the timer (optional). This is for debugging using \c esp_timer_dump().
58 */
59 ESPTimer(std::function<void()> timeout_cb, const std::string &timer_name = "ESPTimer");
60
61 /**
62 * Stop the timer if necessary and delete it.
63 */
64 ~ESPTimer();
65
66 /**
67 * Default copy constructor is deleted since one instance of esp_timer_handle_t must not be shared.
68 */
69 ESPTimer(const ESPTimer&) = delete;
70
71 /**
72 * Default copy assignment is deleted since one instance of esp_timer_handle_t must not be shared.
73 */
74 ESPTimer &operator=(const ESPTimer&) = delete;
75
76 /**
77 * @brief Start one-shot timer
78 *
79 * Timer should not be running (started) when this function is called.
80 *
81 * @param timeout timer timeout, in microseconds relative to the current moment.
82 *
83 * @throws ESPException with error ESP_ERR_INVALID_STATE if the timer is already running.
84 */
start(std::chrono::microseconds timeout)85 inline void start(std::chrono::microseconds timeout)
86 {
87 CHECK_THROW(esp_timer_start_once(timer_handle, timeout.count()));
88 }
89
90 /**
91 * @brief Start periodic timer
92 *
93 * Timer should not be running when this function is called. This function will
94 * start a timer which will trigger every 'period' microseconds.
95 *
96 * Timer should not be running (started) when this function is called.
97 *
98 * @param timeout timer timeout, in microseconds relative to the current moment.
99 *
100 * @throws ESPException with error ESP_ERR_INVALID_STATE if the timer is already running.
101 */
start_periodic(std::chrono::microseconds period)102 inline void start_periodic(std::chrono::microseconds period)
103 {
104 CHECK_THROW(esp_timer_start_periodic(timer_handle, period.count()));
105 }
106
107 /**
108 * @brief Stop the previously started timer.
109 *
110 * This function stops the timer previously started using \c start() or \c start_periodic().
111 *
112 * @throws ESPException with error ESP_ERR_INVALID_STATE if the timer has not been started yet.
113 */
stop()114 inline void stop()
115 {
116 CHECK_THROW(esp_timer_stop(timer_handle));
117 }
118
119 private:
120 /**
121 * Internal callback to hook into esp_timer component.
122 */
123 static void esp_timer_cb(void *arg);
124
125 /**
126 * Timer instance of the underlying esp_event component.
127 */
128 esp_timer_handle_t timer_handle;
129
130 /**
131 * Callback which will be called once the timer triggers.
132 */
133 std::function<void()> timeout_cb;
134
135 /**
136 * Name of the timer, will be passed to the underlying timer framework and is used for debugging.
137 */
138 const std::string name;
139 };
140
141 } // esp_timer
142
143 } // idf
144
145 #endif // __cpp_exceptions
146
