Mission Computer Lab: architecture and contracts

This repository implements two WSL/Linux test environments for a benign inspection mission: a fast kinematic policy harness and an actual PX4/Gazebo/ROS 2 integration, which also flies a three-drone fleet from a moving carrier. It does not emulate the Qualcomm SoC. The diagram and component table below describe the fast harness; the SITL guide specifies the real firmware integration, topic contracts, frames and failsafe ownership.

Fast harness data path

This data-flow diagram shows which outputs influence motion and which are recorded as payload observations.

flowchart TD
    MODEL[Generated ONNX model] --> GATE[SHA-256 and Ed25519 user-space gate]
    GATE --> CPU[ONNX Runtime CPU]
    WORLD[Synthetic world] --> RGB[64 by 48 RGB camera]
    RGB --> CPU
    CPU --> HEALTH[Capture age and inference duration]
    CPU --> BOX[Bounding box for observation only]
    WORLD --> LIDAR[72 planar LiDAR rays]
    LIDAR --> MAP[Inflated occupancy grid]
    MAP --> PLAN[A-star static waypoints]
    WORLD --> SENSORS[Noisy GNSS and IMU]
    SENSORS --> KF[Educational Kalman filter]
    KF --> CORE[C++ supervisor over bounded pipe IPC]
    HEALTH --> CORE
    PLAN --> CORE
    CORE --> STUB[Autopilot stub with command watchdog]
    STUB --> WORLD
    BOX --> EVIDENCE[JSON and CSV evidence with offline replay]
    CORE --> EVIDENCE
    WORLD --> EVIDENCE

flowchart TD
    MODEL[Generated ONNX model] --> GATE[SHA-256 and Ed25519 user-space gate]
    GATE --> CPU[ONNX Runtime CPU]
    WORLD[Synthetic world] --> RGB[64 by 48 RGB camera]
    RGB --> CPU
    CPU --> HEALTH[Capture age and inference duration]
    CPU --> BOX[Bounding box for observation only]
    WORLD --> LIDAR[72 planar LiDAR rays]
    LIDAR --> MAP[Inflated occupancy grid]
    MAP --> PLAN[A-star static waypoints]
    WORLD --> SENSORS[Noisy GNSS and IMU]
    SENSORS --> KF[Educational Kalman filter]
    KF --> CORE[C++ supervisor over bounded pipe IPC]
    HEALTH --> CORE
    PLAN --> CORE
    CORE --> STUB[Autopilot stub with command watchdog]
    STUB --> WORLD
    BOX --> EVIDENCE[JSON and CSV evidence with offline replay]
    CORE --> EVIDENCE
    WORLD --> EVIDENCE

The text equivalent below remains useful in terminals and Markdown viewers without Mermaid support.

Generated ONNX artifact
      │ SHA-256 + Ed25519 signature + version/device checks
      ▼
User-space boot gate ──► ONNX Runtime CPU session
                              ▲                 │ mask → synthetic object bbox
Synthetic world ──► RGB camera┘                 ▼
       ├─────────► planar LiDAR ─► inflated occupancy ─► A* waypoints
       ├─────────► noisy GNSS ─┐                         │
       └─────────► noisy IMU ──┴─► Kalman localization ──┤
                                                       ▼
                         Python ── local process IPC ─► C++17 supervisor
                                                       │ bounded ENU velocity
                                                       ▼
                            Independent autopilot stub + kinematic vehicle
                                                       │
                    JSON / CSV / events / actual camera frames / browser replay

Perception is an observed payload branch: its freshness and latency affect supervision, but its bounding box does not steer the vehicle. LiDAR builds the occupancy map for A*; every later scan is added, and the route is replanned if it closes. The planner is not doing visual pursuit, dynamic obstacle avoidance or SLAM.

Component boundaries

Fleet from a moving carrier (SITL)

The fleet scenario reuses every single-drone contract and adds one coordinating node. Each vehicle keeps its own complete stack: its own PX4 instance and MAV_SYS_ID, DDS namespace, payload, verified perception, observer and mission adapter with a C++ supervisor. The station on the carrier sequences who may launch or land and drives the carrier; it has no path to arm, change modes or override a vehicle.

