alro65/AR-Autopilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
295efa2d83a6b9b365520cda6616fd3baf6f7eb0
AR-Autopilot/CHANGELOG.md
T
alro65 295efa2d83 sprint-2: PID inner loop + Python rudder simulator 
End-to-end implementation per docs/sprint-2-plan.md.

Builds: pio run -e esp32-dev SUCCESS, RAM 6.8%, Flash 26.8% (351 KB).
Tests: pytest 129/129 green (110 Sprint 1 + 19 Sprint 2).

Python (arautopilot/studio/simulator/):

- rudder_dynamics.py: marine-realistic physical model of a hydraulic
  rudder actuator. Defaults tuned so 100 % PWM produces steady-state
  v_max ~5 deg/s, matching the brief's "typical 3-6 dps" for a 30 m
  yacht. Includes deadband, min-useful PWM snap, port/stbd asymmetry,
  end-stops, optional external torque, RunRecorder helper.
- pid_inner.py: pure-Python reference PID. Anti-windup via back-
  calculation, setpoint rate limit, setpoint deadband, derivative LPF,
  actuator non-linearity compensation. This module is the algorithmic
  source of truth; C++ firmware is a line-by-line port.

Firmware (firmware/ar_autopilot_v1/src/pid/):

- pid_inner.h: header-only C++17 controller, byte-equivalent port of
  pid_inner.py. Compiles on ESP32 toolchain AND on host g++/clang/MSVC
  (no Arduino dependencies) -- ready for native Unity cross-validation
  once a host compiler is installed.
- pid_inner_task.{h,cpp}: FreeRTOS task wrapper. 50 Hz on Core 1
  (real-time core). Subscribes to TWDT, bleeds integrator during
  STANDBY, surfaces telemetry + tunables via the Modbus slave.

Modbus map (regenerated from YAML):

- 6 new INPUT registers (40-45): setpoint, output, error, kp/ki/kd live
- 4 new HOLDING registers (16-19): writable setpoint + kp/ki/kd req
  (writes propagate atomically; zero kp rejected as ILLEGAL_DATA_VALUE)

Tests:

- test_rudder_simulator.py: 9 tests (zero-input rest, full deflection,
  end-stop saturation, deadband, min-useful snap, asymmetry, recorder
  API, invalid dt, end-stop velocity zeroing).
- test_pid_inner_python.py: 10 tests (positive/negative step response,
  setpoint deadband holds, anti-windup bounds under saturation,
  allowed=false bleeds integrator, actuator deadband + asymmetry
  compensation, output saturation, rate limit, disturbance rejection).

NOT in Sprint 2 (intentional per brief sec. 12):
  - Outer heading PID, gain scheduling by SOG, ROT feed-forward
    (those land in Sprint 3)
  - Cross-validation tests via ctypes (need host C++ compiler that
    this Windows machine lacks; algorithmic parity enforced by review)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-18 15:27:45 -04:00

218 lines
10 KiB
Markdown
Raw Blame History

# 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-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.
Reference in New Issue View Git Blame Copy Permalink