Merge pull request #3 from arduino-libraries/refactorings

Use enum to determine previous CPU mode

Author: sebromero

Diff for: README.md

@@ -43,7 +43,7 @@ In addition to the three Deep Sleep Locks already mentioned, additional locks ma
 
 ### 😴 Standby Mode
 
-In Standby Mode, both the sketch and Mbed are entirely stopped by the library, and it asks the microcontroller to turn off almost all functionality to save power. You can wake it up from this mode in two ways: pulling the GPIO 0 pin low on the Portenta Breakout Board (no external pull-up resistor is necessary) or asking the library to wake up after a certain amount of time. The delay can be set anywhere from 1 second up to 36 hours, 24 minutes, and 32 seconds. When the board wakes up again, it's more or less in the same state as it would have been if you had pressed the reset button. You can ask the library what the board was doing before it started by calling one or a combination of the functions: `modeWasD1Standby()`, `modeWasD2Standby()`, `modeWasStandby()`, and `modeWasStop()`.
+In Standby Mode, both the sketch and Mbed are entirely stopped by the library, and it asks the microcontroller to turn off almost all functionality to save power. You can wake it up from this mode in two ways: pulling the GPIO 0 pin low on the Portenta Breakout Board (no external pull-up resistor is necessary) or asking the library to wake up after a certain amount of time. The delay can be set anywhere from 1 second up to 36 hours, 24 minutes, and 32 seconds. When the board wakes up again, it's more or less in the same state as it would have been if you had pressed the reset button. You can ask the library what the board was doing before it started by calling `wasInCPUMode()`. More information on this can be found [here](./docs).
 
 ## ⚖️ License
 

Diff for: docs/README.md

