Documentation improvements plus Ethernet turn-off fix

docs/api.md

@@ -28,7 +28,7 @@ This class is specific to the Portenta H7 board.
 | [`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_1a1eb5cec6e9604a48074f1c10ef5e7fb0) | Make the M7 core enter Standby Mode. |
+| [`standbyM7`](#class_low_power_portenta_h7_1aa9c1cb86c832c35f6653a3d6c9f0d32f) | 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 being in Standby Mode) or power-on depending on what happened last. |
 | [`timeSpentIdle`](#class_low_power_portenta_h7_1ad42fdfa6885d8e0fdca5aa012fdb4c60) | Time spent in idle. |
 | [`timeSpentInSleep`](#class_low_power_portenta_h7_1a994eb6fcc0382515a82b81fa37ca9f3c) | Time spent in Sleep Mode. |
@@ -130,18 +130,18 @@ Make the M4 core enter Standby Mode.
 A constant from the LowPowerReturnCode enum.
 <hr />
 
-### `standbyM7` <a id="class_low_power_portenta_h7_1a1eb5cec6e9604a48074f1c10ef5e7fb0" class="anchor"></a>
+### `standbyM7` <a id="class_low_power_portenta_h7_1aa9c1cb86c832c35f6653a3d6c9f0d32f" class="anchor"></a>
 
 ```cpp
-template<> std::enable_if< ArgumentsAreCorrect< T, Args... >::value, LowPowerReturnCode >::type standbyM7(const T standbyType, const Args... args) const
+LowPowerReturnCode standbyM7(const T standbyType, const Args... args) const
 ```
 
 Make the M7 core enter Standby Mode.
 
 #### 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. 
 
-* `args` The delay before waking up again 
+* `args` An optional delay before waking up again, if [LowPowerStandbyType::untilTimeElapsed](#class_low_power_standby_type_1aa4882e571c0e9444c5978c8520e8e90e) is used. 
 
 #### Returns
 A constant from the LowPowerReturnCode enum.

examples/Standby/Standby.ino

@@ -127,8 +127,13 @@ void setup() {
 
 #if defined CORE_CM7
   LowPower.standbyM7(LowPowerStandbyType::untilPinActivity | LowPowerStandbyType::untilTimeElapsed, 10_s);
-  // The following is an alternative way to go into standby for 10 seconds
+  //
+  // The following is an alternative way to go into Standby Mode for 10 seconds:
   // LowPower.standbyM7(LowPowerStandbyType::untilTimeElapsed, RTCWakeupDelay(0, 0, 10));
+  //
+  // The following is how to go to into Standby Mode waiting only for a wakeup pin:
+  // LowPower.standbyM7(LowPowerStandbyType::untilPinActivity);
+  //
 #else
   LowPower.standbyM4();
 #endif

src/Arduino_LowPowerPortentaH7.cpp

@@ -233,7 +233,7 @@ bool LowPowerPortentaH7::wasInCPUMode(CPUMode mode) const
 
 void LowPowerPortentaH7::resetPreviousCPUModeFlags() const
 {
-    PWR->CPUCR |= PWR_CPUCR_CSSF; // Clear standby flags
+    PWR->CPUCR |= PWR_CPUCR_CSSF;
 }
 
 uint16_t LowPowerPortentaH7::numberOfDeepSleepLocks() const
@@ -312,7 +312,7 @@ LowPowerReturnCode LowPowerPortentaH7::standbyM4() const
     // <--
 
     // Disable and clear all pending interrupts in the NVIC. There are 8
-    // registers in the Cortex-M7.
+    // registers in the Cortex-M4.
     for (auto i = 0; i < 8; i++)
     {
         NVIC->ICER[i] = 0xffffffff;

src/Arduino_LowPowerPortentaH7.h

@@ -312,7 +312,7 @@ class LowPowerPortentaH7 {
         */
        [[deprecated("This function is experimental and should not be used in production code")]]
         uint16_t numberOfDeepSleepLocks() const;
-        
+
         /**
         * @brief Prepare the option bytes for entry into Standby Mode.
         * @return A constant from the LowPowerReturnCode enum.
@@ -325,18 +325,27 @@ class LowPowerPortentaH7 {
         */
         LowPowerReturnCode standbyM4() const;
 
+        // This is the variant that the compiler will see and use
+        /// @cond DEV
+        template<typename T, typename... Args>
+        typename std::enable_if<ArgumentsAreCorrect<T, Args...>::value,
+                 LowPowerReturnCode>::type
+        standbyM7(const T standbyType, const Args... args) const;
+        /// @endcond
+        // This is the simplified variant that Doxygen will see and use
+        // Notice that DOXYGEN_ONLY isn't defined anywhere - it doesn't
+        // have to be since Doxygen is configured with ENABLE_PREPROCESSING NO
+        #ifdef DOXYGEN_ONLY
         /**
         * @brief Make the M7 core enter Standby Mode.
         * @param standbyType One or a combination of LowPowerStandbyType::untilPinActivity 
         * and LowPowerStandbyType::untilTimeElapsed. The combination is done with the | operator.
-        * @param args The delay before waking up again
+        * @param args An optional delay before waking up again, if LowPowerStandbyType::untilTimeElapsed is used.
         * @return A constant from the LowPowerReturnCode enum.
         */
-        template<typename T, typename... Args>
-        typename std::enable_if<ArgumentsAreCorrect<T, Args...>::value,
-                 LowPowerReturnCode>::type
-        standbyM7(const T standbyType, const Args... args) const;
-
+        LowPowerReturnCode standbyM7(const T standbyType, const Args... args) const;
+        #endif
+
         /**
         * @brief Time since the board was booted.
         * It reports the time since the last wake-up reset (after being in Standby Mode) 
@@ -436,6 +445,7 @@ LowPowerStandbyType::UntilEitherClass operator|(
 ********************************************************************************
 */
 
+/// @cond DEV
 template<typename T, typename... Args>
 typename std::enable_if<LowPowerPortentaH7::ArgumentsAreCorrect<T, Args...>::value,
                         LowPowerReturnCode>::type
@@ -453,11 +463,18 @@ LowPowerPortentaH7::standbyM7(const T standbyType,
     // otherwise, the Ethernet transmit termination resistors will overheat
     // from the voltage that gets applied over them. It would be 125 mW in each
     // of them, while they are rated at 50 mW. If we fail to turn off Ethernet,
-    // we must not proceed.
+    // we must not proceed. If this library is used with another library that
+    // turns off the rail that powers the Ethernet chip before calling this
+    // function, that library should #define NO_ETHERNET_TURN_OFF, or entering
+    // 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;
     }
+    #endif
 
     // Prevent Mbed from changing things
     core_util_critical_section_enter();
@@ -687,5 +704,6 @@ LowPowerPortentaH7::standbyM7(const T standbyType,
 
     return LowPowerReturnCode::m7StandbyFailed;
 }
+/// @endcond
 
 #endif  // End of header guard