Project plan¶

Status key: [ ] todo · [~] in progress · [x] done

Guiding principle: build software against the simulator first, then hardware on the bench, and only fly last. Each phase ends with a demo-able exit criterion. Don't start a flight phase until the previous phase's exit criterion is met.

Phase 0: Requirements, regulations, budget¶

Confirm the country or countries of operation, and record the rules in docs/OPEN_QUESTIONS.md. Cover VLOS vs BVLOS, operator ID, remote ID, and whether a SIM may be used airborne under the carrier's terms.
Choose the airframe: an off-the-shelf foam VTOL or a DIY QuadPlane conversion. Record it in docs/DECISIONS.md.
Choose the flight controller (ADR-0002): the F405 Wing V2 on hand for the bench and RC tuning, an H743 before browser-flown missions (2026-10-11).
Finalise docs/BOM.md and order parts.
Rent the VPS in a region near the flying area.
Get a data SIM and check LTE coverage and uplink at the site.

Exit: BOM ordered, regulations understood, flying site chosen.

Phase 1: Software (no hardware). Start here in the CLI.¶

Order: frontend first against a mock vehicle, then the real backend underneath it. See docs/FRONTEND.md for the contract that keeps UI work safe from backend changes (ADR-0009).

1a: Frontend against MockLink ← START HERE¶

Exit 1a: the whole operator workflow is usable end to end against MockLink on phone and laptop.

1b: SITL + drone agent¶

Do this before new planner features (ADR-0017). Mapping reference: docs/MAVLINK.md. - [x] sim/: ArduPlane SITL in Docker with a QuadPlane frame. MAVLink exposed over TCP/UDP. (2026-10-07: Plane-4.7.1, ports 5760/5762, sim/README.md) - [ ] agent/ (Go, Pion WebRTC): - [x] MAVLink2 connection (serial or TCP) → map into protocol/ messages (VehicleState, events). Mode mapping → app FlightMode. (internal/fc, -fc flag) - [x] Mission translation rules per docs/MAVLINK.md, as code: Go agent/internal/mission (authoritative) + TS preview web/src/ardupilot, both held to testdata/mission-translation/ (2026-10-07) - [x] Wire mission.Translate into the agent's mission.upload: MAVLink upload with retries, readback into onVehicle, seq ↔ app index for MISSION_CURRENT, fence upload + FENCE_ALT_MAX, stored mission identity (and adopting a mission already on the FC) - [x] Decide clock-mode loiter: Lua script on the FC, sim/scripts/loiter_until.lua, proven in SITL (ADR-0017) - [ ] Fly the same missions in MockLink and SITL; tune the mock to SITL (waypoint reached, RTL altitude, turn radius, cruise speed: SITL cruises at 25 m/s, see docs/MAVLINK.md) - [x] Fly a mission from the browser through WebRtcLink → agent → SITL: web/e2e-sitl (npm run e2e:sitl), flight, RC takeover by the mode switch, and start needing the switch at AUTO. (2026-10-08: all three pass, 5.6 min) - [ ] More SITL scenarios: browser closed mid-mission, agent killed mid-flight, mission changed from another ground station - [ ] WebRtcLink: when the agent restarts, start a fresh peer connection instead of an ICE restart. Seen 2026-10-12: ICE reconnected to the new agent process but the data channels didn't, so commands failed with not_connected until the operator reconnected - [x] Data channels: telemetry (unreliable) and control (reliable), carrying the same protocol/ v1 messages as MockLink (flown end to end by web/e2e-sitl, 2026-10-08) - [x] Command whitelist and safety gate. Mission upload, download and verify state machine. (Flown end to end in SITL by cmd/sitlcheck; not yet from a browser) - [x] GCS heartbeat only while a commander session is alive. Informational since ADR-0020 (FS_GCS_ENABL 0): no failsafe depends on it. (Any session with an open control channel counts; one-commander rule still to do) - [x] RC-override awareness: report RC link and mode-switch state; refuse browser mode changes while RC holds a manual mode. (2026-10-08: switch position read via FLTMODE_CH, reported as rc.modeSwitch; off AUTO while armed is an override; start needs RC linked + switch at AUTO. Proven in SITL with cmd/sitlpilot -switch. Still open: a LOITER-switch test that a pilot's loiter isn't time-limited, ADR-0020) - [ ] Video track: test pattern in SITL mode - [ ] Gimbal lock and release (DO_SET_ROI_LOCATION / ROI_NONE, release past 500 m), gimbal attitude and WIND into telemetry, free fly as a rolling mission (ADR-0023, -0024, -0026) - [ ] battery_rtl.lua: return home when the battery is down to the trip home plus the reserve, proven in SITL (ADR-0025) - [ ] Agent refuses a mission that needs an FC script (a clock-mode loiter) when the FC can't run scripts (SCR_ENABLE 0 or absent, as on the F405), and the console says why (ADR-0002) - [x] Local command and flight log (JSONL): internal/flightlog, -flight-log-dir; sessions, commands, uploads, FC events, state samples (2026-10-08); uploaded to the server when finished (internal/logupload, 2026-10-11) - [x] WSS client to signalling with a per-drone key; verify the Ed25519 session token before answering an offer (ADR-0030, 2026-10-11) - [ ] Generate JSON Schema from the zod protocol/ definitions; Go types generated from it or hand-mirrored with tests

