sprint-0: foundations -- data model, seed library, tests, demo

Initial commit. Delivers what the brief calls 'Sprint 0 - Foundations'
(see docs/AR_Autopilot_brief.md section 12):

- Complete repository structure (arautopilot package + firmware, display,
  installer, tools placeholders + docs).
- Core data model (Pydantic v2): modes, alarms, actuator config, PID
  config + gain scheduling, vessel config, knob state machine, project
  config with YAML/JSON serialisation.
- Seed library: 2 actuator profiles (hydraulic & electric DC reversible)
  and 2 default tunings (yacht motor planeo 30 m and 40 m). Conservative
  literature values, NOT the integrator's production tuning IP.
- Firmware skeleton: only src/hal/pinout.h with the 21 I/O contract for
  the AR-NMEA-IO v1.0 board. No drivers, no main loop.
- Studio stubs (real PySide6 app starts in Sprint 4).
- pytest suite (80 tests, all green): modes, alarms, actuator, PID
  (incl. gain interpolation and the +/-50% adaptive bound from brief
  section 6), vessel, knob state, project config, library loader,
  end-to-end roundtrip.
- examples/sprint0_demo.py - the acceptance demo from the brief.

Acceptance criteria met:
- pytest green (80/80)
- demo creates, saves (YAML + JSON), reloads, and verifies a full
  ProjectConfig using the seed library
- repository ready for tag `sprint-0-approved`

See CHANGELOG.md for the detailed scope.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

arautopilot/library/__init__.py

@@ -0,0 +1,7 @@
+"""Curated seed library: actuator profiles, default vessel tunings, vessel profiles.
+
+The contents of this package are **proprietary**. Default PID gains shipped
+here are conservative literature-based starting values intended only for
+bench testing and initial commissioning — they are NOT the integrator's
+production-tuned values.
+"""

arautopilot/library/_schemas/README.md

@@ -0,0 +1,19 @@
+# JSON Schemas
+
+This directory is reserved for JSON Schemas auto-generated from the Pydantic
+models in `arautopilot.core`. They are useful for:
+
+- IDE autocompletion / validation when editing actuator profiles or PID
+  tunings outside the Studio
+- External tooling that consumes `.appack` configurations
+- Documentation generation
+
+Schemas are not generated in Sprint 0 but can be produced on demand:
+
+```python
+from arautopilot.core.actuator_config import ActuatorConfig
+import json
+print(json.dumps(ActuatorConfig.model_json_schema(), indent=2))
+```
+
+A `tools/regenerate_schemas.py` script will be added later (Sprint 4+).

arautopilot/library/actuators/electric_dc_reversible.json

@@ -0,0 +1,11 @@
+{
+  "type": "electric_dc_reversible",
+  "name": "Generic reversible DC motor with mechanical end-stops (Lewmar / Simpson Lawrence class)",
+  "deadband_pct": 4.0,
+  "min_useful_pwm_pct": 8.0,
+  "asymmetry_stbd_over_port": 1.00,
+  "max_rudder_angle_deg": 35.0,
+  "max_rate_dps": 5.5,
+  "max_current_a": 30.0,
+  "feedback_required": true
+}

arautopilot/library/actuators/hydraulic_reversible.json

@@ -0,0 +1,11 @@
+{
+  "type": "hydraulic_reversible",
+  "name": "Generic reversible hydraulic pump (Hynautic / Hypro / Octopus / Vetus / L&S class)",
+  "deadband_pct": 7.0,
+  "min_useful_pwm_pct": 12.0,
+  "asymmetry_stbd_over_port": 1.00,
+  "max_rudder_angle_deg": 35.0,
+  "max_rate_dps": 4.0,
+  "max_current_a": 20.0,
+  "feedback_required": true
+}

arautopilot/library/default_tunings/yacht_motor_planeo_30m.yaml

@@ -0,0 +1,58 @@
+# =============================================================================
+# Default PID tuning — 30 m planing motor yacht
+# =============================================================================
+#
+# WARNING — Conservative bench/start values only.
+# These gains come from classical marine control literature (Fossen 2011,
+# Perez 2005) scaled to a 30 m planing motor yacht class. They are intended
+# only for bench testing and the very first sea trial — they MUST be replaced
+# with the integrator's affinated values during commissioning.
+#
+# The "real" tuning libraries are integrator IP and are NOT shipped here.
+#
+# Units:
+#   - kp/ki/kd: dimensionless (controller internal units)
+#   - frequencies: Hz
+#   - rate / deadband: degrees, degrees/second
+#
+# Cascaded loops (brief section 6):
+#   - inner: rudder-position controller, 50 Hz
+#   - outer: heading controller, 10 Hz
+#
+# Gain scheduling: outer-loop gains interpolated over SOG (knots).
+# Outside the scheduled range the closest endpoint is held.
+# =============================================================================
+
+schema_version: "0.1.0"
+
+inner_loop_base:
+  kp: 2.5
+  ki: 0.15
+  kd: 0.30
+inner_loop_freq_hz: 50.0
+
+outer_loop_base:
+  kp: 0.90
+  ki: 0.02
+  kd: 1.20
+outer_loop_freq_hz: 10.0
+
+# Three-point schedule covering manoeuvring (5 kn), cruise (15 kn), top (28 kn).
+# At low speed: more kp, less kd (rudder bites more, less inertia anticipation).
+# At high speed: less kp, more kd (gentler corrections, anticipate overshoot).
+gain_schedule:
+  - speed_knots: 5.0
+    gains: { kp: 1.20, ki: 0.03, kd: 0.80 }
+  - speed_knots: 15.0
+    gains: { kp: 0.90, ki: 0.02, kd: 1.20 }
+  - speed_knots: 28.0
+    gains: { kp: 0.55, ki: 0.01, kd: 1.80 }
+
+rot_feedforward_gain: 1.50
+
+setpoint_deadband_deg: 0.5
+setpoint_rate_limit_dps: 4.0
+anti_windup_limit: 8.0
+
+adaptive_enabled: false
+adaptive_max_deviation_pct: 50.0

