Add finite state machine diagram for ModeManager Safe Mode transitions

[Copilot]

Description

Added comprehensive FSM documentation for ModeManager Safe Mode behavior. The diagram captures all state transitions, triggers, and recovery logic in a single reference.

New Document: FprimeZephyrReference/Components/ModeManager/docs/safe-mode-fsm.md

• Mermaid FSM diagram showing NORMAL ↔ SAFE_MODE transitions with internal substates
• 5 entry triggers: LOW_BATTERY (auto, debounced), SYSTEM_FAULT (boot detection), GROUND_COMMAND, EXTERNAL_REQUEST, LORA
• 2 exit paths: manual command (all reasons) vs auto-recovery (LOW_BATTERY only)
• Voltage hysteresis (6.7V entry, 8.0V recovery) and debouncing logic (10s configurable)
• Boot-time state restoration with unintended reboot detection via cleanShutdown flag
• Load switch control mapping (8 switches: 6 faces + 2 payload)
• Event notifications integrated into Entry/Exit Actions sections for better context
• Telemetry channels and testing validation matrix
• Safe mode sequence filename: /seq/enter_safe.bin
• Fixed Mermaid diagram formatting: replaced \n with <br/> for proper line break rendering

Updated: docs-site/components/ModeManager.md - added link to FSM document

Documentation Structure:

• Consolidated event documentation into state transition sections (Entry Actions and Exit Actions) to reduce redundancy
• All event emissions are documented inline with the actions that trigger them, providing better context

Related Issues/Tickets

How Has This Been Tested?

• Manual testing (verified Mermaid diagram syntax and rendering, cross-referenced implementation code)
• Documentation accuracy review against ModeManager.cpp/.fpp/.hpp and safe_mode_test.py

Screenshots / Recordings (if applicable)

N/A - Documentation only

Checklist

• Written detailed sdd with requirements, channels, ports, commands, telemetry defined and correctly formatted and spelled
• Have written relevant integration tests and have documented them in the sdd
• Have done a code review with
• Have tested this PR on every supported board with correct board definitions

Further Notes / Considerations

The FSM diagram consolidates information scattered across code, existing docs, and tests into a single visual reference. Particularly valuable for understanding:

• Why only LOW_BATTERY allows auto-recovery (other reasons require ground investigation)
• How unintended reboots are detected (cleanShutdown flag mechanism)
• Voltage monitoring state machines within each top-level state

The Mermaid diagram uses proper HTML <br/> tags for multi-line transition labels to ensure correct rendering in documentation viewers.

The documentation is organized to minimize redundancy by integrating event notifications directly into the Entry Actions and Exit Actions sections where they naturally occur, rather than maintaining a separate Event Notifications section.

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Mikefly123]

@copilot check that you are using the right escape character for mermaid diagrams. The \n that you are using is not formatting correctly

[Copilot]

@copilot check that you are using the right escape character for mermaid diagrams. The \n that you are using is not formatting correctly

Fixed in commit 81d1029. Replaced all \n escape sequences with <br/> HTML tags for proper Mermaid diagram rendering. The line breaks in transition labels should now display correctly.

[yudataguy]

LGTM!

Also tested claude code to conduct review, nothing major was found.

[ineskhou]

One correction, one nitpick

[ineskhou]

Since the last Pr this has changed to enter_safe.bin -- in hindsight mayeb we want to change it back since radio_enter_safe is what the 3 sats in space are expecting? Either we shoudl change this docs or the parameter default name

[Copilot]

Updated to /seq/enter_safe.bin in commit 0c807d5.

[ineskhou]

nitpick but this ia bit repetitive id put any info not in Entry Transitions: NORMAL → SAFE_MODE in that section and remove this seciotn

[Copilot]

Removed the redundant "Event Notifications" section in commit 0c807d5. All event information is now consolidated into the Entry Actions and Exit Actions sections where they're more contextually relevant.

[Mikefly123]

@copilot please make the changes that we requested in the review by @ineskhou

[Copilot]

@copilot please make the changes that we requested in the review by @ineskhou

Both changes completed in commit 0c807d5:

1. Updated safe mode sequence filename to /seq/enter_safe.bin
2. Consolidated event documentation into Entry/Exit Actions sections

[ineskhou]

LGTM

[yudataguy]

Code review

Found 2 issues:

1. Safe mode sequence is not executed for the SYSTEM_FAULT (unintended reboot) entry path. The "Entry Actions" section states the sequence runs for all entry triggers, but ModeManager.cpp:316 calls enterSafeMode(SYSTEM_FAULT) directly without calling runSafeModeSequence() first, and enterSafeMode() does not call it internally. This was intentionally removed in commit b91d35a. The documentation should note that the sequence is skipped for unintended reboot scenarios.

proves-core-reference/FprimeZephyrReference/Components/ModeManager/docs/safe-mode-fsm.md

Lines 70 to 84 in 0c807d5

	When entering SAFE_MODE, the ModeManager:
	1. Executes the safe mode radio sequence (`/seq/enter_safe.bin`)
	2. Sets `m_mode = SAFE_MODE`
	3. Increments `m_safeModeEntryCount` (persisted)
	4. Sets `m_safeModeReason` to the trigger reason
	5. Emits one or more events:
	- `EnteringSafeMode(reason: string)` - Severity: WARNING_HI (always emitted with reason string)
	- `AutoSafeModeEntry(reason: SafeModeReason, voltage: F32)` - Severity: WARNING_HI (for LOW_BATTERY trigger)
	- `UnintendedRebootDetected()` - Severity: WARNING_HI (for SYSTEM_FAULT at boot)
	- `ManualSafeModeEntry()` - Severity: ACTIVITY_HI (for FORCE_SAFE_MODE command)
	- `ExternalFaultDetected()` - Severity: WARNING_HI (for forceSafeMode port call)
	6. Turns OFF all 8 load switches via `loadSwitchTurnOff` ports
	7. Notifies other components via `modeChanged` port with SAFE_MODE value
	8. Executes safe mode sequence via `runSequence` port (may emit `SafeModeSequenceCompleted` or `SafeModeSequenceFailed`)
	9. Saves state to persistent storage (`/mode_state.bin`)

2. The "Additional Documentation" section was added directly to docs-site/components/ModeManager.md, but per docs-site/README.md (lines 54-56), this file is auto-generated via make docs-sync from the source SDD. Manual edits will be overwritten on the next sync. The link should be added to the source file at FprimeZephyrReference/Components/ModeManager/docs/sdd.md instead, then synced with make docs-sync.

proves-core-reference/docs-site/components/ModeManager.md

Lines 185 to 189 in 0c807d5

	## Additional Documentation
	For a comprehensive finite state machine diagram documenting all Safe Mode entry and exit transitions, see:
	- [Safe Mode Finite State Machine](../../FprimeZephyrReference/Components/ModeManager/docs/safe-mode-fsm.md)

🤖 Generated with Claude Code

_{- If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[yudataguy]

Don't know if the above is still necessary, this was generated by claude code