mirror of
https://github.com/espressif/esp-idf.git
synced 2026-10-01 18:50:34 +03:00
Merge branch 'doc-fix_sleep_mode_doc_v5.2' into 'release/v5.2'
docs(system): update GPIO wakeup section for clarity on EXT0 and EXT1 support (v5.2) See merge request espressif/esp-idf!49112
This commit is contained in:
Jiang Jiang Jian
@@ -42,10 +42,14 @@ Dynamic frequency scaling (DFS) and automatic Light-sleep can be enabled in an a
|
||||
|
||||
In Light-sleep, peripherals are clock gated, and interrupts (from GPIOs and internal peripherals) will not be generated. A wakeup source described in the :doc:`sleep_modes` documentation can be used to trigger wakeup from the Light-sleep state.
|
||||
|
||||
.. only:: SOC_PM_SUPPORT_EXT0_WAKEUP or SOC_PM_SUPPORT_EXT1_WAKEUP
|
||||
.. only:: SOC_PM_SUPPORT_EXT0_WAKEUP and SOC_PM_SUPPORT_EXT1_WAKEUP
|
||||
|
||||
For example, the EXT0 and EXT1 wakeup sources can be used to wake up the chip via a GPIO.
|
||||
|
||||
.. only:: SOC_PM_SUPPORT_EXT1_WAKEUP and not SOC_PM_SUPPORT_EXT0_WAKEUP
|
||||
|
||||
For example, the EXT1 wakeup source can be used to wake up the chip via a GPIO.
|
||||
|
||||
|
||||
Power Management Locks
|
||||
----------------------
|
||||
|
||||
@@ -4,6 +4,7 @@ Sleep Modes
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
{IDF_TARGET_SPI_POWER_DOMAIN:default="VDD_SPI", esp32="VDD_SDIO"}
|
||||
{IDF_TARGET_RTC_POWER_DOMAIN:default="VDD3P3_RTC", esp32c5="VDDPST1", esp32c6="VDDPST1"}
|
||||
|
||||
Overview
|
||||
--------
|
||||
@@ -217,6 +218,8 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi
|
||||
|
||||
.. only:: SOC_PM_SUPPORT_EXT1_WAKEUP
|
||||
|
||||
.. _sleep-ext1-wakeup:
|
||||
|
||||
External Wakeup (``ext1``)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -232,7 +235,7 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi
|
||||
- wake up if any of the selected pins is high (``ESP_EXT1_WAKEUP_ANY_HIGH``)
|
||||
- wake up if any of the selected pins is low (``ESP_EXT1_WAKEUP_ANY_LOW``)
|
||||
|
||||
This wakeup source is controlled by the RTC controller. Unlike ``ext0``, this wakeup source supports wakeup even when the RTC peripheral is powered down. Although the power domain of the RTC peripheral, where RTC IOs are located, is powered down during sleep modes, ESP-IDF will automatically lock the state of the wakeup pin before the system enters sleep modes and unlock upon exiting sleep modes. Therefore, the internal pull-up or pull-down resistors can still be configured for the wakeup pin::
|
||||
This wakeup source is controlled by the RTC controller. It supports wakeup even when the RTC peripheral is powered down. Although the power domain of the RTC peripheral, where RTC IOs are located, is powered down during sleep modes, ESP-IDF will automatically lock the state of the wakeup pin before the system enters sleep modes and unlock upon exiting sleep modes. Therefore, the internal pull-up or pull-down resistors can still be configured for the wakeup pin::
|
||||
|
||||
esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON);
|
||||
rtc_gpio_pullup_dis(gpio_num);
|
||||
@@ -286,10 +289,14 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi
|
||||
GPIO Wakeup (Light-sleep Only)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. only:: (SOC_PM_SUPPORT_EXT0_WAKEUP or SOC_PM_SUPPORT_EXT1_WAKEUP)
|
||||
.. only:: SOC_PM_SUPPORT_EXT0_WAKEUP and SOC_PM_SUPPORT_EXT1_WAKEUP
|
||||
|
||||
In addition to EXT0 and EXT1 wakeup sources described above, one more method of wakeup from external inputs is available in Light-sleep mode. With this wakeup source, each pin can be individually configured to trigger wakeup on high or low level using :cpp:func:`gpio_wakeup_enable` function. Unlike EXT0 and EXT1 wakeup sources, which can only be used with RTC IOs, this wakeup source can be used with any IO (RTC or digital).
|
||||
|
||||
.. only:: SOC_PM_SUPPORT_EXT1_WAKEUP and not SOC_PM_SUPPORT_EXT0_WAKEUP
|
||||
|
||||
In addition to the EXT1 wakeup source described above, one more method of wakeup from external inputs is available in Light-sleep mode. With this wakeup source, each pin can be individually configured to trigger wakeup on high or low level using :cpp:func:`gpio_wakeup_enable` function. Unlike the EXT1 wakeup source, which can only be used with RTC IOs, this wakeup source can be used with any IO (RTC or digital).
|
||||
|
||||
.. only:: not (SOC_PM_SUPPORT_EXT0_WAKEUP or SOC_PM_SUPPORT_EXT1_WAKEUP)
|
||||
|
||||
One more method of wakeup from external inputs is available in Light-sleep mode. With this wakeup source, each pin can be individually configured to trigger wakeup on high or low level using :cpp:func:`gpio_wakeup_enable` function. This wakeup source can be used with any IO (RTC or digital).
|
||||
@@ -318,22 +325,72 @@ RTC peripherals or RTC memories do not need to be powered on during sleep in thi
|
||||
|
||||
In Light-sleep mode, if you set Kconfig option :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`， to continue using :cpp:func:`gpio_wakeup_enable` for GPIO wakeup, you need to first call :cpp:func:`rtc_gpio_init` and :cpp:func:`rtc_gpio_set_direction`, setting the RTCIO to input mode.
|
||||
|
||||
.. only:: not SOC_RTCIO_WAKE_SUPPORTED
|
||||
.. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
|
||||
|
||||
.. _deep_sleep_gpio_wakeup:
|
||||
|
||||
GPIO Wakeup from Deep-sleep
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
In addition to the GPIO wakeup mechanism available in Light-sleep mode, {IDF_TARGET_NAME} also supports waking up from Deep-sleep using GPIOs.
|
||||
|
||||
This wakeup source is implemented by :cpp:func:`esp_deep_sleep_enable_gpio_wakeup`, which allows selecting one or more GPIOs and the wakeup level (high or low). Only GPIOs powered by the {IDF_TARGET_RTC_POWER_DOMAIN} power domain can be used as Deep-sleep GPIO wakeup sources. The exact set of supported pins can be checked in the `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__ > Section IO Pins.
|
||||
|
||||
.. note::
|
||||
This API also works for Light-sleep mode when the peripheral power domain is powered down (see :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`). In this case, it should be used instead of :cpp:func:`esp_sleep_enable_gpio_wakeup` because the GPIO module is powered down during sleep.
|
||||
|
||||
For a complete example of using GPIO to wake up from Deep-sleep, see :example:`system/deep_sleep`.
|
||||
|
||||
.. only:: not SOC_RTCIO_WAKE_SUPPORTED and not esp32h2
|
||||
|
||||
GPIO Wakeup
|
||||
^^^^^^^^^^^
|
||||
|
||||
.. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
|
||||
|
||||
There are two GPIO wakeup APIs available, each designed for different sleep scenarios:
|
||||
|
||||
.. only:: not SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
|
||||
|
||||
On {IDF_TARGET_NAME}, :cpp:func:`esp_sleep_enable_gpio_wakeup` together with :cpp:func:`gpio_wakeup_enable` can wake the chip from Light-sleep.
|
||||
|
||||
.. only:: SOC_PM_SUPPORT_EXT1_WAKEUP
|
||||
|
||||
To wake from Deep-sleep using RTC GPIOs, use EXT1 wakeup (:cpp:func:`esp_sleep_enable_ext1_wakeup_io`); see :ref:`sleep-ext1-wakeup`.
|
||||
|
||||
**1. :cpp:func:`esp_sleep_enable_gpio_wakeup` - For Light-sleep (GPIO module powered on)**
|
||||
|
||||
Any IO can be used as the external input to wake up the chip from Light-sleep when the GPIO module remains powered on. Each pin can be individually configured to trigger wakeup on high or low level using the :cpp:func:`gpio_wakeup_enable` function. Then the :cpp:func:`esp_sleep_enable_gpio_wakeup` function should be called to enable this wakeup source.
|
||||
|
||||
.. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
|
||||
|
||||
.. note::
|
||||
This API is **not available** when :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP` is enabled, because the GPIO module is powered down during sleep in this case. Use :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` instead.
|
||||
|
||||
.. only:: not SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
|
||||
|
||||
.. note::
|
||||
When :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP` is enabled, to keep using :cpp:func:`gpio_wakeup_enable`, call :cpp:func:`rtc_gpio_init` and :cpp:func:`rtc_gpio_set_direction` so the pin is used as an RTC GPIO input.
|
||||
|
||||
.. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
|
||||
|
||||
**2. :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` - For Deep-sleep and Light-sleep (peripheral powerdown)**
|
||||
|
||||
IOs that are powered by the VDD3P3_RTC power domain can be used to wake up the chip from Deep-sleep or Light-sleep when the peripheral power domain is powered down. The wakeup pin and wakeup trigger level can be configured by calling :cpp:func:`esp_deep_sleep_enable_gpio_wakeup`. This function works for:
|
||||
|
||||
- Deep-sleep mode (always)
|
||||
- Light-sleep mode when :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP` is enabled
|
||||
|
||||
.. note::
|
||||
Only GPIOs powered by the VDD3P3_RTC power domain (RTC IOs) can be used with this API. The exact set of supported pins can be checked in the `datasheet <{IDF_TARGET_DATASHEET_EN_URL}>`__ > Section IO Pins.
|
||||
|
||||
.. only:: esp32h2
|
||||
|
||||
GPIO Wakeup
|
||||
^^^^^^^^^^^
|
||||
|
||||
Any IO can be used as the external input to wake up the chip from Light-sleep. Each pin can be individually configured to trigger wakeup on high or low level using the :cpp:func:`gpio_wakeup_enable` function. Then the :cpp:func:`esp_sleep_enable_gpio_wakeup` function should be called to enable this wakeup source.
|
||||
|
||||
Additionally, IOs that are powered by the VDD3P3_RTC power domain can be used to wake up the chip from Deep-sleep. The wakeup pin and wakeup trigger level can be configured by calling :cpp:func:`esp_deep_sleep_enable_gpio_wakeup`. The function will enable the Deep-sleep wakeup for the selected pin.
|
||||
|
||||
.. only:: SOC_PM_SUPPORT_TOP_PD
|
||||
|
||||
.. note::
|
||||
|
||||
.. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
|
||||
|
||||
In Light-sleep mode, if you set Kconfig option :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`， you can use :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` directly for GPIO wakeup, because the digital IO power domain is being powered off, where the situation is the same as entering Deep-sleep.
|
||||
|
||||
UART Wakeup (Light-sleep Only)
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -471,12 +528,17 @@ Application Example
|
||||
|
||||
.. list::
|
||||
|
||||
- :example:`protocols/sntp`: the implementation of basic functionality of Deep-sleep, where ESP module is periodically waken up to retrieve time from NTP server.
|
||||
- :example:`wifi/power_save`: the usage of Wi-Fi Modem-sleep mode and automatic Light-sleep feature to maintain Wi-Fi connections.
|
||||
:SOC_BT_SUPPORTED: - :example:`bluetooth/nimble/power_save`: the usage of Bluetooth Modem-sleep mode and automatic Light-sleep feature to maintain Bluetooth connections.
|
||||
:SOC_ULP_SUPPORTED: - :example:`system/deep_sleep`: the usage of various Deep-sleep wakeup triggers and ULP coprocessor programming.
|
||||
:not SOC_ULP_SUPPORTED: - :example:`system/deep_sleep`: the usage of Deep-sleep wakeup triggered by timer.
|
||||
|
||||
- :example:`protocols/sntp` demonstrates the implementation of basic functionality of Deep-sleep, where ESP module is periodically waken up to retrieve time from NTP server.
|
||||
:SOC_WIFI_SUPPORTED: - :example:`wifi/power_save` demonstrates the usage of Wi-Fi Modem-sleep mode and automatic Light-sleep feature to maintain Wi-Fi connections.
|
||||
:SOC_BT_SUPPORTED: - :example:`bluetooth/nimble/power_save` demonstrates the usage of Bluetooth Modem-sleep mode and automatic Light-sleep feature to maintain Bluetooth connections.
|
||||
:SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` demonstrates the usage of various Deep-sleep wakeup triggers and ULP coprocessor programming.
|
||||
:not SOC_ULP_SUPPORTED and not esp32c3 and not esp32h2 and SOC_PM_SUPPORT_EXT1_WAKEUP and SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer, GPIOs, EXT1, supported by {IDF_TARGET_NAME}.
|
||||
:not SOC_ULP_SUPPORTED and not esp32c3 and not esp32h2 and SOC_PM_SUPPORT_EXT1_WAKEUP and not SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer and EXT1, supported by {IDF_TARGET_NAME}.
|
||||
:not SOC_ULP_SUPPORTED and not esp32c3 and not esp32h2 and not SOC_PM_SUPPORT_EXT1_WAKEUP: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer, GPIOs, supported by {IDF_TARGET_NAME}.
|
||||
:esp32c3: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer, GPIOs, supported by ESP32-C3.
|
||||
:esp32h2: - :example:`system/deep_sleep` demonstrates the usage of Deep-sleep wakeup triggered by various sources, such as the RTC timer and EXT1, supported by ESP32-H2.
|
||||
- :example:`system/light_sleep` demonstrates the usage of Light-sleep wakeup triggered by various sources, such as the timer, GPIOs, supported by {IDF_TARGET_NAME}.
|
||||
:SOC_TOUCH_SENSOR_SUPPORTED and SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP: - :example:`system/deep_sleep` demonstrates the usage of Light-sleep and Deep-sleep wakeup triggered by the touch sensor.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
Reference in New Issue
Block a user