mirror of
https://github.com/azaion/autopilot.git
synced 2026-06-21 17:11:10 +00:00
Oleksandr Bezdieniezhnykh
bc40ea7300
Greenfield Steps 1-6 baseline for the autopilot rewrite from legacy Qt/C++ to a Rust workspace. - Remove legacy Qt/C++ tree (ai_controller, drone_controller, misc/camera, python_scaffold, root Dockerfile, autopilot.pro, legacy main.py / requirements.txt). - Add _docs/00_problem (problem, restrictions, acceptance criteria, security approach, input data + fixtures). - Add _docs/01_solution/solution_draft01. - Add _docs/02_document (architecture, system-flows, data_model, glossary, decision-rationale, deployment, 13 component descriptions, tests/ specs, FINAL_report, module-layout). - Add _docs/02_tasks/todo with 47 task specs (AZ-640..AZ-686, one bootstrap + 46 component tasks) and _dependencies_table.md. - Add .cursor/rules/artifact-srp.mdc (single-responsibility rule for canonical _docs artifacts). - Track autodev state in _docs/_autodev_state.md (Step 6 completed, ready for Step 7 Implement). Jira: bootstrap AZ-626; component epics AZ-627..AZ-639; tasks AZ-640..AZ-686. Total complexity 173 points across 12 epics. Co-authored-by: Cursor <cursoragent@cursor.com>
4.0 KiB
4.0 KiB
Component — telemetry_stream
Layer: Telemetry plane (always-on, parallel to the decision loop) Status: forward-looking design (Rust)
1. Purpose
Continuous, always-on push of the camera feed + UAV telemetry + bbox overlay to the Ground Station API over modem. Carries operator commands (confirm / decline / target-follow start / target-follow release) on the return path. Independent of the decision loop — the operator always sees the live feed, not just on detection.
2. Inputs
| Input | Source | Cadence | Notes |
|---|---|---|---|
Decoded Frame |
frame_ingest |
up to 30 fps | Re-encoded for the modem link bandwidth. |
DetectionBatch |
detection_client |
per frame | Used to build the bbox overlay (server-burn-in or client-render — see Open Questions). |
MovementCandidate (zoom-out + zoom-in) |
scan_controller (forwarded) |
per candidate | Surfaced in operator overlay; the source_zoom_band tag is preserved so the overlay can render zoom-out vs zoom-in candidates differently. |
| UAV telemetry | mavlink_layer (via mission_executor) |
10 Hz | Position, attitude, mode, sys-status. |
| Gimbal state | gimbal_controller |
per change | yaw / pitch / zoom. |
POI events |
operator_bridge |
per POI surface / dequeue | Passed straight through. |
| Operator commands | Ground Station (return path) | event | Forwarded to operator_bridge. |
3. Outputs
| Output | Consumer | Shape |
|---|---|---|
| Outbound stream | Ground Station API (over modem) | per stream protocol (TBD — see Open Questions) |
| Inbound operator commands | operator_bridge |
event |
| Health metric | health aggregator | link_state, bandwidth_used_mbps, frame_drop_rate, last_command_received_ts. |
4. Key Responsibilities
- Encode and push the camera feed + telemetry + bbox overlay continuously, regardless of detection state.
- Apply bandwidth-aware rate adaptation (drop bbox-overlay frequency before frame frequency; drop frame frequency before resolution).
- Surface the modem link state to the health aggregator;
operator_bridgeconsults this to decide whether to surface POIs. - Receive operator commands on the return path; forward to
operator_bridgewith monotonic timestamps.
5. Internal State
- Stream session handle.
- Rate-adaptation state machine.
- In-flight frame buffer (bounded).
State is in-process only.
6. Failure Modes
| Failure | Detection | Behaviour |
|---|---|---|
| Modem link down | transport error / heartbeat | Surface link_lost; pause outbound push (do not buffer indefinitely); operator_bridge pauses POI surfacing. |
| Bandwidth saturation | adaptive monitor | Reduce bbox-overlay rate, then frame rate, then resolution; surface to health → yellow. |
| Inbound command unparseable | parser error | Reject; ack with error; do not act. |
| Inbound command from unauthenticated peer | session check (per Ground Station contract) | Reject; alert. |
7. Dependencies
In-process (input): frame_ingest, detection_client, scan_controller, mavlink_layer, gimbal_controller, operator_bridge.
In-process (output): operator_bridge (return-path commands).
External: Ground Station API. Contract owner: ../_docs/04_system_design_clarifications.md.
8. Non-Functional Targets
| Concern | Target |
|---|---|
| End-to-end glass-to-operator latency | bounded by modem characteristics; target ≤2 s p99 on a healthy link |
| Always-on | yes; not detection-gated |
| Rate adaptation | smooth; no sudden full-resolution → no-feed transitions |
| Outbound buffering | bounded; no unbounded growth on slow link |
9. Open Questions
- Ground Station API contract (
architecture.md §8 Q2): stream protocol (WebRTC / WebSocket-H.264 / gRPC server-streaming?), session/auth model, bbox-overlay rendering (server-side burn-in vs client-side render).
10. References
architecture.md §3,§5 Architectural Principles(always-on stream, no silent error swallowing),§7.6 Integration and reliability.system-flows.md §F5 Operator round trip.../_docs/04_system_design_clarifications.md.