autopilot/_docs/02_document/glossary.md

autopilot — Glossary

Status: confirmed-by-user (2026-05-17), updated for the rewrite paradigm.

Project-specific terms only. Generic CS / industry terms (RTSP, gRPC, FastAPI, MAVLink, JSON, etc.) are intentionally omitted.

---

AUTO mode — fixed-wing autopilot flight mode in which the airframe follows its uploaded mission. mission_executor's fixed-wing variant uploads the mission and waits for the operator to switch the airframe into AUTO via RC; only then does it transition to FLY_MISSION. source: architecture.md §7.7.

Behaviour tree (BT) — hierarchical decision-making model (Selector / Sequence / Condition / Action / Decorator) ticked from the root every cycle. The canonical decomposition of scan_controller's logic. The implementation may use a typed deterministic state machine that satisfies the same priorities, preemption, and tick scenarios. source: system-flows.md §F4.

Benchmark gate — proof-of-concept milestone. Tier 1 ≤100 ms/frame, Tier 2 ≤200 ms/ROI, VLM ≤5 s/ROI, A40 transition ≤2 s, decision-to-movement ≤500 ms, ≤5 POIs/min. Must pass before product code begins. source: architecture.md §7.6 Benchmark gate.

../detections — separate sibling repo. FastAPI / Cython service running TensorRT YOLO26 + YOLOE-26 FP16 engines. Tier 1 primitive detection lives here, NOT in autopilot. Consumed by detection_client over bi-directional gRPC. source: architecture.md §1, ../_docs/03_detections.md.

detection_client — autopilot component: bi-directional gRPC client to ../detections; streams frames out, receives bounding boxes back; same bboxes are reused for Tier 2 ROI selection and for operator overlay. source: components/detection_client/description.md.

Confidence-scaled timeout — operator-decision window scales linearly with target confidence: 40 % → 30 s, 100 % → 120 s. Below 40 % a target is not surfaced. Timeout = forget; decline = IgnoredItem entry. source: architecture.md §5 Architectural Principles.

Ego-motion compensation — separating target motion from platform motion in movement_detector, using synchronised video + gimbal angle + zoom state + UAV telemetry. Naive frame-differencing is explicitly rejected. Per-zoom-band thresholds: tighter at zoom-in. source: architecture.md §5 Architectural Principles, components/movement_detector/description.md.

Flight-gate — suite-wide convention: a marker file (/run/azaion/in-flight) written by autopilot at startup and removed at shutdown, read by model-sync.service to defer model swaps during flight. source: ../_docs/00_top_level_architecture.md, deployment/containerization.md §3.

frame_ingest — autopilot component: pulls RTSP from ViewPro A40, decodes, timestamps, hands frames to detection_client, movement_detector, and telemetry_stream. source: components/frame_ingest/description.md.

Geofence (INCLUSION / EXCLUSION) — polygonal area constraint in the mission. Both are enforced symmetrically in the rewrite (mission_executor); a violation triggers RTL. source: architecture.md §5 Architectural Principles, §7.7 MAVLink and Piloting, components/mission_executor/description.md.

gimbal_controller — autopilot component: ViewPro A40 control protocol (yaw / pitch / zoom) + zoom-out sweep + zoom-in path-follow + target-follow centre-window. source: components/gimbal_controller/description.md.

Ground Station API — external, out-of-this-repo service that receives a continuous camera + telemetry stream from each UAV and hosts the operator browser UI (bbox overlay, target confirm/decline). Not built; not in autopilot scope. source: architecture.md §1, ../_docs/04_system_design_clarifications.md.

Hand-rolled MAVLink layer — mavlink_layer implements the ~10–15 MAVLink commands this codebase actually uses with no third-party SDK. Eliminates the largest dependency-risk item. source: architecture.md §7.7, components/mavlink_layer/description.md.

H3 spatial index — hexagonal hierarchical geospatial indexing used by mapobjects_store for fast new / moved / existing / removed diffs. source: architecture.md §7.9, components/mapobjects_store/description.md.

IgnoredItem — operator-declined target. Persisted in mapobjects_store as (MGRS, class_group); new detections matching an entry are suppressed before reaching the operator. source: architecture.md §7.12, components/mapobjects_store/description.md, data_model.md §IgnoredItem.

Jetson Orin Nano — edge-device compute platform (NVIDIA, aarch64, CUDA-capable). 8 GB shared LPDDR5; ~2 GB used by Tier 1, ~6 GB available for the rest of autopilot + VLM. source: architecture.md §7.3.

Zoom-out / zoom-in scan — two-tier search behaviour. Zoom-out level = wide / light-medium zoom sweep along the UAV route, runs movement_detector + Tier 1. Zoom-in level = zoom into a queued POI for Tier 2 ROI analysis + optional VLM confirmation; movement_detector continues to run with per-zoom-band thresholds. State-machine variants: ZoomedOut, ZoomedIn { roi, hold_started_at }. source: architecture.md §7.1, components/scan_controller/description.md.

