Refactorings

Author: sebromero

examples/DeepSleep_WakeFromPin/DeepSleep_WakeFromPin.ino

@@ -45,7 +45,7 @@ void loop() {
         sleepFlag = false;
 
         //board.setAllPeripheralsPower(false);
-        board.deepSleepUntilWakeupEvent();
+        board.standByUntilWakeupEvent();
     } else {
 
         digitalWrite(LEDB, HIGH);

examples/DeepSleep_WakeFromRTC_C33/DeepSleep_WakeFromRTC_C33.ino

@@ -37,6 +37,6 @@ void setup() {
 
 void loop(){
     //board.setAllPeripheralsPower(false);
-    board.deepSleepUntilWakeupEvent();
+    board.standByUntilWakeupEvent();
 }
 

examples/DeepSleep_WakeFromRTC_H7/DeepSleep_WakeFromRTC_H7.ino

@@ -16,7 +16,7 @@ void setup() {
     pinMode(LEDB, OUTPUT);
     digitalWrite(LEDB, LOW);
     board.setAllPeripheralsPower(false);
-    board.deepSleepUntilWakeupEvent();
+    board.standByUntilWakeupEvent();
 }
 
 void loop() {

src/Board.cpp

@@ -1,6 +1,8 @@
 #include "Board.h"
 #include <map>
 
+constexpr int UNKNOWN_VALUE = 0xFF;
+
 std::map<float, Ldo2Voltage> ldo2VoltageMap = {
     {1.80f, Ldo2Voltage::V_1_80},
     {1.90f, Ldo2Voltage::V_1_90},
@@ -43,20 +45,20 @@ std::map<float, Sw2Voltage> sw2VoltageMap = {
 };
 
 Board::Board() {
- #if defined(ARDUINO_PORTENTA_C33)
-        this -> lowPower = new LowPower();
-    #elif defined(ARDUINO_PORTENTA_H7_M7) || defined(ARDUINO_NICLA_VISION)
-        if (CM7_CPUID == HAL_GetCurrentCPUID())
-        {
+    #if defined(ARDUINO_PORTENTA_C33)
+        this->lowPower = new LowPower();
+    #endif
+}
+
+bool Board::begin() {
+    #if defined(ARDUINO_PORTENTA_H7_M7) || defined(ARDUINO_NICLA_VISION)
+        if (CM7_CPUID == HAL_GetCurrentCPUID()){
             if (LowPowerReturnCode::success != LowPower.checkOptionBytes()){
                 LowPower.prepareOptionBytes();
             }
             bootM4();
         }
     #endif 
-}
-
-bool Board::begin() {
     return PMIC.begin() == 0;
 }
 
@@ -80,19 +82,19 @@ void Board::setExternalPowerEnabled(bool on) {
 
 bool Board::setExternalVoltage(float voltage) {
         this -> setExternalPowerEnabled(false);
-        uint8_t voltageRegisterValue = getRailVoltage(voltage, 4);
+        uint8_t targetVoltage = getRailVoltageEnum(voltage, CONTEXT_SW2);
 
-        if (voltageRegisterValue == EMPTY_REGISTER){                    
+        if (targetVoltage == UNKNOWN_VALUE){                    
             return false;
         }
 
-        PMIC.writePMICreg(Register::PMIC_SW2_VOLT, voltageRegisterValue);
-        if(PMIC.readPMICreg(Register::PMIC_SW2_VOLT) == voltageRegisterValue){
+        PMIC.writePMICreg(Register::PMIC_SW2_VOLT, targetVoltage);
+        if(PMIC.readPMICreg(Register::PMIC_SW2_VOLT) == targetVoltage){
             this -> setExternalPowerEnabled(true);
             return true;
-        } else {
-            return false;
         }
+ 
+        return false;
 }
 
 void Board::setCameraPowerEnabled(bool on) {
@@ -106,8 +108,6 @@ void Board::setCameraPowerEnabled(bool on) {
             PMIC.getControl()->turnLDO2Off(Ldo2Mode::Normal);
             PMIC.getControl()->turnLDO3Off(Ldo3Mode::Normal);
         }
-    #else 
-        #warning "This feature is currently only supported on the Nicla Vision Board"
     #endif
 }
 
@@ -192,7 +192,7 @@ void Board::sleepUntilWakeupEvent(){
 }
 #endif
 
-void Board::deepSleepUntilWakeupEvent(){
+void Board::standByUntilWakeupEvent(){
     #if defined(ARDUINO_PORTENTA_C33)
         lowPower -> deepSleep();
     #elif defined(ARDUINO_PORTENTA_H7_M7) || defined(ARDUINO_PORTENTA_H7_M4) || defined(ARDUINO_NICLA_VISION)
@@ -263,6 +263,7 @@ void Board::setAnalogDigitalConverterPower(bool on){
 #endif
 
 void Board::setCommunicationPeripheralsPower(bool on){
+    // TODO: Why do we only use the normal mode here?
     if(on)
         PMIC.getControl()->turnSw1On(Sw1Mode::Normal);
     else
@@ -271,19 +272,19 @@ void Board::setCommunicationPeripheralsPower(bool on){
 
 
 bool Board::setReferenceVoltage(float voltage) {
-    uint8_t voltageRegisterValue = getRailVoltage(voltage, CONTEXT_LDO2);
+    uint8_t voltageRegisterValue = getRailVoltageEnum(voltage, CONTEXT_LDO2);
 
     // If voltageRegisterValue is not empty, write it to the PMIC register 
     // and return the result of the comparison directly.
-    if (voltageRegisterValue != EMPTY_REGISTER) {
+    if (voltageRegisterValue != UNKNOWN_VALUE) {
         PMIC.writePMICreg(Register::PMIC_LDO2_VOLT, voltageRegisterValue);
         return (PMIC.readPMICreg(Register::PMIC_LDO2_VOLT) == voltageRegisterValue);
     }
 
     return false;
 }
 
- uint8_t Board::getRailVoltage(float voltage, int context) {
+ uint8_t Board::getRailVoltageEnum(float voltage, int context) {
     switch (context) {
         case CONTEXT_LDO2:
             if (ldo2VoltageMap.find(voltage) != ldo2VoltageMap.end()) {
@@ -304,10 +305,9 @@ bool Board::setReferenceVoltage(float voltage) {
             break;
 
         default:
-            return EMPTY_REGISTER;
-            break;
+            return UNKNOWN_VALUE;
     }
 
 
-    return EMPTY_REGISTER;
+    return UNKNOWN_VALUE;
 }

src/Board.h

@@ -13,16 +13,15 @@
     #include "Arduino_LowPowerPortentaH7.h"
 #endif 
 
-#define CONTEXT_LDO2 2
-#define CONTEXT_SW1 3 
-#define CONTEXT_SW2 4 
+#define CONTEXT_LDO2 2 // LDO regulator: 1.8 V to 3.3 V, 400 mA
+#define CONTEXT_SW1 3 // Buck converter: 1.0 A; 0.6 V to 1.3875 V 
+#define CONTEXT_SW2 4 // Buck converter: 1.0 A; 0.6 V to 1.3875 V
 
 enum class StandbyType : uint8_t {
     none = 0,
     untilPinActivity = 1,
     untilTimeElapsed = 2,
     untilEither = 3
-
 };
 
 inline constexpr StandbyType operator|(StandbyType x, StandbyType y){
@@ -33,8 +32,6 @@ inline constexpr StandbyType operator|=(StandbyType& x, StandbyType y){
     return x = x | y;
 }
 
-constexpr int EMPTY_REGISTER = 0xFF;
-
 /**
  * @brief Represents a board with power management capabilities.
  * 
@@ -185,7 +182,7 @@ class Board {
          * A wakeup event can be an interrupt on a pin or the RTC, 
          * depending on what you set with enableWakeupFromPin() and enableWakeupFromRTC().
          */
-        void sleepUntilWakeupEvent();
+        void standByUntilWakeupEvent();
         #endif
 
         // TODO Same as above
@@ -197,15 +194,14 @@ class Board {
          * A wakeup event can be an interrupt on a pin or the RTC, depending on what 
          * you set with enableWakeupFromPin() and enableWakeupFromRTC().
          */
-        void deepSleepUntilWakeupEvent();
+        void standByUntilWakeupEvent();
 
         /**
          * @brief Toggle the peripherals' power on Portenta C33 (ADC, RGB LED, Secure Element, Wifi and Bluetooth).
          * @param on True to turn on the power, false to turn it off.
         */
         void setAllPeripheralsPower(bool on);
 
-
         /**
          * @brief Toggles the communication peripherials' power on Portenta C33 (Wifi, Bluetooth and Secure Element)
          * @param on True to turn on the power, false to turn it off.
@@ -221,7 +217,7 @@ class Board {
 
         #endif
         /**
-         * @brief Set the reference voltage on Portenta C33. This value is used by the ADC to convert analog values to digital values.
+         * @brief Set the reference voltage. This value is used by the ADC to convert analog values to digital values.
          * This can be particularly useful to increase the accuracy of the ADC when working with low voltages
          * @param voltage Reference voltage value in volts. It can be anything between 1.80V and 3.30V in steps of 0.10V. 
          * Any value outside this range or with different steps will not be accepted by the library.
@@ -232,7 +228,10 @@ class Board {
         // TODO add function to shut down the fuel gauge / and hibernate mode
 
     private:
-        static uint8_t getRailVoltage(float voltage, int context);
+        /**
+        * Convert a numeric voltage value to the corresponding enum value for the PMIC library.
+        */
+        static uint8_t getRailVoltageEnum(float voltage, int context);
 
         #if defined(ARDUINO_PORTENTA_C33)
             LowPower * lowPower;