alro65
65860948b4
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>
AR-Autopilot
Professional marine autopilot for vessels in the 30-40 m range (motor yachts, motor sailboats, fishing vessels, small ferries, coastal patrol boats).
Part of the AR Suite alongside AR-ECDIS, VMS-Sailor, AR-ShipDesign, AR-ElecArrangement, and AR-StabCol. Sold standalone or bundled with AR-ECDIS.
NOT Dynamic Positioning. NOT joystick docking. This is a classic heading-and-track autopilot with intelligent drift compensation, controlling rudder actuators (hydraulic or electric).
Status
Sprint 0 — Foundations (in progress).
This sprint delivers the repository structure, core data model, seed library, and a passing test suite. No functional firmware, Studio GUI, or display yet — those start in Sprint 1.
See docs/AR_Autopilot_brief.md for the complete project brief, scope, and roadmap.
Components
| Component | Tech | Purpose |
|---|---|---|
Studio (arautopilot/studio/) |
Python 3.11 + PySide6 | Project configurator (integrator-side, not shipped to customers). Generates per-vessel .appack packages |
Firmware (firmware/ar_autopilot_v1/) |
C++ on ESP32 via PlatformIO | Real-time PID control, NMEA 2000 + Modbus, safety logic. Runs on the AR-NMEA-IO v1.0 board (shared with VMS-Sailor) |
Display (display/) |
Flutter Desktop (Win + Linux) | Dedicated bridge cockpit-feel touch display with rotary knob input |
Core models (arautopilot/core/) |
Pydantic v2 | Shared data model (vessel config, PID config, actuator config, alarms, modes, knob state) |
Library (arautopilot/library/) |
YAML + JSON | Curated seed: actuator profiles, default tunings per vessel type |
Requirements
- Python 3.11 or newer
- Git
- (Later sprints) PlatformIO, Flutter SDK, WiX Toolset
Quick start (Sprint 0)
# Create venv and install
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -U pip
pip install -e ".[dev]"
# Run tests
pytest
# Run the Sprint 0 demo (creates, saves, reloads a project config)
python examples/sprint0_demo.py
Repository layout
AR-Autopilot/
├── arautopilot/ # Python package (core models, library, studio stubs, tests)
├── firmware/ # ESP32 firmware (Sprint 1+; only pinout.h in Sprint 0)
├── display/ # Flutter dedicated display (Sprint 4+)
├── examples/ # Runnable demos
├── docs/ # Brief + per-sprint design docs
├── installer/ # WiX MSI scripts (later)
└── tools/ # Helper scripts (later)
See docs/architecture.md for a one-page architecture overview.
Sprint roadmap
| Sprint | Focus |
|---|---|
| 0 | Foundations: repo structure, core data model, seed library, tests |
| 1 | Firmware base (I/O, Modbus, NMEA 2000 read, STANDBY mode) |
| 2 | PID inner loop (rudder position control) |
| 3 | PID outer loop + Heading Hold (with ROT feed-forward & gain scheduling) |
| 4 | Studio + basic dedicated display |
| 5 | True Course + Track Keeping (smooth XTE correction) |
| 6 | Safety, alarms, NMEA 2000 publish, VMS alarm consumption |
| 7 | Knob + commissioning + offline auto-tuning |
| 8 | EKF + adaptive tuning + telemetry + VPN |
| 9 | Hardening + integrated testing |
| 10+ | Phase 2 (wind modes for sailboats) and beyond |
Full detail in the brief.
License
Proprietary. All rights reserved. See LICENSE.txt.
Commercial deployment requires a per-vessel license bound to the installation HWID. Contact alro65@gmail.com for licensing.