AR-Autopilot/CHANGELOG.md

# Changelog

All notable changes to AR-Autopilot will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).

---

## [Unreleased]

## [0.1.0-sprint3] — Sprint 3 — PID outer + Heading Hold — 2026-05-18

> Closes the cascade: outer loop (heading control, 10 Hz) drives the inner
> loop (rudder position control, 50 Hz from Sprint 2). First real mode
> other than STANDBY is now activable: HEADING_HOLD.

### Added

#### Python (`arautopilot/studio/simulator/`)

- **`vessel_heading.py`** -- first-order yaw model of a vessel. ROT
  responds to rudder*speed; damping returns ROT to zero when the rudder
  is centred. Defaults tuned so 5 deg rudder @ 10 kn produces ~3 dps
  steady-state ROT. Includes `heading_error_deg()` shortest-arc helper
  and a `HeadingRunRecorder`.
- **`pid_outer.py`** -- pure-Python reference implementation of the
  outer heading PID. Anti-windup via back-calculation, gain scheduling
  by SOG, deadband, derivative LPF, output saturation, **ROT
  feed-forward** (brief sec. 6 -- the term that distinguishes a premium
  autopilot from a basic one), rate limit on produced rudder setpoint,
  shortest-arc heading wrap-around.

#### Firmware (`firmware/ar_autopilot_v1/src/pid/`)

- **`pid_outer.h`** -- header-only C++17 port. Same algorithm, same
  variables, same numerics. Includes inline `heading_error_deg()` and
  fixed-capacity gain schedule (up to 8 points).
- **`pid_outer_task.{h,cpp}`** -- 10 Hz FreeRTOS task on Core 1.
  Subscribes to TWDT. Reads heading + ROT from the NMEA 2000 snapshot;
  uses operator-configurable SOG (default 15 kn until PGN 129026 wiring
  in Sprint 5). Pushes its rudder setpoint into the inner loop *only*
  when current_mode == HEADING_HOLD.

#### Modes (`firmware/ar_autopilot_v1/src/modes/standby.cpp`)

- HEADING_HOLD is now activable via `request_mode(HEADING_HOLD)`.
  Pre-conditions enforced:
    - NMEA 2000 heading sensor must be valid (fresh PGN 127250).
    - Rudder sensor must be valid (median filter has filled).
  On success, captures the current heading as the initial setpoint --
  the operator does not get a sudden swing toward an old setpoint left
  in the Modbus holding register.

#### Modbus register map (regenerated from YAML)

- 7 new INPUT registers (50-56): outer-loop heading setpoint, produced
  rudder setpoint, heading error, current SOG, live kp/ki/kd.
- 5 new HOLDING registers (24-28): writable heading setpoint, SOG
  override, outer base gains. Writing any of kp/ki/kd disables the
  built-in 3-point gain schedule (operator override).

#### Tests

- `test_vessel_heading_simulator.py` -- 6 dynamics tests + 9
  parameterised `heading_error_deg` cases (including all the wrap-around
  edge cases).
- `test_pid_outer_python.py` -- 12 tests: gain interpolation,
  per-tick outer PID behaviour (deadband, sign, ROT feed-forward,
  saturation, rate limit, allowed=false bleed), and three end-to-end
  cascade tests (positive step, negative step, wrap-around 360->10).

### Verification

- `pio run -e esp32-dev` -- SUCCESS, RAM 6.8 %, Flash 27.1 % (355 KB).
- `pytest` -- **258 passed** in 5.31 s (231 Sprint 2.5 + 27 Sprint 3 new).
- End-to-end cascade in Python: outer + inner + rudder dynamics +
  vessel-heading simulator settles a 30 deg step within +-2 deg in 60 s.

### Not in Sprint 3 (intentional)

- True Course mode (COG-based with drift compensation) -- Sprint 5.
- Track Keeping (waypoint following with smooth XTE correction) -- Sprint 5.
- Dodge -- Sprint 5.
- Off-course alarms + auto-disengage on sensor loss -- Sprint 6.
- COG / SOG / Position from PGN 129025 / 129026 / 129029 -- Sprint 5.

