docs(system): update GPIO wakeup section for clarity on EXT0 and EXT1 support

backport !47362
2026-10-01 18:50:34 +03:00 · 2026-06-03 10:57:54 +08:00
parent 33589325c7
commit 2ea0d4639d
6 changed files with 135 additions and 25 deletions
@@ -48,10 +48,14 @@ ESP-IDF 中集成的电源管理算法可以根据应用程序组件的需求，

  Light-sleep 状态下，外设设有时钟门控，不会产生来自 GPIO 和内部外设的中断。:doc:`sleep_modes` 文档中所提到的唤醒源可用于从 Light-sleep 状态触发唤醒。

-.. only:: SOC_PM_SUPPORT_EXT0_WAKEUP or SOC_PM_SUPPORT_EXT1_WAKEUP
+.. only:: SOC_PM_SUPPORT_EXT0_WAKEUP and SOC_PM_SUPPORT_EXT1_WAKEUP

  例如，EXT0 和 EXT1 唤醒源可以通过 GPIO 唤醒芯片。

+.. only:: SOC_PM_SUPPORT_EXT1_WAKEUP and not SOC_PM_SUPPORT_EXT0_WAKEUP
+
+  例如，EXT1 唤醒源可以通过 GPIO 唤醒芯片。
+

 电源管理锁
 ----------------------
@@ -4,6 +4,7 @@
 :link_to_translation:`en:[English]`

 {IDF_TARGET_SPI_POWER_DOMAIN:default="VDD_SPI", esp32="VDD_SDIO"}
+{IDF_TARGET_RTC_POWER_DOMAIN:default="VDD3P3_RTC", esp32c5="VDDPST1", esp32c6="VDDPST1", esp32c61="VDDPST1", esp32p4="VDD_LP"}

 概述
 --------
@@ -217,6 +218,8 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒

 .. only:: SOC_PM_SUPPORT_EXT1_WAKEUP

+    .. _sleep-ext1-wakeup:
+
    外部唤醒 (``ext1``)
    ^^^^^^^^^^^^^^^^^^^^^^

@@ -232,7 +235,7 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒
        - 当任意一个所选管脚为高电平时唤醒 (ESP_EXT1_WAKEUP_ANY_HIGH)
        - 当任意一个所选管脚为低电平时唤醒 (ESP_EXT1_WAKEUP_ANY_LOW)

-    此唤醒源由 RTC 控制器实现。区别于 ``ext0`` 唤醒源，在 RTC 外设断电的情况下此唤醒源同样支持唤醒。虽然睡眠期间 RTC IO 所在的 RTC 外设电源域将会断电，但是 ESP-IDF 会自动在系统进入睡眠前锁定唤醒管脚的状态并在退出睡眠时解除锁定，所以仍然可为唤醒管脚配置内部上拉或下拉电阻::
+    此唤醒源由 RTC 控制器实现。即使在 RTC 外设断电的情况下仍支持唤醒。虽然睡眠期间 RTC IO 所在的 RTC 外设电源域将会断电，但是 ESP-IDF 会自动在系统进入睡眠前锁定唤醒管脚的状态并在退出睡眠时解除锁定，所以仍然可为唤醒管脚配置内部上拉或下拉电阻::

        esp_sleep_pd_config(ESP_PD_DOMAIN_RTC_PERIPH, ESP_PD_OPTION_ON);
        gpio_pullup_dis(gpio_num);
@@ -286,10 +289,14 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒
    GPIO 唤醒（仅适用于 Light-sleep 模式）
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-    .. only:: SOC_PM_SUPPORT_EXT0_WAKEUP or SOC_PM_SUPPORT_EXT1_WAKEUP
+    .. only:: SOC_PM_SUPPORT_EXT0_WAKEUP and SOC_PM_SUPPORT_EXT1_WAKEUP

        除了上述 EXT0 和 EXT1 唤醒源之外，还有一种从外部唤醒 Light-sleep 模式的方法——使用函数 :cpp:func:`gpio_wakeup_enable`。启用该唤醒源后，可将每个管脚单独配置为在高电平或低电平时唤醒。EXT0 和 EXT1 唤醒源只能用于 RTC IO，但此唤醒源既可以用于 RTC IO，可也用于数字 IO。

