# 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 |