alro65
700756c16f
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>
117 lines
4.4 KiB
Python
117 lines
4.4 KiB
Python
"""Alarm types, severities, and the ``Alarm`` runtime record.
|
|
|
|
The catalogue mirrors section 7 of the brief. Each ``AlarmType`` has a
|
|
canonical default ``AlarmSeverity`` and a hard-coded flag stating whether
|
|
that alarm, when fired, should also trigger automatic disengagement of
|
|
the autopilot (return to STANDBY).
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from datetime import datetime, timezone
|
|
from enum import Enum
|
|
|
|
from pydantic import BaseModel, ConfigDict, Field
|
|
|
|
|
|
class AlarmSeverity(str, Enum):
|
|
"""IEC-style four-level severity scheme."""
|
|
|
|
EMERGENCY = "emergency"
|
|
"""Immediate danger; loudest annunciation, blocking modal on display."""
|
|
|
|
HIGH = "high"
|
|
"""Operator must act within a few seconds."""
|
|
|
|
LOW = "low"
|
|
"""Warning; degraded operation but no immediate danger."""
|
|
|
|
INFO = "info"
|
|
"""Informational only; ack with one tap."""
|
|
|
|
|
|
class AlarmType(str, Enum):
|
|
"""The fixed catalogue of alarms emitted by the firmware.
|
|
|
|
Adding an entry here is a deliberate, reviewed change — the firmware
|
|
state machine and the display strings must be updated in lockstep.
|
|
"""
|
|
|
|
OFF_COURSE = "off_course"
|
|
OFF_COURSE_SEVERE = "off_course_severe"
|
|
RUDDER_NOT_RESPONDING = "rudder_not_responding"
|
|
HEADING_SENSOR_LOST = "heading_sensor_lost"
|
|
ACTUATOR_OVERCURRENT = "actuator_overcurrent"
|
|
VOLTAGE_LOW = "voltage_low"
|
|
LIMIT_SWITCH_REACHED = "limit_switch_reached"
|
|
WATCHDOG_TRIPPED = "watchdog_tripped"
|
|
VMS_CRITICAL = "vms_critical"
|
|
|
|
|
|
# Canonical metadata per alarm type. Source of truth referenced by both
|
|
# the firmware (via code-generated header) and the Studio (via the GUI).
|
|
_CATALOGUE: dict[AlarmType, tuple[AlarmSeverity, bool, str]] = {
|
|
AlarmType.OFF_COURSE: (AlarmSeverity.LOW, False, "Heading deviates from setpoint beyond threshold"),
|
|
AlarmType.OFF_COURSE_SEVERE: (AlarmSeverity.EMERGENCY, True, "Heading deviation >30 deg for >5 s — auto-disengage"),
|
|
AlarmType.RUDDER_NOT_RESPONDING:(AlarmSeverity.EMERGENCY, True, "Rudder command sent but no feedback motion — auto-disengage"),
|
|
AlarmType.HEADING_SENSOR_LOST: (AlarmSeverity.EMERGENCY, True, "NMEA 2000 PGN 127250 not received for >5 s — auto-disengage"),
|
|
AlarmType.ACTUATOR_OVERCURRENT: (AlarmSeverity.HIGH, True, "Actuator current exceeded configured limit"),
|
|
AlarmType.VOLTAGE_LOW: (AlarmSeverity.HIGH, True, "Supply voltage below safe operating threshold"),
|
|
AlarmType.LIMIT_SWITCH_REACHED: (AlarmSeverity.LOW, False, "Rudder reached mechanical end-stop"),
|
|
AlarmType.WATCHDOG_TRIPPED: (AlarmSeverity.EMERGENCY, True, "Firmware watchdog fired — controller reset to STANDBY"),
|
|
AlarmType.VMS_CRITICAL: (AlarmSeverity.EMERGENCY, True, "VMS reported blackout or critical electrical overload"),
|
|
}
|
|
|
|
|
|
def default_severity(alarm_type: AlarmType) -> AlarmSeverity:
|
|
"""Return the canonical severity for ``alarm_type``."""
|
|
return _CATALOGUE[alarm_type][0]
|
|
|
|
|
|
def triggers_auto_disengage(alarm_type: AlarmType) -> bool:
|
|
"""Return ``True`` iff this alarm forces the pilot into STANDBY."""
|
|
return _CATALOGUE[alarm_type][1]
|
|
|
|
|
|
def default_message(alarm_type: AlarmType) -> str:
|
|
"""Return the canonical default human-readable description."""
|
|
return _CATALOGUE[alarm_type][2]
|
|
|
|
|
|
class Alarm(BaseModel):
|
|
"""A single alarm event raised by the firmware at runtime.
|
|
|
|
Persisted to the immutable audit log (brief section 14, rule #14).
|
|
"""
|
|
|
|
model_config = ConfigDict(frozen=True, extra="forbid")
|
|
|
|
type: AlarmType
|
|
severity: AlarmSeverity
|
|
message: str = Field(min_length=1, max_length=240)
|
|
timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
|
|
source: str = Field(
|
|
default="firmware",
|
|
description="Subsystem that raised the alarm (e.g. 'firmware', 'display', 'vms').",
|
|
max_length=64,
|
|
)
|
|
acknowledged: bool = False
|
|
auto_disengage_triggered: bool = False
|
|
|
|
@classmethod
|
|
def from_type(
|
|
cls,
|
|
alarm_type: AlarmType,
|
|
*,
|
|
message: str | None = None,
|
|
source: str = "firmware",
|
|
) -> "Alarm":
|
|
"""Convenience constructor using catalogue defaults."""
|
|
return cls(
|
|
type=alarm_type,
|
|
severity=default_severity(alarm_type),
|
|
message=message or default_message(alarm_type),
|
|
source=source,
|
|
auto_disengage_triggered=triggers_auto_disengage(alarm_type),
|
|
)
|