Merge branch 'feature/deactivate_wakeup_trigger' into 'master'

esp32: Add deactivation of wake up trigger for different sources

See merge request idf/esp-idf!2079

Author: igrr

components/esp32/include/esp_sleep.h

@@ -60,8 +60,28 @@ typedef enum {
     ESP_SLEEP_WAKEUP_TIMER,        //!< Wakeup caused by timer
     ESP_SLEEP_WAKEUP_TOUCHPAD,     //!< Wakeup caused by touchpad
     ESP_SLEEP_WAKEUP_ULP,          //!< Wakeup caused by ULP program
-} esp_sleep_wakeup_cause_t;
+} esp_sleep_source_t;
 
+/* Leave this type define for compatibility */
+typedef esp_sleep_source_t esp_sleep_wakeup_cause_t;
+
+/**
+ * @brief 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.
+ *
+ * See docs/sleep-modes.rst for details.
+ *
+ * @param source - number of source to disable of type esp_sleep_source_t
+ * @return
+ *      - ESP_OK on success
+ *      - ESP_ERR_INVALID_STATE if trigger was not active
+ */
+esp_err_t esp_sleep_disable_wakeup_source(esp_sleep_source_t source);
 
 /**
  * @brief Enable wakeup by ULP coprocessor

components/esp32/sleep_modes.c

@@ -42,6 +42,9 @@
 // Time from VDD_SDIO power up to first flash read in ROM code
 #define VDD_SDIO_POWERUP_TO_FLASH_READ_US 700
 
+#define CHECK_SOURCE(source, value, mask) ((s_config.wakeup_triggers & mask) && \
+                                            (source == value))
+
 /**
  * Internal structure which holds all requested deep sleep parameters
  */
@@ -282,6 +285,40 @@ esp_err_t esp_light_sleep_start()
 
 void system_deep_sleep(uint64_t) __attribute__((alias("esp_deep_sleep")));
 
+esp_err_t esp_sleep_disable_wakeup_source(esp_sleep_source_t source)
+{
+    // For most of sources it is enough to set trigger mask in local
+    // configuration structure. The actual RTC wake up options
+    // will be updated by esp_sleep_start().
+    if (CHECK_SOURCE(source, ESP_SLEEP_WAKEUP_TIMER, RTC_TIMER_TRIG_EN)) {
+        s_config.wakeup_triggers &= ~RTC_TIMER_TRIG_EN;
+        s_config.sleep_duration = 0;
+    }
+    else if (CHECK_SOURCE(source, ESP_SLEEP_WAKEUP_EXT0, RTC_EXT0_TRIG_EN)) {
+        s_config.ext0_rtc_gpio_num = 0;
+        s_config.ext0_trigger_level = 0;
+        s_config.wakeup_triggers &= ~RTC_EXT0_TRIG_EN;
+    }
+    else if (CHECK_SOURCE(source, ESP_SLEEP_WAKEUP_EXT1, RTC_EXT1_TRIG_EN)) {
+        s_config.ext1_rtc_gpio_mask = 0;
+        s_config.ext1_trigger_mode = 0;
+        s_config.wakeup_triggers &= ~RTC_EXT1_TRIG_EN;
+    }
+    else if (CHECK_SOURCE(source, ESP_SLEEP_WAKEUP_TOUCHPAD, RTC_TOUCH_TRIG_EN)) {
+        s_config.wakeup_triggers &= ~RTC_TOUCH_TRIG_EN;
+    }
+#ifdef CONFIG_ULP_COPROC_ENABLED
+    else if (CHECK_SOURCE(source, ESP_SLEEP_WAKEUP_ULP, RTC_ULP_TRIG_EN)) {
+        s_config.wakeup_triggers &= ~RTC_ULP_TRIG_EN;
+    }
+#endif
+    else {
+        ESP_LOGE(TAG, "Incorrect wakeup source (%d) to disable.", (int) source);
+        return ESP_ERR_INVALID_STATE;
+    }
+    return ESP_OK;
+}
+
 esp_err_t esp_sleep_enable_ulp_wakeup()
 {
 #ifdef CONFIG_ULP_COPROC_ENABLED

components/esp32/test/test_sleep.c

@@ -5,6 +5,15 @@
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 
+#include "soc/rtc.h"            // for wakeup trigger defines
+#include "soc/rtc_cntl_reg.h"   // for read rtc registers directly (cause)
+#include "soc/soc.h"            // for direct register read macros
+
+#define ESP_EXT0_WAKEUP_LEVEL_LOW 0
+#define ESP_EXT0_WAKEUP_LEVEL_HIGH 1
+
+static struct timeval tv_start, tv_stop;
+
 TEST_CASE("esp_deepsleep works", "[deepsleep][reset=DEEPSLEEP_RESET]")
 {
     esp_deep_sleep(2000000);
@@ -33,7 +42,6 @@ TEST_CASE("wake up using timer", "[deepsleep][reset=DEEPSLEEP_RESET]")
     esp_deep_sleep_start();
 }
 
-
 TEST_CASE("wake up from light sleep using timer", "[deepsleep]")
 {
     esp_sleep_enable_timer_wakeup(2000000);
@@ -60,7 +68,7 @@ TEST_CASE("wake up using ext0 (13 high)", "[deepsleep][ignore]")
     ESP_ERROR_CHECK(rtc_gpio_init(GPIO_NUM_13));
     ESP_ERROR_CHECK(gpio_pullup_dis(GPIO_NUM_13));
     ESP_ERROR_CHECK(gpio_pulldown_en(GPIO_NUM_13));
-    ESP_ERROR_CHECK(esp_sleep_enable_ext0_wakeup(GPIO_NUM_13, 1));
+    ESP_ERROR_CHECK(esp_sleep_enable_ext0_wakeup(GPIO_NUM_13, ESP_EXT0_WAKEUP_LEVEL_HIGH));
     esp_deep_sleep_start();
 }
 
@@ -69,7 +77,7 @@ TEST_CASE("wake up using ext0 (13 low)", "[deepsleep][ignore]")
     ESP_ERROR_CHECK(rtc_gpio_init(GPIO_NUM_13));
     ESP_ERROR_CHECK(gpio_pullup_en(GPIO_NUM_13));
     ESP_ERROR_CHECK(gpio_pulldown_dis(GPIO_NUM_13));
-    ESP_ERROR_CHECK(esp_sleep_enable_ext0_wakeup(GPIO_NUM_13, 0));
+    ESP_ERROR_CHECK(esp_sleep_enable_ext0_wakeup(GPIO_NUM_13, ESP_EXT0_WAKEUP_LEVEL_LOW));
     esp_deep_sleep_start();
 }
 