@@ -17,9 +17,12 @@ The only function necessary to enable automatic Deep Sleep Mode is `allowDeepSle
 
 ### Standby Mode
 
-To use Standby Mode, you need the following functions: `checkOptionBytes()`, `prepareOptionBytes()`, `standbyM7()`, and `standbyM4()`. The option byte functions are necessary to ensure that the flash option bytes in the microcontroller are correctly set for going into Standby Mode. Additionally, you can use the following functions to check what the board was doing before it started: `modeWasD1Standby()`, `modeWasD2Standby()`, `modeWasStandby()`, and `modeWasStop()`. Only `modeWasStandby()` should return true if Standby Mode was entered correctly. The other functions can be handy for troubleshooting. Remember to clear the mode flags by calling `resetPreviousMode()` when you are done checking them.
+To use Standby Mode, you need the following functions: `checkOptionBytes()`, `prepareOptionBytes()`, `standbyM7()`, and `standbyM4()`. The option byte functions are necessary to ensure that the flash option bytes in the microcontroller are correctly set for going into Standby Mode. 
+Additionally, you can use `wasInCPUMode()` to check what the board was doing before it started:
+By passing one of the modes `d1DomainStandby`, `d2DomainStandby`, `standby` or `stop` as parameter you can determine in which of these modes the CPU was before it started. It's possible that the CPU was in more than one of these modes so you need to check for each mode separately to get the complete picture.
+Only if `wasInCPUMode(CPUMode::standby)` returns true, Standby Mode was entered correctly. The other functions can be handy for troubleshooting. Remember to clear the mode flags by calling `resetPreviousCPUModeFlags()` when you are done checking them.
 
-The microcontroller has three power domains: one for the M7 core (D1), one for the M4 core (D2), and a separate third domain (D3) for some other functionality. `modeWasD1Standby()` returns true if D1 was in standby, but all three weren't at the same time, while `modeWasD2Standby()` returns true if D2 was in standby, but all three weren't at the same time. Both functions can return true simultaneously if D1 and D2 were in standby mode while D3 was still awake. When all three domains are in standby mode simultaneously, the microcontroller as a whole enters Standby Mode automatically, and only `modeWasStandby()` returns true when it wakes up again. The `modeWasStop()` function should never return true but can be helpful for further troubleshooting if you contact Arduino support.
+The microcontroller has three power domains: one for the M7 core (D1), one for the M4 core (D2), and a separate third domain (D3) for some other functionality. `wasInCPUMode(CPUMode::d1DomainStandby)` returns true if D1 was in standby, but all three weren't at the same time, while `wasInCPUMode(CPUMode::d2DomainStandby)()` returns true if D2 was in standby, but all three weren't at the same time. Both functions can return true simultaneously if D1 and D2 were in standby mode while D3 was still awake. When all three domains are in standby mode simultaneously, the microcontroller as a whole enters Standby Mode automatically, and `wasInCPUMode(CPUMode::standby)` returns true when it wakes up again. The `wasInCPUMode(CPUMode::stop)` function should never return true but can be helpful for further troubleshooting if you encounter any issues with this library.
 
 All configuration of Standby Mode is done when calling `standbyM7()`. It takes one or two parameters, depending on the conditions you want to set for waking up. The first parameter is one of the flags `LowPowerStandbyType::untilPinActivity` and `LowPowerStandbyType::untilTimeElapsed`. If you want to wake up from either type of event, you can combine the flags like so: `LowPowerStandbyType::untilPinActivity | LowPowerStandbyType::untilTimeElapsed`. If `LowPowerStandbyType::untilTimeElapsed` is present, the function takes a second parameter. This parameter's preferred format is `2_h + 30_min + 45_s`. You can use any combination of hours, minutes, and seconds. For example, `15_h`, or `1_h + 30_min`, or just `90_s`. If you first have to calculate the delay in your sketch, you can also pass something like this: `RTCWakeupDelay(1, 20, 30)`. The first number is hours, the second minutes, and the third seconds. But, the preferred option is to use _h, _min, and _s since that's more explicit.
 

Diff for: docs/api.md

@@ -23,13 +23,10 @@ This class is specific to the Portenta H7 board.
 | [`allowDeepSleep`](#class_low_power_portenta_h7_1a7ed518f8205a0b7306d23b7e2a22e82b) | Make Deep Sleep possible in the default case. |
 | [`canDeepSleep`](#class_low_power_portenta_h7_1a07d9e0f356e40ac70655e279fbad87a9) | Check if Deep Sleep is possible or not at the moment. |
 | [`checkOptionBytes`](#class_low_power_portenta_h7_1a7519d3acf693f450af84312576d8e669) | Check if the option bytes are correct to enter Standby Mode. |
-| [`modeWasD1Standby`](#class_low_power_portenta_h7_1a4eb99fd03e8891f93d43aca4ea2329f9) | Check if the D1 domain was in Standby Mode or not. |
-| [`modeWasD2Standby`](#class_low_power_portenta_h7_1a81e1c97f6411de6c6df390f7cb1ef8dc) | Check if the D2 domain was in Standby Mode or not. |
-| [`modeWasStandby`](#class_low_power_portenta_h7_1afb2fc28d8a59bc34799e4c83a746f7c4) | Check if the whole microcontroller was in Standby Mode or not. |
-| [`modeWasStop`](#class_low_power_portenta_h7_1a8420caa1148e61bc4d40e9627866afe3) | Check if the whole microcontroller was in Stop Mode or not. |
+| [`wasInCPUMode`](#class_low_power_portenta_h7_1ae2059eb4fb01a30342b9fb6918b6ab4c) | Checks if the microcontroller was in the given standby mode before waking up. Note: It's possible that the microcontroller was in more than one of these modes during standby. Call this function multiple times to check for each mode. Important: When you're done checking, call resetStandbyModeFlags() to reset the flags so they are reported correctly the next time the microcontroller wakes up.  |
+| [`resetPreviousCPUModeFlags`](#class_low_power_portenta_h7_1a1753e3c053b2b64b59da3cbb9b921d76) | Reset the flags that are used to determine the microcontroller's previous standby mode. This is necessary to get correct results from [wasInCPUMode()](#class_low_power_portenta_h7_1ae2059eb4fb01a30342b9fb6918b6ab4c). |
 | [`numberOfDeepSleepLocks`](#class_low_power_portenta_h7_1a9d2730d86abf42782261b0f03778c3bb) | Check how many Deep Sleep locks are held at the moment. |
 | [`prepareOptionBytes`](#class_low_power_portenta_h7_1abdc0ce13b68d3a2188702690997af2ae) | Prepare the option bytes for entry into Standby Mode. |
-| [`resetPreviousMode`](#class_low_power_portenta_h7_1a6f09b3ffe26355372f287ab90a451cc2) | Reset the flags behind the modeWas...() functions. |
 | [`standbyM4`](#class_low_power_portenta_h7_1a9e07fd4f7895a7753e7e28f99aca1ace) | Make the M4 core enter Standby Mode. |
 | [`standbyM7`](#class_low_power_portenta_h7_1a1eb5cec6e9604a48074f1c10ef5e7fb0) | Make the M7 core enter Standby Mode. |
 | [`timeSinceBoot`](#class_low_power_portenta_h7_1a4758c25574b6d099545ac8d55eff6f68) | Time since the board was booted. It reports the time since the last wake-up reset (after standby) or power-on depending on what happened last. |
@@ -73,52 +70,28 @@ Check if the option bytes are correct to enter Standby Mode.
 A constant from the LowPowerReturnCode enum.
 <hr />
 
-### `modeWasD1Standby` <a id="class_low_power_portenta_h7_1a4eb99fd03e8891f93d43aca4ea2329f9" class="anchor"></a>
+### `wasInCPUMode` <a id="class_low_power_portenta_h7_1ae2059eb4fb01a30342b9fb6918b6ab4c" class="anchor"></a>
 
 ```cpp