1c: Server + real link¶

Exit: a full autonomous VTOL mission in SITL, run from a phone browser and a laptop browser, through the deployed VPS, with both direct and relayed paths tested. No UI feature code changed when switching from MockLink to WebRtcLink.

Link slice on a Raspberry Pi 5 (pulled forward from 1b/1c, ADR-0014, details in `docs/P2P_TESTING.md`)¶

Phase 2: Air unit on the bench¶

Orange Pi 5 (ADR-0018): flash a minimal Debian/Armbian. Cross-compile the agent (GOARCH=arm64). Run it as a systemd service.
Bring up the LTE modem: ModemManager/NetworkManager, APN, reconnect watchdog. Report signal metrics (RSRP, SINR, band) as telemetry.
Gimbal camera: forward its Ethernet H.264/H.265 into the Pion track without transcoding. Measure glass-to-glass latency.
Aux cameras: hardware H.264 through the RK MPP encoder (GStreamer mpph264enc) into Pion; switch the one live stream between gimbal and aux cameras (video.source and the video telemetry field, ADR-0029). Measure latency, bitrate and CPU.
CV cameras: capture into an RKNN model on the NPU; send results (not video) to the browser. Measure CPU, NPU load and power.
UART to the FC (MAVLink2, 921600 baud). SERIALx_PROTOCOL=2.
Power: a 5 V 3 A BEC, plus a capacitor near the modem for TX peaks. Measure total draw.
Measure how often LTE CGNAT forces TURN vs direct. Record it in docs/DECISIONS.md.

Exit: on the bench, the FC (USB-powered, ArduPlane) shows live video and telemetry in a phone browser over LTE.

Phase 3: Airframe build and tuning (local RC only)¶

Build: FC, GPS/compass, airspeed sensor, ELRS RC override, air unit. Keep the LTE antennas away from GPS.
ArduPilot QuadPlane setup and calibrations
QHOVER/QLOITER tuning → FBWA → transitions → AUTOTUNE, under RC
Check for interference from the air unit (GPS noise, power sag)

Exit: reliable VTOL takeoff, transition and landing under RC.

Phase 4: Autonomous missions from the browser, VLOS with a safety pilot¶

Set the failsafes: FS_GCS_ENABL 0 (ADR-0020), FS_LONG_ACTN, Q_RTL_MODE, geofence, battery. Install pause_resume.lua and loiter_until.lua on the FC
Bench test: pull the modem mid-mission and check the response
Configure and test the RC override (ADR-0008): mode-switch takeover mid-mission, hand back to AUTO, and RC loss in AUTO continues the mission
Short, low missions started from the browser, with the RC pilot ready to take over
Log link quality along the flight path (RTT, signal, direct vs relay)

Exit: 10+ successful VLOS autonomous missions run from the browser. Link loss tested in flight.

Phase 5: Hardening¶

Exit: a production-ready system that meets your local regulatory requirements.

Suggested first CLI session¶

"Read CLAUDE.md, docs/PLAN.md and docs/FRONTEND.md. Start Phase 1a: scaffold web/ and build the domain types, protocol schemas, VehicleLink interface + contract tests, and MockLink first, before any UI screens."