flowchart TB
    ST[Fleet station node, riding on the carrier]
    CAR[Carrier in Gazebo: velocity controller and odometry]
    subgraph FLEET[Three independent vehicle stacks]
        V0[px4_0: adapter, C++ supervisor, PX4 instance 0, system ID 1]
        V1[px4_1: adapter, C++ supervisor, PX4 instance 1, system ID 2]
        V2[px4_2: adapter, C++ supervisor, PX4 instance 2, system ID 3]
    end
    ST -->|drive command| CAR
    CAR -->|pose and speed| ST
    ST -->|launch and land clearances| FLEET
    FLEET -->|phase, position, layer, pad error| ST
    CAR -->|pad pose and velocity| FLEET

flowchart TB
    ST[Fleet station node, riding on the carrier]
    CAR[Carrier in Gazebo: velocity controller and odometry]
    subgraph FLEET[Three independent vehicle stacks]
        V0[px4_0: adapter, C++ supervisor, PX4 instance 0, system ID 1]
        V1[px4_1: adapter, C++ supervisor, PX4 instance 1, system ID 2]
        V2[px4_2: adapter, C++ supervisor, PX4 instance 2, system ID 3]
    end
    ST -->|drive command| CAR
    CAR -->|pose and speed| ST
    ST -->|launch and land clearances| FLEET
    FLEET -->|phase, position, layer, pad error| ST
    CAR -->|pad pose and velocity| FLEET

In this simulation the station and vehicles share one host and one DDS domain, so message delivery is effectively perfect, except where the guardian scenario deliberately jams it. Guardian drones builds on the same fleet: an authority split between each drone, the station and a command center, evaluated across eight threat scenarios and flown on PX4. The carrier's road is obstacle-free by design. The SITL guide lists the phases, topics and acceptance criteria.

Clock, units and frames

The simulation advances in fixed 0.05 s steps and runs faster than wall time. Every synthetic sensor timestamp uses the same simulation clock. WSL wall-clock duration is used only to measure ONNX calls and supervisor IPC. These clocks must not be mixed when interpreting failure latencies.

In the PX4 integration, every ROS adapter runs on Gazebo's simulation clock (use_sim_time), the clock PX4 itself runs on. Freshness therefore holds when the simulation runs slower than real time, as it does while recording video. On hardware the same code falls back to the monotonic clock.

All motion uses ENU: x east, y north, z up, metres and metres/second. The tested enu_to_ned helper maps (x,y,z) to (y,x,-z). A real PX4 adapter also needs body-frame conventions, orientation conversion and timestamp handling. Applying only this vector swap to every message would be wrong.

Camera timestamps are capture times; the current graph's measured inference duration is stored separately. The overload scenario injects a reported 120 ms duration. It does not sleep for 120 ms or model CPU/NPU contention. LiDAR raycasts use truth for the ideal sensor geometry; that shortcut means this is not a SLAM evaluation.

Supervisor protocol

One input line has exactly 15 space-separated fields:

sequence now imu_stamp gnss_stamp vision_stamp link_stamp battery
pos_e pos_n pos_u target_e target_n target_u inference_ms complete

The line above wraps for readability; the wire frame must be one line. complete is 0 or 1. Sequence and now must increase strictly. Sensor timestamps must be nonnegative and no later than now. Battery is a fraction in [0,1]. Nonfinite numbers, invalid ranges, extra fields or replayed frames terminate the process with code 2 and emit no command for that frame.

One output line contains:

sequence mode reason velocity_e velocity_n velocity_u

The runner correlates sequence numbers and imposes a three-second wall-clock response timeout. Unexpected transport failure aborts the experiment. The explicit companion_crash injection exercises a separate stub watchdog; this is not a general production process supervisor.

Health policy and state machine

stateDiagram-v2
    [*] --> INIT
    INIT --> ACTIVE: Healthy for 1 second
    INIT --> HOLD: Unhealthy sample
    ACTIVE --> HOLD: Sensor or latency fault
    HOLD --> ACTIVE: Healthy recovery dwell
    HOLD --> LAND: Fault episode reaches 2 seconds
    ACTIVE --> COMPLETE: Mission goal accepted
    INIT --> LAND: Hard limit
    ACTIVE --> LAND: Hard limit
    HOLD --> LAND: Hard limit
    COMPLETE --> LAND: Hard limit if core is evaluated again
    LAND --> LAND: Latched
    COMPLETE --> COMPLETE: Latched within limits