## [0.1.0-sprint2.5] — Sprint 2.5 — RBAC + Studio + Flash Console — 2026-05-18

> New sprint added at the user's request: 4-role RBAC and a "mini Arduino
> IDE" inside the Studio that lets an Engineer flash firmware to an
> AR-NMEA-IO board with the Super Admin's PIN as a second factor.

### Added

#### RBAC core (`arautopilot/core/`)

- **`rbac.py`** -- 4 roles (`SUPER_ADMIN`, `ENGINEER`, `OWNER`, `USER`),
  12 capabilities, immutable capability matrix, `has()`,
  `capabilities_of()`, `require()`, and `requires_dual_auth()` policy
  helper. Engineer flashing firmware needs SA approval; everything else
  is single-factor.
- **`user.py`** -- `User` model with PBKDF2-HMAC-SHA256 PIN hashing
  (200k iterations, 16-byte salt). Self-describing hash format for
  future migrations. 4-8 digit numeric PINs enforced.
- **`user_store.py`** -- JSON-backed user database (one file per Studio
  install). `seed_demo_users()` for first-run UX.
- **`audit.py`** -- Append-only JSONL audit log. `AuditEvent` records
  user_id, role, action, target, outcome (success/denied/failed/
  approval_pending), reason, and optional secondary_user_id for
  dual-auth events. Crypto-signing of lines deferred to Sprint 8.

#### Studio GUI (`arautopilot/studio/`)

- **`app.py`** -- entry point. Replaces the Sprint 0 stub. Supports
  `--seed-demo` (populate demo users without launching GUI), `--data-dir`
  (override the `~/.ar-autopilot/studio/` default).
- **`session.py`** -- runtime context: `Session` (user + audit + caps),
  `SessionHolder` (process-global singleton). `check()` always records
  an audit event; `verify_super_admin_pin()` for dual-auth flows;
  `log_dual_auth_grant()` for the approval-recorded variant.
- **`login_window.py`** -- modal login dialog with user picker + PIN
  field. Audits login attempts (success and bad-PIN denials).
- **`main_window.py`** -- top-level window with sidebar (user + role +
  granted capabilities) and central tab area (Overview, Flash Console,
  placeholders for Project and Telemetry tabs).
- **`flash_console.py`** -- the "mini Arduino IDE". Lists serial ports
  via pyserial; lets the operator pick the firmware variant
  (`esp32-dev` / `esp32-debug`); compiles via `pio run`; flashes via
  `pio run -t upload --upload-port <port>`; streams pio output to a
  dark-themed read-only console; supports cancel. For Engineer flashes,
  asks the Super Admin for their PIN inline before invoking pio. The
  audit log records both the dual-auth grant and the pio exit code.

#### Dependencies (new optional group)

- New `[project.optional-dependencies]` group `studio`:
  `PySide6>=6.6`, `pyserial>=3.5`, `platformio>=6.1`. Kept optional so
  the core can be installed in lean / CI environments.

#### Tests (`arautopilot/tests/`)

- `test_rbac.py` -- 32 tests covering capability assignment per role,
  dual-auth policy, `require()` helper, no-privilege-escalation
  invariants, partial-overlap between Engineer and Owner.
- `test_user.py` -- 11 tests covering PIN hashing, verification,
  serialisation, salting (different hashes for same PIN), pin_hash
  field validator, vessel-scoped users.
- `test_audit.py` -- 9 tests covering single-line JSONL append,
  immutability, round-trip, corrupt-line detection, dual-auth event
  shape, extra payload, blank-line tolerance.
- `test_user_store.py` -- 10 tests covering CRUD, persistence across
  instances, role filtering, demo seed idempotency, membership tests.
- `test_session.py` -- 9 tests covering capability checks with audit
  side effects, SA PIN verification, dual-auth recording,
  `SessionHolder` lifecycle.
- `test_studio_smoke.py` -- 5 headless tests verifying Studio modules
  import without a display server, `--seed-demo` works, the helpers in
  `flash_console` are safe to call without hardware.

