autopilot/_docs/02_document/components/mission_executor/description.md

Component — mission_executor

Layer: Action (data plane out) Status: forward-looking design (Rust)

1. Purpose

Drives the airframe through a typed state machine: connect → health-check → pre-flight self-test (BIT, F9) → (variant-specific arm/takeoff or wait-for-AUTO) → upload mission → fly mission → land. Owns geofence enforcement (both INCLUSION and EXCLUSION), the lost-link failsafe ladder (F10), and battery / fuel threshold enforcement. Inserts middle waypoints on operator-confirmed targets and resumes the original mission after target-follow ends. Issues all autopilot-facing commands through mavlink_layer. Triggers post-flight MapObjects push (F8) on terminal state.

2. Inputs

Input	Source	Cadence	Notes
Mission JSON (parsed)	mission_client	once at start; on middle-waypoint update	Contains waypoints + INCLUSION/EXCLUSION geofences + return point.
Airframe variant	startup config	once	multirotor or fixed_wing.
MAVLink telemetry	mavlink_layer	continuous	Position, attitude, mode, sys-status, mission progress.
Middle-waypoint hint	scan_controller (from operator_bridge)	event on operator confirm	Triggers mission re-upload.
Target-follow release / loss / timeout	scan_controller	event	Triggers reverting to the original mission.
Health input from peer components	health aggregator	continuous	Used for the health-check gate before takeoff.

3. Outputs

Output	Consumer	Shape
MAVLink commands (arm, takeoff, set-mode, change-speed, change-alt, land, RTL, mission-clear, mission-upload, set-current, RTL)	mavlink_layer	per state transition
UAV telemetry (forwarded)	scan_controller, movement_detector, telemetry_stream	continuous
Mission state	scan_controller, operator_bridge	event on transitions
Health metric	health aggregator	current state, state_duration_ms, transition_failures_by_state, geofence violations, retry counts.

4. Key Responsibilities

• Run the variant-specific state machine (see architecture.md §7.7):
  • Multirotor: DISCONNECTED → CONNECTED → HEALTH_OK → BIT_OK → ARMED → TAKE_OFF → MISSION_UPLOADED → FLY_MISSION → LAND → POST_FLIGHT_SYNC → DONE.
  • Fixed-wing: DISCONNECTED → CONNECTED → HEALTH_OK → BIT_OK → MISSION_UPLOADED → WAIT_AUTO → FLY_MISSION → LAND → POST_FLIGHT_SYNC → DONE.
• Apply bounded retry with exponential backoff at every transition; explicit max-retry; on exceeding it, health flips to red and the executor surfaces the failure via operator_bridge. No infinite retry.
• Run pre-flight BIT (F9) before transitioning to ARMED / WAIT_AUTO. BIT covers every dependency in architecture.md §5 plus mission load + MapObjects pre-flight pull (cached fallback acknowledged) + persistent-store free space + wall-clock binding. On BIT FAIL, no transition. On DEGRADED, surface to operator for signed acknowledgement (per Q9).
• Run the lost-link failsafe ladder (F10) every tick: LinkOk → LinkDegraded → LinkLost → LinkLostInFollow. Default RTL after 30 s grace; configurable. MAVLink-link loss to ArduPilot itself is a separate, more severe event — health → red, airframe failsafe takes over (we do NOT override it).
• Enforce battery / fuel thresholds. Read SYS_STATUS / EXTENDED_SYS_STATE continuously; trigger RTL at battery ≤ rtl_threshold (default 25 %); land-now at battery ≤ hard_floor (default 15 %); operator override only via signed command.
• Enforce geofences. INCLUSION violations halt forward progress and trigger RTL; EXCLUSION violations trigger the same. Both are honoured (the earlier C++ behaviour silently ignored EXCLUSION; the new design rejects that).
• On middle-waypoint hint: recompute the mission (current_position → middle_waypoint → resume_original_route), MISSION_CLEAR_ALL, re-upload via the standard sequence, MISSION_SET_CURRENT(0), and resume.
• On target-follow ending: recompute and re-upload the original mission from the current position; resume.
• Trigger post-flight MapObjects push (F8) on entry to POST_FLIGHT_SYNC — that is, after LAND completes (or after RTL completes, or after operator-acknowledged abort). Hand off to mission_client.
• Forward MAVLink telemetry to scan_controller (for proximity priority + middle-waypoint computation), to movement_detector (for ego-motion compensation), and to telemetry_stream (for operator overlay).

