Implement RAII-patterned token class for ForcedLightSleep begin()/end().

esp8266 · dok-net · Apr 13, 2021 · Apr 15, 2021 · Apr 15, 2021 · Apr 15, 2021
commit dd6ea93254a9497f72d2da5bf5786d680910256d
diff --git a/cores/esp8266/Esp.h b/cores/esp8266/Esp.h
@@ -293,4 +293,34 @@ class EspClass {
 
 extern EspClass ESP;
 
+/// RAII helper token class for forcedLightSleepBegin()/End().
+/// Cast to bool to check that forced light sleep can commence.
+/// The forced light sleep is entered when the token goes out of scope.
+/// Call cancel() to prevent sleeping.
+class ESPForcedLightSleepToken {
+private:
+    ESPForcedLightSleepToken() = delete;
+    ESPForcedLightSleepToken(const ESPForcedLightSleepToken&) = delete;
+    ESPForcedLightSleepToken& operator=(const ESPForcedLightSleepToken&) = delete;
+
+    bool isArmed = false;
+
+public:
+    ESPForcedLightSleepToken(uint32_t duration_us, void (*wakeupCb)()) {
+        isArmed = ESP.forcedLightSleepBegin(10 * 1000 * 1000, wakeupCb);
+    }
+    ~ESPForcedLightSleepToken() {
+        if (isArmed) ESP.forcedLightSleepEnd(false);
+    }
+    operator bool() {
+        return isArmed;
+    }
+    void cancel() {
+        if (isArmed) {
+            ESP.forcedLightSleepEnd(true);
+            isArmed = false;
+        }
+    }
+};
+
 #endif //ESP_H
diff --git a/libraries/esp8266/examples/ForcedLightSleep/ForcedLightSleep.ino b/libraries/esp8266/examples/ForcedLightSleep/ForcedLightSleep.ino
@@ -26,70 +26,77 @@
 // you can use any GPIO for WAKE_UP_PIN except for D0/GPIO16 as it doesn't support interrupts
 
 void IRAM_ATTR wakeupPinIsr() {
-  // For edge-triggered IRQ.
-  detachInterrupt(WAKE_UP_PIN);
-  schedule_function([]() {
-    Serial.println("GPIO went from HI to LO");
-  });
+    // For edge-triggered IRQ.
+    detachInterrupt(WAKE_UP_PIN);
+    schedule_function([]() {
+        Serial.println("GPIO went from HI to LO");
+        });
 }
 
 void IRAM_ATTR wakeupPinIsrWE() {
-  // Wakeup IRQs are available as level-triggered only.
-  detachInterrupt(WAKE_UP_PIN);
-  schedule_function([]() {
-    Serial.println("GPIO wakeup IRQ");
-  });
-  wakeupPinIsr();
-  // reattach falling edge IRQ in loop
+    // Wakeup IRQs are available as level-triggered only.
+    detachInterrupt(WAKE_UP_PIN);
+    schedule_function([]() {
+        Serial.println("GPIO wakeup IRQ");
+        });
+    wakeupPinIsr();
+    // reattach falling edge IRQ in loop
 }
 
 void wakeupCallback() {
-  schedule_function([]() {
-    Serial.println("wakeup callback was performed");
-  });
-  // return to falling edge IRQ, otherwise level-triggered IRQ with wakeup
-  // would get called unexpectedly while awake.
-  attachInterrupt(WAKE_UP_PIN, wakeupPinIsr, FALLING);
+    schedule_function([]() {
+        Serial.println("wakeup callback was performed");
+        });
+    // return to falling edge IRQ, otherwise level-triggered IRQ with wakeup
+    // would get called unexpectedly while awake.
+    attachInterrupt(WAKE_UP_PIN, wakeupPinIsr, FALLING);
 }
 
 void setup() {
-      Serial.begin(74880);
-  while (!Serial)
-    ;
-  delay(100);
-  pinMode(LED_BUILTIN, OUTPUT);        // activity and status indicator
-  digitalWrite(LED_BUILTIN, LOW);      // turn on the LED
-  pinMode(WAKE_UP_PIN, INPUT_PULLUP);  // polled to advance tests, interrupt for Forced Light Sleep
-  attachInterrupt(WAKE_UP_PIN, wakeupPinIsr, FALLING);
+    Serial.begin(74880);
+    while (!Serial)
+        ;
+    delay(100);
+    pinMode(LED_BUILTIN, OUTPUT);        // activity and status indicator
+    digitalWrite(LED_BUILTIN, LOW);      // turn on the LED
+    pinMode(WAKE_UP_PIN, INPUT_PULLUP);  // polled to advance tests, interrupt for Forced Light Sleep
+    attachInterrupt(WAKE_UP_PIN, wakeupPinIsr, FALLING);
 }
 
 using oneShotYieldMs = esp8266::polledTimeout::timeoutTemplate<false, esp8266::polledTimeout::YieldPolicy::YieldOrSkip>;
 oneShotYieldMs gotoSleep(2000);
 
 void loop() {
-  if (gotoSleep && ESP.forcedLightSleepBegin(10 * 1000 * 1000, wakeupCallback)) {
-    // No new timers, no delay(), between forcedLightSleepBegin() and forcedLightSleepEnd().
-    // Only ONLOW_WE or ONHIGH_WE interrupts work, no edge, that's an SDK or CPU limitation.
-    // If the GPIO is in the state that will cause a wakeup on attaching the interrupt,
-    // it cannot trigger a wakeup later, but any sleep duration will be honored.
-    bool wakeupPinIsHigh = digitalRead(WAKE_UP_PIN);
-    delayMicroseconds(5000);
-    wakeupPinIsHigh &= digitalRead(WAKE_UP_PIN);
-    delayMicroseconds(5000);
-    wakeupPinIsHigh &= digitalRead(WAKE_UP_PIN);
-    // the GPIO might still bounce to LOW after this but before sleep is full engaged,
-    // disabling wakeup after all
-    if (wakeupPinIsHigh) {
-      attachInterrupt(WAKE_UP_PIN, wakeupPinIsrWE, ONLOW_WE);
+    if (gotoSleep) {
+        // No new timers, no delay(), while RAII ForcedLightSleepToken exists.
+        // Only ONLOW_WE or ONHIGH_WE interrupts work, no edge, that's an SDK or CPU limitation.
+        // If the GPIO is in the state that will cause a wakeup on attaching the interrupt,
+        // it cannot trigger a wakeup later, but any sleep duration will be honored.
+        bool wakeupPinIsHigh = digitalRead(WAKE_UP_PIN);
+        {
+            ESPForcedLightSleepToken token(10 * 1000 * 1000, wakeupCallback);
+            if (token) { // if true, run user code to set up forced light sleep details
+                // debouncing the wake up pin
+                delayMicroseconds(5000);
+                wakeupPinIsHigh &= digitalRead(WAKE_UP_PIN);
+                delayMicroseconds(5000);
+                wakeupPinIsHigh &= digitalRead(WAKE_UP_PIN);
+                // the GPIO might still bounce to LOW after this but before sleep is full engaged,
+                // disabling wakeup after all
+                if (wakeupPinIsHigh) {
+                    attachInterrupt(WAKE_UP_PIN, wakeupPinIsrWE, ONLOW_WE);
+                }
+                digitalWrite(LED_BUILTIN, HIGH);  // turn the LED off so they know the CPU isn't running
+                if (!wakeupPinIsHigh) token.cancel();
+            }
+            // RAII token gets destructed, going to sleep if all went well
+        }
+        digitalWrite(LED_BUILTIN, LOW);  // turn on the LED
+        // retry immediately if the GPIO was found not ready for entering sleep
+        if (wakeupPinIsHigh) {
+            gotoSleep.reset();
+        }
+        // restore falling edge IRQ
+        attachInterrupt(WAKE_UP_PIN, wakeupPinIsr, FALLING);
     }
-    digitalWrite(LED_BUILTIN, HIGH);  // turn the LED off so they know the CPU isn't running
-    ESP.forcedLightSleepEnd(!wakeupPinIsHigh);
-    digitalWrite(LED_BUILTIN, LOW);  // turn on the LED
-    // retry immediately if the GPIO was found not ready for entering sleep
-    if (wakeupPinIsHigh) {
-      gotoSleep.reset();
-    }
-    // restore falling edge IRQ
-    attachInterrupt(WAKE_UP_PIN, wakeupPinIsr, FALLING);
-  }
 }