### Verification

- `pytest` -- **231 passed** in 4.78 s (129 from Sprint 2 + 102 new).
- `python -m arautopilot.studio.app --seed-demo --data-dir <tmp>` --
  populates 4 demo users, prints a notice, exits 0.

### Not in Sprint 2.5 (intentional)

- Cryptographic signing of audit log lines (hash-chain) -- Sprint 8.
- HWID binding of the user store -- Sprint 8.
- Project configurator + .appack compiler -- Sprint 4.
- Flutter bridge display -- Sprint 4.
- Telemetry dashboard tab -- Sprint 4.
- Serial monitor as a separate tab -- a future enhancement; for now the
  Flash Console only streams pio output, not arbitrary serial.

## [0.1.0-sprint2] — Sprint 2 — PID inner loop + rudder simulator — 2026-05-18

> Continues the overnight execution under blanket authorisation. Builds on
> Sprint 1 firmware foundation. New cross-cutting concern introduced:
> Python is the **algorithmic source of truth** for the PID; C++ firmware
> is a line-by-line port; tests pin both.

### Added

#### Python (`arautopilot/studio/simulator/`)

- **`rudder_dynamics.py`** -- bench-grade physical model of a hydraulic
  rudder actuator. Marine-realistic defaults (actuator_gain=0.2, friction=4
  -> steady-state v_max ~5 deg/s for a 30 m yacht). Includes deadband,
  min-useful-PWM snap, port/starboard asymmetry, mechanical end-stops,
  optional constant external torque, and a `RunRecorder` helper for
  trajectory capture.
- **`pid_inner.py`** -- pure-Python reference implementation of the inner
  PID. Anti-windup via back-calculation, setpoint rate limit, setpoint
  deadband, derivative low-pass filter, actuator non-linearity
  compensation (deadband + min-useful + asymmetry). Algorithmic source
  of truth -- the firmware C++ port matches it line-by-line.

#### Firmware (`firmware/ar_autopilot_v1/src/pid/`)

- **`pid_inner.h`** -- header-only C++17 controller, byte-equivalent port
  of `pid_inner.py`. Compiles on the ESP32 toolchain AND on host
  g++/clang/MSVC (no Arduino dependencies). Suitable for native Unity
  tests once a host compiler is available.
- **`pid_inner_task.{h,cpp}`** -- FreeRTOS task wrapper. 50 Hz on Core 1
  (real-time core). Reads rudder position from `hal::rudder_sensor`,
  consumes setpoint from Modbus / outer loop, commands
  `hal::rudder_command`. Bleeds integrator during STANDBY. Subscribes
  to the watchdog and feeds it every loop.

#### Modbus register map (regenerated from YAML)

- 6 new INPUT registers (40-45) -- PID telemetry: setpoint, output,
  error, kp/ki/kd live.
- 4 new HOLDING registers (16-19) -- writable: rudder setpoint request,
  kp/ki/kd request. Writes propagate atomically to the controller.

#### Tests

- `test_rudder_simulator.py` -- 9 tests of the physical model: zero-input
  rest, full-deflection drive, end-stop saturation, deadband, min-useful
  snap, asymmetry behaviour, recorder API, invalid dt, end-stop velocity
  zeroing.
- `test_pid_inner_python.py` -- 10 tests of the Python PID against the
  simulator: positive/negative step response, setpoint deadband holds,
  anti-windup bounds integrator under saturation, allowed=false bleeds
  integrator, actuator deadband compensation, asymmetry compensation,
  output saturation, rate limit caps slew, disturbance rejection.

### Verification

- `pio run -e esp32-dev` -- SUCCESS, RAM 6.8 %, Flash 26.8 % (351 KB).
- `pytest` -- **129 passed** in 0.31 s (110 Sprint 1 + 19 Sprint 2 new).

### Not in Sprint 2 (intentional)