+    .. only:: SOC_PM_SUPPORT_EXT1_WAKEUP and not SOC_PM_SUPPORT_EXT0_WAKEUP
+
+        除了上述 EXT1 唤醒源之外，还有一种从外部唤醒 Light-sleep 模式的方法——使用函数 :cpp:func:`gpio_wakeup_enable`。启用该唤醒源后，可将每个管脚单独配置为在高电平或低电平时唤醒。EXT1 唤醒源只能用于 RTC IO，但此唤醒源既可以用于 RTC IO，可也用于数字 IO。
+
    .. only:: not (SOC_PM_SUPPORT_EXT0_WAKEUP or SOC_PM_SUPPORT_EXT1_WAKEUP)

       此外，还有一种从外部唤醒 Light-sleep 模式的方法。启用该唤醒源后，可将每个管脚单独配置为在高电平或低电平时调用 :cpp:func:`gpio_wakeup_enable` 函数触发唤醒。此唤醒源既可以用于 RTC IO，可也用于数字 IO。
@@ -318,22 +325,64 @@ RTC 控制器中内嵌定时器，可用于在预定义的时间到达后唤醒

                在 Light-sleep 模式下，如果设置 Kconfig 选项 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，为了继续使用 :cpp:func:`gpio_wakeup_enable` 用于 GPIO 唤醒， 需要先调用 :cpp:func:`rtc_gpio_init` 和 :cpp:func:`rtc_gpio_set_direction`，用于设置 RTC IO 为输入模式。

