change mode enum values

Author: yudataguy

FprimeZephyrReference/Components/ModeManager/ModeManager.cpp

@@ -45,13 +45,14 @@ void ModeManager ::run_handler(FwIndexType portNum, U32 context) {
 
 void ModeManager ::forceSafeMode_handler(FwIndexType portNum) {
     // Force entry into safe mode (called by other components)
-    // Provides immediate safe mode entry for critical component-detected faults
+    // Only allowed from NORMAL (sequential +1/-1 transitions)
     this->log_WARNING_HI_ExternalFaultDetected();
 
-    // Allow safe mode entry from NORMAL or PAYLOAD_MODE (emergency override)
-    if (this->m_mode == SystemMode::NORMAL || this->m_mode == SystemMode::PAYLOAD_MODE) {
+    // Only enter safe mode from NORMAL - payload mode must be exited first
+    if (this->m_mode == SystemMode::NORMAL) {
         this->enterSafeMode("External component request");
     }
+    // Note: Request ignored if in PAYLOAD_MODE or already in SAFE_MODE
 }
 
 Components::SystemMode ModeManager ::getMode_handler(FwIndexType portNum) {
@@ -65,14 +66,26 @@ Components::SystemMode ModeManager ::getMode_handler(FwIndexType portNum) {
 // ----------------------------------------------------------------------
 
 void ModeManager ::FORCE_SAFE_MODE_cmdHandler(FwOpcodeType opCode, U32 cmdSeq) {
-    // Force entry into safe mode
-    this->log_ACTIVITY_HI_ManualSafeModeEntry();
+    // Force entry into safe mode - only allowed from NORMAL (sequential +1/-1 transitions)
 
-    // Allow safe mode entry from NORMAL or PAYLOAD_MODE (emergency override)
-    if (this->m_mode == SystemMode::NORMAL || this->m_mode == SystemMode::PAYLOAD_MODE) {
-        this->enterSafeMode("Ground command");
+    // Reject if in payload mode - must exit payload mode first
+    if (this->m_mode == SystemMode::PAYLOAD_MODE) {
+        Fw::LogStringArg cmdNameStr("FORCE_SAFE_MODE");
+        Fw::LogStringArg reasonStr("Must exit payload mode first");
+        this->log_WARNING_LO_CommandValidationFailed(cmdNameStr, reasonStr);
+        this->cmdResponse_out(opCode, cmdSeq, Fw::CmdResponse::VALIDATION_ERROR);
+        return;
     }
 
+    // Already in safe mode - idempotent success
+    if (this->m_mode == SystemMode::SAFE_MODE) {
+        this->cmdResponse_out(opCode, cmdSeq, Fw::CmdResponse::OK);
+        return;
+    }
+
+    // Enter safe mode from NORMAL
+    this->log_ACTIVITY_HI_ManualSafeModeEntry();
+    this->enterSafeMode("Ground command");
     this->cmdResponse_out(opCode, cmdSeq, Fw::CmdResponse::OK);
 }
 
@@ -150,8 +163,9 @@ void ModeManager ::loadState() {
         status = file.read(reinterpret_cast<U8*>(&state), bytesRead, Os::File::WaitType::WAIT);
 
         if (status == Os::File::OP_OK && bytesRead == sizeof(PersistentState)) {
-            // Validate state data before restoring
-            if (state.mode <= static_cast<U8>(SystemMode::PAYLOAD_MODE)) {
+            // Validate state data before restoring (valid range: 1-3 for SAFE, NORMAL, PAYLOAD)
+            if (state.mode >= static_cast<U8>(SystemMode::SAFE_MODE) &&
+                state.mode <= static_cast<U8>(SystemMode::PAYLOAD_MODE)) {
                 // Valid mode value - restore state
                 this->m_mode = static_cast<SystemMode>(state.mode);
                 this->m_safeModeEntryCount = state.safeModeEntryCount;

FprimeZephyrReference/Components/ModeManager/ModeManager.fpp

@@ -1,10 +1,10 @@
 module Components {
 
-    @ System mode enumeration
+    @ System mode enumeration (values ordered for +1/-1 sequential transitions)
     enum SystemMode {
-        NORMAL = 0 @< Normal operational mode
         SAFE_MODE = 1 @< Safe mode with non-critical components powered off
-        PAYLOAD_MODE = 2 @< Payload mode with payload power and battery enabled
+        NORMAL = 2 @< Normal operational mode
+        PAYLOAD_MODE = 3 @< Payload mode with payload power and battery enabled
     }
 
     @ Port for notifying about mode changes

FprimeZephyrReference/Components/ModeManager/ModeManager.hpp

@@ -125,8 +125,8 @@ class ModeManager : public ModeManagerComponentBase {
     // Private enums and types
     // ----------------------------------------------------------------------
 
-    //! System mode enumeration
-    enum class SystemMode : U8 { NORMAL = 0, SAFE_MODE = 1, PAYLOAD_MODE = 2 };
+    //! System mode enumeration (values ordered for +1/-1 sequential transitions)
+    enum class SystemMode : U8 { SAFE_MODE = 1, NORMAL = 2, PAYLOAD_MODE = 3 };
 
     //! Persistent state structure
     struct PersistentState {

FprimeZephyrReference/Components/ModeManager/docs/sdd.md

@@ -24,7 +24,7 @@ Future work: a HIBERNATION mode remains planned; it will follow the same persist
 | MM0016 | The ModeManager shall turn on payload load switches (indices 6 and 7) when entering payload mode and turn them off when exiting payload mode | Integration Testing |
 | MM0017 | The ModeManager shall track and report the number of times payload mode has been entered | Integration Testing |
 | MM0018 | The ModeManager shall persist payload mode state and payload mode entry count to non-volatile storage and restore them on initialization | Integration Testing |
-| MM0019 | The ModeManager shall allow FORCE_SAFE_MODE to override payload mode and transition to safe mode | Integration Testing |
+| MM0019 | The ModeManager shall reject FORCE_SAFE_MODE from payload mode (must exit payload mode first for sequential transitions) | Integration Testing |
 
 ## Usage Examples
 
@@ -44,7 +44,7 @@ The ModeManager component operates as an active component that manages system-wi
    - Keeps payload load switches (indices 6 and 7) off unless payload mode is explicitly entered
 
 3. **Safe Mode Entry**
-   - Can be triggered by:
+   - Can be triggered by (only from NORMAL mode - sequential transitions enforced):
      - Ground command: `FORCE_SAFE_MODE`
      - External component request via `forceSafeMode` port
    - Actions performed:
@@ -130,9 +130,9 @@ classDiagram
         }
         class SystemMode {
             <<enumeration>>
-            NORMAL = 0
             SAFE_MODE = 1
-            PAYLOAD_MODE = 2
+            NORMAL = 2
+            PAYLOAD_MODE = 3
         }
     }
     ModeManagerComponentBase <|-- ModeManager : inherits
@@ -304,7 +304,7 @@ sequenceDiagram
 
 | Name | Arguments | Description |
 |---|---|---|
-| FORCE_SAFE_MODE | None | Forces the system into safe mode immediately. Emits ManualSafeModeEntry event. Can be called from any mode (idempotent). |
+| FORCE_SAFE_MODE | None | Forces the system into safe mode. Only allowed from NORMAL mode (rejects from PAYLOAD_MODE with validation error). Emits ManualSafeModeEntry event. Idempotent when already in safe mode. |
 | EXIT_SAFE_MODE | None | Exits safe mode and returns to normal operation. Fails with CommandValidationFailed if not currently in safe mode. |
 | ENTER_PAYLOAD_MODE | None | Enters payload mode from NORMAL. Fails with CommandValidationFailed if issued from SAFE_MODE or if already in payload mode (idempotent success when already in payload). Emits ManualPayloadModeEntry event. |
 | EXIT_PAYLOAD_MODE | None | Exits payload mode and returns to normal operation. Fails with CommandValidationFailed if not currently in payload mode. |
@@ -327,7 +327,7 @@ sequenceDiagram
 
 | Name | Type | Update Rate | Description |
 |---|---|---|---|
-| CurrentMode | U8 | 1Hz | Current system mode (0 = NORMAL, 1 = SAFE_MODE, 2 = PAYLOAD_MODE) |
+| CurrentMode | U8 | 1Hz | Current system mode (1 = SAFE_MODE, 2 = NORMAL, 3 = PAYLOAD_MODE) |
 | SafeModeEntryCount | U32 | On change | Number of times safe mode has been entered (persists across reboots) |
 | PayloadModeEntryCount | U32 | On change | Number of times payload mode has been entered (persists across reboots) |
 
@@ -360,7 +360,7 @@ See `FprimeZephyrReference/test/int/mode_manager_test.py` and `FprimeZephyrRefer
 | test_19_safe_mode_state_persists | Verifies safe mode persistence to flash | State persistence |
 | test_payload_01_enter_exit_payload_mode | Validates payload mode entry/exit, events, telemetry, payload load switches | Payload mode entry/exit |
 | test_payload_02_cannot_enter_from_safe_mode | Ensures ENTER_PAYLOAD_MODE fails from SAFE_MODE | Command validation |
-| test_payload_03_safe_mode_override_from_payload | Ensures FORCE_SAFE_MODE overrides payload mode | Emergency override |
+| test_payload_03_safe_mode_rejected_from_payload | Ensures FORCE_SAFE_MODE is rejected from payload mode (sequential transitions) | Command validation |
 | test_payload_04_state_persists | Verifies payload mode and counters persist | Payload persistence |
 
 ## Design Decisions
@@ -388,12 +388,13 @@ Mode state is persisted to `/mode_state.bin` to maintain operational context acr
 
 This ensures the system resumes in the correct mode after recovery.
 
-### Idempotent Safe Mode Entry
-The FORCE_SAFE_MODE command can be called from any mode without error. If already in safe mode, it succeeds without re-entering. This simplifies fault handling logic in external components.
+### Sequential Mode Transitions
+Mode transitions follow a +1/-1 sequential pattern: SAFE_MODE(1) ↔ NORMAL(2) ↔ PAYLOAD_MODE(3). Direct jumps (e.g., PAYLOAD→SAFE) are not allowed - users must exit payload mode first before entering safe mode. FORCE_SAFE_MODE is idempotent when already in safe mode.
 
 ## Change Log
 | Date | Description |
 |---|---|
+| 2025-11-26 | Reordered enum values (SAFE=1, NORMAL=2, PAYLOAD=3) for sequential +1/-1 transitions; FORCE_SAFE_MODE now rejected from payload mode |
 | 2025-11-26 | Removed forcePayloadMode port - payload mode now only entered via ENTER_PAYLOAD_MODE ground command |
 | 2025-11-25 | Added PAYLOAD_MODE (commands, events, telemetry, persistence, payload load switch control) and documented payload integration tests |
 | 2025-11-19 | Added getMode query port and enhanced modeChanged to carry mode value |

FprimeZephyrReference/test/int/mode_manager_test.py

@@ -11,6 +11,8 @@
 - Edge cases
 
 Total: 9 tests
+
+Mode enum values: SAFE_MODE=1, NORMAL=2, PAYLOAD_MODE=3
 """
 
 import time
@@ -87,12 +89,12 @@ def test_01_initial_telemetry(fprime_test_api: IntegrationTestAPI, start_gds):
     # Trigger telemetry update by sending Health packet (ID 1)
     proves_send_and_assert_command(fprime_test_api, "CdhCore.tlmSend.SEND_PKT", ["1"])
 
-    # Read CurrentMode telemetry (0 = NORMAL, 1 = SAFE_MODE)
+    # Read CurrentMode telemetry (1 = SAFE_MODE, 2 = NORMAL, 3 = PAYLOAD_MODE)
     mode_result: ChData = fprime_test_api.assert_telemetry(
         f"{component}.CurrentMode", start="NOW", timeout=3
     )
     current_mode = mode_result.get_val()
-    assert current_mode in [0, 1], f"Invalid mode value: {current_mode}"
+    assert current_mode in [1, 2, 3], f"Invalid mode value: {current_mode}"
 
 
 # ==============================================================================
@@ -103,13 +105,11 @@ def test_01_initial_telemetry(fprime_test_api: IntegrationTestAPI, start_gds):
 def test_04_force_safe_mode_command(fprime_test_api: IntegrationTestAPI, start_gds):
     """
     Test FORCE_SAFE_MODE command enters safe mode by checking telemetry.
+    Note: With idempotent behavior, ManualSafeModeEntry is only emitted when
+    transitioning from NORMAL, not when already in SAFE_MODE.
     """
-    # Send FORCE_SAFE_MODE command - still expect ManualSafeModeEntry for logging
-    proves_send_and_assert_command(
-        fprime_test_api,
-        f"{component}.FORCE_SAFE_MODE",
-        events=[f"{component}.ManualSafeModeEntry"],
-    )
+    # Send FORCE_SAFE_MODE command (idempotent - succeeds even if already in safe mode)
+    proves_send_and_assert_command(fprime_test_api, f"{component}.FORCE_SAFE_MODE")
 
     # Wait for mode transition (happens in 1Hz rate group)
     time.sleep(3)
@@ -201,7 +201,7 @@ def test_13_exit_safe_mode_fails_not_in_safe_mode(
         f"{component}.CurrentMode", start="NOW", timeout=3
     )
 
-    if mode_result.get_val() != 0:
+    if mode_result.get_val() != 2:
         pytest.skip("Not in NORMAL mode - cannot test this scenario")
 
     # Try to exit safe mode when not in it - should fail
@@ -219,7 +219,7 @@ def test_14_exit_safe_mode_success(fprime_test_api: IntegrationTestAPI, start_gd
     Test EXIT_SAFE_MODE succeeds.
     Verifies:
     - ExitingSafeMode event is emitted
-    - CurrentMode returns to NORMAL (0)
+    - CurrentMode returns to NORMAL (2)
     """
     # Enter safe mode
     proves_send_and_assert_command(fprime_test_api, f"{component}.FORCE_SAFE_MODE")
@@ -234,12 +234,12 @@ def test_14_exit_safe_mode_success(fprime_test_api: IntegrationTestAPI, start_gd
 
     time.sleep(2)
 
-    # Verify mode is NORMAL (0)
+    # Verify mode is NORMAL (2)
     proves_send_and_assert_command(fprime_test_api, "CdhCore.tlmSend.SEND_PKT", ["1"])
     mode_result: ChData = fprime_test_api.assert_telemetry(
         f"{component}.CurrentMode", start="NOW", timeout=3
     )
-    assert mode_result.get_val() == 0, "Should be in NORMAL mode"
+    assert mode_result.get_val() == 2, "Should be in NORMAL mode"
 
 
 # ==============================================================================
@@ -250,7 +250,7 @@ def test_14_exit_safe_mode_success(fprime_test_api: IntegrationTestAPI, start_gd
 def test_18_force_safe_mode_idempotent(fprime_test_api: IntegrationTestAPI, start_gds):
     """
     Test that calling FORCE_SAFE_MODE while already in safe mode is idempotent.
-    Should succeed and not cause issues.
+    Should succeed without emitting events (no re-entry).
     """
     # Enter safe mode first time
     proves_send_and_assert_command(fprime_test_api, f"{component}.FORCE_SAFE_MODE")
@@ -259,13 +259,8 @@ def test_18_force_safe_mode_idempotent(fprime_test_api: IntegrationTestAPI, star
     # Clear event history
     fprime_test_api.clear_histories()
 
-    # Force safe mode again - should succeed without EnteringSafeMode event
-    # But ManualSafeModeEntry event is still emitted (logging)
-    proves_send_and_assert_command(
-        fprime_test_api,
-        f"{component}.FORCE_SAFE_MODE",
-        events=[f"{component}.ManualSafeModeEntry"],
-    )
+    # Force safe mode again - should succeed silently (no events, no re-entry)
+    proves_send_and_assert_command(fprime_test_api, f"{component}.FORCE_SAFE_MODE")
 
     # Verify still in safe mode
     time.sleep(1)

FprimeZephyrReference/test/int/payload_mode_test.py

@@ -6,10 +6,12 @@
 Tests cover:
 - Payload mode entry and exit
 - Mode transition validation (cannot enter from safe mode)
-- Emergency safe mode override from payload mode
+- Sequential transitions (FORCE_SAFE_MODE rejected from payload mode)
 - State persistence
 
 Total: 4 tests
+
+Mode enum values: SAFE_MODE=1, NORMAL=2, PAYLOAD_MODE=3
 """
 
 import time
@@ -84,10 +86,10 @@ def test_payload_01_enter_exit_payload_mode(
     Test ENTER_PAYLOAD_MODE and EXIT_PAYLOAD_MODE commands.
     Verifies:
     - EnteringPayloadMode event is emitted
-    - CurrentMode telemetry = 2 (PAYLOAD_MODE)
+    - CurrentMode telemetry = 3 (PAYLOAD_MODE)
     - Payload load switches (6 & 7) are ON
     - ExitingPayloadMode event is emitted on exit
-    - CurrentMode returns to 0 (NORMAL)
+    - CurrentMode returns to 2 (NORMAL)
     """
     # Enter payload mode
     proves_send_and_assert_command(
@@ -98,12 +100,12 @@ def test_payload_01_enter_exit_payload_mode(
 
     time.sleep(2)
 
-    # Verify mode is PAYLOAD_MODE (2)
+    # Verify mode is PAYLOAD_MODE (3)
     proves_send_and_assert_command(fprime_test_api, "CdhCore.tlmSend.SEND_PKT", ["1"])
     mode_result: ChData = fprime_test_api.assert_telemetry(
         f"{component}.CurrentMode", timeout=5
     )
-    assert mode_result.get_val() == 2, "Should be in PAYLOAD_MODE"
+    assert mode_result.get_val() == 3, "Should be in PAYLOAD_MODE"
 
     # Verify payload load switches are ON
     proves_send_and_assert_command(fprime_test_api, "CdhCore.tlmSend.SEND_PKT", ["9"])
@@ -123,12 +125,12 @@ def test_payload_01_enter_exit_payload_mode(
 
     time.sleep(2)
 
-    # Verify mode is NORMAL (0)
+    # Verify mode is NORMAL (2)
     proves_send_and_assert_command(fprime_test_api, "CdhCore.tlmSend.SEND_PKT", ["1"])
     mode_result: ChData = fprime_test_api.assert_telemetry(
         f"{component}.CurrentMode", timeout=5
     )
-    assert mode_result.get_val() == 0, "Should be in NORMAL mode"
+    assert mode_result.get_val() == 2, "Should be in NORMAL mode"
 
     # Verify payload load switches are OFF in NORMAL mode
     proves_send_and_assert_command(fprime_test_api, "CdhCore.tlmSend.SEND_PKT", ["9"])
@@ -176,16 +178,16 @@ def test_payload_02_cannot_enter_from_safe_mode(
     assert mode_result.get_val() == 1, "Should still be in SAFE_MODE"
 
 
-def test_payload_03_safe_mode_override_from_payload(
+def test_payload_03_safe_mode_rejected_from_payload(
     fprime_test_api: IntegrationTestAPI, start_gds
 ):
     """
-    Test that FORCE_SAFE_MODE works from PAYLOAD_MODE (emergency override).
+    Test that FORCE_SAFE_MODE is rejected from PAYLOAD_MODE (sequential transitions).
+    Must exit payload mode first before entering safe mode.
     Verifies:
-    - Can enter safe mode from payload mode
-    - EnteringSafeMode event is emitted
-    - CurrentMode = 1 (SAFE_MODE)
-    - All load switches are OFF
+    - FORCE_SAFE_MODE fails with validation error from payload mode
+    - CommandValidationFailed event is emitted
+    - Remains in PAYLOAD_MODE (3)
     """
     # Enter payload mode first
     proves_send_and_assert_command(fprime_test_api, f"{component}.ENTER_PAYLOAD_MODE")
@@ -196,33 +198,22 @@ def test_payload_03_safe_mode_override_from_payload(
     mode_result: ChData = fprime_test_api.assert_telemetry(
         f"{component}.CurrentMode", timeout=5
     )
-    assert mode_result.get_val() == 2, "Should be in PAYLOAD_MODE"
+    assert mode_result.get_val() == 3, "Should be in PAYLOAD_MODE"
 
-    # Force safe mode (emergency override)
+    # Try to force safe mode - should fail (sequential transitions required)
     fprime_test_api.clear_histories()
-    proves_send_and_assert_command(
-        fprime_test_api,
-        f"{component}.FORCE_SAFE_MODE",
-        events=[f"{component}.ManualSafeModeEntry"],
-    )
+    with pytest.raises(Exception):
+        proves_send_and_assert_command(fprime_test_api, f"{component}.FORCE_SAFE_MODE")
 
-    time.sleep(2)
+    # Verify CommandValidationFailed event
+    fprime_test_api.assert_event(f"{component}.CommandValidationFailed", timeout=3)
 
-    # Verify mode is SAFE_MODE (1)
+    # Verify still in payload mode
     proves_send_and_assert_command(fprime_test_api, "CdhCore.tlmSend.SEND_PKT", ["1"])
     mode_result: ChData = fprime_test_api.assert_telemetry(
         f"{component}.CurrentMode", timeout=5
     )
-    assert mode_result.get_val() == 1, "Should be in SAFE_MODE"
-
-    # Verify all load switches are OFF
-    proves_send_and_assert_command(fprime_test_api, "CdhCore.tlmSend.SEND_PKT", ["9"])
-    for channel in all_load_switch_channels:
-        value = fprime_test_api.assert_telemetry(channel, timeout=5).get_val()
-        if isinstance(value, str):
-            assert value.upper() == "OFF", f"{channel} should be OFF in safe mode"
-        else:
-            assert value == 0, f"{channel} should be OFF in safe mode"
+    assert mode_result.get_val() == 3, "Should still be in PAYLOAD_MODE"
 
 
 def test_payload_04_state_persists(fprime_test_api: IntegrationTestAPI, start_gds):
@@ -234,12 +225,12 @@ def test_payload_04_state_persists(fprime_test_api: IntegrationTestAPI, start_gd
     proves_send_and_assert_command(fprime_test_api, f"{component}.ENTER_PAYLOAD_MODE")
     time.sleep(2)
 
-    # Verify mode is saved as PAYLOAD_MODE
+    # Verify mode is saved as PAYLOAD_MODE (3)
     proves_send_and_assert_command(fprime_test_api, "CdhCore.tlmSend.SEND_PKT", ["1"])
     mode_result: ChData = fprime_test_api.assert_telemetry(
         f"{component}.CurrentMode", timeout=5
     )
-    assert mode_result.get_val() == 2, "Mode should be saved as PAYLOAD_MODE"
+    assert mode_result.get_val() == 3, "Mode should be saved as PAYLOAD_MODE"
 
     # Verify PayloadModeEntryCount is tracking
     count_result: ChData = fprime_test_api.assert_telemetry(