@@ -108,3 +116,91 @@ TEST_CASE("wake up using ext1 when RTC_PERIPH is on (13 low)", "[deepsleep][igno
     ESP_ERROR_CHECK(esp_sleep_enable_ext1_wakeup(BIT(GPIO_NUM_13), ESP_EXT1_WAKEUP_ALL_LOW));
     esp_deep_sleep_start();
 }
+
+static float get_time_ms(void)
+{
+    gettimeofday(&tv_stop, NULL);
+    
+    float dt = (tv_stop.tv_sec - tv_start.tv_sec) * 1e3f +
+                (tv_stop.tv_usec - tv_start.tv_usec) * 1e-3f;
+    return fabs(dt);
+}
+
+static uint32_t get_cause()
+{
+    uint32_t wakeup_cause = REG_GET_FIELD(RTC_CNTL_WAKEUP_STATE_REG, \
+                                            RTC_CNTL_WAKEUP_CAUSE);
+    return wakeup_cause;
+}
+
+// This test case verifies deactivation of trigger for wake up sources 
+TEST_CASE("disable source trigger behavior", "[deepsleep]")
+{
+    float dt = 0;
+
+    printf("Setup timer and ext0 to wakeup imediately from GPIO_13 \n");
+    
+    // Setup ext0 configuration to wake up almost immediately
+    // The wakeup time is proportional to input capacitance * pullup resistance
+    ESP_ERROR_CHECK(rtc_gpio_init(GPIO_NUM_13));
+    ESP_ERROR_CHECK(gpio_pullup_en(GPIO_NUM_13));
+    ESP_ERROR_CHECK(gpio_pulldown_dis(GPIO_NUM_13));
+    ESP_ERROR_CHECK(esp_sleep_enable_ext0_wakeup(GPIO_NUM_13, ESP_EXT0_WAKEUP_LEVEL_HIGH));
+            
+    // Setup timer to wakeup with timeout
+     esp_sleep_enable_timer_wakeup(2000000);
+
+    // Save start time
+    gettimeofday(&tv_start, NULL);
+    esp_light_sleep_start();
+
+    dt = get_time_ms();
+    printf("Ext0 sleep time = %d \n", (int) dt);
+
+    // Check wakeup from Ext0 using time measurement because wakeup cause is 
+    // not available in light sleep mode
+    TEST_ASSERT_INT32_WITHIN(299, 300, (int) dt);
+    
+    TEST_ASSERT((get_cause() & RTC_EXT0_TRIG_EN) != 0);
+    
+    // Disable Ext0 source. Timer source should be triggered
+    ESP_ERROR_CHECK(esp_sleep_disable_wakeup_source(ESP_SLEEP_WAKEUP_EXT0));
+    printf("Disable ext0 trigger and leave timer active.\n");
+            
+    gettimeofday(&tv_start, NULL);
+    esp_light_sleep_start();
+
+    dt = get_time_ms();
+    printf("Timer sleep time = %d \n", (int) dt);
+    
+    TEST_ASSERT_INT32_WITHIN(500, 2000, (int) dt);
+
+    // Additionaly check wakeup cause
+    TEST_ASSERT((get_cause() & RTC_TIMER_TRIG_EN) != 0);
+
+    // Disable timer source.
+    ESP_ERROR_CHECK(esp_sleep_disable_wakeup_source(ESP_SLEEP_WAKEUP_TIMER));
+
+    // Setup ext0 configuration to wake up immediately
+    ESP_ERROR_CHECK(rtc_gpio_init(GPIO_NUM_13));
+    ESP_ERROR_CHECK(gpio_pullup_en(GPIO_NUM_13));
+    ESP_ERROR_CHECK(gpio_pulldown_dis(GPIO_NUM_13));
+    ESP_ERROR_CHECK(esp_sleep_enable_ext0_wakeup(GPIO_NUM_13, ESP_EXT0_WAKEUP_LEVEL_HIGH));
+
+    printf("Disable timer trigger to wake up from ext0 source.\n");
+
+    gettimeofday(&tv_start, NULL);
+    esp_light_sleep_start();
+
+    dt = get_time_ms();
+    printf("Ext0 sleep time = %d \n", (int) dt);
+
+    TEST_ASSERT_INT32_WITHIN(199, 200, (int) dt);
+    TEST_ASSERT((get_cause() & RTC_EXT0_TRIG_EN) != 0);
+    
+    // Check error message when source is already disabled 
+    esp_err_t err_code = esp_sleep_disable_wakeup_source(ESP_SLEEP_WAKEUP_TIMER);
+    TEST_ASSERT(err_code == ESP_ERR_INVALID_STATE);
+    printf("Test case completed successfully.");
+}
+