- Heading control (outer loop) -- that is Sprint 3.
- Gain scheduling by SOG -- Sprint 3.
- Rate-of-Turn feed-forward -- Sprint 3.
- Cross-validation tests Python ↔ C++ via ctypes -- requires host C++
  compiler that this machine lacks; the algorithm parity is enforced by
  code review (line-by-line port) and will be backed by automated
  cross-validation as soon as a host compiler is available.

## [0.1.0-sprint1] — Sprint 1 — Firmware ESP32 base — 2026-05-18

> Sprint 1 was executed autonomously overnight after the user gave explicit
> blanket authorisation (no per-decision approval) to push through subsequent
> sprints. The four technical decisions in `docs/sprint-1-plan.md` §2 were
> taken with the **recommended** option (Arduino-only framework -- pragmatic
> shift from the dual-framework plan, see Architecture note below).

### Added

#### Firmware (`firmware/ar_autopilot_v1/`)

- **`platformio.ini`** — Build configuration for ESP32-DOWD on the
  AR-NMEA-IO v1.0 board. Three envs:
  - `esp32-dev` — release build (-Os, default).
  - `esp32-debug` — debug build (-O0, verbose logs).
  - `native` — host Unity tests (no hardware required, host C++ compiler
    needed).
  - `check` — cppcheck static analysis.
- **Sprint 1 dependencies** pinned: `NMEA2000-library` v4.22+,
  `NMEA2000_esp32` v1.0+, `eModbus` v1.7.4.
- **`src/main.cpp`** — boot, FreeRTOS task spawn, returns to scheduler.
- **`src/system/`** — `ar_log.h` logging facade, `task_config.h` central
  table of stack sizes / priorities / core pinning, `heartbeat.cpp`
  (1 Hz LED + uptime log on Core 0).
- **`src/modes/`** — STANDBY-only mode state machine. Non-STANDBY mode
  requests rejected with a warning.
- **`src/hal/`** — `di_do.{h,cpp}` (5 DI + 10 DO with software debouncing
  and last-state cache); `rudder_sensor.{h,cpp}` (100 Hz ADC + 5-sample
  median filter, Core 1); `rudder_actuator.{h,cpp}` (DO1/DO2/DO3 driver
  with three layered safety interlocks: power-off, STANDBY, limit switch).
- **`src/safety/`** — `watchdog.{h,cpp}` (TWDT @ 2 s, panic on expire);
  `safety_monitor.{h,cpp}` (50 Hz DI polling on Core 1, DI1 disengage
  button enforced, DI4 external alarm, both-limit-switch interlock).
- **`src/protocols/modbus_slave.{h,cpp}`** — eModbus RTU server on UART2
  @ 38400 8N1, slave ID 1. 17 input registers, 19 discrete inputs,
  5 holding registers, 4 coils. Reads pull from live telemetry (mode,
  rudder, NMEA 2000 snapshot, heap). Writes validate range and route to
  the corresponding handler.
- **`src/protocols/nmea2000_consumer.{h,cpp}`** — NMEA 2000 stack open
  with CAN TX=GPIO3 RX=GPIO1, subscribed to PGN 127250 (Heading) and
  PGN 127251 (Rate of Turn). Snapshot exposed via Modbus input registers
  24-26 (heading_deg_x100, rot_dps_x100, heading_age_ms). 5 s staleness
  flag built in for Sprint 6 alarm wiring.
- **`src/filters/median.h`** — Templated `MedianFilter<T, N>` (host
  testable).
- **`modbus_registers.yaml`** — Single source of truth for the Modbus
  register map. 45 entries total.
- **`test/test_median_filter/test_median.cpp`** — 8 Unity tests of the
  median filter (host-side, no Arduino dependency).
- **`tools/modbus_client_test.py`** — manual Modbus client for poking
  the slave from a PC with a USB-RS485 dongle.

#### Cross-cutting

- **`tools/gen_modbus_registers.py`** — YAML -> C++ header + Python
  module code generator with `--check` mode for CI/drift detection.
- **`arautopilot/shared/modbus_register_map.py`** — generated Python
  mirror of the firmware register contract (`Reg` dataclass per entry,
  grouped into `DISCRETES`, `COILS`, `INPUTS`, `HOLDINGS`).
