Merge pull request #7 from alrvid/main

sebromero · web-flow · commit 2c68a6372e58 · 2024-05-16T09:57:37.000+02:00
Fix function order and improve documentation
diff --git a/docs/README.md b/docs/README.md
@@ -26,8 +26,10 @@ The microcontroller has three power domains: one for the M7 core (D1), one for t
 
 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.
 
+When the microcontroller wakes up again from Standby Mode, both the M7 and the M4 cores do so in parallel.
+
 > [!IMPORTANT]
-> You must always upload a sketch to the M4 core, in which you call `standbyM4()`, even if you don't intend to use the M4 core. If you don't, the microcontroller won't enter Standby Mode as a whole, even if you call `standbyM7()`.
+> You must always upload a sketch to the M4 core, in which you call `standbyM4()`, even if you don't intend to use the M4 core. If you don't, the microcontroller won't enter Standby Mode as a whole, even if you call `standbyM7()`, and that will lead to an increased power consumption.
 
 ## 👀 Examples
 
diff --git a/docs/api.md b/docs/api.md
@@ -3,14 +3,14 @@
  Members                        | Descriptions                                
 --------------------------------|---------------------------------------------
 `class ` [`LowPowerPortentaH7`](#class_low_power_portenta_h7) | A class that provides low power functionality for the Portenta H7 board.
-`class ` [`LowPowerStandbyType`](#class_low_power_standby_type) | The [LowPowerStandbyType](#class_low_power_standby_type) class represents different types of standby modes for low power operation.
-`class ` [`RTCWakeupDelay`](#class_r_t_c_wakeup_delay) | The [RTCWakeupDelay](#class_r_t_c_wakeup_delay) class represents a delay before waking up from a low power mode.
+`class ` [`LowPowerStandbyType`](#class_low_power_standby_type) | The [LowPowerStandbyType](#class_low_power_standby_type) class represents different methods of wakeup.
+`class ` [`RTCWakeupDelay`](#class_r_t_c_wakeup_delay) | The [RTCWakeupDelay](#class_r_t_c_wakeup_delay) class represents a delay before waking up from Standby Mode.
 
 # class `LowPowerPortentaH7` <a id="class_low_power_portenta_h7" class="anchor"></a>
 
 A class that provides low power functionality for the Portenta H7 board.
 
-The [LowPowerPortentaH7](#class_low_power_portenta_h7) class allows the microcontroller on the Portenta H7 board to enter low power modes such as Standby Mode and Deep Sleep Mode. It provides functions to check the current mode, prepare the option bytes for entering Standby Mode, and control the M4 and M7 cores independently. It also provides functions to measure the time since boot, time spent in idle, sleep, and deep sleep modes.
+The [LowPowerPortentaH7](#class_low_power_portenta_h7) class allows the microcontroller on the Portenta H7 board to enter low power modes such as Standby Mode and Deep Sleep Mode. It provides functions to check the mode before startup, prepare the option bytes for entering Standby Mode, and control the M4 and M7 cores independently. It also provides functions to measure the time since boot, time spent in Idle, Sleep, and Deep Sleep modes.
 
 This class is a singleton and shall always be accessed through the global LowPower object.
 
@@ -23,16 +23,16 @@ 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. |
-| [`wasInCPUMode`](#class_low_power_portenta_h7_1ae2059eb4fb01a30342b9fb6918b6ab4c) | 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.  |
 | [`resetPreviousCPUModeFlags`](#class_low_power_portenta_h7_1a1753e3c053b2b64b59da3cbb9b921d76) | Reset the flags that are used to determine the microcontroller's previous CPU 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. |
-| [`standbyM4`](#class_low_power_portenta_h7_1a9e07fd4f7895a7753e7e28f99aca1ace) | Make the M4 core enter Standby Mode. |
-| [`standbyM7`](#class_low_power_portenta_h7_1aa9c1cb86c832c35f6653a3d6c9f0d32f) | Make the M7 core enter Standby Mode. |
+| [`standbyM4`](#class_low_power_portenta_h7_1a9e07fd4f7895a7753e7e28f99aca1ace) | Make the M4 core and D2 domain enter standby mode. |
+| [`standbyM7`](#class_low_power_portenta_h7_1aa9c1cb86c832c35f6653a3d6c9f0d32f) | Make the M7 core and D1 domain enter standby mode, and make it possible for the D3 domain to do so too. |
 | [`timeSinceBoot`](#class_low_power_portenta_h7_1a4758c25574b6d099545ac8d55eff6f68) | Time since the board was booted. It reports the time since the last wake-up reset (after being in Standby Mode) or power-on depending on what happened last. |
-| [`timeSpentIdle`](#class_low_power_portenta_h7_1ad42fdfa6885d8e0fdca5aa012fdb4c60) | Time spent in idle. |
+| [`timeSpentIdle`](#class_low_power_portenta_h7_1ad42fdfa6885d8e0fdca5aa012fdb4c60) | Time spent in Idle Mode. |
 | [`timeSpentInSleep`](#class_low_power_portenta_h7_1a994eb6fcc0382515a82b81fa37ca9f3c) | Time spent in Sleep Mode. |
 | [`timeSpentInDeepSleep`](#class_low_power_portenta_h7_1a146eb61800a74360687fd34b456c0b44) | Time spent in Deep Sleep Mode. |
+| [`wasInCPUMode`](#class_low_power_portenta_h7_1ae2059eb4fb01a30342b9fb6918b6ab4c) | 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.  |
 
 ## Members
 
@@ -70,20 +70,6 @@ Check if the option bytes are correct to enter Standby Mode.
 A constant from the LowPowerReturnCode enum.
 <hr />
 
-### `wasInCPUMode` <a id="class_low_power_portenta_h7_1ae2059eb4fb01a30342b9fb6918b6ab4c" class="anchor"></a>
-
-```cpp
-bool wasInCPUMode( CPUMode mode) 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. 
-#### Parameters
-* `mode` The CPU mode to check. 
-
-#### Returns
-True if the microcontroller was in the given mode, false otherwise.
-<hr />
-
 ### `resetPreviousCPUModeFlags` <a id="class_low_power_portenta_h7_1a1753e3c053b2b64b59da3cbb9b921d76" class="anchor"></a>
 
 ```cpp
@@ -124,7 +110,7 @@ A constant from the LowPowerReturnCode enum.
 LowPowerReturnCode standbyM4() const
 ```
 
-Make the M4 core enter Standby Mode.
+Make the M4 core and D2 domain enter standby mode.
 
 #### Returns
 A constant from the LowPowerReturnCode enum.
@@ -136,7 +122,7 @@ A constant from the LowPowerReturnCode enum.
 LowPowerReturnCode standbyM7(const T standbyType, const Args... args) const
 ```
 
-Make the M7 core enter Standby Mode.
+Make the M7 core and D1 domain enter standby mode, and make it possible for the D3 domain to do so too.
 
 #### Parameters
 * `standbyType` One or a combination of [LowPowerStandbyType::untilPinActivity](#class_low_power_standby_type_1a4c5b50ac615cf60ff88dd3b9bb145fa9) and [LowPowerStandbyType::untilTimeElapsed](#class_low_power_standby_type_1aa4882e571c0e9444c5978c8520e8e90e). The combination is done with the | operator. 
@@ -165,7 +151,7 @@ Number of microseconds.
 uint64_t timeSpentIdle() const
 ```
 
-Time spent in idle.
+Time spent in Idle Mode.
 
 #### Returns
 Number of microseconds.
@@ -195,11 +181,25 @@ Time spent in Deep Sleep Mode.
 Number of microseconds.
 <hr />
 
+### `wasInCPUMode` <a id="class_low_power_portenta_h7_1ae2059eb4fb01a30342b9fb6918b6ab4c" class="anchor"></a>
+
+```cpp
+bool wasInCPUMode( CPUMode mode) 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. 
+#### Parameters
+* `mode` The CPU mode to check. 
+
+#### Returns
+True if the microcontroller was in the given mode, false otherwise.
+<hr />
+
 # class `LowPowerStandbyType` <a id="class_low_power_standby_type" class="anchor"></a>
 
-The [LowPowerStandbyType](#class_low_power_standby_type) class represents different types of standby modes for low power operation.
+The [LowPowerStandbyType](#class_low_power_standby_type) class represents different methods of wakeup.
 
-This class provides options for the following standby modes: waiting until pin activity or until a specified time has elapsed, or both. Those are represented by [LowPowerStandbyType::untilPinActivity](#class_low_power_standby_type_1a4c5b50ac615cf60ff88dd3b9bb145fa9) and [LowPowerStandbyType::untilTimeElapsed](#class_low_power_standby_type_1aa4882e571c0e9444c5978c8520e8e90e). To combine the two options use the | operator.
+This class provides options for the following methods of wakeup: waiting until pin activity or until a specified time has elapsed, or both. Those are represented by [LowPowerStandbyType::untilPinActivity](#class_low_power_standby_type_1a4c5b50ac615cf60ff88dd3b9bb145fa9) and [LowPowerStandbyType::untilTimeElapsed](#class_low_power_standby_type_1aa4882e571c0e9444c5978c8520e8e90e). To combine the two options use the | operator.
 
 ## Summary
 
@@ -210,7 +210,7 @@ This class provides options for the following standby modes: waiting until pin a
 
 # class `RTCWakeupDelay` <a id="class_r_t_c_wakeup_delay" class="anchor"></a>
 
-The [RTCWakeupDelay](#class_r_t_c_wakeup_delay) class represents a delay before waking up from a low power mode.
+The [RTCWakeupDelay](#class_r_t_c_wakeup_delay) class represents a delay before waking up from Standby Mode.
 
 ## Summary
 
diff --git a/src/Arduino_LowPowerPortentaH7.cpp b/src/Arduino_LowPowerPortentaH7.cpp
@@ -210,27 +210,6 @@ LowPowerReturnCode LowPowerPortentaH7::checkOptionBytes() const
     return LowPowerReturnCode::success;
 }
 
-bool LowPowerPortentaH7::wasInCPUMode(CPUMode mode) const
-{
-    const auto registerValue = PWR->CPUCR;
-
-    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;
-    }
-
-    return false;
-}
-
 void LowPowerPortentaH7::resetPreviousCPUModeFlags() const
 {
     PWR->CPUCR |= PWR_CPUCR_CSSF;
@@ -395,3 +374,24 @@ void LowPowerPortentaH7::waitForFlashReady() const
     while ((FLASH->SR1 & 0x07) || (FLASH->SR2 & 0x07))
       ;
 }
+
+bool LowPowerPortentaH7::wasInCPUMode(CPUMode mode) const
+{
+    const auto registerValue = PWR->CPUCR;
+
+    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;
+    }
+
+    return false;
+}
diff --git a/src/Arduino_LowPowerPortentaH7.h b/src/Arduino_LowPowerPortentaH7.h
@@ -39,7 +39,7 @@
 
 /**
  * @enum LowPowerReturnCode
- * @brief Provides the return codes for the standby operations.
+ * @brief Provides the return codes for the API functions of the library.
  * The codes indicate the success or failure of the operations.
  */
 enum class LowPowerReturnCode
@@ -62,8 +62,7 @@ enum class LowPowerReturnCode
 /**
  * @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.
+ * Those can be used to determine in which mode the CPU was before waking up.
 */
 enum class CPUMode
 {
@@ -80,9 +79,9 @@ enum class CPUMode
 */
 
 /**
- * @brief The LowPowerStandbyType class represents different types of standby modes for low power operation.
+ * @brief The LowPowerStandbyType class represents different methods of wakeup.
  * 
- * This class provides options for the following standby modes: waiting until pin activity 
+ * This class provides options for the following methods of wakeup: waiting until pin activity
  * or until a specified time has elapsed, or both.
  * Those are represented by LowPowerStandbyType::untilPinActivity and LowPowerStandbyType::untilTimeElapsed.
  * To combine the two options use the | operator.
@@ -91,7 +90,7 @@ class LowPowerStandbyType {
     public:
         /// @cond DEV
         /**
-         * @brief A class representing the condition that waits until a wakeup pin changes its state.
+         * @brief A class representing a wakeup option that waits until a wakeup pin changes its state.
          * 
          * This class provides functionality to wait until a specified pin changes its state,
          * from HIGH to LOW.
@@ -127,7 +126,7 @@ class LowPowerStandbyType {
         /// @cond DEV
         /**
          * @brief Represents a wakeup option which waits until either 
-         * a pin activity occurs or a specified time has elapsed.
+         * a pin activity occurs or a specified time has elapsed, whichever happens first
         */
         class UntilEitherClass {
         };
@@ -143,7 +142,7 @@ class LowPowerStandbyType {
 };
 
 /**
- * @brief The RTCWakeupDelay class represents a delay before waking up from a low power mode.
+ * @brief The RTCWakeupDelay class represents a delay before waking up from Standby Mode.
 */
 class RTCWakeupDelay {
     public:
@@ -188,9 +187,9 @@ class RTCWakeupDelay {
  * 
  * The LowPowerPortentaH7 class allows the microcontroller on the Portenta H7 board
  * to enter low power modes such as Standby Mode and Deep Sleep Mode. It provides
- * functions to check the current mode, prepare the option bytes for entering Standby Mode,
+ * functions to check the mode before startup, prepare the option bytes for entering Standby Mode,
  * and control the M4 and M7 cores independently. It also provides functions to measure
- * the time since boot, time spent in idle, sleep, and deep sleep modes.
+ * the time since boot, time spent in Idle, Sleep, and Deep Sleep modes.
  * 
  * This class is a singleton and shall always be accessed through the global LowPower object.
  * 
@@ -285,17 +284,6 @@ class LowPowerPortentaH7 {
         */
         LowPowerReturnCode checkOptionBytes() 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 Reset the flags that are used to determine the microcontroller's
         * previous CPU mode. This is necessary to get correct results from
@@ -320,7 +308,7 @@ class LowPowerPortentaH7 {
         LowPowerReturnCode prepareOptionBytes() const;
 
         /**
-        * @brief Make the M4 core enter Standby Mode.
+        * @brief Make the M4 core and D2 domain enter standby mode.
         * @return A constant from the LowPowerReturnCode enum.
         */
         LowPowerReturnCode standbyM4() const;
@@ -337,7 +325,7 @@ class LowPowerPortentaH7 {
         // have to be since Doxygen is configured with ENABLE_PREPROCESSING NO
         #ifdef DOXYGEN_ONLY
         /**
-        * @brief Make the M7 core enter Standby Mode.
+        * @brief Make the M7 core and D1 domain enter standby mode, and make it possible for the D3 domain to do so too.
         * @param standbyType One or a combination of LowPowerStandbyType::untilPinActivity 
         * and LowPowerStandbyType::untilTimeElapsed. The combination is done with the | operator.
         * @param args An optional delay before waking up again, if LowPowerStandbyType::untilTimeElapsed is used.
@@ -355,7 +343,7 @@ class LowPowerPortentaH7 {
         uint64_t timeSinceBoot() const;
 
         /**
-        * @brief Time spent in idle.
+        * @brief Time spent in Idle Mode.
         * @return Number of microseconds.
         */
         uint64_t timeSpentIdle() const;
@@ -371,6 +359,17 @@ class LowPowerPortentaH7 {
         * @return Number of microseconds.
         */
         uint64_t timeSpentInDeepSleep() 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;
 };
 
 /*
@@ -469,11 +468,15 @@ LowPowerPortentaH7::standbyM7(const T standbyType,
     // Standby Mode will fail. Anyone who defines that constant takes
     // responsibility for not overheating the resistors. It is NOT part of the
     // API intended for ordinary users.
-    #ifndef NO_ETHERNET_TURN_OFF
-    if (false == turnOffEthernet())
-    {
-        return LowPowerReturnCode::turningOffEthernetFailed;
-    }
+    #ifdef NO_ETHERNET_TURN_OFF
+        #warning "If you are defining NO_ETHERNET_TURN_OFF in your own sketch \
+or library, then please make sure to turn off the power \
+to the Ethernet chip before going into Standby Mode."
+    #else
+        if (false == turnOffEthernet())
+        {
+            return LowPowerReturnCode::turningOffEthernetFailed;
+        }
     #endif
 
     // Prevent Mbed from changing things
