feat: AR-ElecArrangement initial commit — Python FastAPI + uvicorn (LAN desktop app, packaged as .exe via PyInstaller)

2026-07-03 12:18:12 -04:00
commit 5f552ca8ab
22 changed files with 1444 additions and 0 deletions
@@ -0,0 +1,100 @@
+# 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`](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)
+
+```powershell
+# 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`](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`](LICENSE.txt).
+
+Commercial deployment requires a per-vessel license bound to the installation HWID. Contact <alro65@gmail.com> for licensing.