MapObject — entry in mapobjects_store; keyed by H3_cell + class; carries GPS, size, class, and a list of recent observations. source: architecture.md §7.9, data_model.md §MapObject.

mapobjects_store — autopilot component: on-device H3-indexed map of detected objects + ignored-items list. No REST API. source: components/mapobjects_store/description.md.

mavlink_layer — autopilot component: hand-rolled MAVLink v2 transport + the small command set this codebase needs. source: components/mavlink_layer/description.md.

MGRS — Military Grid Reference System; primary coordinate encoding for autopilot ⇄ operator sync messages and for mapobjects_store keys. source: architecture.md §7.10, data_model.md §MGRS sync message.

Middle waypoint — autopilot-inserted waypoint between the current position and the next mission waypoint, computed from an operator-confirmed POI. Triggers a mission re-upload (MISSION_CLEAR_ALL + standard upload sequence). source: architecture.md §7.7, components/mission_executor/description.md.

mission_client — autopilot component: pulls the mission from the missions API on start; POSTs middle-waypoint inserts; honours the mission cascade signal. source: components/mission_client/description.md.

mission_executor — autopilot component: variant-specific (multirotor / fixed-wing) state machine that drives the airframe through connect → health-check → arm/takeoff (multirotor) or wait-for-AUTO (fixed-wing) → upload → fly → land. Owns geofence enforcement. source: architecture.md §7.7, components/mission_executor/description.md.

mission-schema — shared schema artefact between autopilot and missions repos. Extraction location TBD (_infra/ at suite root, or a small third repo) — architecture.md §8 Q5. source: architecture.md §5.

missions — separate sibling repo (.NET service). Hosts the missions REST API. Stays separate from autopilot; the two share mission-schema. source: ../_docs/02_missions.md.

Movement candidate — small moving point/cluster emitted by movement_detector in either zoom-out or zoom-in. Tagged with source_zoom_band. Promoted to a zoom-in POI by scan_controller (or used to bump in-progress ROI confidence at zoom-in). source: architecture.md §7.4, data_model.md §MovementCandidate.

movement_detector — autopilot component: OpenCV optical-flow / global-motion estimation with mandatory ego-motion compensation. Active at both zoom-out and zoom-in (suppressed only during target-follow); per-zoom-band thresholds. Classical-CV adequacy at zoom-in is benchmark-gated; learned-CV fallback per Q14. source: components/movement_detector/description.md.

operator_bridge — autopilot component: surfaces POIs (via telemetry_stream → Ground Station) for operator confirm / decline; forwards target-follow start / release; on decline appends an IgnoredItem. source: components/operator_bridge/description.md.

Optionality model (VLM) — VLM is the only optional Tier. Two complementary mechanisms: a runtime vlm_enabled flag, and a build-time feature module. The system MUST function correctly with VLM absent. source: architecture.md §7.6 Local VLM confirmation > Optionality model, components/vlm_client/description.md §9.

POI (Point of Interest) — a queued candidate for zoom-in inspection (footpath start, branch pile, tree row, movement candidate, etc.). source: architecture.md §7.1, data_model.md §POI.

POI queue — operator-review queue inside scan_controller; ordered by confidence × proximity × age_factor; hard cap of ≤5 POIs/min to bound operator workload. source: architecture.md §5, components/scan_controller/description.md.

RTL (Return-to-Launch) — MAVLink-driven return to the configured rally point; triggered by INCLUSION / EXCLUSION violation, by max-retry exhaustion in mission_executor, or by failsafe in the autopilot itself. source: architecture.md §7.7, components/mission_executor/description.md.

Scan controller — autopilot component: central deterministic typed state machine — ZoomedOut, ZoomedIn, TargetFollow. Owns POI queue, timeouts, gimbal commands, ≤5 POIs/min cap. source: architecture.md §7.6 Scan controller and POI queue, components/scan_controller/description.md (full BT spec in system-flows.md §F4).

semantic_analyzer — autopilot component (Tier 2): primitive graph + lightweight ROI CNN, reasoning over paths, branch piles, dark entrances, etc. source: components/semantic_analyzer/description.md.

SITL conformance gate — CI stage in which autopilot runs against ArduPilot SITL with a mocked ../detections and a fixture mission, asserting the MAVLink command surface and geofence enforcement. source: deployment/ci_cd_pipeline.md §5.

Sweep — zoom-out camera motion: gimbal swings left-right across the UAV's flight path while the UAV flies the mission. Exact pattern (pendulum / raster / lawn-mower), FOV per zoom tier, dwell time, and mission-segment alignment are unresolved (architecture.md §8 Q1). source: architecture.md §7.1, components/gimbal_controller/description.md.

