gps-denied-onboard/docs/02_components/09_System_Orchestrator/spec.md

System Orchestrator Component

Detailed Description

The System Orchestrator ties all components together. It implements the main control loop (or async pipeline) and the state machine for the system's operational modes:

1. Initializing: Loading models, maps.
2. Tracking: Normal operation (L1 active, L3 periodic).
3. Lost/Searching: L1 failed, L2 aggressive search active.
4. Critical Failure: L2 failed repeatedly, requesting User Input.

It subscribes to the Input Manager, pushes data to L1/L2/L3, updates the State Estimator, and publishes results via the Service Interface. It also monitors PDM@K proxy metrics to trigger the "Human-in-the-Loop".

API Methods

run_pipeline_step

• Input: void (Driven by event loop)
• Output: void
• Description:
  1. Get frame from Input Manager.
  2. Run L1.
  3. Check if L3 (Global) update is needed (e.g., every 10th frame or if L1 confidence low).
  4. If needed, run L2 -> L3.
  5. Update State Estimator.
  6. Check health (Covariance size).
  7. If Critical -> Publish Request Input.
  8. Publish Telemetry.
• Test Cases:
  • Normal flow -> Telemetry published.
  • Loss of tracking -> State transitions to "Searching".

handle_user_input

• Input: UserCommand
• Output: void
• Description: Passes manual fix data to State Estimator and resets failure counters.

Integration Tests

• End-to-End Simulation: Connect all components. Run the full sequence. Verify final output CSV matches requirements.

Non-functional Tests

• Timing Budget: Measure total wall-clock time per run_pipeline_step. Must be < 5.0s (average).