Hibernation Mode

FprimeZephyrReference/Components/ModeManager/CMakeLists.txt

@@ -19,6 +19,7 @@ register_fprime_library(
         "${CMAKE_CURRENT_LIST_DIR}/ModeManager.fpp"
     SOURCES
         "${CMAKE_CURRENT_LIST_DIR}/ModeManager.cpp"
+        "${CMAKE_CURRENT_LIST_DIR}/PicoSleep.cpp"
 #   DEPENDS
 #       MyPackage_MyOtherModule
 )

FprimeZephyrReference/Components/ModeManager/ModeManager.fpp

@@ -2,8 +2,10 @@ module Components {
 
     @ System mode enumeration
     enum SystemMode {
-        NORMAL = 0 @< Normal operational mode
+        HIBERNATION_MODE = 0 @< Ultra-low-power hibernation with periodic wake windows
         SAFE_MODE = 1 @< Safe mode with non-critical components powered off
+        NORMAL = 2 @< Normal operational mode
+        PAYLOAD_MODE = 3 @< Payload mode with payload power and battery enabled
     }
 
     @ Port for notifying about mode changes
@@ -57,6 +59,28 @@ module Components {
         @ Only succeeds if currently in safe mode
         sync command EXIT_SAFE_MODE()
 
+        @ Command to enter payload mode
+        @ Only succeeds if currently in normal mode
+        sync command ENTER_PAYLOAD_MODE()
+
+        @ Command to exit payload mode
+        @ Only succeeds if currently in payload mode
+        sync command EXIT_PAYLOAD_MODE()
+
+        @ Command to enter hibernation mode (only from SAFE_MODE)
+        @ Uses RP2350 dormant mode with RTC alarm wake
+        @ sleepDurationSec: Duration of each sleep cycle in seconds (default 3600 = 60 min)
+        @ wakeDurationSec: Duration of each wake window in seconds (default 60 = 1 min)
+        sync command ENTER_HIBERNATION(
+            sleepDurationSec: U32 @< Sleep cycle duration in seconds (0 = default 3600)
+            wakeDurationSec: U32 @< Wake window duration in seconds (0 = default 60)
+        )
+
+        @ Command to exit hibernation mode
+        @ Only succeeds if currently in hibernation mode wake window
+        @ Transitions to SAFE_MODE
+        sync command EXIT_HIBERNATION()
+
         # ----------------------------------------------------------------------
         # Events
         # ----------------------------------------------------------------------
@@ -83,6 +107,22 @@ module Components {
             severity warning high \
             format "External fault detected - external component forced safe mode"
 
+        @ Event emitted when entering payload mode
+        event EnteringPayloadMode(
+            reason: string size 100 @< Reason for entering payload mode
+        ) \
+            severity activity high \
+            format "ENTERING PAYLOAD MODE: {}"
+
+        @ Event emitted when exiting payload mode
+        event ExitingPayloadMode() \
+            severity activity high \
+            format "Exiting payload mode"
+
+        @ Event emitted when payload mode is manually commanded
+        event ManualPayloadModeEntry() \
+            severity activity high \
+            format "Payload mode entry commanded manually"
 
         @ Event emitted when command validation fails
         event CommandValidationFailed(
@@ -100,6 +140,55 @@ module Components {
             severity warning low \
             format "State persistence {} failed with status {}"
 
+        @ Event emitted when entering hibernation mode
+        event EnteringHibernation(
+            reason: string size 100 @< Reason for entering hibernation
+            sleepDurationSec: U32 @< Sleep cycle duration in seconds
+            wakeDurationSec: U32 @< Wake window duration in seconds
+        ) \
+            severity warning high \
+            format "ENTERING HIBERNATION: {} (sleep={}s, wake={}s)"
+
+        @ Event emitted when exiting hibernation mode
+        event ExitingHibernation(
+            cycleCount: U32 @< Total hibernation cycles completed
+            totalSeconds: U32 @< Total time spent in hibernation
+        ) \
+            severity activity high \
+            format "Exiting hibernation after {} cycles ({}s total)"
+
+        @ Event emitted when hibernation wake window starts
+        event HibernationWakeWindow(
+            cycleNumber: U32 @< Current wake cycle number
+        ) \
+            severity activity low \
+            format "Hibernation wake window #{}"
+
+        @ Event emitted when starting a new hibernation sleep cycle
+        event HibernationSleepCycle(
+            cycleNumber: U32 @< Sleep cycle number starting
+        ) \
+            severity activity low \
+            format "Hibernation sleep cycle #{} starting"
+
+        @ Event emitted when hibernation dormant sleep entry fails
+        @ CRITICAL: Ground already received OK response before this failure
+        @ Mode reverts to SAFE_MODE, counters are rolled back
+        event HibernationEntryFailed(
+            reason: string size 100 @< Reason for failure
+        ) \
+            severity warning high \
+            format "HIBERNATION ENTRY FAILED (command ack'd OK but dormant failed): {}"
+
+        @ Event emitted when state restoration fails on boot
+        @ CRITICAL: System defaults to SAFE_MODE to maintain conservative power profile
+        @ This prevents violating power constraints if system was in hibernation
+        event StateRestorationFailed(
+            reason: string size 100 @< Description of the failure
+        ) \
+            severity warning high \
+            format "STATE RESTORATION FAILED - defaulting to SAFE_MODE: {}"
+
         # ----------------------------------------------------------------------
         # Telemetry
         # ----------------------------------------------------------------------
@@ -110,6 +199,15 @@ module Components {
         @ Number of times safe mode has been entered
         telemetry SafeModeEntryCount: U32
 
+        @ Number of times payload mode has been entered
+        telemetry PayloadModeEntryCount: U32
+
+        @ Number of hibernation sleep/wake cycles completed
+        telemetry HibernationCycleCount: U32
+
+        @ Total time spent in hibernation (seconds)
+        telemetry HibernationTotalSeconds: U32
+
 
         ###############################################################################
         # Standard AC Ports: Required for Channels, Events, Commands, and Parameters  #

FprimeZephyrReference/Components/ModeManager/ModeManager.hpp

@@ -70,6 +70,28 @@ class ModeManager : public ModeManagerComponentBase {
                                    U32 cmdSeq            //!< The command sequence number
                                    ) override;
 
+    //! Handler implementation for command ENTER_PAYLOAD_MODE
+    void ENTER_PAYLOAD_MODE_cmdHandler(FwOpcodeType opCode,  //!< The opcode
+                                       U32 cmdSeq            //!< The command sequence number
+                                       ) override;
+
+    //! Handler implementation for command EXIT_PAYLOAD_MODE
+    void EXIT_PAYLOAD_MODE_cmdHandler(FwOpcodeType opCode,  //!< The opcode
+                                      U32 cmdSeq            //!< The command sequence number
+                                      ) override;
+
+    //! Handler implementation for command ENTER_HIBERNATION
+    void ENTER_HIBERNATION_cmdHandler(FwOpcodeType opCode,   //!< The opcode
+                                      U32 cmdSeq,            //!< The command sequence number
+                                      U32 sleepDurationSec,  //!< Sleep cycle duration in seconds
+                                      U32 wakeDurationSec    //!< Wake window duration in seconds
+                                      ) override;
+
+    //! Handler implementation for command EXIT_HIBERNATION
+    void EXIT_HIBERNATION_cmdHandler(FwOpcodeType opCode,  //!< The opcode
+                                     U32 cmdSeq            //!< The command sequence number
+                                     ) override;
+
   private:
     // ----------------------------------------------------------------------
     // Private helper methods
@@ -87,9 +109,21 @@ class ModeManager : public ModeManagerComponentBase {
     //! Exit safe mode
     void exitSafeMode();
 
+    //! Enter payload mode with optional reason override
+    void enterPayloadMode(const char* reason = nullptr);
+
+    //! Exit payload mode
+    void exitPayloadMode();
+
     //! Turn off non-critical components
     void turnOffNonCriticalComponents();
 
+    //! Turn on payload (load switches 6 & 7)
+    void turnOnPayload();
+
+    //! Turn off payload (load switches 6 & 7)
+    void turnOffPayload();
+
     //! Turn on components (restore normal operation)
     void turnOnComponents();
 
@@ -99,26 +133,63 @@ class ModeManager : public ModeManagerComponentBase {
     //! \return Current voltage (only valid if valid parameter is set to true)
     F32 getCurrentVoltage(bool& valid);
 
+    //! Enter hibernation mode with configurable durations
+    //! \param sleepDurationSec Duration of each sleep cycle in seconds
+    //! \param wakeDurationSec Duration of each wake window in seconds
+    //! \param reason Reason for entering hibernation
+    void enterHibernation(U32 sleepDurationSec, U32 wakeDurationSec, const char* reason = nullptr);
+
+    //! Exit hibernation mode (transitions to SAFE_MODE)
+    void exitHibernation();
+
+    //! Enter dormant sleep (calls PicoSleep, does not return on success)
+    void enterDormantSleep();
+
+    //! Start wake window after dormant wake
+    void startWakeWindow();
+
+    //! Handle wake window tick (called from run_handler at 1Hz)
+    void handleWakeWindowTick();
+
     // ----------------------------------------------------------------------
     // Private enums and types
     // ----------------------------------------------------------------------
 
     //! System mode enumeration
-    enum class SystemMode : U8 { NORMAL = 0, SAFE_MODE = 1 };
+    enum class SystemMode : U8 {
+        HIBERNATION_MODE = 0,  //!< Ultra-low-power hibernation with periodic wake windows
+        SAFE_MODE = 1,         //!< Safe mode with non-critical components powered off
+        NORMAL = 2,            //!< Normal operational mode
+        PAYLOAD_MODE = 3       //!< Payload mode with payload power and battery enabled
+    };
 
-    //! Persistent state structure
+    //! Persistent state structure (version 2 with hibernation support)
     struct PersistentState {
-        U8 mode;                 //!< Current mode (SystemMode)
-        U32 safeModeEntryCount;  //!< Number of times safe mode entered
+        U8 mode;                      //!< Current mode (SystemMode)
+        U32 safeModeEntryCount;       //!< Number of times safe mode entered
+        U32 payloadModeEntryCount;    //!< Number of times payload mode entered
+        U32 hibernationCycleCount;    //!< Number of hibernation sleep/wake cycles
+        U32 hibernationTotalSeconds;  //!< Total time spent in hibernation (seconds)
+        U32 sleepDurationSec;         //!< Configured sleep cycle duration (for resume)
+        U32 wakeDurationSec;          //!< Configured wake window duration (for resume)
     };
 
     // ----------------------------------------------------------------------
     // Private member variables
     // ----------------------------------------------------------------------
 
-    SystemMode m_mode;         //!< Current system mode
-    U32 m_safeModeEntryCount;  //!< Counter for safe mode entries
-    U32 m_runCounter;          //!< Counter for run handler calls (1Hz)
+    SystemMode m_mode;            //!< Current system mode
+    U32 m_safeModeEntryCount;     //!< Counter for safe mode entries
+    U32 m_payloadModeEntryCount;  //!< Counter for payload mode entries
+    U32 m_runCounter;             //!< Counter for run handler calls (1Hz)
+
+    // Hibernation state variables
+    bool m_inHibernationWakeWindow;  //!< True if currently in wake window
+    U32 m_wakeWindowCounter;         //!< Seconds elapsed in current wake window
+    U32 m_hibernationCycleCount;     //!< Total hibernation cycles completed
+    U32 m_hibernationTotalSeconds;   //!< Total seconds spent in hibernation
+    U32 m_sleepDurationSec;          //!< Configured sleep cycle duration
+    U32 m_wakeDurationSec;           //!< Configured wake window duration
 
     static constexpr const char* STATE_FILE_PATH = "/mode_state.bin";  //!< State file path
 };