mirror of
https://github.com/azaion/autopilot.git
synced 2026-06-21 16:21:11 +00:00
[AZ-626] Decompose complete: 47 tasks + docs + module layout
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>
This commit is contained in:
@@ -0,0 +1,78 @@
|
||||
# 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_bridge` consults this to decide whether to surface POIs.
|
||||
- Receive operator commands on the return path; forward to `operator_bridge` with 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`.
|
||||
Reference in New Issue
Block a user