docs/en/api-reference/system/sleep_modes.rst

@@ -10,18 +10,18 @@ In light sleep mode, digital peripherals, most of the RAM, and CPUs are clock-ga
 
 In deep sleep mode, CPUs, most of the RAM, and all the digital peripherals which are clocked from APB_CLK are powered off. The only parts of the chip which can still be powered on are: RTC controller, RTC peripherals (including ULP coprocessor), and RTC memories (slow and fast).
 
-Wakeup from deep and light sleep modes can be done using several sources. These sources can be combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup sources can be enabled using ``esp_sleep_enable_X_wakeup`` APIs. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering light or deep sleep mode. 
+Wakeup from deep and light sleep modes can be done using several sources. These sources can be combined, in this case the chip will wake up when any one of the sources is triggered. Wakeup sources can be enabled using ``esp_sleep_enable_X_wakeup`` APIs and can be disabled using :cpp:func:`esp_sleep_disable_wakeup_source` API. Next section describes these APIs in detail. Wakeup sources can be configured at any moment before entering light or deep sleep mode. 
 
-Additionally, the application can force specific powerdown modes for the RTC peripherals and RTC memories using ``esp_sleep_pd_config`` API.
+Additionally, the application can force specific powerdown modes for the RTC peripherals and RTC memories using :cpp:func:`esp_sleep_pd_config` API.
 
-Once wakeup sources are configured, application can enter sleep mode using ``esp_light_sleep_start`` or ``esp_deep_sleep_start`` APIs. At this point the hardware will be configured according to the requested wakeup sources, and RTC controller will either power down or power off the CPUs and digital peripherals.
+Once wakeup sources are configured, application can enter sleep mode using :cpp:func:`esp_light_sleep_start` or :cpp:func:`esp_deep_sleep_start` APIs. At this point the hardware will be configured according to the requested wakeup sources, and RTC controller will either power down or power off the CPUs and digital peripherals.
 
 WiFi/BT and sleep modes
 -----------------------
 
-In deep sleep mode, wireless peripherals are powered down. Before entering sleep mode, applications must disable WiFi and BT using appropriate calls ( ``esp_bluedroid_disable``, ``esp_bt_controller_disable``, ``esp_wifi_stop``). 
+In deep sleep mode, wireless peripherals are powered down. Before entering sleep mode, applications must disable WiFi and BT using appropriate calls ( :cpp:func:`esp_bluedroid_disable`, :cpp:func:`esp_bt_controller_disable`, :cpp:func:`esp_wifi_stop`). 
 