-bool modeWasD1Standby() const
+bool wasInCPUMode( CPUMode mode) const
 ```
 
-Check if the D1 domain was in Standby Mode or not.
-
-#### Returns
-Was: true. Was not: false;
-<hr />
-
-### `modeWasD2Standby` <a id="class_low_power_portenta_h7_1a81e1c97f6411de6c6df390f7cb1ef8dc" class="anchor"></a>
-
-```cpp
-bool modeWasD2Standby() const
-```
-
-Check if the D2 domain was in Standby Mode or not.
-
-#### Returns
-Was: true. Was not: false;
-<hr />
-
-### `modeWasStandby` <a id="class_low_power_portenta_h7_1afb2fc28d8a59bc34799e4c83a746f7c4" class="anchor"></a>
-
-```cpp
-bool modeWasStandby() const
-```
-
-Check if the whole microcontroller was in Standby Mode or not.
+Checks if the microcontroller was in the given standby mode before waking up. Note: It's possible that the microcontroller was in more than one of these modes during standby. Call this function multiple times to check for each mode. Important: When you're done checking, call resetStandbyModeFlags() to reset the flags so they are reported correctly the next time the microcontroller wakes up. 
+#### Parameters
+* `mode` The CPU mode to check. 
 
 #### Returns
-Was: true. Was not: false;
+True if the microcontroller was in the given mode, false otherwise.
 <hr />
 
-### `modeWasStop` <a id="class_low_power_portenta_h7_1a8420caa1148e61bc4d40e9627866afe3" class="anchor"></a>
+### `resetPreviousCPUModeFlags` <a id="class_low_power_portenta_h7_1a1753e3c053b2b64b59da3cbb9b921d76" class="anchor"></a>
 
 ```cpp
