1 // Copyright 2015-2016 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 #ifndef _DRIVER_RTC_GPIO_H_
16 #define _DRIVER_RTC_GPIO_H_
17
18 #include <stdint.h>
19 #include "esp_err.h"
20 #include "soc/soc_caps.h"
21 #include "soc/rtc_io_periph.h"
22 #include "hal/rtc_io_types.h"
23 #include "driver/gpio.h"
24
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 /**
31 * @brief Determine if the specified GPIO is a valid RTC GPIO.
32 *
33 * @param gpio_num GPIO number
34 * @return true if GPIO is valid for RTC GPIO use. false otherwise.
35 */
rtc_gpio_is_valid_gpio(gpio_num_t gpio_num)36 static inline bool rtc_gpio_is_valid_gpio(gpio_num_t gpio_num)
37 {
38 #if SOC_RTCIO_INPUT_OUTPUT_SUPPORTED
39 return (gpio_num < GPIO_PIN_COUNT && rtc_io_num_map[gpio_num] >= 0);
40 #else
41 return false;
42 #endif
43 }
44
45 #define RTC_GPIO_IS_VALID_GPIO(gpio_num) rtc_gpio_is_valid_gpio(gpio_num) // Deprecated, use rtc_gpio_is_valid_gpio()
46
47 #if SOC_RTCIO_INPUT_OUTPUT_SUPPORTED
48 /**
49 * @brief Get RTC IO index number by gpio number.
50 *
51 * @param gpio_num GPIO number
52 * @return
53 * >=0: Index of rtcio.
54 * -1 : The gpio is not rtcio.
55 */
rtc_io_number_get(gpio_num_t gpio_num)56 static inline int rtc_io_number_get(gpio_num_t gpio_num)
57 {
58 return rtc_io_num_map[gpio_num];
59 }
60
61 /**
62 * @brief Init a GPIO as RTC GPIO
63 *
64 * This function must be called when initializing a pad for an analog function.
65 *
66 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
67 *
68 * @return
69 * - ESP_OK success
70 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
71 */
72 esp_err_t rtc_gpio_init(gpio_num_t gpio_num);
73
74 /**
75 * @brief Init a GPIO as digital GPIO
76 *
77 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
78 *
79 * @return
80 * - ESP_OK success
81 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
82 */
83 esp_err_t rtc_gpio_deinit(gpio_num_t gpio_num);
84
85 /**
86 * @brief Get the RTC IO input level
87 *
88 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
89 *
90 * @return
91 * - 1 High level
92 * - 0 Low level
93 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
94 */
95 uint32_t rtc_gpio_get_level(gpio_num_t gpio_num);
96
97 /**
98 * @brief Set the RTC IO output level
99 *
100 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
101 * @param level output level
102 *
103 * @return
104 * - ESP_OK Success
105 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
106 */
107 esp_err_t rtc_gpio_set_level(gpio_num_t gpio_num, uint32_t level);
108
109 /**
110 * @brief RTC GPIO set direction
111 *
112 * Configure RTC GPIO direction, such as output only, input only,
113 * output and input.
114 *
115 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
116 * @param mode GPIO direction
117 *
118 * @return
119 * - ESP_OK Success
120 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
121 */
122 esp_err_t rtc_gpio_set_direction(gpio_num_t gpio_num, rtc_gpio_mode_t mode);
123
124 /**
125 * @brief RTC GPIO set direction in deep sleep mode or disable sleep status (default).
126 * In some application scenarios, IO needs to have another states during deep sleep.
127 *
128 * NOTE: ESP32 support INPUT_ONLY mode.
129 * ESP32S2 support INPUT_ONLY, OUTPUT_ONLY, INPUT_OUTPUT mode.
130 *
131 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
132 * @param mode GPIO direction
133 *
134 * @return
135 * - ESP_OK Success
136 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
137 */
138 esp_err_t rtc_gpio_set_direction_in_sleep(gpio_num_t gpio_num, rtc_gpio_mode_t mode);
139
140 /**
141 * @brief RTC GPIO pullup enable
142 *
143 * This function only works for RTC IOs. In general, call gpio_pullup_en,
144 * which will work both for normal GPIOs and RTC IOs.
145 *
146 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
147 *
148 * @return
149 * - ESP_OK Success
150 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
151 */
152 esp_err_t rtc_gpio_pullup_en(gpio_num_t gpio_num);
153
154 /**
155 * @brief RTC GPIO pulldown enable
156 *
157 * This function only works for RTC IOs. In general, call gpio_pulldown_en,
158 * which will work both for normal GPIOs and RTC IOs.
159 *
160 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
161 *
162 * @return
163 * - ESP_OK Success
164 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
165 */
166 esp_err_t rtc_gpio_pulldown_en(gpio_num_t gpio_num);
167
168 /**
169 * @brief RTC GPIO pullup disable
170 *
171 * This function only works for RTC IOs. In general, call gpio_pullup_dis,
172 * which will work both for normal GPIOs and RTC IOs.
173 *
174 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
175 *
176 * @return
177 * - ESP_OK Success
178 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
179 */
180 esp_err_t rtc_gpio_pullup_dis(gpio_num_t gpio_num);
181
182 /**
183 * @brief RTC GPIO pulldown disable
184 *
185 * This function only works for RTC IOs. In general, call gpio_pulldown_dis,
186 * which will work both for normal GPIOs and RTC IOs.
187 *
188 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
189 *
190 * @return
191 * - ESP_OK Success
192 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
193 */
194 esp_err_t rtc_gpio_pulldown_dis(gpio_num_t gpio_num);
195
196 /**
197 * @brief Set RTC GPIO pad drive capability
198 *
199 * @param gpio_num GPIO number, only support output GPIOs
200 * @param strength Drive capability of the pad
201 *
202 * @return
203 * - ESP_OK Success
204 * - ESP_ERR_INVALID_ARG Parameter error
205 */
206 esp_err_t rtc_gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength);
207
208 /**
209 * @brief Get RTC GPIO pad drive capability
210 *
211 * @param gpio_num GPIO number, only support output GPIOs
212 * @param strength Pointer to accept drive capability of the pad
213 *
214 * @return
215 * - ESP_OK Success
216 * - ESP_ERR_INVALID_ARG Parameter error
217 */
218 esp_err_t rtc_gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t* strength);
219
220 #endif // SOC_RTCIO_INPUT_OUTPUT_SUPPORTED
221
222 #if SOC_RTCIO_HOLD_SUPPORTED
223
224 /**
225 * @brief Enable hold function on an RTC IO pad
226 *
227 * Enabling HOLD function will cause the pad to latch current values of
228 * input enable, output enable, output value, function, drive strength values.
229 * This function is useful when going into light or deep sleep mode to prevent
230 * the pin configuration from changing.
231 *
232 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
233 * @return
234 * - ESP_OK Success
235 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
236 */
237 esp_err_t rtc_gpio_hold_en(gpio_num_t gpio_num);
238
239 /**
240 * @brief Disable hold function on an RTC IO pad
241 *
242 * Disabling hold function will allow the pad receive the values of
243 * input enable, output enable, output value, function, drive strength from
244 * RTC_IO peripheral.
245 *
246 * @param gpio_num GPIO number (e.g. GPIO_NUM_12)
247 * @return
248 * - ESP_OK Success
249 * - ESP_ERR_INVALID_ARG GPIO is not an RTC IO
250 */
251 esp_err_t rtc_gpio_hold_dis(gpio_num_t gpio_num);
252
253 /**
254 * @brief Helper function to disconnect internal circuits from an RTC IO
255 * This function disables input, output, pullup, pulldown, and enables
256 * hold feature for an RTC IO.
257 * Use this function if an RTC IO needs to be disconnected from internal
258 * circuits in deep sleep, to minimize leakage current.
259 *
260 * In particular, for ESP32-WROVER module, call
261 * rtc_gpio_isolate(GPIO_NUM_12) before entering deep sleep, to reduce
262 * deep sleep current.
263 *
264 * @param gpio_num GPIO number (e.g. GPIO_NUM_12).
265 * @return
266 * - ESP_OK on success
267 * - ESP_ERR_INVALID_ARG if GPIO is not an RTC IO
268 */
269 esp_err_t rtc_gpio_isolate(gpio_num_t gpio_num);
270
271 /**
272 * @brief Enable force hold signal for all RTC IOs
273 *
274 * Each RTC pad has a "force hold" input signal from the RTC controller.
275 * If this signal is set, pad latches current values of input enable,
276 * function, output enable, and other signals which come from the RTC mux.
277 * Force hold signal is enabled before going into deep sleep for pins which
278 * are used for EXT1 wakeup.
279 */
280 esp_err_t rtc_gpio_force_hold_all(void);
281
282 /**
283 * @brief Disable force hold signal for all RTC IOs
284 */
285 esp_err_t rtc_gpio_force_hold_dis_all(void);
286
287 #endif // SOC_RTCIO_HOLD_SUPPORTED
288
289 #if SOC_RTCIO_WAKE_SUPPORTED
290
291 /**
292 * @brief Enable wakeup from sleep mode using specific GPIO
293 * @param gpio_num GPIO number
294 * @param intr_type Wakeup on high level (GPIO_INTR_HIGH_LEVEL) or low level
295 * (GPIO_INTR_LOW_LEVEL)
296 * @return
297 * - ESP_OK on success
298 * - ESP_ERR_INVALID_ARG if gpio_num is not an RTC IO, or intr_type is not
299 * one of GPIO_INTR_HIGH_LEVEL, GPIO_INTR_LOW_LEVEL.
300 */
301 esp_err_t rtc_gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type);
302
303 /**
304 * @brief Disable wakeup from sleep mode using specific GPIO
305 * @param gpio_num GPIO number
306 * @return
307 * - ESP_OK on success
308 * - ESP_ERR_INVALID_ARG if gpio_num is not an RTC IO
309 */
310 esp_err_t rtc_gpio_wakeup_disable(gpio_num_t gpio_num);
311
312 #endif // SOC_RTCIO_WAKE_SUPPORTED
313
314 #ifdef __cplusplus
315 }
316 #endif
317
318 #endif
319