Merge remote-tracking branch 'origin' into sandbox

Author: M65649

src/examples/low_power/low_power.ino

@@ -32,7 +32,7 @@ void setup() {
     //
     // Here we say that we want to sleep for 30 seconds * 2 = 60 seconds each
     // time we invoke sleep
-    LowPower.begin(SleepMultiplier::THIRTY_SECONDS, 2);
+    LowPower.begin(SleepMultiplier::THIRTY_SECONDS, 2, SleepMode::REGULAR);
     Lte.begin();
 
     while (!Lte.isConnected()) {
@@ -49,7 +49,7 @@ void loop() {
 
     digitalWrite(TIMING_PIN, digitalRead(TIMING_PIN) ? 0 : 1);
 
-    SleepStatusCode status_code = LowPower.sleep(SleepMode::REGULAR);
-    Log.infof("Got out of sleep with status code %d, doing work...\r\n",
-              status_code);
+    WakeUpReason wakeup_reason = LowPower.sleep();
+    Log.infof("Got out of sleep with wake up reason %d, doing work...\r\n",
+              wakeup_reason);
 }

src/low_power.cpp

@@ -60,6 +60,7 @@ static volatile bool ring_line_activity = false;
 static volatile bool modem_is_in_power_save = false;
 static volatile bool pit_triggered = false;
 
+static SleepMode sleep_mode;
 static bool retrieved_sleep_time = false;
 static uint32_t sleep_time = 0;
 
@@ -278,7 +279,7 @@ static void disablePIT(void) {
 /**
  * Modem sleeping and CPU deep sleep.
  */
-static SleepStatusCode regularSleep(void) {
+static WakeUpReason regularSleep(void) {
 
     const unsigned long start_time_ms = millis();
 
@@ -288,7 +289,7 @@ static SleepStatusCode regularSleep(void) {
         sleep_time = retrieveOperatorSleepTime();
 
         if (sleep_time == 0) {
-            return SleepStatusCode::INVALID_SLEEP_TIME;
+            return WakeUpReason::INVALID_SLEEP_TIME;
         } else {
             retrieved_sleep_time = true;
         }
@@ -301,18 +302,18 @@ static SleepStatusCode regularSleep(void) {
     // If we surpassed the sleep time during setting the LTE to sleep, we
     // don't have any more time to sleep the CPU, so just return.
     if (millis() - start_time_ms >= sleep_time * 1000) {
-        return SleepStatusCode::TIMEOUT;
+        return WakeUpReason::MODEM_TIMEOUT;
     }
 
     enablePIT();
 
     uint32_t remaining_time_seconds =
         sleep_time - (uint32_t)(((millis() - start_time_ms) / 1000.0f));
 
-    SleepStatusCode status_code = SleepStatusCode::OK;
+    WakeUpReason wakeup_reason = WakeUpReason::OK;
 
     if (remaining_time_seconds < 0) {
-        status_code = SleepStatusCode::TIMEOUT;
+        wakeup_reason = WakeUpReason::MODEM_TIMEOUT;
     }
 
     // As the PIT timer has a minimum frequency of 1 Hz, we loop over the
@@ -332,10 +333,10 @@ static SleepStatusCode regularSleep(void) {
         if (!modem_is_in_power_save) {
 
             if (remaining_time_seconds < PSM_REMAINING_SLEEP_TIME_THRESHOLD) {
-                status_code = SleepStatusCode::OK;
+                wakeup_reason = WakeUpReason::OK;
                 break;
             } else {
-                status_code = SleepStatusCode::AWOKEN_BY_MODEM_PREMATURELY;
+                wakeup_reason = WakeUpReason::AWOKEN_BY_MODEM_PREMATURELY;
                 break;
             }
         }
@@ -348,13 +349,13 @@ static SleepStatusCode regularSleep(void) {
 
     disablePIT();
 
-    return status_code;
+    return wakeup_reason;
 }
 
 /**
  * Modem turned off and CPU deep sleep.
  */
-static SleepStatusCode deepSleep(void) {
+static WakeUpReason deepSleep(void) {
 
     const unsigned long start_time_ms = millis();
 
@@ -382,11 +383,14 @@ static SleepStatusCode deepSleep(void) {
 
     Lte.begin();
 
-    return SleepStatusCode::OK;
+    return WakeUpReason::OK;
 }
 
 bool LowPowerClass::begin(const SleepMultiplier sleep_multiplier,
-                          const uint8_t sleep_value) {
+                          const uint8_t sleep_value,
+                          const SleepMode mode) {
+
+    sleep_mode = mode;
 
     // Reset in case there is a reconfiguration after sleep has been called
     // previously
@@ -448,13 +452,13 @@ bool LowPowerClass::begin(const SleepMultiplier sleep_multiplier,
     return SequansController.retryCommand(command);
 }
 
-SleepStatusCode LowPowerClass::sleep(const SleepMode sleep_mode) {
+WakeUpReason LowPowerClass::sleep(void) {
     switch (sleep_mode) {
     case SleepMode::REGULAR:
         return regularSleep();
     case SleepMode::DEEP:
         return deepSleep();
     }
 
-    return SleepStatusCode::OK;
+    return WakeUpReason::OK;
 }

src/low_power.h

@@ -18,14 +18,14 @@ enum class SleepMultiplier {
     ONE_MINUTE = 5,
 };
 
-enum class SleepStatusCode {
+enum class WakeUpReason {
     // Invoked if the sleep time retrieved from the operator wasn't valid
     INVALID_SLEEP_TIME = 4,
 
     // Invoked if it took so long to put the modem in sleep that it wasn't time
     // left for the CPU to sleep. The sleep time should be considered to be
     // increased.
-    TIMEOUT = 3,
+    MODEM_TIMEOUT = 3,
 
     // The modem went out of sleep before the total time, which may happen if
     // e.g. the interval of needing to send MQTT heartbeat is lower than the
@@ -68,10 +68,16 @@ class LowPowerClass {
      *
      * @param sleep_value Note that max value is 31.
      *
+     * @param sleep_modem:
+     * - REGULAR: Modem in sleep, CPU in deep sleep
+     * - DEEP: Modem powered off, CPU in deep sleep. Note that the modem will be
+     *   started again after the sleep in this mode
+     *
      * @return True if configuration was set successfully.
      */
     bool begin(const SleepMultiplier sleep_multiplier,
-               const uint8_t sleep_value);
+               const uint8_t sleep_value,
+               const SleepMode = SleepMode::REGULAR);
 
     /**
      * @brief Will attempt to put the modem in sleep and then the MCU for the
@@ -80,16 +86,12 @@ class LowPowerClass {
      * some time, so the total time both of the units are asleep is highly
      * likely to be some seconds shorter than the total sleep time.
      *
-     * @param sleep_modem:
-     * - REGULAR: Modem in sleep, CPU in deep sleep
-     * - DEEP: Modem powered off, CPU in deep sleep
-     *
      * @return Status code:
      * - INVALID_SLEEP_TIME: if the sleep time configured in begin() wasn't
      * valid or something else failed. Consider modifying the sleep time.
      *
-     * - TIMEOUT: Happens when the remining time after putting the modem to
-     * sleep left there being no time for the CPU to sleep. Not necessarily a
+     * - MODEM_TIMEOUT: Happens when the remining time after putting the modem
+     * to sleep left there being no time for the CPU to sleep. Not necessarily a
      * problem, but the CPU won't get any sleep time. This can be alleviated by
      * increasing the sleep time.
      *
@@ -104,7 +106,7 @@ class LowPowerClass {
      *
      * - OK: Sleep went fine.
      */
-    SleepStatusCode sleep(const SleepMode sleep_mode);
+    WakeUpReason sleep(void);
 };
 
 extern LowPowerClass LowPower;