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