-WiFi can coexist with light sleep mode, allowing the chip to go into light sleep mode when there is no network activity, and waking up the chip from light sleep mode when required. However **APIs described in this section can not be used for that purpose**. ``esp_light_sleep_start`` forces the chip to enter light sleep mode, regardless of whether WiFi is active or not. Automatic entry into light sleep mode, coordinated with WiFi driver, will be supported using a separate set of APIs.
+WiFi can coexist with light sleep mode, allowing the chip to go into light sleep mode when there is no network activity, and waking up the chip from light sleep mode when required. However **APIs described in this section can not be used for that purpose**. :cpp:func:`esp_light_sleep_start` forces the chip to enter light sleep mode, regardless of whether WiFi is active or not. Automatic entry into light sleep mode, coordinated with WiFi driver, will be supported using a separate set of APIs.
 
 Wakeup sources
 --------------
@@ -52,7 +52,7 @@ External wakeup (ext0)
 
 RTC IO module contains logic to trigger wakeup when one of RTC GPIOs is set to a predefined logic level. RTC IO is part of RTC peripherals power domain, so RTC peripherals will be kept powered on during deep sleep if this wakeup source is requested. 
 
-Because RTC IO module is enabled in this mode, internal pullup or pulldown resistors can also be used. They need to be configured by the application using ``rtc_gpio_pullup_en`` and ``rtc_gpio_pulldown_en`` functions, before calling ``esp_sleep_start``.
+Because RTC IO module is enabled in this mode, internal pullup or pulldown resistors can also be used. They need to be configured by the application using :cpp:func:`rtc_gpio_pullup_en` and :cpp:func:`rtc_gpio_pulldown_en` functions, before calling :cpp:func:`esp_sleep_start`.
 
 In revisions 0 and 1 of the ESP32, this wakeup source is incompatible with ULP and touch wakeup sources.
 
@@ -97,11 +97,11 @@ The following function can be used to enable this wakeup mode:
 Power-down of RTC peripherals and memories
 ------------------------------------------
 
-By default, ``esp_deep_sleep_start`` and ``esp_light_sleep_start`` functions will power down all RTC power domains which are not needed by the enabled wakeup sources. To override this behaviour, ``esp_sleep_pd_config`` function is provided.
+By default, :cpp:func:`esp_deep_sleep_start` and :cpp:func:`esp_light_sleep_start` functions will power down all RTC power domains which are not needed by the enabled wakeup sources. To override this behaviour, :cpp:func:`esp_sleep_pd_config` function is provided.
 
 Note: in revision 0 of the ESP32, RTC fast memory will always be kept enabled in deep sleep, so that the deep sleep stub can run after reset. This can be overriden, if the application doesn't need clean reset behaviour after deep sleep.
 
-If some variables in the program are placed into RTC slow memory (for example, using ``RTC_DATA_ATTR`` attribute), RTC slow memory will be kept powered on by default. This can be overriden using ``esp_sleep_pd_config`` function, if desired.
+If some variables in the program are placed into RTC slow memory (for example, using ``RTC_DATA_ATTR`` attribute), RTC slow memory will be kept powered on by default. This can be overriden using :cpp:func:`esp_sleep_pd_config` function, if desired.
 
 .. doxygenfunction:: esp_sleep_pd_config
 .. doxygenenum:: esp_sleep_pd_domain_t
@@ -142,10 +142,17 @@ Checking sleep wakeup cause
 The following function can be used to check which wakeup source has triggered wakeup from sleep mode. For touch pad and ext1 wakeup sources, it is possible to identify pin or touch pad which has caused wakeup.
 
 .. doxygenfunction:: esp_sleep_get_wakeup_cause
-.. doxygenenum:: esp_sleep_wakeup_cause_t
+.. doxygentypedef:: esp_sleep_wakeup_cause_t
 .. doxygenfunction:: esp_sleep_get_touchpad_wakeup_status
 .. doxygenfunction:: esp_sleep_get_ext1_wakeup_status
 
+Disable sleep wakeup source
+---------------------------
+
+Previously configured wakeup source can be disabled later using :cpp:func:`esp_sleep_disable_wakeup_source` API. This function deactivates trigger for source defined as input parameter if it should not be used to wake up from sleep.
+
+.. doxygenenum:: esp_sleep_source_t
+.. doxygenfunction:: esp_sleep_disable_wakeup_source
 
 Application Example
 -------------------