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

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>

firmware/ar_autopilot_v1/src/modes/standby.cpp

@@ -0,0 +1,80 @@
+// =============================================================================
+//  modes/standby.cpp -- pilot mode state (Sprint 1)
+// =============================================================================
+
+#include "standby.h"
+
+#include <Arduino.h>
+
+#include "../system/ar_log.h"
+
+namespace arautopilot::modes {
+
+namespace {
+constexpr const char* TAG = "AR/MODE";
+
+portMUX_TYPE g_mux = portMUX_INITIALIZER_UNLOCKED;
+Mode g_mode = Mode::STANDBY;
+
+const char* mode_name(Mode m) {
+    switch (m) {
+        case Mode::STANDBY:       return "STANDBY";
+        case Mode::HEADING_HOLD:  return "HEADING_HOLD";
+        case Mode::TRUE_COURSE:   return "TRUE_COURSE";
+        case Mode::TRACK_KEEPING: return "TRACK_KEEPING";
+        case Mode::DODGE:         return "DODGE";
+    }
+    return "UNKNOWN";
+}
+}  // namespace
+
+void mode_init() {
+    portENTER_CRITICAL(&g_mux);
+    g_mode = Mode::STANDBY;
+    portEXIT_CRITICAL(&g_mux);
+    AR_LOGI(TAG, "mode_init: %s", mode_name(g_mode));
+}
+
+Mode current_mode() {
+    portENTER_CRITICAL(&g_mux);
+    Mode m = g_mode;
+    portEXIT_CRITICAL(&g_mux);
+    return m;
+}
+
+bool is_standby() { return current_mode() == Mode::STANDBY; }
+
+bool request_mode(Mode m) {
+    // Sprint 1: only STANDBY is reachable. The other modes exist in the enum
+    // for forward compatibility (Modbus already has slots for them) but the
+    // PID and modes machinery is not in place yet.
+    if (m == Mode::STANDBY) {
+        portENTER_CRITICAL(&g_mux);
+        Mode prev = g_mode;
+        g_mode = Mode::STANDBY;
+        portEXIT_CRITICAL(&g_mux);
+        if (prev != Mode::STANDBY) {
+            AR_LOGI(TAG, "mode change: %s -> STANDBY", mode_name(prev));
+        }
+        return true;
+    }
+
+    AR_LOGW(TAG,
+            "request_mode(%s) rejected: only STANDBY is implemented in "
+            "Sprint 1; current mode remains %s",
+            mode_name(m), mode_name(current_mode()));
+    return false;
+}
+
+void force_standby(const char* reason) {
+    portENTER_CRITICAL(&g_mux);
+    Mode prev = g_mode;
+    g_mode = Mode::STANDBY;
+    portEXIT_CRITICAL(&g_mux);
+    if (prev != Mode::STANDBY) {
+        AR_LOGE(TAG, "force_standby: %s -> STANDBY (reason: %s)",
+                mode_name(prev), reason != nullptr ? reason : "unspecified");
+    }
+}
+
+}  // namespace arautopilot::modes

firmware/ar_autopilot_v1/src/modes/standby.h

@@ -0,0 +1,46 @@
+// =============================================================================
+//  modes/standby.h -- pilot mode state (Sprint 1)
+// =============================================================================
+//
+//  Holds the global "what mode is the pilot in" flag. In Sprint 1 the only
+//  mode that does anything real is STANDBY. The other Phase 1 modes
+//  (HEADING_HOLD, TRUE_COURSE, TRACK_KEEPING, DODGE) are reserved in the
+//  enum but cannot be entered yet -- attempting to set them logs a warning
+//  and stays in STANDBY.
+//
+//  Later sprints expand this module into a proper state machine driven by
+//  the safety system and the operator's Modbus commands.
+// =============================================================================
+
+#pragma once
+
+#include <cstdint>
+
+namespace arautopilot::modes {
+
+enum class Mode : uint8_t {
+    STANDBY = 0,
+    HEADING_HOLD = 1,
+    TRUE_COURSE = 2,
+    TRACK_KEEPING = 3,
+    DODGE = 4,
+};
+
+/// Initialise to STANDBY. Must be called once from setup().
+void mode_init();
+
+/// Atomically read the current mode.
+Mode current_mode();
+
+/// True if and only if current_mode() == STANDBY.
+bool is_standby();
+
+/// Try to enter `m`. In Sprint 1 only STANDBY is accepted; anything else
+/// is rejected with a warning. Returns true on success.
+bool request_mode(Mode m);
+
+/// Force-return to STANDBY (called by the safety system on auto-disengage,
+/// watchdog reset, or the DI1 physical button).
+void force_standby(const char* reason);
+
+}  // namespace arautopilot::modes