autopilot/_docs/00_problem/input_data/services.md

External Services — Test-Mock Requirements

Black-box catalogue of every external system autopilot depends on at runtime, with the test-fixture / mock shape required for each. Service-side design (protocols, component contracts, ownership boundaries) lives in _docs/02_document/architecture.md — this file owns ONLY the test-data dependency view (per .cursor/rules/artifact-srp.mdc, _docs/00_problem/input_data/ is a test-data concern).

Runtime input shapes (frame rates, message types) are described in data_parameters.md. This file extends them with the acquisition status of the corresponding test fixture.

Index

#	External system	Production role	Test-mock shape needed	Acquisition status
1	Tier-1 detection (../detections)	Primitive YOLO inference on every frame; returns class + bbox + confidence	Recorded bi-stream replay file (request frame → response detections)	MISSING — no replay recorded yet
2	Mission planner (missions API)	Mission JSON pull at start; middle-waypoint POST on operator-confirm; pre-flight area-map pull + post-flight diff push	Mock HTTPS exchanges for GET/POST + sample mission + sample mapobjects state	MISSING — schema known (mission-schema), no fixture recorded
3	Ground Station (modem)	Continuous push of camera + telemetry + bbox overlay; return path carries operator commands (confirm / decline / target-follow / abort)	Scripted session traces: nominal session, modem drop at T=N, reconnect at T=M, lost-link sustained ≥30 s	MISSING — authorable inline (no external dependency)
4	Airframe autopilot (ArduPilot / PX4)	MAVLink v2 transport for the ~10–15 commands in architecture.md §7.7; battery + position telemetry; geofence enforcement	ArduPilot SITL traces: waypoint upload, geofence INCLUSION + EXCLUSION, RTL on lost-link, RTL on battery floor	MISSING — needs SITL run with scripted scenarios
5	ViewPro A40 camera (frames)	H.264/265 1080p RTSP video feed at 30/60 fps	Recorded frame sequences (.mp4) — wide-zoom, light-zoom, medium-zoom, high-zoom variants	PARTIAL — 4 wide-zoom clips on disk (fixtures/movement/video0[1-4].mp4); zoom-band variants missing
6	ViewPro A40 gimbal (control)	Vendor UDP control protocol; yaw / pitch / zoom telemetry per tick	Per-frame-sequence gimbal.csv paired with the matching video; per-tick yaw/pitch/zoom + timestamp	MISSING — no gimbal.csv paired with the 4 movement videos; ego-motion compensation (M1–M4) is unfalsifiable without this
7	Deep-analysis VLM (local IPC)	Optional Tier-3 confirmation over bounded ROI; structured VlmAssessment response	Recorded I/O pairs (ROI in → VlmAssessment out) + schema-violation cases for fail-closed tests	MISSING — depends on the local model choice; can be authored against the assessment schema once the model is pinned
8	Time source (GPS / NTP)	Wall-clock; drift triggers the R8 health-yellow gate	Scripted drift scenarios (no real GPS/NTP hardware needed) — clock offset, jump, source loss	MISSING — authorable inline

Per-service detail — what acquisition would look like

The table above is the index; the rows below explain the shape and acquisition path so the gaps can be planned out one at a time.

1. Tier-1 detection replay (../detections)

