mirror of
https://github.com/azaion/autopilot.git
synced 2026-06-21 17:11:10 +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 — `gimbal_controller`
|
||||
|
||||
**Layer**: Action (data plane out)
|
||||
**Status**: forward-looking design (Rust); ViewPro A40 vendor protocol
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
Drives the ViewPro A40 gimbal: pan (yaw), tilt (pitch), and zoom. Honours the ≤2 s zoom-transition budget and ≤500 ms decision-to-movement latency. Owns the zoom-out sweep, the smooth-pan path-tracking primitive used during the zoom-in level (follow-the-footpath behaviour), and the centre-window primitive used during target-follow.
|
||||
|
||||
## 2. Inputs
|
||||
|
||||
| Input | Source | Cadence | Notes |
|
||||
|---|---|---|---|
|
||||
| `GimbalCommand` | `scan_controller` | per state-machine tick or per zoom-in plan step | yaw / pitch / zoom goal; or pan plan; or centre-on-target. |
|
||||
| Sweep config | startup config | once | Zoom-out sweep pattern (pendulum / raster / lawn-mower — see `architecture.md §8 Q1`). |
|
||||
| Live gimbal status | ViewPro A40 (vendor protocol) | as emitted by camera | yaw / pitch / zoom feedback + faults. |
|
||||
|
||||
## 3. Outputs
|
||||
|
||||
| Output | Consumer | Shape |
|
||||
|---|---|---|
|
||||
| Vendor-protocol commands | ViewPro A40 (UDP) | yaw / pitch / zoom commands |
|
||||
| `GimbalState` | `frame_ingest` (for telemetry tagging), `movement_detector` (for ego-motion compensation) | `{ yaw, pitch, zoom, ts_monotonic, command_in_flight: bool }` |
|
||||
| Health metric | health aggregator | `commands_per_min`, `decision_to_movement_p99_ms`, `zoom_transition_p99_ms`, `vendor_faults_total`. |
|
||||
|
||||
## 4. Key Responsibilities
|
||||
|
||||
- Send vendor-protocol commands to the ViewPro A40 over UDP. Re-issue on timeout with bounded retry.
|
||||
- Run the zoom-out sweep pattern when `scan_controller` is in `ZoomedOut` (pattern itself depends on `architecture.md §8 Q1` resolution).
|
||||
- For the zoom-in path-follow, accept a pan plan (sequence of yaw / pitch / zoom goals with timing) from `scan_controller` / `semantic_analyzer` and execute it smoothly.
|
||||
- For target-follow, accept a centre-on-target stream (target bbox normalized) from `scan_controller` and command the gimbal to keep the target inside the centre 25 % of frame while visible.
|
||||
- Stamp every emitted command with a monotonic timestamp so `movement_detector` can synchronise it with frames.
|
||||
- Surface vendor-protocol faults to health and to `scan_controller`.
|
||||
|
||||
## 5. Internal State
|
||||
|
||||
- Last-known commanded yaw / pitch / zoom.
|
||||
- Last-known reported yaw / pitch / zoom (from gimbal feedback).
|
||||
- Sweep pattern state (current direction, dwell counter).
|
||||
- Current execution mode: `Sweep | PanPlan | CentreOnTarget | Idle`.
|
||||
|
||||
State is in-process only.
|
||||
|
||||
## 6. Failure Modes
|
||||
|
||||
| Failure | Detection | Behaviour |
|
||||
|---|---|---|
|
||||
| ViewPro A40 not responding | command timeout | Bounded exponential backoff; health → yellow then red; `scan_controller` is informed and may pause zoom-in. |
|
||||
| Decision-to-movement above budget | self-instrumented | Health → yellow; investigate (likely UDP loss or vendor firmware issue). |
|
||||
| Zoom transition stalls | feedback shows no zoom progress | Re-issue command; health → yellow; report to `scan_controller`. |
|
||||
| Target lost during target-follow | feedback + tracker | Surface `target_lost` to `scan_controller`; controller decides to release follow. |
|
||||
| Conflicting commands | execution-mode mismatch | Reject the lower-priority command; log a hard error; never silently merge. |
|
||||
|
||||
## 7. Dependencies
|
||||
|
||||
**In-process** (input): `scan_controller`.
|
||||
**In-process** (output): `frame_ingest`, `movement_detector` (timestamped state).
|
||||
|
||||
**External**: ViewPro A40 over UDP (vendor protocol).
|
||||
|
||||
## 8. Non-Functional Targets
|
||||
|
||||
| Concern | Target |
|
||||
|---|---|
|
||||
| Decision-to-movement latency | ≤500 ms |
|
||||
| Zoom transition (medium → high) | ≤2 s |
|
||||
| Sweep pattern stability | bounded jitter; no overshoot beyond configured FOV bounds |
|
||||
| Target-follow centre-window | target inside centre 25 % of frame while visible |
|
||||
|
||||
## 9. Open Questions
|
||||
|
||||
- Sweep pattern specification (`architecture.md §8 Q1`): pendulum / raster / lawn-mower; FOV per zoom tier; dwell time per direction.
|
||||
|
||||
## 10. References
|
||||
|
||||
- `architecture.md §3`, `§6 NFR`, `§7.6 Solution Architecture`.
|
||||
- `system-flows.md §F2 Movement detection (zoom-out + zoom-in)`.
|
||||
- `data_model.md §GimbalState`.
|
||||
Reference in New Issue
Block a user