alro65/AR-Autopilot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

sprint-1: firmware ESP32 base -- STANDBY + Modbus + NMEA 2000 + watchdog

Browse Source 
End-to-end implementation of Sprint 1 per docs/sprint-1-plan.md.

Builds: pio run -e esp32-dev SUCCESS, RAM 6.7%, Flash 26.5% (347 KB).
Tests: pytest 110/110 green; pio test -e native deferred (needs host
       C++ compiler -- none on this Windows machine).

Firmware (firmware/ar_autopilot_v1/):

- platformio.ini: 4 envs (esp32-dev release, esp32-debug, native unity
  tests, check static analysis). NMEA2000-library@4.22, NMEA2000_esp32@
  1.0, eModbus@1.7.4 pinned.
- main.cpp: boot in STANDBY, FreeRTOS task spawn, returns to scheduler.
- system/: ar_log.h facade, task_config.h (priorities/stacks/cores
  central table), heartbeat (1 Hz LED + uptime).
- modes/: STANDBY-only state machine; non-STANDBY rejected.
- hal/: di_do.cpp (5 DI + 10 DO with debounce + last-state cache),
  rudder_sensor.cpp (100 Hz ADC + 5-sample median filter, Core 1),
  rudder_actuator.cpp (DO1/DO2/DO3 with three safety interlocks:
  power-off, STANDBY mode, limit switch).
- safety/: TWDT @ 2 s panic-on-expire; 50 Hz safety task on Core 1
  enforcing DI1 physical disengage button, DI4 external alarm,
  both-limit-switch interlock.
- protocols/modbus_slave.cpp: eModbus RTU server on UART2 @ 38400 8N1,
  slave ID 1. 17 inputs + 19 discretes + 5 holdings + 4 coils. Reads
  pull live telemetry; writes validate range and route to handlers.
- protocols/nmea2000_consumer.cpp: stack open with CAN TX=GPIO3
  RX=GPIO1, subscribed to PGN 127250 (Heading) + PGN 127251 (Rate of
  Turn). 5 s staleness flag built in for Sprint 6 alarm wiring.
- filters/median.h: templated MedianFilter<T,N> (host testable).

Cross-cutting:

- modbus_registers.yaml: single source of truth for the Modbus register
  map. 45 entries.
- tools/gen_modbus_registers.py: YAML -> C++ header + Python module
  generator with --check for drift detection.
- arautopilot/shared/modbus_register_map.py: generated Python mirror,
  imported by Studio + tools.
- arautopilot/tests/test_modbus_register_map.py: 30 tests covering
  schema, address uniqueness, range, spot-checks, and drift detection
  (fails if YAML edited without regenerating).
- firmware/ar_autopilot_v1/tools/modbus_client_test.py: manual Modbus
  client for poking the slave from a PC with USB-RS485 dongle.
- firmware/ar_autopilot_v1/test/test_median_filter/test_median.cpp:
  8 Unity tests of the median filter (host-side, no Arduino dependency).
- docs/firmware.md: full operator + integrator guide (toolchain, build,
  flash, expected boot log, troubleshooting, Sprint 1 capability matrix).

Architecture note: opted for Arduino-on-ESP32 only instead of the
proposed dual Arduino-as-ESP-IDF-component setup. Rationale documented
in CHANGELOG and docs/firmware.md -- Arduino-on-ESP32 already provides
the FreeRTOS primitives we need; dual framework adds fragility without
benefit at Sprint 1 scope. Reconsider in Sprint 8 (OTA + secure boot).

NOT in Sprint 1 (intentional per brief sec. 12):
  - PID loops (inner/outer)
  - True Course / Track Keeping
  - Full alarm catalogue beyond DI1/DI4
  - Knob driver
  - Studio GUI / dedicated display

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Alvaro Enrique Romero Donado
2026-05-18 10:45:56 -04:00
parent 1d7dd63327
commit 65860948b4
31 changed files with 3310 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CHANGELOG.md
+104
View File
@@ -9,6 +9,110 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
## [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