Sleep modes¶

API Reference¶

Header File¶

esp8266/include/esp_sleep.h

Functions¶

void esp_deep_sleep(uint64_t time_in_us)¶

Enter deep-sleep mode.

       The device will automatically wake up after the deep-sleep time set
       by the users. Upon waking up, the device boots up from user_init.

Attention

1. XPD_DCDC should be connected to EXT_RSTB through 0 ohm resistor in order to support deep-sleep wakeup.

Attention

2. system_deep_sleep(0): there is no wake up timer; in order to wake up, connect a GPIO to pin RST, the chip will wake up by a falling-edge on pin RST

Attention

3. esp_deep_sleep does not shut down WiFi and higher level protocol connections gracefully. Make sure esp_wifi_stop are called to close any connections and deinitialize the peripherals.

Return

null

Parameters

time_in_us: deep-sleep time, unit: microsecond

esp_err_t esp_pm_configure(const void *config)¶

Set implementation-specific power management configuration.

Return

ESP_OK on success
ESP_ERR_INVALID_ARG if the configuration values are not correct
ESP_ERR_NOT_SUPPORTED if certain combination of values is not supported.

Parameters

config: pointer to implementation-specific configuration structure (e.g. esp_pm_config_esp32)

void esp_deep_sleep_set_rf_option(uint8_t option)¶

Call this API before esp_deep_sleep and esp_wifi_init to set the activity after the next deep-sleep wakeup.

If this API is not called, default to be esp_deep_sleep_set_rf_option(1).

Return

null

Parameters

option: radio option 0 : Radio calibration after the deep-sleep wakeup is decided by byte 108 of esp_init_data_default.bin (0~127byte). 1 : Radio calibration will be done after the deep-sleep wakeup. This will lead to stronger current. 2 : Radio calibration will not be done after the deep-sleep wakeup. This will lead to weaker current. 4 : Disable radio calibration after the deep-sleep wakeup (the same as modem-sleep). This will lead to the weakest current, but the device can’t receive or transmit data after waking up.

void esp_wifi_fpm_open(void)¶

Enable force sleep function.

Attention: Force sleep function is disabled by default.
Return: null

void esp_wifi_fpm_close(void)¶

Disable force sleep function.

Return: null

void esp_wifi_fpm_do_wakeup(void)¶

Wake ESP8266 up from MODEM_SLEEP_T force sleep.

Attention: This API can only be called when MODEM_SLEEP_T force sleep function is enabled, after calling wifi_fpm_open. This API can not be called after calling wifi_fpm_close.
Return: null

void esp_wifi_fpm_set_wakeup_cb(fpm_wakeup_cb cb)¶

Set a callback of waken up from force sleep because of time out.

Attention

1. This API can only be called when force sleep function is enabled, after calling wifi_fpm_open. This API can not be called after calling wifi_fpm_close.

Attention

2. fpm_wakeup_cb_func will be called after system woke up only if the force sleep time out (wifi_fpm_do_sleep and the parameter is not 0xFFFFFFF).

Attention

3. fpm_wakeup_cb_func will not be called if woke up by wifi_fpm_do_wakeup from MODEM_SLEEP_T type force sleep.

Return

null

Parameters

cb: callback of waken up

esp_err_t esp_wifi_fpm_do_sleep(uint32_t sleep_time_in_us)¶

Force ESP8266 enter sleep mode, and it will wake up automatically when time out.

Attention

1. This API can only be called when force sleep function is enabled, after calling wifi_fpm_open. This API can not be called after calling wifi_fpm_close.

Attention

2. If this API returned 0 means that the configuration is set successfully, but the ESP8266 will not enter sleep mode immediately, it is going to sleep in the system idle task. Please do not call other WiFi related function right after calling this API.

Return

ESP_OK, setting succeed;

Return

ESP_ERR_WIFI_FPM_MODE, fail to sleep, force sleep function is not enabled.

Return

ESP_ERR_WIFI_PM_MODE_OPEN, fail to sleep, Please call esp_wifi_set_ps(WIFI_PS_NONE) first.

Return

ESP_ERR_WIFI_MODE, fail to sleep, Please call esp_wifi_set_mode(WIFI_MODE_NULL) first.

Parameters

sleep_time_in_us: sleep time, ESP8266 will wake up automatically when time out. Unit: us. Range: 10000 ~ 268435455(0xFFFFFFF).
- If sleep_time_in_us is 0xFFFFFFF, the ESP8266 will sleep till
- if wifi_fpm_set_sleep_type is set to be LIGHT_SLEEP_T, ESP8266 can wake up by GPIO.
- if wifi_fpm_set_sleep_type is set to be MODEM_SLEEP_T, ESP8266 can wake up by wifi_fpm_do_wakeup.

