mirror of
https://github.com/azaion/autopilot.git
synced 2026-06-21 14:41:09 +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,87 @@
|
||||
# Component — `mavlink_layer`
|
||||
|
||||
**Layer**: Action (data plane out)
|
||||
**Status**: forward-looking design (Rust); hand-rolled (no third-party SDK)
|
||||
|
||||
## 1. Purpose
|
||||
|
||||
Hand-rolled MAVLink v2 transport. Implements only the ~10–15 commands this codebase needs (full list in `architecture.md §7.7`). Owns serialisation / deserialisation, heartbeat, sequence numbers, retry, and a single connection abstraction (UDP or serial, picked at startup from CLI / env). No third-party SDK — eliminating the largest current dependency-risk item.
|
||||
|
||||
## 2. Inputs
|
||||
|
||||
| Input | Source | Cadence | Notes |
|
||||
|---|---|---|---|
|
||||
| Outgoing `COMMAND_LONG`, `MISSION_*`, `SET_MODE` | `mission_executor` | per state transition | Hand-rolled message constructors per command. |
|
||||
| Outgoing heartbeat | self (timer) | 1 Hz | `HEARTBEAT` to keep the autopilot's GCS-link alive. |
|
||||
| Connection URI | startup config | once | `udp://...` or `serial:///dev/...`. |
|
||||
| MAVLink-2 signing config | startup config | once | If supported by the link, signing is enabled; otherwise the link is treated as trusted. |
|
||||
|
||||
## 3. Outputs
|
||||
|
||||
| Output | Consumer | Shape |
|
||||
|---|---|---|
|
||||
| Decoded MAVLink messages | `mission_executor`, `telemetry_stream`, `movement_detector` (for UAV motion telemetry) | typed enum per message kind |
|
||||
| Connection state | health aggregator | `connected`, `last_heartbeat_age_ms`, `tx_seq`, `rx_seq`, `parse_errors_total`, `signing_enabled`. |
|
||||
|
||||
The supported message surface (concise list; full table in `architecture.md §7.7`):
|
||||
|
||||
- `HEARTBEAT` (bidir)
|
||||
- `COMMAND_LONG` subset (out): arm/disarm, takeoff, set-mode, change-speed, change-alt, land, RTL
|
||||
- `COMMAND_ACK` (in)
|
||||
- `MISSION_COUNT`, `MISSION_REQUEST_INT`, `MISSION_ITEM_INT`, `MISSION_ACK`, `MISSION_SET_CURRENT`, `MISSION_CURRENT`, `MISSION_ITEM_REACHED`, `MISSION_CLEAR_ALL`
|
||||
- `GLOBAL_POSITION_INT`, `ATTITUDE`, `SYS_STATUS`, `EXTENDED_SYS_STATE`, `STATUSTEXT`
|
||||
- `SET_MODE` (out, fixed-wing)
|
||||
|
||||
## 4. Key Responsibilities
|
||||
|
||||
- Open and maintain the MAVLink connection (UDP or serial). Reconnect on transport loss with bounded backoff.
|
||||
- Encode outgoing messages with correct sequence numbers, system / component IDs, and (when enabled) MAVLink-2 signing.
|
||||
- Decode incoming messages with strict validation: reject malformed frames, unknown message IDs, and signing failures.
|
||||
- Emit a 1 Hz heartbeat. Detect autopilot heartbeat timeouts and surface to health.
|
||||
- Demux `COMMAND_ACK` to the originating caller (per `command_id`); enforce a wall-clock ack timeout.
|
||||
|
||||
## 5. Internal State
|
||||
|
||||
- Connection handle (UDP socket or serial port).
|
||||
- Outgoing sequence number.
|
||||
- In-flight command map (`command_id → (caller, deadline)`).
|
||||
- Per-message-kind parse error counters.
|
||||
|
||||
State is in-process only.
|
||||
|
||||
## 6. Failure Modes
|
||||
|
||||
| Failure | Detection | Behaviour |
|
||||
|---|---|---|
|
||||
| Transport open failure | OS error | Bounded backoff; surface to health → red. |
|
||||
| Heartbeat from autopilot missing | wall-clock timeout | Surface `link_lost` to health and to `mission_executor`; do not silently fail. |
|
||||
| Command-ack timeout | wall-clock | Bubble timeout to `mission_executor`; the executor decides retry vs failure. |
|
||||
| Malformed inbound frame | parser error | Drop the frame; increment counter; do not abort the link. |
|
||||
| MAVLink-2 signing mismatch (if enabled) | signature check | Reject the frame; alert; do not silently accept. |
|
||||
| Sequence-number gap | rx_seq vs expected | Log; not a hard failure on its own. |
|
||||
|
||||
## 7. Dependencies
|
||||
|
||||
**In-process** (input): `mission_executor`.
|
||||
**In-process** (output): `mission_executor`, `telemetry_stream`, `movement_detector`.
|
||||
|
||||
**External**: ArduPilot / PX4 over MAVLink v2 (UDP or serial).
|
||||
|
||||
## 8. Non-Functional Targets
|
||||
|
||||
| Concern | Target |
|
||||
|---|---|
|
||||
| Per-message round-trip on a healthy link | ≤50 ms p99 |
|
||||
| Heartbeat cadence | 1 Hz out |
|
||||
| Command-ack timeout | configurable; default 1 s, with retry handled by `mission_executor` |
|
||||
| Reconnect after transport loss | ≤2 s on serial / ≤5 s on UDP |
|
||||
| Message subset | ~10–15 commands only — adding more requires explicit design review |
|
||||
|
||||
## 9. Open Questions
|
||||
|
||||
- **MAVLink-2 message signing** (`architecture.md §8 Q6`): whether the airframe link enables signing or treats the link as trusted.
|
||||
|
||||
## 10. References
|
||||
|
||||
- `architecture.md §3`, `§5 Architectural Principles` (no MAVSDK, no silent error swallowing), `§7.7 MAVLink and Piloting`.
|
||||
- `system-flows.md §F6 Mission lifecycle`.
|
||||
Reference in New Issue
Block a user