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, and this project adheres to Semantic Versioning.

---

[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.