sprint-0: foundations -- data model, seed library, tests, demo
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>
This commit is contained in:
@@ -0,0 +1,137 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user