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