stateDiagram-v2
    [*] --> INIT
    INIT --> ACTIVE: Healthy for 1 second
    INIT --> HOLD: Unhealthy sample
    ACTIVE --> HOLD: Sensor or latency fault
    HOLD --> ACTIVE: Healthy recovery dwell
    HOLD --> LAND: Fault episode reaches 2 seconds
    ACTIVE --> COMPLETE: Mission goal accepted
    INIT --> LAND: Hard limit
    ACTIVE --> LAND: Hard limit
    HOLD --> LAND: Hard limit
    COMPLETE --> LAND: Hard limit if core is evaluated again
    LAND --> LAND: Latched
    COMPLETE --> COMPLETE: Latched within limits

This is the C++ policy graph. A fault episode starts at the first unhealthy sample and ends only after 2 s of continuous health, so a link or sensor that keeps dropping out escalates to LAND instead of alternating between HOLD and brief ACTIVE commands. In the ROS adapter, LAND or COMPLETE transfers control to PX4 once and permanently stops core evaluation and offboard streaming. PX4 then owns touchdown and disarm, so landing estimator noise cannot start a new application transition. The adapter also hands off permanently if a pilot or GCS leaves OFFBOARD after it was entered; it never switches the vehicle back.

These are design choices for the lab; they are not values prescribed by a program requirement or safety-qualified flight limits.

INIT ── healthy dwell ──► ACTIVE ── mission done ──► COMPLETE
  │                         │
  └── unhealthy ──► HOLD ◄───┘
                      │  └── healthy recovery dwell ──► ACTIVE
                      └── fault episode ≥ 2 s ──► LAND (latched)
Any state ── hard limit / low battery ────────► LAND

HOLD outputs zero velocity in this ideal plant. It does not prove that a real aircraft can hold position when its estimator is invalid. LAND is a descent between 0.3 and 0.7 m/s that continues until touchdown is detected, even when a drifted estimate already reads zero altitude; actual actions must depend on estimator validity, environment and autopilot policy. COMPLETE remains stationary at the final waypoint. The harness also applies truth-based ground contact; that is simulator mechanics, not an available real-world sensor.

Threat model and implemented evidence

This is artifact verification, not an OTA updater. It has no download transport, A/B partition handling, power-loss recovery, rollback counter persistence, certificate rotation or hardware root of trust.

Evidence and acceptance criteria

The executable suite includes one CTest program with multiple supervisor checks, the Python unit and process tests, eight scenario runs, and six signed-artifact cases (current counts). Tests fail the run on unexpected terminal mode, collision with a modeled obstacle, excessive estimator error, missing required transitions, malformed evidence or failed update checks.

The PX4 flights are judged the same way, by named checks computed from independently recorded logs; integration/acceptance.py holds them, and a required check that cannot be evaluated fails rather than going missing.

The eight scenarios cover nominal completion; recoverable camera loss and inference overload; sustained GNSS, link and IMU loss; low battery; and an actual supervisor-process kill. Every scenario records events, sampled states, camera frames, LiDAR endpoints, measurements and checks. The execution report contains the observed values.

The current error bound is a deliberately loose 2 m check on this small synthetic world. Collision checks are sampled circular-obstacle clearance checks, not continuous swept-volume validation. A fixed random seed makes sensor noise reproducible, while timing measurements remain machine/load dependent.

Production migration sequence

1. Completed in the integration track: add PX4 SITL and validate coordinate frames, modes, acks and loss behavior.
2. Completed in the integration track: add typed ROS 2 messages and explicit QoS around the C++ process boundary; retain the supervisor's policy tests.
3. Completed in the integration track: run several vehicles with per-vehicle namespaces and system IDs, coordinated by a station that only grants clearances, including recovery onto a moving carrier.
4. Replace synthetic perception with licensed recorded data and a trained model with separate accuracy evaluation.
5. Replace the simple estimator with a validated localization stack and calibrated sensor timing/extrinsics.
6. Deploy to the exact Qualcomm board/BSP; verify supported accelerator operators, numerical outputs and device measurements.
7. Integrate vendor boot/provisioning/update flows with protected keys and recovery design. Keep manufacturing changes distinct from mission application changes.

Each replacement should preserve one reference input/output trace and add tests at the newly real boundary. Hardware success cannot be inferred from the WSL results.