-bool modeWasStop() const
+void resetPreviousCPUModeFlags() const
 ```
 
-Check if the whole microcontroller was in Stop Mode or not.
+Reset the flags that are used to determine the microcontroller's previous standby mode. This is necessary to get correct results from [wasInCPUMode()](#class_low_power_portenta_h7_1ae2059eb4fb01a30342b9fb6918b6ab4c).
 
-#### Returns
-Was: true. Was not: false;
 <hr />
 
 ### `numberOfDeepSleepLocks` <a id="class_low_power_portenta_h7_1a9d2730d86abf42782261b0f03778c3bb" class="anchor"></a>
@@ -145,16 +118,6 @@ Prepare the option bytes for entry into Standby Mode.
 A constant from the LowPowerReturnCode enum.
 <hr />
 
-### `resetPreviousMode` <a id="class_low_power_portenta_h7_1a6f09b3ffe26355372f287ab90a451cc2" class="anchor"></a>
-
-```cpp
-void resetPreviousMode() const
-```
-
-Reset the flags behind the modeWas...() functions.
-
-<hr />
-
 ### `standbyM4` <a id="class_low_power_portenta_h7_1a9e07fd4f7895a7753e7e28f99aca1ace" class="anchor"></a>
 
 ```cpp

Diff for: examples/Standby/Standby.ino

@@ -7,7 +7,7 @@
 * The microcontroller has three power domains: one for the M7 core (D1), 
 * one for the M4 core (D2), and a separate third domain (D3) for some other functionality.
 * When all three domains are in standby mode simultaneously, the microcontroller as a whole 
-* enters Standby Mode automatically, and `modeWasStandby()` only returns true when it wakes up again.
+* enters Standby Mode automatically, and `wasInCPUMode(CPUMode::standby)` returns true when it wakes up again.
 *
 * IMPORTANT: Upload the same sketch to both the M7 and the M4 core.
 *