• Production transport: bi-directional gRPC. The autopilot streams frames out; ../detections streams Detections messages back.
• Mock shape: a .replay file (one per scenario) recording timestamped frames + the exact Detections responses the model emitted. Used by detection_client integration tests in isolation — no need to boot the real Tier-1 service.
• Acquisition path: record one replay against the currently pinned ../detections model. Re-record when the upstream model changes (the monorepo-e2e skill should eventually own this drift; see the suite's leftovers).
• Blocks AC rows: every row that needs a deterministic detection stream — practically L1, L2, D1, D2, D6 in isolation; in suite-e2e mode these run live against the real ../detections.

2. Mission + MapObjects mock (missions API)

• Production transport: HTTPS REST.
• Mock shape: JSON fixtures per endpoint + a small mock HTTP server (or replay-style fixtures consumed by a test double). Endpoints in scope:
  • GET /missions/{id} — mission JSON, validated against mission-schema.
  • POST /missions/{id} — middle-waypoint insertion (200 OK + updated mission).
  • GET /missions/{id}/mapobjects — pre-flight area-map pull (response shape: map-object records keyed by spatial cell; volume target ~10000 objects for the 30×30 km gate Mp1).
  • POST /missions/{id}/mapobjects — post-flight diff push (NEW / MOVED / REMOVED / CONFIRMED-EXISTING; volume target per Mp3 ~17500 records).
• Acquisition path: author JSON fixtures against the known schema; record real exchanges once missions is reachable from the test bench.
• Blocks AC rows: Mp1–Mp5 (all 5 map-reconciliation rows).

3. Ground Station session trace

• Production transport: continuous push over modem (suite-level protocol).
• Mock shape: scripted timing trace per scenario. Each scenario is a list of (t, event) pairs: connect, push frame, push telemetry, operator-click, modem-drop, reconnect, lost-link.
• Acquisition path: authorable inline from architecture.md §7 and acceptance_criteria.md §Reliability & Safety. No external dependency — just a fixture generator.
• Blocks AC rows: R4 (lost-link → RTL at 30 s); O8, O9, O10 (operator command lifecycle on the return path, but O9/O10 also depend on Q9 for the auth scheme).

4. MAVLink SITL trace

• Production transport: MAVLink v2 over UDP or serial.
• Mock shape: ArduPilot SITL recording capturing the autopilot's command stream + the airframe's response stream. One trace per scenario: waypoint upload, geofence INCLUSION violation, geofence EXCLUSION violation, lost-link RTL, battery RTL-floor RTL, battery hard-floor land-now.
• Acquisition path: run ArduPilot SITL with a scripted mission; capture the full MAVLink stream with mavlink-router or equivalent.
• Blocks AC rows: R4 (RTL exact timing), R5, R6, R7, R9; plus the project-level "MAVLink command surface MUST pass SITL conformance" gate.

5. Camera frame sequences (ViewPro A40)

• Production transport: RTSP/RTP over TCP/UDP, 1080p H.264/265 at 30/60 fps.
• Current local fixtures: fixtures/movement/video0[1-4].mp4 (4 clips, ~5–6 MB each), fixtures/videos/94d42580bd1ad6ff.mp4 (one reconnaissance clip used for T3 frame-rate floor).
• Mock-shape gap: zoom-band coverage. Each AC scenario that names a zoom level (wide, light, medium, high) needs a representative clip at that zoom band. The 4 movement clips do not enumerate which zoom band each represents — this needs documenting per clip OR re-recording with zoom-band labels.
• Acquisition path: existing clips usable for movement-detection visual baselines; new recordings at each zoom band require flight time.

6. Gimbal telemetry CSV (paired with frames)

• Production transport: ViewPro A40 vendor protocol over UDP; per-tick yaw/pitch/zoom updates.
• Mock shape: gimbal.csv with columns (t, yaw_deg, pitch_deg, zoom_band, focal_mm), one CSV per video file, timestamps aligned to frame timestamps within ≤ 1 frame.
• Acquisition path: requires re-flying the recording with the gimbal-feedback channel captured alongside. CANNOT be back-fitted to existing videos.
• Blocks AC rows: M1, M2, M3, M4 (movement-detection ego-motion compensation); also tightens L6, L7 (movement candidate enqueue latency).
• Confirmed not available today (user-stated 2026-05-19).

7. VLM I/O pairs

• Production transport: Unix-domain socket IPC to local-onboard VLM (NanoLLM / VILA1.5-3B per architecture §1).
• Mock shape: paired (roi.png, prompt.txt, vlm_response.json) per scenario + a small set of schema-violation cases (truncated JSON, wrong field types, missing required fields) for fail-closed tests.
• Acquisition path: depends on the local VLM model choice. Once pinned, capture real I/O during a flight or scripted run; schema-violation cases authored inline.
• Blocks AC rows: L3 (Tier-3 ≤5 s latency on bounded ROI), S5 (deep-analysis hold-cap interaction).

8. Operator-command envelopes

• Production transport: comes back to autopilot via Ground Station modem return path.
• Mock shape: per envelope, a (scheme, payload, signature, sequence_id) tuple. One fixture per case: valid, expired, replayed (same envelope sent twice), malformed (signature mismatch), unsigned.
• Acquisition path: blocked on Q9 (operator-command auth scheme — open in _docs/02_document/architecture.md §8). Once the scheme is chosen, envelopes are authorable inline.
• Blocks AC rows: O9 (replay protection), O10 (signature validation); strengthens O8 (confirm pathway).

9. GPS / NTP drift scripts

• Production transport: kernel-level wall clock + GPS lock state.
• Mock shape: scripted offset injection — bump the clock by N ms, drop GPS lock, change time source.
• Acquisition path: authorable inline; no external dependency.
• Blocks AC rows: R8.

Coverage summary by service

Service	Rows covered (real fixture)	Rows blocked on this service	Acquisition priority
Tier-1 replay	L1, D2, D6 (live; replay desirable for isolation)	none independently blocked	low (can use live ../detections in suite-e2e)
missions mock	none	Mp1–Mp5 (5 rows)	medium
Ground Station trace	none	R4, O8 (2 rows)	low (inline-authorable)
MAVLink SITL	none	R4, R5, R6, R7, R9 (5 rows) + project conformance gate	high
Frame sequences	L1 (with image), T3 (with video)	enriches L6/L7 with telemetry	medium
Gimbal CSV	none	M1–M4 (4 rows) + L6, L7	high — explicit user gap
VLM I/O pairs	none	L3, S5 (2 rows)	low (model-choice gated)
Operator envelopes	none	O9, O10 (2 rows)	blocked on Q9
GPS/NTP drift	none	R8	low (inline-authorable)

Per-row binding lives in expected_results/results_report.md. The status of each gap is mirrored in _docs/_process_leftovers/ so the next /autodev run can replay the missing-fixture decision.

What this file does NOT own

• Component design (how detection_client talks to Tier-1, how mission_client retries, etc.) — _docs/02_document/architecture.md and _docs/02_document/components/*/description.md.
• Production data shapes (frame rate, MAVLink message types) — data_parameters.md already has these.
• AC text — _docs/00_problem/acceptance_criteria.md.
• The choice of which mocks to use during a given test run (live vs replay vs scripted) — _docs/02_document/tests/ (test strategy doc, authored by /test-spec Phase 2).