5. Internal State

• Current state + variant.
• Currently active mission (original) + active patched mission (with middle waypoint), if any.
• Per-transition retry counter and last-failure reason.
• Mission progress (current item index).
• Geofence violation history (for diagnostics).

State is in-process only; restart re-runs the state machine from DISCONNECTED.

6. Failure Modes

Failure	Detection	Behaviour
MAVLink connection lost	heartbeat timeout from mavlink_layer	Bounded retry; health → red after threshold; state machine pauses (does not reset).
Health-check gate fails (sensors not ok, low battery, etc.)	telemetry inspection	Stay in CONNECTED state; alert; no takeoff.
BIT FAIL on any item	F9 evaluation	No transition past BIT_OK; surface report to operator; remain in HEALTH_OK.
Mission upload MISSION_ACK rejection	mavlink_layer response	Bounded retry with full re-upload; on max-retry, health → red, surface to operator.
Geofence INCLUSION exit	telemetry vs polygon	Trigger RTL via MAVLink; surface alert; transition to LAND.
Geofence EXCLUSION entry	telemetry vs polygon	Trigger RTL via MAVLink; surface alert; transition to LAND.
Operator/Ground-Station modem link lost	F10 ladder evaluation	LinkDegraded (5–30 s) → health yellow + queue events; LinkLost (>30 s) → RTL; LinkLostInFollow (>30 s in target-follow) → 30 s grace then RTL. Configurable.
MAVLink-link loss to ArduPilot/PX4	heartbeat timeout	Health → red; airframe's own MAVLink failsafe takes over (we do NOT override).
Battery ≤ rtl_threshold (default 25 %)	SYS_STATUS	Trigger RTL; surface alert; transition to LAND.
Battery ≤ hard_floor (default 15 %)	SYS_STATUS	Land-now via MAV_CMD_NAV_LAND at safest reachable point; health → red.
Operator override of safety threshold	signed command (Q9)	Permitted; recorded in audit log with operator ID + rationale.
Middle-waypoint compute fails (e.g., target outside INCLUSION)	pre-upload validation	Reject the hint with reason; surface to operator_bridge; original mission continues.
Target-follow handover from scan_controller while not yet airborne	state guard	Reject; surface error; never deliver target-follow before FLY_MISSION.
Post-flight MapObjects push fails	F8 status	Persist pending diff on disk; bounded retry; operator-visible warning after max retries. State machine still reaches DONE so a new mission can start.

7. Dependencies

In-process (input): mission_client, mavlink_layer, scan_controller, health aggregator. In-process (output): mavlink_layer, scan_controller, movement_detector, telemetry_stream, operator_bridge.

External: ArduPilot / PX4 over MAVLink (mediated by mavlink_layer).

8. Non-Functional Targets

Concern	Target
Time-to-takeoff (multirotor, healthy startup)	bounded; no infinite waits
Mission-upload retry budget	configurable max; default 3 attempts
Geofence response time	≤500 ms from violation detection to RTL command
Middle-waypoint re-upload	≤2 s end-to-end

9. References

• architecture.md §3, §5 Architectural Principles (bounded retry, geofence symmetric, lost-link mandatory, BIT mandatory, MapObjects mission-bracketed), §7.3 Reliability and safety, §7.7 MAVLink and Piloting (lost-link ladder + battery thresholds).
• system-flows.md §F6 Mission lifecycle, §F8 MapObjects sync, §F9 Pre-flight self-test, §F10 Lost-link failsafe ladder.
• data_model.md §MissionItem, §MissionWaypoint, §Geofence.