void esp_wifi_fpm_set_sleep_type(wifi_sleep_type_t type)¶

Set sleep type for force sleep function.

Attention

This API can only be called before wifi_fpm_open.

Return

null

Parameters

type: sleep type

wifi_sleep_type_t esp_wifi_fpm_get_sleep_type(void)¶

Get sleep type of force sleep function.

Return: sleep type

void esp_wifi_enable_gpio_wakeup(uint32_t gpio_num, gpio_int_type_t intr_status)¶

Set a GPIO to wake the ESP8266 up from light-sleep mode ESP8266 will be wakened from Light-sleep, when the GPIO is in low-level.

If the ESP8266 enters light-sleep automatically(esp_wifi_set_sleep_type(LIGHT_SLEEP_T);), after being waken up by GPIO, when the chip attempts to sleep again, it will check the status of the GPIO: Note: • If the GPIO is still in the wakeup status, the EP8266 will enter modem-sleep mode instead; • If the GPIO is NOT in the wakeup status, the ESP8266 will enter light-sleep mode

Return

null

Parameters

gpio_num: GPIO number, range: [0, 15]. gpio_int_type_t intr_status: status of GPIO interrupt to trigger the wakeup process.
- if esp_wifi_fpm_set_sleep_type is set to be LIGHT_SLEEP_T, ESP8266 can wake up by GPIO.
- if esp_wifi_fpm_set_sleep_type is set to be MODEM_SLEEP_T, ESP8266 can wake up by esp_wifi_fpm_do_wakeup.
intr_status: GPIO interrupt type

void esp_wifi_disable_gpio_wakeup(void)¶: Disable the function that the GPIO can wake the ESP8266 up from light-sleep mode.

esp_err_t esp_sleep_enable_timer_wakeup(uint32_t time_in_us)¶

Enable wakeup by timer.

Return

ESP_OK on success
ESP_ERR_INVALID_ARG if value is out of range (TBD)

Parameters

time_in_us: time before wakeup, in microseconds

esp_err_t esp_light_sleep_start(void)¶

Enter light sleep with the configured wakeup options.

Attention

esp_deep_sleep does not shut down WiFi and higher level protocol connections gracefully. Make sure esp_wifi_stop are called to close any connections and deinitialize the peripherals.

Return

ESP_OK on success (returned after wakeup)
ESP_ERR_INVALID_STATE if WiFi is not stopped

void esp_sleep_start(void)¶

Operation system start check time and enter sleep.

Note: This function is called by system, user should not call this

esp_err_t esp_sleep_enable_gpio_wakeup(void)¶

Enable wakeup from light sleep using GPIOs.

Return

ESP_OK on success
ESP_ERR_INVALID_STATE if wakeup triggers conflict

esp_err_t esp_sleep_disable_wakeup_source(esp_sleep_source_t source)¶

Disable wakeup source.

This function is used to deactivate wake up trigger for source defined as parameter of the function.

Note

This function does not modify wake up configuration in RTC. It will be performed in esp_sleep_start function.

Return

ESP_OK on success
ESP_ERR_INVALID_STATE if trigger was not active

Parameters

source: - number of source to disable of type esp_sleep_source_t

void esp_power_consumption_info(bool clear_old_data)¶

Print power consumption information.

Note

This function is used to print power consumption data. The current when the RF and CPU are both turned on is 70 mA. The current when only the CPU is turned on is 18 mA. 900uA when both CPU and RF are off. There may be some errors compared to the actual power consumption. The power consumption is based on the actual measurement, and the printing in the function is for reference only.

Return

null

Parameters

clear_old_data: - Recalculate power consumption info or not.

Type Definitions¶

typedef enum esp_sleep_mode esp_sleep_mode_t¶

typedef void (*fpm_wakeup_cb)(void)¶

Enumerations¶

enum wifi_sleep_type_t¶

Values:

WIFI_NONE_SLEEP_T = 0¶

WIFI_LIGHT_SLEEP_T¶

WIFI_MODEM_SLEEP_T¶

enum esp_sleep_mode¶

Values:

ESP_CPU_WAIT = 0¶

ESP_CPU_LIGHTSLEEP¶

enum esp_sleep_source_t¶

Sleep wakeup cause.

Values:

ESP_SLEEP_WAKEUP_UNDEFINED¶: In case of deep sleep, reset was not caused by exit from deep sleep.

ESP_SLEEP_WAKEUP_ALL¶: Not a wakeup cause, used to disable all wakeup sources with esp_sleep_disable_wakeup_source.

ESP_SLEEP_WAKEUP_TIMER¶: Wakeup caused by timer.

ESP_SLEEP_WAKEUP_GPIO¶: Wakeup caused by GPIO (light sleep only)