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>
9.9 KiB
9.9 KiB
AR-Autopilot — Architecture overview
One-page architectural overview. For full scope, see
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.honly — 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 |
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 |