Target-follow mode — gimbal keeps an operator-confirmed target centred (within the centre 25 % of frame) while the UAV continues to move. Ends on operator release or tracking loss. State-machine variant: TargetFollow { target_id, started_at }. source: architecture.md §7.1, components/scan_controller/description.md.

telemetry_stream — autopilot component: continuous (always-on) push of camera frames + flight telemetry + bbox overlay over modem to the Ground Station API. Operator always sees live feed, not just on detection. Carries operator commands on the return path. source: components/telemetry_stream/description.md.

Tier 1 detection — primitive YOLO over the full frame; delegated to ../detections. source: architecture.md §7.6 Tier 1 primitive detector.

Tier 2 semantic — primitive-graph + lightweight ROI CNN reasoning over zoom-in crops; lives in autopilot. source: architecture.md §7.6 Tier 2 semantic analyzer.

Tier 3 / VLM (Vision Language Model) — NanoLLM running VILA1.5-3B in a separate local process, invoked only for bounded zoom-in ROI confirmation. Local IPC over Unix domain socket with peer-credential check. No cloud egress. Optional. source: architecture.md §7.6 Local VLM confirmation, components/vlm_client/description.md, system-flows.md §F3.

vlm_client — autopilot component: optional local-IPC client to a NanoLLM/VILA1.5-3B process; validates ROI payload, calls VLM, validates response against the VlmAssessment schema. source: components/vlm_client/description.md.

VlmAssessment — structured-schema output from the VLM. The free-form VLM text is not a downstream API contract. source: architecture.md §5 Architectural Principles, data_model.md §VlmAssessment.

ViewPro A40 — deployment gimbal hardware. NFR budget: zoom transition ≤2 s, decision-to-movement ≤500 ms. source: architecture.md §7.3, components/gimbal_controller/description.md.

Waypoint — mission node coordinate (lat, lon, alt). Pulled from the missions API by mission_client; the operator-confirm flow may insert a middle waypoint to detour toward a confirmed target. source: architecture.md §7.7, data_model.md §MissionWaypoint.

BIT (Built-In Self Test) — pre-flight gate run by mission_executor. Covers GPS lock, camera RTSP, gimbal homing, ../detections, VLM warmup (if enabled), mission load, MapObjects pre-flight pull, persistent-store free space, wall-clock binding, MAVLink + airframe health. Items return OK | DEGRADED | FAIL. DEGRADED requires signed operator acknowledgement. FAIL blocks transition past HEALTH_OK. source: architecture.md §5 / §7.3, system-flows.md §F9.

Lost-link failsafe ladder — typed ladder evaluated each tick by mission_executor against the operator/Ground-Station modem heartbeat: LinkOk (≤5 s) → LinkDegraded (≤30 s, queue events, health yellow) → LinkLost (>30 s, no follow) → LinkLostInFollow (>30 s in target-follow, +30 s grace). Default action on lost link is RTL. MAVLink-link loss to ArduPilot itself is a separate, more severe event. source: architecture.md §5 / §7.7, system-flows.md §F10.

MapObjects sync — pre-flight pull + post-flight push of MapObjects + IgnoredItems against the central missions API extension /missions/{id}/mapobjects. In-flight is batched only (no streaming over modem). On-device store is a working copy; central store is the source of truth across missions. source: architecture.md §5 / §7.13, system-flows.md §F8, components/mapobjects_store/description.md, components/mission_client/description.md.

Per-zoom-band thresholds — movement_detector configuration is split between zoom-out and zoom-in because the pixel-to-metre ratio differs by ~10×. Cluster persistence threshold, residual-velocity floor, telemetry-skew tolerance, and enqueue-latency budget are all per-band. source: architecture.md §7.6 Movement detector, components/movement_detector/description.md §5.

Operator-command authentication — every operator command (confirm / decline / target-follow / safety-override / BIT-degraded-acknowledge) carries a session-bound signature with replay protection, validated by operator_bridge before dispatch. The principle is committed; the exact scheme is open per Q9. source: architecture.md §5 / §8 Q9, components/operator_bridge/description.md.

Sync state (mapobjects_store) — synced | cached_fallback | degraded. synced after a fresh successful pull or a successful post-flight push. cached_fallback when pre-flight pull failed and the operator acknowledged continuing on cache. degraded after a persistent push failure or a stale cache. scan_controller suppresses MapObject diff classifications while degraded to avoid corrupting the central observation log. source: components/mapobjects_store/description.md §5.

Wall-clock source — autopilot binds wall-clock to GPS time once GPS is locked (preferred) or to NTP at boot if reachable. Drift > 200 ms surfaces health → yellow. Monotonic clock (independent of wall-clock) is authoritative for telemetry-skew compensation and tick budgets. source: architecture.md §7.3 Reliability and safety.