1 // Copyright 2015-2017 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 #include <stdint.h> 18 #include "esp_err.h" 19 20 #include "hal/touch_sensor_types.h" 21 #include "hal/gpio_types.h" 22 23 #include "soc/soc_caps.h" 24 25 #ifdef __cplusplus 26 extern "C" { 27 #endif 28 29 /** 30 * @brief Logic function used for EXT1 wakeup mode. 31 */ 32 typedef enum { 33 ESP_EXT1_WAKEUP_ALL_LOW = 0, //!< Wake the chip when all selected GPIOs go low 34 ESP_EXT1_WAKEUP_ANY_HIGH = 1 //!< Wake the chip when any of the selected GPIOs go high 35 } esp_sleep_ext1_wakeup_mode_t; 36 37 #if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP 38 typedef enum { 39 ESP_GPIO_WAKEUP_GPIO_LOW = 0, 40 ESP_GPIO_WAKEUP_GPIO_HIGH = 1 41 } esp_deepsleep_gpio_wake_up_mode_t; 42 #endif 43 44 /** 45 * @brief Power domains which can be powered down in sleep mode 46 */ 47 typedef enum { 48 ESP_PD_DOMAIN_RTC_PERIPH, //!< RTC IO, sensors and ULP co-processor 49 ESP_PD_DOMAIN_RTC_SLOW_MEM, //!< RTC slow memory 50 ESP_PD_DOMAIN_RTC_FAST_MEM, //!< RTC fast memory 51 ESP_PD_DOMAIN_XTAL, //!< XTAL oscillator 52 ESP_PD_DOMAIN_CPU, //!< CPU core 53 ESP_PD_DOMAIN_VDDSDIO, //!< VDD_SDIO 54 ESP_PD_DOMAIN_MAX //!< Number of domains 55 } esp_sleep_pd_domain_t; 56 57 /** 58 * @brief Power down options 59 */ 60 typedef enum { 61 ESP_PD_OPTION_OFF, //!< Power down the power domain in sleep mode 62 ESP_PD_OPTION_ON, //!< Keep power domain enabled during sleep mode 63 ESP_PD_OPTION_AUTO //!< Keep power domain enabled in sleep mode, if it is needed by one of the wakeup options. Otherwise power it down. 64 } esp_sleep_pd_option_t; 65 66 /** 67 * @brief Sleep wakeup cause 68 */ 69 typedef enum { 70 ESP_SLEEP_WAKEUP_UNDEFINED, //!< In case of deep sleep, reset was not caused by exit from deep sleep 71 ESP_SLEEP_WAKEUP_ALL, //!< Not a wakeup cause, used to disable all wakeup sources with esp_sleep_disable_wakeup_source 72 ESP_SLEEP_WAKEUP_EXT0, //!< Wakeup caused by external signal using RTC_IO 73 ESP_SLEEP_WAKEUP_EXT1, //!< Wakeup caused by external signal using RTC_CNTL 74 ESP_SLEEP_WAKEUP_TIMER, //!< Wakeup caused by timer 75 ESP_SLEEP_WAKEUP_TOUCHPAD, //!< Wakeup caused by touchpad 76 ESP_SLEEP_WAKEUP_ULP, //!< Wakeup caused by ULP program 77 ESP_SLEEP_WAKEUP_GPIO, //!< Wakeup caused by GPIO (light sleep only) 78 ESP_SLEEP_WAKEUP_UART, //!< Wakeup caused by UART (light sleep only) 79 ESP_SLEEP_WAKEUP_WIFI, //!< Wakeup caused by WIFI (light sleep only) 80 ESP_SLEEP_WAKEUP_COCPU, //!< Wakeup caused by COCPU int 81 ESP_SLEEP_WAKEUP_COCPU_TRAP_TRIG, //!< Wakeup caused by COCPU crash 82 ESP_SLEEP_WAKEUP_BT, //!< Wakeup caused by BT (light sleep only) 83 } esp_sleep_source_t; 84 85 /* Leave this type define for compatibility */ 86 typedef esp_sleep_source_t esp_sleep_wakeup_cause_t; 87 88 /** 89 * @brief Disable wakeup source 90 * 91 * This function is used to deactivate wake up trigger for source 92 * defined as parameter of the function. 93 * 94 * @note This function does not modify wake up configuration in RTC. 95 * It will be performed in esp_sleep_start function. 96 * 97 * See docs/sleep-modes.rst for details. 98 * 99 * @param source - number of source to disable of type esp_sleep_source_t 100 * @return 101 * - ESP_OK on success 102 * - ESP_ERR_INVALID_STATE if trigger was not active 103 */ 104 esp_err_t esp_sleep_disable_wakeup_source(esp_sleep_source_t source); 105 106 #if SOC_ULP_SUPPORTED 107 /** 108 * @brief Enable wakeup by ULP coprocessor 109 * @note In revisions 0 and 1 of the ESP32, ULP wakeup source 110 * cannot be used when RTC_PERIPH power domain is forced 111 * to be powered on (ESP_PD_OPTION_ON) or when 112 * ext0 wakeup source is used. 113 * @return 114 * - ESP_OK on success 115 * - ESP_ERR_NOT_SUPPORTED if additional current by touch (CONFIG_ESP32_RTC_EXT_CRYST_ADDIT_CURRENT) is enabled. 116 * - ESP_ERR_INVALID_STATE if ULP co-processor is not enabled or if wakeup triggers conflict 117 */ 118 esp_err_t esp_sleep_enable_ulp_wakeup(void); 119 120 #endif // SOC_ULP_SUPPORTED 121 122 /** 123 * @brief Enable wakeup by timer 124 * @param time_in_us time before wakeup, in microseconds 125 * @return 126 * - ESP_OK on success 127 * - ESP_ERR_INVALID_ARG if value is out of range (TBD) 128 */ 129 esp_err_t esp_sleep_enable_timer_wakeup(uint64_t time_in_us); 130 131 #if SOC_TOUCH_SENSOR_NUM > 0 132 133 /** 134 * @brief Enable wakeup by touch sensor 135 * 136 * @note In revisions 0 and 1 of the ESP32, touch wakeup source 137 * can not be used when RTC_PERIPH power domain is forced 138 * to be powered on (ESP_PD_OPTION_ON) or when ext0 wakeup 139 * source is used. 140 * 141 * @note The FSM mode of the touch button should be configured 142 * as the timer trigger mode. 143 * 144 * @return 145 * - ESP_OK on success 146 * - ESP_ERR_NOT_SUPPORTED if additional current by touch (CONFIG_ESP32_RTC_EXT_CRYST_ADDIT_CURRENT) is enabled. 147 * - ESP_ERR_INVALID_STATE if wakeup triggers conflict 148 */ 149 esp_err_t esp_sleep_enable_touchpad_wakeup(void); 150 151 /** 152 * @brief Get the touch pad which caused wakeup 153 * 154 * If wakeup was caused by another source, this function will return TOUCH_PAD_MAX; 155 * 156 * @return touch pad which caused wakeup 157 */ 158 touch_pad_t esp_sleep_get_touchpad_wakeup_status(void); 159 160 #endif // SOC_TOUCH_SENSOR_NUM > 0 161 162 /** 163 * @brief Returns true if a GPIO number is valid for use as wakeup source. 164 * 165 * @note For SoCs with RTC IO capability, this can be any valid RTC IO input pin. 166 * 167 * @param gpio_num Number of the GPIO to test for wakeup source capability 168 * 169 * @return True if this GPIO number will be accepted as a sleep wakeup source. 170 */ 171 bool esp_sleep_is_valid_wakeup_gpio(gpio_num_t gpio_num); 172 173 #if SOC_PM_SUPPORT_EXT_WAKEUP 174 175 /** 176 * @brief Enable wakeup using a pin 177 * 178 * This function uses external wakeup feature of RTC_IO peripheral. 179 * It will work only if RTC peripherals are kept on during sleep. 180 * 181 * This feature can monitor any pin which is an RTC IO. Once the pin transitions 182 * into the state given by level argument, the chip will be woken up. 183 * 184 * @note This function does not modify pin configuration. The pin is 185 * configured in esp_sleep_start, immediately before entering sleep mode. 186 * 187 * @note In revisions 0 and 1 of the ESP32, ext0 wakeup source 188 * can not be used together with touch or ULP wakeup sources. 189 * 190 * @param gpio_num GPIO number used as wakeup source. Only GPIOs which are have RTC 191 * functionality can be used: 0,2,4,12-15,25-27,32-39. 192 * @param level input level which will trigger wakeup (0=low, 1=high) 193 * @return 194 * - ESP_OK on success 195 * - ESP_ERR_INVALID_ARG if the selected GPIO is not an RTC GPIO, 196 * or the mode is invalid 197 * - ESP_ERR_INVALID_STATE if wakeup triggers conflict 198 */ 199 esp_err_t esp_sleep_enable_ext0_wakeup(gpio_num_t gpio_num, int level); 200 201 /** 202 * @brief Enable wakeup using multiple pins 203 * 204 * This function uses external wakeup feature of RTC controller. 205 * It will work even if RTC peripherals are shut down during sleep. 206 * 207 * This feature can monitor any number of pins which are in RTC IOs. 208 * Once any of the selected pins goes into the state given by mode argument, 209 * the chip will be woken up. 210 * 211 * @note This function does not modify pin configuration. The pins are 212 * configured in esp_sleep_start, immediately before 213 * entering sleep mode. 214 * 215 * @note internal pullups and pulldowns don't work when RTC peripherals are 216 * shut down. In this case, external resistors need to be added. 217 * Alternatively, RTC peripherals (and pullups/pulldowns) may be 218 * kept enabled using esp_sleep_pd_config function. 219 * 220 * @param mask bit mask of GPIO numbers which will cause wakeup. Only GPIOs 221 * which are have RTC functionality can be used in this bit map: 222 * 0,2,4,12-15,25-27,32-39. 223 * @param mode select logic function used to determine wakeup condition: 224 * - ESP_EXT1_WAKEUP_ALL_LOW: wake up when all selected GPIOs are low 225 * - ESP_EXT1_WAKEUP_ANY_HIGH: wake up when any of the selected GPIOs is high 226 * @return 227 * - ESP_OK on success 228 * - ESP_ERR_INVALID_ARG if any of the selected GPIOs is not an RTC GPIO, 229 * or mode is invalid 230 */ 231 esp_err_t esp_sleep_enable_ext1_wakeup(uint64_t mask, esp_sleep_ext1_wakeup_mode_t mode); 232 233 #endif // SOC_PM_SUPPORT_EXT_WAKEUP 234 235 #if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP 236 /** 237 * @brief Enable wakeup using specific gpio pins 238 * 239 * This function enables an IO pin to wake the chip from deep sleep 240 * 241 * @note This function does not modify pin configuration. The pins are 242 * configured in esp_sleep_start, immediately before 243 * entering sleep mode. 244 * 245 * @note You don't need to care to pull-up or pull-down before using this 246 * function, because this will be done in esp_sleep_start based on 247 * param mask you give. BTW, when you use low level to wake up the 248 * chip, we strongly recommand you to add external registors(pull-up). 249 * 250 * @param gpio_pin_mask Bit mask of GPIO numbers which will cause wakeup. Only GPIOs 251 * which are have RTC functionality can be used in this bit map. 252 * @param mode Select logic function used to determine wakeup condition: 253 * - ESP_GPIO_WAKEUP_GPIO_LOW: wake up when the gpio turn to low. 254 * - ESP_GPIO_WAKEUP_GPIO_HIGH: wake up when the gpio turn to high. 255 * @return 256 * - ESP_OK on success 257 * - ESP_ERR_INVALID_ARG if gpio num is more than 5 or mode is invalid, 258 */ 259 esp_err_t esp_deep_sleep_enable_gpio_wakeup(uint64_t gpio_pin_mask, esp_deepsleep_gpio_wake_up_mode_t mode); 260 #endif 261 /** 262 * @brief Enable wakeup from light sleep using GPIOs 263 * 264 * Each GPIO supports wakeup function, which can be triggered on either low level 265 * or high level. Unlike EXT0 and EXT1 wakeup sources, this method can be used 266 * both for all IOs: RTC IOs and digital IOs. It can only be used to wakeup from 267 * light sleep though. 268 * 269 * To enable wakeup, first call gpio_wakeup_enable, specifying gpio number and 270 * wakeup level, for each GPIO which is used for wakeup. 271 * Then call this function to enable wakeup feature. 272 * 273 * @note In revisions 0 and 1 of the ESP32, GPIO wakeup source 274 * can not be used together with touch or ULP wakeup sources. 275 * 276 * @return 277 * - ESP_OK on success 278 * - ESP_ERR_INVALID_STATE if wakeup triggers conflict 279 */ 280 esp_err_t esp_sleep_enable_gpio_wakeup(void); 281 282 /** 283 * @brief Enable wakeup from light sleep using UART 284 * 285 * Use uart_set_wakeup_threshold function to configure UART wakeup threshold. 286 * 287 * Wakeup from light sleep takes some time, so not every character sent 288 * to the UART can be received by the application. 289 * 290 * @note ESP32 does not support wakeup from UART2. 291 * 292 * @param uart_num UART port to wake up from 293 * @return 294 * - ESP_OK on success 295 * - ESP_ERR_INVALID_ARG if wakeup from given UART is not supported 296 */ 297 esp_err_t esp_sleep_enable_uart_wakeup(int uart_num); 298 299 /** 300 * @brief Enable wakeup by WiFi MAC 301 * @return 302 * - ESP_OK on success 303 */ 304 esp_err_t esp_sleep_enable_wifi_wakeup(void); 305 306 /** 307 * @brief Disable wakeup by WiFi MAC 308 * @return 309 * - ESP_OK on success 310 */ 311 esp_err_t esp_sleep_disable_wifi_wakeup(void); 312 313 /** 314 * @brief Get the bit mask of GPIOs which caused wakeup (ext1) 315 * 316 * If wakeup was caused by another source, this function will return 0. 317 * 318 * @return bit mask, if GPIOn caused wakeup, BIT(n) will be set 319 */ 320 uint64_t esp_sleep_get_ext1_wakeup_status(void); 321 322 #if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP 323 /** 324 * @brief Get the bit mask of GPIOs which caused wakeup (gpio) 325 * 326 * If wakeup was caused by another source, this function will return 0. 327 * 328 * @return bit mask, if GPIOn caused wakeup, BIT(n) will be set 329 */ 330 uint64_t esp_sleep_get_gpio_wakeup_status(void); 331 #endif //SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP 332 333 /** 334 * @brief Set power down mode for an RTC power domain in sleep mode 335 * 336 * If not set set using this API, all power domains default to ESP_PD_OPTION_AUTO. 337 * 338 * @param domain power domain to configure 339 * @param option power down option (ESP_PD_OPTION_OFF, ESP_PD_OPTION_ON, or ESP_PD_OPTION_AUTO) 340 * @return 341 * - ESP_OK on success 342 * - ESP_ERR_INVALID_ARG if either of the arguments is out of range 343 */ 344 esp_err_t esp_sleep_pd_config(esp_sleep_pd_domain_t domain, 345 esp_sleep_pd_option_t option); 346 347 /** 348 * @brief Enter deep sleep with the configured wakeup options 349 * 350 * This function does not return. 351 */ 352 void esp_deep_sleep_start(void) __attribute__((noreturn)); 353 354 /** 355 * @brief Enter light sleep with the configured wakeup options 356 * 357 * @return 358 * - ESP_OK on success (returned after wakeup) 359 * - ESP_ERR_INVALID_STATE if WiFi or BT is not stopped 360 */ 361 esp_err_t esp_light_sleep_start(void); 362 363 /** 364 * @brief Enter deep-sleep mode 365 * 366 * The device will automatically wake up after the deep-sleep time 367 * Upon waking up, the device calls deep sleep wake stub, and then proceeds 368 * to load application. 369 * 370 * Call to this function is equivalent to a call to esp_deep_sleep_enable_timer_wakeup 371 * followed by a call to esp_deep_sleep_start. 372 * 373 * esp_deep_sleep does not shut down WiFi, BT, and higher level protocol 374 * connections gracefully. 375 * Make sure relevant WiFi and BT stack functions are called to close any 376 * connections and deinitialize the peripherals. These include: 377 * - esp_bluedroid_disable 378 * - esp_bt_controller_disable 379 * - esp_wifi_stop 380 * 381 * This function does not return. 382 * 383 * @param time_in_us deep-sleep time, unit: microsecond 384 */ 385 void esp_deep_sleep(uint64_t time_in_us) __attribute__((noreturn)); 386 387 388 /** 389 * @brief Get the wakeup source which caused wakeup from sleep 390 * 391 * @return cause of wake up from last sleep (deep sleep or light sleep) 392 */ 393 esp_sleep_wakeup_cause_t esp_sleep_get_wakeup_cause(void); 394 395 396 /** 397 * @brief Default stub to run on wake from deep sleep. 398 * 399 * Allows for executing code immediately on wake from sleep, before 400 * the software bootloader or ESP-IDF app has started up. 401 * 402 * This function is weak-linked, so you can implement your own version 403 * to run code immediately when the chip wakes from 404 * sleep. 405 * 406 * See docs/deep-sleep-stub.rst for details. 407 */ 408 void esp_wake_deep_sleep(void); 409 410 /** 411 * @brief Function type for stub to run on wake from sleep. 412 * 413 */ 414 typedef void (*esp_deep_sleep_wake_stub_fn_t)(void); 415 416 /** 417 * @brief Install a new stub at runtime to run on wake from deep sleep 418 * 419 * If implementing esp_wake_deep_sleep() then it is not necessary to 420 * call this function. 421 * 422 * However, it is possible to call this function to substitute a 423 * different deep sleep stub. Any function used as a deep sleep stub 424 * must be marked RTC_IRAM_ATTR, and must obey the same rules given 425 * for esp_wake_deep_sleep(). 426 */ 427 void esp_set_deep_sleep_wake_stub(esp_deep_sleep_wake_stub_fn_t new_stub); 428 429 /** 430 * @brief Get current wake from deep sleep stub 431 * @return Return current wake from deep sleep stub, or NULL if 432 * no stub is installed. 433 */ 434 esp_deep_sleep_wake_stub_fn_t esp_get_deep_sleep_wake_stub(void); 435 436 /** 437 * @brief The default esp-idf-provided esp_wake_deep_sleep() stub. 438 * 439 * See docs/deep-sleep-stub.rst for details. 440 */ 441 void esp_default_wake_deep_sleep(void); 442 443 /** 444 * @brief Disable logging from the ROM code after deep sleep. 445 * 446 * Using LSB of RTC_STORE4. 447 */ 448 void esp_deep_sleep_disable_rom_logging(void); 449 450 #if SOC_GPIO_SUPPORT_SLP_SWITCH 451 /** 452 * @brief Configure to isolate all GPIO pins in sleep state 453 */ 454 void esp_sleep_config_gpio_isolate(void); 455 456 /** 457 * @brief Enable or disable GPIO pins status switching between slept status and waked status. 458 * @param enable decide whether to switch status or not 459 */ 460 void esp_sleep_enable_gpio_switch(bool enable); 461 #endif 462 463 #if CONFIG_MAC_BB_PD 464 /** 465 * @brief Function type for stub to run mac bb power down. 466 */ 467 typedef void (* mac_bb_power_down_cb_t)(void); 468 469 /** 470 * @brief Function type for stub to run mac bb power up. 471 */ 472 typedef void (* mac_bb_power_up_cb_t)(void); 473 474 /** 475 * @brief Registet mac bb power down callback. 476 * @param cb mac bb power down callback. 477 * @return 478 * - ESP_OK on success 479 */ 480 esp_err_t esp_register_mac_bb_pd_callback(mac_bb_power_down_cb_t cb); 481 482 /** 483 * @brief Unregistet mac bb power down callback. 484 * @param cb mac bb power down callback. 485 * @return 486 * - ESP_OK on success 487 */ 488 esp_err_t esp_unregister_mac_bb_pd_callback(mac_bb_power_down_cb_t cb); 489 490 /** 491 * @brief Registet mac bb power up callback. 492 * @param cb mac bb power up callback. 493 * @return 494 * - ESP_OK on success 495 */ 496 esp_err_t esp_register_mac_bb_pu_callback(mac_bb_power_up_cb_t cb); 497 498 /** 499 * @brief Unregistet mac bb power up callback. 500 * @param cb mac bb power up callback. 501 * @return 502 * - ESP_OK on success 503 */ 504 esp_err_t esp_unregister_mac_bb_pu_callback(mac_bb_power_up_cb_t cb); 505 #endif 506 507 #ifdef __cplusplus 508 } 509 #endif 510
