esp32: Add esp32.wake_on_gpio.

meirarmon · meirarmon · commit a12c15cc32b5 · 2025-06-20T13:56:33.000+03:00
Some boards support waking up via GPIO pins, but this is not currently
supported by MicroPython. This commit adds support for waking with GPIO
in a similar interface to waking with ext0, ext1, touch and ulp.
This commit adds documentation for this new function as well.

Signed-off-by: Meir Armon &lt;meirarmon@gmail.com&gt;
diff --git a/docs/library/esp32.rst b/docs/library/esp32.rst
@@ -43,6 +43,15 @@ Functions
 
     .. note:: This is only available for boards that have ext1 support.
 
+.. function:: wake_on_gpio(pins, level)
+
+    Configure how GPIO wakes the device from sleep.  *pins* can be ``None``
+    or a tuple/list of valid Pin objects.  *level* should be ``esp32.WAKEUP_ALL_LOW``
+    or ``esp32.WAKEUP_ANY_HIGH``.
+
+    .. note:: Some boards don't support waking on GPIO from deep sleep,
+       on those boards, the pins set here can only be used to wake from light sleep.
+
 .. function:: gpio_deep_sleep_hold(enable)
 
     Configure whether non-RTC GPIO pin configuration is retained during
diff --git a/ports/esp32/machine_rtc.c b/ports/esp32/machine_rtc.c
@@ -86,8 +86,9 @@ machine_rtc_config_t machine_rtc_config = {
     .ext1_pins = 0,
     #endif
     #if SOC_PM_SUPPORT_EXT0_WAKEUP
-    .ext0_pin = -1
+    .ext0_pin = -1,
     #endif
+    .gpio_pins = 0,
 };
 
 static mp_obj_t machine_rtc_make_new(const mp_obj_type_t *type, size_t n_args, size_t n_kw, const mp_obj_t *args) {
diff --git a/ports/esp32/machine_rtc.h b/ports/esp32/machine_rtc.h
@@ -37,6 +37,7 @@ typedef struct {
     #if SOC_PM_SUPPORT_EXT0_WAKEUP
     int8_t ext0_pin;   // just the pin#, -1 == None
     #endif
+    uint64_t gpio_pins; // set bit == pin#
     #if SOC_TOUCH_SENSOR_SUPPORTED
     bool wake_on_touch : 1;
     #endif
@@ -50,6 +51,7 @@ typedef struct {
     #if SOC_PM_SUPPORT_EXT1_WAKEUP
     bool ext1_level : 1;
     #endif
+    bool gpio_level : 1;
 } machine_rtc_config_t;
 
 extern machine_rtc_config_t machine_rtc_config;
diff --git a/ports/esp32/modesp32.c b/ports/esp32/modesp32.c
@@ -46,12 +46,13 @@
 #define MULTI_HEAP_FREERTOS
 #include "../multi_heap_platform.h"
 #include "../heap_private.h"
+#include "driver/rtc_io.h"
 
 #if SOC_TOUCH_SENSOR_SUPPORTED
 static mp_obj_t esp32_wake_on_touch(const mp_obj_t wake) {
 
     #if SOC_PM_SUPPORT_EXT0_WAKEUP
-    if (machine_rtc_config.ext0_pin != -1) {
+    if (machine_rtc_config.ext0_pin != -1 || machine_rtc_config.gpio_pins != 0) {
         mp_raise_ValueError(MP_ERROR_TEXT("no resources"));
     }
     #endif
@@ -140,7 +141,7 @@ static MP_DEFINE_CONST_FUN_OBJ_KW(esp32_wake_on_ext1_obj, 0, esp32_wake_on_ext1)
 #if SOC_ULP_SUPPORTED
 static mp_obj_t esp32_wake_on_ulp(const mp_obj_t wake) {
     #if SOC_PM_SUPPORT_EXT0_WAKEUP
-    if (machine_rtc_config.ext0_pin != -1) {
+    if (machine_rtc_config.ext0_pin != -1 || machine_rtc_config.gpio_pins != 0) {
         mp_raise_ValueError(MP_ERROR_TEXT("no resources"));
     }
     #endif
@@ -150,6 +151,51 @@ static mp_obj_t esp32_wake_on_ulp(const mp_obj_t wake) {
 static MP_DEFINE_CONST_FUN_OBJ_1(esp32_wake_on_ulp_obj, esp32_wake_on_ulp);
 #endif
 
+static mp_obj_t esp32_wake_on_gpio(size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
+    enum {ARG_pins, ARG_level};
+    const mp_arg_t allowed_args[] = {
+        { MP_QSTR_pins, MP_ARG_OBJ, {.u_obj = mp_const_none} },
+        { MP_QSTR_level, MP_ARG_BOOL, {.u_bool = machine_rtc_config.gpio_level} },
+    };
+    mp_arg_val_t args[MP_ARRAY_SIZE(allowed_args)];
+    mp_arg_parse_all(n_args, pos_args, kw_args, MP_ARRAY_SIZE(allowed_args), allowed_args, args);
+    uint64_t gpio_pins = machine_rtc_config.gpio_pins;
+
+    #if SOC_ULP_SUPPORTED
+    if (machine_rtc_config.wake_on_ulp) {
+        mp_raise_ValueError(MP_ERROR_TEXT("no resources"));
+    }
+    #endif
+
+    #if SOC_TOUCH_SENSOR_SUPPORTED
+    if (machine_rtc_config.wake_on_touch) {
+        mp_raise_ValueError(MP_ERROR_TEXT("no resources"));
+    }
+    #endif
+
+    // Check that all pins are allowed
+    if (args[ARG_pins].u_obj != mp_const_none) {
+        size_t len = 0;
+        mp_obj_t *elem;
+        mp_obj_get_array(args[ARG_pins].u_obj, &len, &elem);
+        gpio_pins = 0;
+
+        for (int i = 0; i < len; i++) {
+            // Don't validate the pins at this point, since we can be using
+            // gpio pins for deepsleep or light sleep.
+            // Validations happen in the relevant sleep functions.
+            gpio_num_t pin_id = machine_pin_get_id(elem[i]);
+            gpio_pins |= (1ll << pin_id);
+        }
+    }
+
+    machine_rtc_config.gpio_level = args[ARG_level].u_bool;
+    machine_rtc_config.gpio_pins = gpio_pins;
+
+    return mp_const_none;
+}
+static MP_DEFINE_CONST_FUN_OBJ_KW(esp32_wake_on_gpio_obj, 0, esp32_wake_on_gpio);
+
 #if !SOC_GPIO_SUPPORT_HOLD_SINGLE_IO_IN_DSLP
 static mp_obj_t esp32_gpio_deep_sleep_hold(const mp_obj_t enable) {
     if (mp_obj_is_true(enable)) {
@@ -284,6 +330,7 @@ static const mp_rom_map_elem_t esp32_module_globals_table[] = {
     #if SOC_ULP_SUPPORTED
     { MP_ROM_QSTR(MP_QSTR_wake_on_ulp), MP_ROM_PTR(&esp32_wake_on_ulp_obj) },
     #endif
+    { MP_ROM_QSTR(MP_QSTR_wake_on_gpio), MP_ROM_PTR(&esp32_wake_on_gpio_obj) },
     #if !SOC_GPIO_SUPPORT_HOLD_SINGLE_IO_IN_DSLP
     { MP_ROM_QSTR(MP_QSTR_gpio_deep_sleep_hold), MP_ROM_PTR(&esp32_gpio_deep_sleep_hold_obj) },
     #endif
diff --git a/ports/esp32/modmachine.c b/ports/esp32/modmachine.c
@@ -125,6 +125,12 @@ static void mp_machine_set_freq(size_t n_args, const mp_obj_t *args) {
 }
 
 static void machine_sleep_helper(wake_type_t wake_type, size_t n_args, const mp_obj_t *args) {
+    #if !SOC_DEEP_SLEEP_SUPPORTED
+    if (MACHINE_WAKE_DEEPSLEEP == wake_type) {
+        mp_raise_ValueError(MP_ERROR_TEXT("DEEPSLEEP not supported on this chip"));
+    }
+    #endif
+
     // First, disable any previously set wake-up source
     esp_sleep_disable_wakeup_source(ESP_SLEEP_WAKEUP_ALL);
 
@@ -164,6 +170,41 @@ static void machine_sleep_helper(wake_type_t wake_type, size_t n_args, const mp_
     }
     #endif
 
+    if (machine_rtc_config.gpio_pins != 0) {
+        #if !SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
+        if (MACHINE_WAKE_DEEPSLEEP == wake_type) {
+            mp_raise_ValueError(MP_ERROR_TEXT("DEEPSLEEP with gpio pins not supported on this chip"));
+        }
+        #endif
+
+        gpio_int_type_t intr_type = machine_rtc_config.gpio_level ? GPIO_INTR_HIGH_LEVEL : GPIO_INTR_LOW_LEVEL;
+
+        for (int i = 0; i < GPIO_NUM_MAX; ++i) {
+            gpio_num_t gpio = (gpio_num_t)i;
+            uint64_t bm = 1ULL << i;
+
+            if (machine_rtc_config.gpio_pins & bm) {
+                gpio_sleep_set_direction(gpio, GPIO_MODE_INPUT);
+
+                if (MACHINE_WAKE_SLEEP == wake_type) {
+                    gpio_wakeup_enable(gpio, intr_type);
+                }
+            }
+        }
+
+        if (MACHINE_WAKE_DEEPSLEEP == wake_type) {
+            #if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
+            if (ESP_OK != esp_deep_sleep_enable_gpio_wakeup(
+                machine_rtc_config.gpio_pins,
+                machine_rtc_config.gpio_level ? ESP_GPIO_WAKEUP_GPIO_HIGH : ESP_GPIO_WAKEUP_GPIO_LOW)) {
+                mp_raise_ValueError(MP_ERROR_TEXT("wake-up pin not supported"));
+            }
+            #endif
+        } else {
+            esp_sleep_enable_gpio_wakeup();
+        }
+    }
+
     switch (wake_type) {
         case MACHINE_WAKE_SLEEP:
             esp_light_sleep_start();