- **`arautopilot/tests/test_modbus_register_map.py`** — 30 tests:
  schema sanity, address uniqueness within group, range bounds,
  spot-checks for critical registers, and **drift detection** that fails
  if anyone edits the YAML without regenerating.
- **`docs/firmware.md`** — firmware operator + integrator guide
  (toolchain, build, flash, expected boot log, troubleshooting,
  Sprint 1 capability matrix).

### Architecture decisions taken

- **Framework**: Arduino-on-ESP32 only (NOT the dual
  Arduino-as-ESP-IDF-component proposed in the Sprint 1 plan). Rationale:
  Arduino-on-ESP32 already provides full FreeRTOS access
  (`xTaskCreatePinnedToCore`, priorities, TWDT, log levels), the dual
  framework is notoriously fragile in PlatformIO, and we hit no
  ESP-IDF-only feature in Sprint 1 scope. OTA-with-rollback and secure
  boot become a real ask in Sprint 8 — at that point we either migrate
  to ESP-IDF or wire the equivalent via Arduino + EspOTA.
- **FreeRTOS core split** as proposed: PID + safety + rudder sensor on
  Core 1 (real-time); NMEA 2000 RX + Modbus + heartbeat on Core 0.
- **Logging**: ESP_LOG via UART0 only, no SD card.

### Verification

- `pio run -e esp32-dev` -> SUCCESS (RAM 6.7 %, Flash 26.5 %, 347 KB).
- `pio run -e esp32-debug` -> SUCCESS.
- `pytest` -> **110 passed** in 0.22 s (80 from Sprint 0 + 30 new).
- `ruff check arautopilot/` -> All checks passed.
- `mypy arautopilot/core library shared` -> Success, 0 issues.
- `pio test -e native` -> deferred: needs host C++ compiler (mingw /
  msvc / clang) on this Windows machine. The Unity test sources compile
  on any standard host once a toolchain is installed.

### Not in Sprint 1 (intentional, per brief §12)

- PID loops (inner/outer).
- True Course / Track Keeping modes.
- Alarm catalogue beyond DI1/DI4 forced disengage.
- Knob driver.
- Studio GUI.
- Dedicated display Flutter app.

## [0.1.0] — Sprint 0 — Foundations — 2026-05-17

## [0.1.0] — Sprint 0 — Foundations — 2026-05-17

### Added

- Repository structure following the layout defined in the project brief (section 11)
- Python package skeleton `arautopilot` with submodules:
  - `core/` — data model (Pydantic v2): modes, alarms, actuator config, PID config,
    vessel config, knob state, project config, IDs
  - `library/` — curated seed: 2 actuator profiles (hydraulic reversible,
    electric DC reversible) and 2 default tunings (yacht motor planeo 30 m, 40 m)
  - `studio/` — empty stubs for Sprint 4
  - `tests/` — pytest suite covering the core data model
- Firmware skeleton: `firmware/ar_autopilot_v1/src/hal/pinout.h` only —
  21 I/O assignment for the AR-NMEA-IO v1.0 board, no functional code yet
- Build configuration:
  - `pyproject.toml` with Pydantic v2, PyYAML, python-dateutil
  - Dev dependencies: pytest, pytest-cov, ruff, mypy
  - Ruff + mypy strict configuration
- `examples/sprint0_demo.py` — end-to-end project creation, save, and reload
- Documentation moved/created:
  - `docs/AR_Autopilot_brief.md` — full project brief
  - `docs/architecture.md` — one-page architecture overview
- `LICENSE.txt` — Proprietary, all rights reserved
- `.gitignore` covering Python, Flutter, PlatformIO, IDEs, Windows artifacts

### Notes

- **No functional firmware**, Studio GUI, or display in this sprint — those
  start in Sprint 1, 4, and 4 respectively.
- The seed PID tunings are **conservative starting values** drawn from
  classical marine control literature (Fossen, Perez). They are explicitly
  **not** the integrator's affinated production values, which remain IP.
- Python ≥3.11 required.