@@ -75,28 +75,30 @@ void setup() {
   digitalWrite(LEDR, LOW);
   digitalWrite(LEDG, LOW);
   delay(500);
-  if (LowPower.modeWasStandby())
+
+
+  if (LowPower.wasInCPUMode(CPUMode::standby))
   {
     digitalWrite(LEDB, HIGH);
     digitalWrite(LEDR, HIGH);
     digitalWrite(LEDG, LOW);
     delay(2500);
   }
-  if (LowPower.modeWasD1Standby())
+  if (LowPower.wasInCPUMode(CPUMode::d1DomainStandby))
   {
     digitalWrite(LEDB, LOW);
     digitalWrite(LEDR, HIGH);
     digitalWrite(LEDG, HIGH);
     delay(2500);      
   }
-  if (LowPower.modeWasD2Standby())
+  if (LowPower.wasInCPUMode(CPUMode::d2DomainStandby))
   {
     digitalWrite(LEDB, HIGH);
     digitalWrite(LEDR, LOW);
     digitalWrite(LEDG, HIGH);
     delay(2500);      
   }
-  if (LowPower.modeWasStop())
+  if (LowPower.wasInCPUMode(CPUMode::stop))
   {
     digitalWrite(LEDB, LOW);
     digitalWrite(LEDR, LOW);
@@ -111,7 +113,7 @@ void setup() {
   digitalWrite(LEDR, LOW);
   digitalWrite(LEDG, LOW);
   delay(500);
-  LowPower.resetPreviousMode();
+  LowPower.resetPreviousCPUModeFlags();
 #endif
   // <--
 

Diff for: src/Arduino_LowPowerPortentaH7.cpp

@@ -210,24 +210,30 @@ LowPowerReturnCode LowPowerPortentaH7::checkOptionBytes() const
     return LowPowerReturnCode::success;
 }
 
-bool LowPowerPortentaH7::modeWasD1Standby() const
+bool LowPowerPortentaH7::wasInCPUMode(CPUMode mode) const
 {
-    return PWR->CPUCR & PWR_CPUCR_SBF_D1;
-}
+    const auto registerValue = PWR->CPUCR;
 
-bool LowPowerPortentaH7::modeWasD2Standby() const
-{
-    return PWR->CPUCR & PWR_CPUCR_SBF_D2;
-}
+    switch (mode)
+    {
+        case CPUMode::d1DomainStandby:
+            return registerValue & PWR_CPUCR_SBF_D1;
+        case CPUMode::d2DomainStandby:
+            return registerValue & PWR_CPUCR_SBF_D2;
+        case CPUMode::standby:
+            return registerValue & PWR_CPUCR_SBF;
+        case CPUMode::stop:
+            return registerValue & PWR_CPUCR_STOPF;
+        default:
+            return false;
+    }
 
-bool LowPowerPortentaH7::modeWasStandby() const
-{
-    return PWR->CPUCR & PWR_CPUCR_SBF;
+    return false;
 }
 
-bool LowPowerPortentaH7::modeWasStop() const
+void LowPowerPortentaH7::resetPreviousCPUModeFlags() const
 {
-    return PWR->CPUCR & PWR_CPUCR_STOPF;
+    PWR->CPUCR |= PWR_CPUCR_CSSF; // Clear standby flags
 }
 
 uint16_t LowPowerPortentaH7::numberOfDeepSleepLocks() const
@@ -277,11 +283,6 @@ LowPowerReturnCode LowPowerPortentaH7::prepareOptionBytes() const
     return LowPowerReturnCode::obLaunchFailed;
 }
 
-void LowPowerPortentaH7::resetPreviousMode() const
-{
-    PWR->CPUCR |= PWR_CPUCR_CSSF;
-}
-
 LowPowerReturnCode LowPowerPortentaH7::standbyM4() const
 {
     // Prevent Mbed from changing things

Diff for: src/Arduino_LowPowerPortentaH7.h

@@ -59,6 +59,20 @@ enum class LowPowerReturnCode
     turningOffEthernetFailed    ///< Unable to turn off Ethernet PHY chip
 };
 
+/**
+ * @enum CPUMode
+ * @brief Provides the different modes of the CPU.
+ * Those can be used to determine in which standby mode the CPU
+ * was before waking up.
+*/
+enum class CPUMode
+{
+    d1DomainStandby,                  ///< Standby mode for the D1 domain
+    d2DomainStandby,                  ///< Standby mode for the D2 domain
+    standby,                    ///< Standby mode for the whole microcontroller
+    stop                        ///< Stop mode for the whole microcontroller
+};
+
 /*
 ********************************************************************************
 *                                 Classes
@@ -273,28 +287,23 @@ class LowPowerPortentaH7 {
         LowPowerReturnCode checkOptionBytes() const;
 
         /**
-        * @brief Check if the D1 domain was in Standby Mode or not.
-        * @return Was: true. Was not: false;
-        */
-        bool modeWasD1Standby() const;
-
-        /**
-        * @brief Check if the D2 domain was in Standby Mode or not.
-        * @return Was: true. Was not: false;
-        */
-        bool modeWasD2Standby() const;
+         * Checks if the microcontroller was in the given CPU mode before starting.
+         * Note: It's possible that the microcontroller was in more than one of these modes
+         * before starting. Call this function multiple times to check for each mode.
+         * Important: When you're done checking, call resetStandbyModeFlags() to reset the flags
+         * so they are reported correctly the next time the microcontroller starts.
+         * @param mode The CPU mode to check.
+         * @return True if the microcontroller was in the given mode, false otherwise.
+         */
+        bool wasInCPUMode(CPUMode mode) const;
 
         /**
-        * @brief Check if the whole microcontroller was in Standby Mode or not.
-        * @return Was: true. Was not: false;
+        * @brief Reset the flags that are used to determine the microcontroller's
+        * previous CPU mode. This is necessary to get correct results from
+        * wasInCPUMode().
         */
-        bool modeWasStandby() const;
+        void resetPreviousCPUModeFlags() const;
 
-        /**
-        * @brief Check if the whole microcontroller was in Stop Mode or not.
-        * @return Was: true. Was not: false;
-        */
-        bool modeWasStop() const;
 
         // The deprecated attribute is used here because we only want this
         // warning to be shown if the user actually calls the function
@@ -311,11 +320,6 @@ class LowPowerPortentaH7 {
         */
         LowPowerReturnCode prepareOptionBytes() const;
 
-        /**
-        * @brief Reset the flags behind the modeWas...() functions.
-        */
-        void resetPreviousMode() const;
-
         /**
         * @brief Make the M4 core enter Standby Mode.
         * @return A constant from the LowPowerReturnCode enum.