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>
This commit is contained in:
@@ -0,0 +1,148 @@
|
||||
// =============================================================================
|
||||
// modbus_registers.h -- AR-Autopilot Modbus RTU register map
|
||||
// =============================================================================
|
||||
//
|
||||
// AUTO-GENERATED. Do not edit by hand.
|
||||
// Source: firmware/ar_autopilot_v1/modbus_registers.yaml
|
||||
// Regenerate with: python tools/gen_modbus_registers.py
|
||||
// =============================================================================
|
||||
|
||||
#pragma once
|
||||
|
||||
#include <cstdint>
|
||||
|
||||
namespace arautopilot::protocols::modbus {
|
||||
|
||||
constexpr const char* MAP_SCHEMA_VERSION = "0.1.0";
|
||||
constexpr uint8_t SLAVE_ID = 1;
|
||||
constexpr uint32_t BAUDRATE = 38400;
|
||||
constexpr char PARITY = 'N';
|
||||
constexpr uint8_t DATA_BITS = 8;
|
||||
constexpr uint8_t STOP_BITS = 1;
|
||||
|
||||
// ----- Discrete inputs (read-only bits) -----
|
||||
constexpr uint16_t DISCRETE_COUNT = 19;
|
||||
constexpr uint16_t DISCRETE_MAX_ADDR = 25;
|
||||
|
||||
// 1 if the pilot is currently engaged (any mode other than STANDBY)
|
||||
constexpr uint16_t DISCRETE_PILOT_ENGAGED = 0;
|
||||
// Live state of the physical Engage/Disengage push-button
|
||||
constexpr uint16_t DISCRETE_DI_DISENGAGE_BUTTON = 1;
|
||||
// Port-side rudder mechanical end-stop reached
|
||||
constexpr uint16_t DISCRETE_DI_LIMIT_PORT = 2;
|
||||
// Starboard-side rudder mechanical end-stop reached
|
||||
constexpr uint16_t DISCRETE_DI_LIMIT_STBD = 3;
|
||||
// External critical alarm (VMS / genset) asserted
|
||||
constexpr uint16_t DISCRETE_DI_EXTERNAL_ALARM = 4;
|
||||
// Manual confirmation switch asserted (emergency override)
|
||||
constexpr uint16_t DISCRETE_DI_MANUAL_CONFIRM = 5;
|
||||
// Master actuator power relay (DO3) commanded ON
|
||||
constexpr uint16_t DISCRETE_ACTUATOR_POWER = 8;
|
||||
// Actuator direction output: driving to port
|
||||
constexpr uint16_t DISCRETE_ACTUATOR_DRIVING_PORT = 9;
|
||||
// Actuator direction output: driving to starboard
|
||||
constexpr uint16_t DISCRETE_ACTUATOR_DRIVING_STBD = 10;
|
||||
// Off-course warning active
|
||||
constexpr uint16_t DISCRETE_ALARM_OFF_COURSE = 16;
|
||||
// Severe off-course alarm (auto-disengage)
|
||||
constexpr uint16_t DISCRETE_ALARM_OFF_COURSE_SEVERE = 17;
|
||||
// Rudder command sent but no feedback motion
|
||||
constexpr uint16_t DISCRETE_ALARM_RUDDER_NOT_RESP = 18;
|
||||
// NMEA 2000 heading PGN not received >5 s
|
||||
constexpr uint16_t DISCRETE_ALARM_HEADING_LOST = 19;
|
||||
// Actuator current over threshold
|
||||
constexpr uint16_t DISCRETE_ALARM_ACTUATOR_OVERCURR = 20;
|
||||
// Supply voltage below safe threshold
|
||||
constexpr uint16_t DISCRETE_ALARM_VOLTAGE_LOW = 21;
|
||||
// Rudder reached mechanical end-stop
|
||||
constexpr uint16_t DISCRETE_ALARM_LIMIT_REACHED = 22;
|
||||
// Firmware watchdog fired -- controller reset
|
||||
constexpr uint16_t DISCRETE_ALARM_WATCHDOG_TRIPPED = 23;
|
||||
// VMS reported blackout or electrical fault
|
||||
constexpr uint16_t DISCRETE_ALARM_VMS_CRITICAL = 24;
|
||||
// OR of all alarm bits (convenience)
|
||||
constexpr uint16_t DISCRETE_ANY_ALARM_ACTIVE = 25;
|
||||
|
||||
// ----- Coils (read-write bits) -----
|
||||
constexpr uint16_t COIL_COUNT = 4;
|
||||
constexpr uint16_t COIL_MAX_ADDR = 3;
|
||||
|
||||
// Rising edge requests pilot engagement (subject to interlocks)
|
||||
constexpr uint16_t COIL_CMD_ENGAGE_REQUEST = 0;
|
||||
// Rising edge forces pilot to STANDBY
|
||||
constexpr uint16_t COIL_CMD_DISENGAGE_REQUEST = 1;
|
||||
// Rising edge acknowledges every active alarm
|
||||
constexpr uint16_t COIL_CMD_ACK_ALL_ALARMS = 2;
|
||||
// Knob arming request (Sprint 7+)
|
||||
constexpr uint16_t COIL_CMD_KNOB_ARM = 3;
|
||||
|
||||
// ----- Input registers (read-only words) -----
|
||||
constexpr uint16_t INPUT_COUNT = 17;
|
||||
constexpr uint16_t INPUT_MAX_ADDR = 33;
|
||||
|
||||
// Firmware major version
|
||||
constexpr uint16_t INPUT_FW_VERSION_MAJOR = 0;
|
||||
// Firmware minor version
|
||||
constexpr uint16_t INPUT_FW_VERSION_MINOR = 1;
|
||||
// Firmware patch version
|
||||
constexpr uint16_t INPUT_FW_VERSION_PATCH = 2;
|
||||
// Modbus map schema version (0=v0.1.0)
|
||||
constexpr uint16_t INPUT_SCHEMA_VERSION = 3;
|
||||
// Uptime seconds, low 16 bits
|
||||
// unit=s
|
||||
constexpr uint16_t INPUT_UPTIME_SECONDS_LO = 4;
|
||||
// Uptime seconds, high 16 bits
|
||||
// unit=s
|
||||
constexpr uint16_t INPUT_UPTIME_SECONDS_HI = 5;
|
||||
// Current AutopilotMode (0=STANDBY,1=HH,2=TC,3=TK,4=DODGE)
|
||||
constexpr uint16_t INPUT_CURRENT_MODE = 6;
|
||||
// Current free heap, KiB
|
||||
// unit=KiB
|
||||
constexpr uint16_t INPUT_FREE_HEAP_KB = 7;
|
||||
// Minimum free heap since boot
|
||||
// unit=KiB
|
||||
constexpr uint16_t INPUT_MIN_FREE_HEAP_KB = 8;
|
||||
// Filtered rudder angle, deg * 100 (-3500..+3500)
|
||||
// unit=deg, scale=0.01
|
||||
constexpr uint16_t INPUT_RUDDER_ANGLE_DEG_X100 = 16;
|
||||
// Raw ADC reading after median filter (0..4095)
|
||||
// unit=counts
|
||||
constexpr uint16_t INPUT_RUDDER_RAW_ADC = 17;
|
||||
// 1 if median filter has filled (>=5 samples)
|
||||
constexpr uint16_t INPUT_RUDDER_VALID = 18;
|
||||
// Current heading from NMEA 2000 PGN 127250, deg*100 (0..35999)
|
||||
// unit=deg, scale=0.01
|
||||
constexpr uint16_t INPUT_HEADING_DEG_X100 = 24;
|
||||
// Rate of turn from PGN 127251, deg/s*100 (signed int16)
|
||||
// unit=deg/s, scale=0.01
|
||||
constexpr uint16_t INPUT_ROT_DPS_X100 = 25;
|
||||
// Milliseconds since the last heading update (0..60000)
|
||||
// unit=ms
|
||||
constexpr uint16_t INPUT_HEADING_AGE_MS = 26;
|
||||
// System battery voltage, V*100
|
||||
// unit=V, scale=0.01
|
||||
constexpr uint16_t INPUT_BATTERY_VOLTAGE_X100 = 32;
|
||||
// Actuator current, A*100
|
||||
// unit=A, scale=0.01
|
||||
constexpr uint16_t INPUT_ACTUATOR_CURRENT_X100 = 33;
|
||||
|
||||
// ----- Holding registers (read-write words) -----
|
||||
constexpr uint16_t HOLDING_COUNT = 5;
|
||||
constexpr uint16_t HOLDING_MAX_ADDR = 8;
|
||||
|
||||
// Mode requested by operator (0=STANDBY,1=HH,2=TC,3=TK,4=DODGE)
|
||||
constexpr uint16_t HOLDING_MODE_REQUEST = 0;
|
||||
// Desired heading, deg*100
|
||||
// unit=deg, scale=0.01
|
||||
constexpr uint16_t HOLDING_HEADING_SETPOINT_X100 = 1;
|
||||
// Display brightness 0..100
|
||||
// unit=%
|
||||
constexpr uint16_t HOLDING_BRIGHTNESS_PCT = 2;
|
||||
// Alarm volume 0..100
|
||||
// unit=%
|
||||
constexpr uint16_t HOLDING_ALARM_VOLUME_PCT = 3;
|
||||
// Dodge mode heading offset, deg*100 (signed int16)
|
||||
// unit=deg, scale=0.01
|
||||
constexpr uint16_t HOLDING_DODGE_OFFSET_DEG_X100 = 8;
|
||||
|
||||
} // namespace arautopilot::protocols::modbus
|
||||
Reference in New Issue
Block a user