+    .. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
+
+        .. _deep_sleep_gpio_wakeup:
+
+        Deep-sleep 模式下的 GPIO 唤醒
+        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+        除了 Light-sleep 模式下的 GPIO 唤醒之外，{IDF_TARGET_NAME} 还支持 Deep-sleep 模式下的 GPIO 唤醒。
+
+        该唤醒源由 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 函数实现，用户可以配置一个或多个 GPIO 管脚以及唤醒电平（高电平或低电平）。只有由 {IDF_TARGET_RTC_POWER_DOMAIN} 电源域供电的 GPIO 管脚才能用作 Deep-sleep GPIO 唤醒源。具体支持的管脚请参考 `datasheet <{IDF_TARGET_DATASHEET_CN_URL}>`__ > IO 管脚。
+
+        .. note::
+            该 API 同样适用于外设电源域掉电时的 Light-sleep 模式（参见 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`）。在这种情况下，应使用此 API 而不是 :cpp:func:`esp_sleep_enable_gpio_wakeup`，因为 GPIO 模块在睡眠期间会被断电。
+
+        完整示例请参考 :example:`system/deep_sleep`。
+
 .. only:: not SOC_RTCIO_WAKE_SUPPORTED and not esp32h2

    GPIO 唤醒
    ^^^^^^^^^^^

-    任何一个 IO 都可以用作外部输入管脚，将芯片从 Light-sleep 状态唤醒。调用 :cpp:func:`gpio_wakeup_enable` 函数可以将任意管脚单独配置为在高电平或低电平触发唤醒。此后，应调用 :cpp:func:`esp_sleep_enable_gpio_wakeup` 函数来启用此唤醒源。
+    .. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP

-    此外，可将由 VDD3P3_RTC 电源域供电的 IO 用于芯片的 Deep-sleep 唤醒。调用 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 函数可以配置相应的唤醒管脚和唤醒触发电平，该函数用于启用相应管脚的 Deep-sleep 唤醒功能。
+        有两种 GPIO 唤醒 API 可供使用，分别适用于不同的睡眠场景：

-    .. only:: SOC_PM_SUPPORT_TOP_PD
+    .. only:: not SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP

-        .. note::
+        在 {IDF_TARGET_NAME} 上，可使用 :cpp:func:`esp_sleep_enable_gpio_wakeup` 与 :cpp:func:`gpio_wakeup_enable` 从 Light-sleep 唤醒芯片。

-            .. only::  SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
+        .. only:: SOC_PM_SUPPORT_EXT1_WAKEUP

-                在 Light-sleep 模式下，如果设置 Kconfig 选项 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP`，可以使用直接调用 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 用于 GPIO 唤醒，因为此时 digital IO 的电源域会被断电，行为与进入 Deep-sleep 模式时相同。
+            若需使用 RTC GPIO 从 Deep-sleep 唤醒，请使用 EXT1 唤醒（:cpp:func:`esp_sleep_enable_ext1_wakeup_io`）；参见 :ref:`sleep-ext1-wakeup`。
+
+    **1. :cpp:func:`esp_sleep_enable_gpio_wakeup` - 适用于 Light-sleep（GPIO 模块保持上电）**
+
+        当 GPIO 模块在睡眠期间保持上电时，任何 IO 都可以用作外部输入管脚，将芯片从 Light-sleep 状态唤醒。调用 :cpp:func:`gpio_wakeup_enable` 函数可以将任意管脚单独配置为在高电平或低电平触发唤醒。此后，应调用 :cpp:func:`esp_sleep_enable_gpio_wakeup` 函数来启用此唤醒源。
+
+        .. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
+
+            .. note::
+                当启用 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP` 时，此 API **不可用**，因为 GPIO 模块在睡眠期间会被断电。请使用 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 替代。
+
+        .. only:: not SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
+
+            .. note::
+                当启用 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP` 时，若仍要使用 :cpp:func:`gpio_wakeup_enable`，请先调用 :cpp:func:`rtc_gpio_init` 与 :cpp:func:`rtc_gpio_set_direction`，将管脚配置为 RTC GPIO 输入。
+
+    .. only:: SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
+
+        **2. :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` - 适用于 Deep-sleep 和外设掉电的 Light-sleep**
+
+            可将由 VDD3P3_RTC 电源域供电的 IO 用于芯片的 Deep-sleep 唤醒，或在外设电源域掉电时的 Light-sleep 唤醒。调用 :cpp:func:`esp_deep_sleep_enable_gpio_wakeup` 函数可以配置相应的唤醒管脚和唤醒触发电平。此函数适用于：
+
+            - Deep-sleep 模式（始终可用）
+            - 启用 :ref:`CONFIG_PM_POWER_DOWN_PERIPHERAL_IN_LIGHT_SLEEP` 时的 Light-sleep 模式
+
+            .. note::
+                只有由 VDD3P3_RTC 电源域供电的 GPIO（RTC IO）可以与此 API 一起使用。具体支持的管脚请参考 `datasheet <{IDF_TARGET_DATASHEET_CN_URL}>`__ > IO 管脚。

 .. only:: esp32h2

@@ -483,9 +532,11 @@ UART 输出处理
    :SOC_WIFI_SUPPORTED: - :example:`wifi/power_save` 演示如何通过 Wi-Fi Modem-sleep 模式和自动 Light-sleep 模式保持 Wi-Fi 连接。
    :SOC_BT_SUPPORTED: - :example:`bluetooth/nimble/power_save` 演示如何通过 Bluetooth Modem-sleep 模式和自动 Light-sleep 模式保持 Bluetooth 连接。
    :SOC_ULP_SUPPORTED: - :example:`system/deep_sleep` 演示如何使用 Deep-sleep 唤醒触发器和 ULP 协处理器编程。
-    :not SOC_ULP_SUPPORTED and not esp32c3 and not esp32h2: - :example:`system/deep_sleep` 演示如何通过 {IDF_TARGET_NAME} 的唤醒源，如 RTC 定时器、GPIO、EXT0、EXT1 等，触发 Deep-sleep 唤醒。
+    :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` 演示如何通过 {IDF_TARGET_NAME} 的唤醒源，如 RTC 定时器、GPIO、EXT1 等，触发 Deep-sleep 唤醒。
+    :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` 演示如何通过 {IDF_TARGET_NAME} 的唤醒源，如 RTC 定时器、EXT1 等，触发 Deep-sleep 唤醒。
+    :not SOC_ULP_SUPPORTED and not esp32c3 and not esp32h2 and not SOC_PM_SUPPORT_EXT1_WAKEUP: - :example:`system/deep_sleep` 演示如何通过 {IDF_TARGET_NAME} 的唤醒源，如 RTC 定时器、GPIO 等，触发 Deep-sleep 唤醒。
    :esp32c3: - :example:`system/deep_sleep` 演示如何通过 ESP32-C3 的唤醒源，如 RTC 定时器、GPIO 等，触发 Deep-sleep 唤醒。
-    :esp32h2: - :example:`system/deep_sleep` 演示如何通过 ESP32-H2 的唤醒源，如 RTC 定时器、EXT0、EXT1 等，触发 Deep-sleep 唤醒。
+    :esp32h2: - :example:`system/deep_sleep` 演示如何通过 ESP32-H2 的唤醒源，如 RTC 定时器、EXT1 等，触发 Deep-sleep 唤醒。
    - :example:`system/light_sleep` 演示如何使用  {IDF_TARGET_NAME} 的唤醒源，如定时器，GPIO 等，触发 Light-sleep 唤醒。
    :SOC_TOUCH_SENSOR_SUPPORTED and SOC_PM_SUPPORT_TOUCH_SENSOR_WAKEUP: - :example:`peripherals/touch_sensor/touch_sens_sleep` 演示如何使用触摸传感器唤醒 Light-sleep 或 Deep-sleep。