arautopilot/library/default_tunings/yacht_motor_planeo_40m.yaml

@@ -0,0 +1,45 @@
+# =============================================================================
+# Default PID tuning — 40 m planing motor yacht
+# =============================================================================
+#
+# WARNING — Conservative bench/start values only.
+# Scaled from the 30 m profile to account for the larger vessel: higher mass
+# moment of inertia and longer time constants. Compared to the 30 m profile:
+#   - kp slightly lower (slower response per unit rudder)
+#   - kd slightly higher (more anticipation needed for the inertia)
+#   - setpoint_rate_limit_dps reduced (gentler heading slew)
+#
+# As with the 30 m profile, these are commissioning starting points and
+# must be replaced with the integrator's production tuning.
+# =============================================================================
+
+schema_version: "0.1.0"
+
+inner_loop_base:
+  kp: 2.20
+  ki: 0.12
+  kd: 0.35
+inner_loop_freq_hz: 50.0
+
+outer_loop_base:
+  kp: 0.75
+  ki: 0.015
+  kd: 1.55
+outer_loop_freq_hz: 10.0
+
+gain_schedule:
+  - speed_knots: 5.0
+    gains: { kp: 1.00, ki: 0.025, kd: 1.10 }
+  - speed_knots: 15.0
+    gains: { kp: 0.75, ki: 0.015, kd: 1.55 }
+  - speed_knots: 28.0
+    gains: { kp: 0.45, ki: 0.008, kd: 2.20 }
+
+rot_feedforward_gain: 1.80
+
+setpoint_deadband_deg: 0.5
+setpoint_rate_limit_dps: 3.0
+anti_windup_limit: 8.0
+
+adaptive_enabled: false
+adaptive_max_deviation_pct: 50.0

arautopilot/library/loader.py

@@ -0,0 +1,74 @@
+"""Filesystem loader for the seed library.
+
+Resolves paths inside the installed ``arautopilot.library`` package and
+deserialises actuator profiles (JSON) and default PID tunings (YAML).
+"""
+
+from __future__ import annotations
+
+import json
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from arautopilot.core.actuator_config import ActuatorConfig
+from arautopilot.core.pid_config import PidConfig
+
+_ACTUATOR_PACKAGE = "arautopilot.library.actuators"
+_TUNINGS_PACKAGE = "arautopilot.library.default_tunings"
+
+
+def list_actuator_profiles() -> list[str]:
+    """Return the IDs (filename stems) of all bundled actuator profiles."""
+    return sorted(
+        r.name.removesuffix(".json")
+        for r in resources.files(_ACTUATOR_PACKAGE).iterdir()
+        if r.is_file() and r.name.endswith(".json")
+    )
+
+
+def list_default_tunings() -> list[str]:
+    """Return the IDs (filename stems) of all bundled default tunings."""
+    return sorted(
+        r.name.removesuffix(".yaml")
+        for r in resources.files(_TUNINGS_PACKAGE).iterdir()
+        if r.is_file() and r.name.endswith(".yaml")
+    )
+
+
+def load_actuator_profile(profile_id: str) -> ActuatorConfig:
+    """Load and validate one bundled actuator profile by ID."""
+    data = _read_json_resource(_ACTUATOR_PACKAGE, f"{profile_id}.json")
+    return ActuatorConfig.model_validate(data)
+
+
+def load_default_tuning(tuning_id: str) -> PidConfig:
+    """Load and validate one bundled default PID tuning by ID."""
+    data = _read_yaml_resource(_TUNINGS_PACKAGE, f"{tuning_id}.yaml")
+    return PidConfig.model_validate(data)
+
+
+def load_actuator_profile_from_path(path: Path | str) -> ActuatorConfig:
+    """Load an actuator profile from an arbitrary filesystem path (for tests / Studio)."""
+    p = Path(path)
+    with p.open("r", encoding="utf-8") as f:
+        return ActuatorConfig.model_validate(json.load(f))
+
+
+def load_default_tuning_from_path(path: Path | str) -> PidConfig:
+    """Load a default PID tuning from an arbitrary filesystem path (for tests / Studio)."""
+    p = Path(path)
+    with p.open("r", encoding="utf-8") as f:
+        return PidConfig.model_validate(yaml.safe_load(f))
+
+
+def _read_json_resource(package: str, filename: str) -> dict[str, Any]:
+    return json.loads(resources.files(package).joinpath(filename).read_text(encoding="utf-8"))
+
+
+def _read_yaml_resource(package: str, filename: str) -> dict[str, Any]:
+    return yaml.safe_load(
+        resources.files(package).joinpath(filename).read_text(encoding="utf-8")
+    )