alro65
700756c16f
Initial commit. Delivers what the brief calls 'Sprint 0 - Foundations' (see docs/AR_Autopilot_brief.md section 12): - Complete repository structure (arautopilot package + firmware, display, installer, tools placeholders + docs). - Core data model (Pydantic v2): modes, alarms, actuator config, PID config + gain scheduling, vessel config, knob state machine, project config with YAML/JSON serialisation. - Seed library: 2 actuator profiles (hydraulic & electric DC reversible) and 2 default tunings (yacht motor planeo 30 m and 40 m). Conservative literature values, NOT the integrator's production tuning IP. - Firmware skeleton: only src/hal/pinout.h with the 21 I/O contract for the AR-NMEA-IO v1.0 board. No drivers, no main loop. - Studio stubs (real PySide6 app starts in Sprint 4). - pytest suite (80 tests, all green): modes, alarms, actuator, PID (incl. gain interpolation and the +/-50% adaptive bound from brief section 6), vessel, knob state, project config, library loader, end-to-end roundtrip. - examples/sprint0_demo.py - the acceptance demo from the brief. Acceptance criteria met: - pytest green (80/80) - demo creates, saves (YAML + JSON), reloads, and verifies a full ProjectConfig using the seed library - repository ready for tag `sprint-0-approved` See CHANGELOG.md for the detailed scope. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
138 lines
9.9 KiB
Markdown
138 lines
9.9 KiB
Markdown
# AR-Autopilot — Architecture overview
|
|
|
|
> One-page architectural overview. For full scope, see [`AR_Autopilot_brief.md`](AR_Autopilot_brief.md).
|
|
|
|
---
|
|
|
|
## Three deployment units + one configuration tool
|
|
|
|
```
|
|
┌──────────────────────────────────────────────────────────────────────────────┐
|
|
│ INTEGRATOR-SIDE (Alvaro's PC) │
|
|
│ │
|
|
│ ┌────────────────────────────────────────────────────────────────────┐ │
|
|
│ │ AR-Autopilot Studio — Python 3.11 + PySide6 │ │
|
|
│ │ • Per-project configurator │ │
|
|
│ │ • Vessel profile + actuator selection + initial PID gains │ │
|
|
│ │ • Generates per-vessel signed .appack + MSI installer │ │
|
|
│ │ • NOT shipped to customer │ │
|
|
│ └────────────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ │ .appack (signed config + firmware) │
|
|
└──────────────────────────────────┼───────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌──────────────────────────────────────────────────────────────────────────────┐
|
|
│ CUSTOMER VESSEL (per-vessel HWID license) │
|
|
│ │
|
|
│ ┌─────────────────────────────────┐ ┌────────────────────────────┐ │
|
|
│ │ Bridge Console │ │ Tech Cabinet │ │
|
|
│ │ │ │ │ │
|
|
│ │ ┌──────────────────────────┐ │ Modbus │ ┌──────────────────────┐ │ │
|
|
│ │ │ AR-Autopilot Display │◄──┼─ RTU ──►│ │ AR-NMEA-IO v1.0 │ │ │
|
|
│ │ │ Flutter Desktop │ │ RS-485 │ │ (ESP32-DOWD) │ │ │
|
|
│ │ │ (Mini-PC or RPi5) │ │ │ │ │ │ │
|
|
│ │ │ │ │ │ │ • PID inner 50 Hz │ │ │
|
|
│ │ │ • Compass rose │ │ │ │ • PID outer 10 Hz │ │ │
|
|
│ │ │ • Rudder indicator │ │ │ │ • ROT feed-forward │ │ │
|
|
│ │ │ • Mode selector │ │ │ │ • Gain scheduling │ │ │
|
|
│ │ │ • DISENGAGE button │ │ │ │ • Safety / alarms │ │ │
|
|
│ │ │ │ │ │ │ • Watchdog 2 s │ │ │
|
|
│ │ │ Inputs: │ │ │ │ │ │ │
|
|
│ │ │ Trackball USB │ │ │ │ 21 I/O: │ │ │
|
|
│ │ │ Knob (panel encoder) │───┼─DI A/B/SW─►│ AI1..AI4 │ │ │
|
|
│ │ │ Disengage button │───┼──DI1───►│ │ DI1..DI5 │ │ │
|
|
│ │ └──────────────────────────┘ │ │ │ RPM1 │ │ │
|
|
│ │ │ │ │ DO1..DO10 │ │ │
|
|
│ └─────────────────────────────────┘ │ └──────────────────────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ │ NMEA 2000 │ │
|
|
│ │ ▼ │ │
|
|
│ │ ┌──────────────────────┐ │ │
|
|
│ │ │ Vessel N2K backbone │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ Subscribes: │ │ │
|
|
│ │ │ 127250 Heading │ │ │
|
|
│ │ │ 127251 ROT │ │ │
|
|
│ │ │ 129025/9 Position │ │ │
|
|
│ │ │ 129026 COG/SOG │ │ │
|
|
│ │ │ 129284 Nav Data │ │ │
|
|
│ │ │ │ │ │
|
|
│ │ │ Publishes: │ │ │
|
|
│ │ │ 127245 Rudder │ │ │
|
|
│ │ │ 127237 Heading Ctl │ │ │
|
|
│ │ └──────────────────────┘ │ │
|
|
│ │ │ │ │
|
|
│ │ ▼ │ │
|
|
│ │ to actuator: pump / motor│ │
|
|
│ │ + rudder feedback sensor │ │
|
|
│ └────────────────────────────┘ │
|
|
└──────────────────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Why the PID lives on the ESP32, not on the display
|
|
|
|
- **Deterministic latency** — fixed loop frequency, no OS jitter
|
|
- **Safety** — if the display crashes or reboots, steering keeps working
|
|
(degraded mode, last good setpoint, alarm raised)
|
|
- **Efficiency** — ESP32-DOWD dual-core at 240 MHz runs the cascaded PID
|
|
in microseconds
|
|
|
|
The display is a **rich UI client** of the autopilot, not its brain.
|
|
|
|
---
|
|
|
|
## Configuration layering (same model as VMS-Sailor)
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────┐
|
|
│ Layer 3 — Owner preferences │
|
|
│ favorite headings, profile (Soft/Normal/Sport), │
|
|
│ alarm sensitivity, brightness, volume │
|
|
├─────────────────────────────────────────────────────┤
|
|
│ Layer 2 — Field commissioning │
|
|
│ actual rudder mechanical limits, affinated gains, │
|
|
│ calibration offsets │
|
|
├─────────────────────────────────────────────────────┤
|
|
│ Layer 1 — Base package (.appack from Studio) │
|
|
│ actuator type, sensors, default gains for vessel │
|
|
│ type, initial configuration │
|
|
└─────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
Each layer overrides the layer below. Firmware/gain updates ship as
|
|
**signed deltas** approved by an explicit work order.
|
|
|
|
---
|
|
|
|
## Sprint 0 scope (what this commit delivers)
|
|
|
|
**Yes:**
|
|
- Complete repository layout
|
|
- Core data model (Pydantic v2) for everything above
|
|
- 2 seed actuator profiles + 2 seed default tunings (conservative literature
|
|
values, not the integrator's IP tunings)
|
|
- Firmware `pinout.h` only — the 21 I/O contract
|
|
- Test suite + end-to-end demo
|
|
|
|
**No (later sprints):**
|
|
- Functional firmware, PID, filters, EKF, auto-tuning
|
|
- Studio GUI, display Flutter app
|
|
- Modbus, NMEA 2000, OTA, VPN, HWID activation
|
|
|
|
---
|
|
|
|
## Further reading
|
|
|
|
| Document | When | What |
|
|
|---|---|---|
|
|
| [`AR_Autopilot_brief.md`](AR_Autopilot_brief.md) | Now | Full project brief — scope, modes, hardware, sprints |
|
|
| `pid_tuning_guide.md` | Sprint 7 | Field tuning methodology |
|
|
| `ekf_implementation.md` | Sprint 8 | Kalman filter derivation + covariance tuning |
|
|
| `nmea2000_protocol.md` | Sprint 6 | PGN-by-PGN consumption/publication detail |
|
|
| `safety_functional.md` | Sprint 6 | Functional safety analysis |
|
|
| `ui_design_system.md` | Sprint 4 | Flutter design system (colors, typography, animations) |
|
|
| `operator_manual.md` | Sprint 9 | End-user manual |
|