esp32: Deactivate wakeup trigger after first wakeup

alisitsyn · alisitsyn · commit 1e9bb5bb7c96 · 2018-03-20T12:23:32.000+05:00
The files updated according to code review discussions. In the sleep_modes.c removed immidiate disable of ULP mode and leave just trigger deactivation. The esp_sleep.h is updated to have the same defines for source as esp_sleep_wakeup_cause_t. Updated documentation in sleep_modes.rst file to include cross references. Some minor changes in test_sleep.c unit test. (TW#18952) Closes #1677
diff --git a/components/esp32/include/esp_deep_sleep.h b/components/esp32/include/esp_deep_sleep.h
@@ -37,11 +37,6 @@ typedef esp_sleep_pd_option_t esp_deep_sleep_pd_option_t;
 typedef esp_sleep_ext1_wakeup_mode_t esp_ext1_wakeup_mode_t;
 typedef esp_sleep_wakeup_cause_t esp_deep_sleep_wakeup_cause_t;
 
-inline static esp_err_t esp_deep_sleep_disable_wakeup_source(esp_sleep_source_t source)
-{
-    return esp_sleep_disable_wakeup_source(source);
-}
-
 inline static esp_err_t esp_deep_sleep_enable_ulp_wakeup(void)
 {
     return esp_sleep_enable_ulp_wakeup();
diff --git a/components/esp32/include/esp_sleep.h b/components/esp32/include/esp_sleep.h
@@ -18,7 +18,6 @@
 #include "esp_err.h"
 #include "driver/gpio.h"
 #include "driver/touch_pad.h"
-#include "soc/rtc.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -61,20 +60,11 @@ 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;
-
-/**
- * @brief Sleep wakeup sources for esp_sleep_disable_wakeup_source function
- */
-typedef enum {
-    ESP_SLEEP_SOURCE_UNDEFINED,     //!< Wakeup source is not defined
-    ESP_SLEEP_SOURCE_EXT0,          //!< Wakeup source for external signal using RTC_IO
-    ESP_SLEEP_SOURCE_EXT1,          //!< Wakeup source for external signal using RTC_CNTL
-    ESP_SLEEP_SOURCE_TIMER,         //!< Wakeup source for timer
-    ESP_SLEEP_SOURCE_TOUCHPAD,      //!< Wakeup source for touchpad
-    ESP_SLEEP_SOURCE_ULP,           //!< Wakeup source for ULP program
 } esp_sleep_source_t;
 
+/* Leave this type define for compatibility */
+typedef esp_sleep_source_t esp_sleep_wakeup_cause_t;
+
 /**
  * @brief Disable wakeup source
  *
diff --git a/components/esp32/sleep_modes.c b/components/esp32/sleep_modes.c
@@ -290,28 +290,25 @@ 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_SOURCE_TIMER, RTC_TIMER_TRIG_EN)) {
+    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_SOURCE_EXT0, RTC_EXT0_TRIG_EN)) {
+    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_SOURCE_EXT1, RTC_EXT1_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_SOURCE_TOUCHPAD, RTC_TOUCH_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_SOURCE_ULP, RTC_ULP_TRIG_EN)) {
-        // The ulp wake up option is disabled immediately
-        CLEAR_PERI_REG_MASK(RTC_CNTL_STATE0_REG, RTC_CNTL_ULP_CP_WAKEUP_FORCE_EN);
-        CLEAR_PERI_REG_MASK(RTC_CNTL_STATE0_REG, RTC_CNTL_ULP_CP_SLP_TIMER_EN);
+    else if (CHECK_SOURCE(source, ESP_SLEEP_WAKEUP_ULP, RTC_ULP_TRIG_EN)) {
         s_config.wakeup_triggers &= ~RTC_ULP_TRIG_EN;
     }
 #endif
diff --git a/components/esp32/test/test_sleep.c b/components/esp32/test/test_sleep.c
@@ -5,25 +5,13 @@
 #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"
+#include "soc/soc.h"            // for direct register read macros
 
 #define ESP_EXT0_WAKEUP_LEVEL_LOW 0
 #define ESP_EXT0_WAKEUP_LEVEL_HIGH 1
 
-// These are flags for wakeup cause to get it directly from RTC
-#define RTC_EXT0_TRIG_EN    BIT(0)  //!< EXT0 GPIO wakeup
-#define RTC_EXT1_TRIG_EN    BIT(1)  //!< EXT1 GPIO wakeup
-#define RTC_GPIO_TRIG_EN    BIT(2)  //!< GPIO wakeup (light sleep only)
-#define RTC_TIMER_TRIG_EN   BIT(3)  //!< Timer wakeup
-#define RTC_SDIO_TRIG_EN    BIT(4)  //!< SDIO wakeup (light sleep only)
-#define RTC_MAC_TRIG_EN     BIT(5)  //!< MAC wakeup (light sleep only)
-#define RTC_UART0_TRIG_EN   BIT(6)  //!< UART0 wakeup (light sleep only)
-#define RTC_UART1_TRIG_EN   BIT(7)  //!< UART1 wakeup (light sleep only)
-#define RTC_TOUCH_TRIG_EN   BIT(8)  //!< Touch wakeup
-#define RTC_ULP_TRIG_EN     BIT(9)  //!< ULP wakeup
-#define RTC_BT_TRIG_EN      BIT(10) //!< BT wakeup (light sleep only)
-
 static struct timeval tv_start, tv_stop;
 
 TEST_CASE("esp_deepsleep works", "[deepsleep][reset=DEEPSLEEP_RESET]")
@@ -129,7 +117,7 @@ TEST_CASE("wake up using ext1 when RTC_PERIPH is on (13 low)", "[deepsleep][igno
     esp_deep_sleep_start();
 }
 
-static float get_time(void)
+static float get_time_ms(void)
 {
     gettimeofday(&tv_stop, NULL);
     
@@ -146,7 +134,7 @@ static uint32_t get_cause()
 }
 
 // This test case verifies deactivation of trigger for wake up sources 
-TEST_CASE("disable source behavior", "[deepsleep][ignore]")
+TEST_CASE("disable source trigger behavior", "[deepsleep]")
 {
     float dt = 0;
 
@@ -166,23 +154,23 @@ TEST_CASE("disable source behavior", "[deepsleep][ignore]")
     gettimeofday(&tv_start, NULL);
     esp_light_sleep_start();
 
-    dt = get_time();
+    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(297, 300, (int) dt);
+    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_SOURCE_EXT0));
-    printf("Disable ext0 source leave timer active.\n");
+    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();
+    dt = get_time_ms();
     printf("Timer sleep time = %d \n", (int) dt);
     
     TEST_ASSERT_INT32_WITHIN(500, 2000, (int) dt);
@@ -191,27 +179,28 @@ TEST_CASE("disable source behavior", "[deepsleep][ignore]")
     TEST_ASSERT((get_cause() & RTC_TIMER_TRIG_EN) != 0);
 
     // Disable timer source.
-    ESP_ERROR_CHECK(esp_sleep_disable_wakeup_source(ESP_SLEEP_SOURCE_TIMER));
+    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 and wake up from ext0 source.\n");
+    printf("Disable timer trigger to wake up from ext0 source.\n");
 
     gettimeofday(&tv_start, NULL);
     esp_light_sleep_start();
 
-    dt = get_time();
+    dt = get_time_ms();
     printf("Ext0 sleep time = %d \n", (int) dt);
 
-    TEST_ASSERT_INT32_WITHIN(198, 200, (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_SOURCE_TIMER);
+    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.");
 }
 
diff --git a/docs/api-reference/system/sleep_modes.rst b/docs/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 and can be disabled using ``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. 
+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
@@ -149,7 +149,7 @@ The following function can be used to check which wakeup source has triggered wa
 Disable sleep wakeup source
 ---------------------------
 
-Previously configured wakeup source can be disabled later using ``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.
+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
