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,35 @@
|
||||
// =============================================================================
|
||||
// ar_log.h -- AR-Autopilot logging facade
|
||||
// =============================================================================
|
||||
//
|
||||
// Thin wrapper around the ESP32 Arduino log_X / ESP_LOGX macros so that the
|
||||
// rest of the firmware uses one consistent style. Compile-time level is
|
||||
// controlled by CORE_DEBUG_LEVEL in platformio.ini.
|
||||
//
|
||||
// Levels (matching ARDUHAL_LOG_LEVEL_*):
|
||||
// 0 NONE
|
||||
// 1 ERROR
|
||||
// 2 WARN
|
||||
// 3 INFO <- default in release
|
||||
// 4 DEBUG
|
||||
// 5 VERBOSE <- default in debug
|
||||
// =============================================================================
|
||||
|
||||
#pragma once
|
||||
|
||||
#include <Arduino.h>
|
||||
|
||||
// Tag prefix conventions used across the codebase:
|
||||
// "AR/MAIN" -- main.cpp boot/shutdown
|
||||
// "AR/PID" -- PID loops
|
||||
// "AR/HAL" -- hardware abstraction
|
||||
// "AR/MB" -- Modbus slave
|
||||
// "AR/N2K" -- NMEA 2000 consumer
|
||||
// "AR/SAFE" -- safety / watchdog / disengage
|
||||
// "AR/SYS" -- health / lifecycle / metrics
|
||||
|
||||
#define AR_LOGE(tag, fmt, ...) log_e("[%s] " fmt, tag, ##__VA_ARGS__)
|
||||
#define AR_LOGW(tag, fmt, ...) log_w("[%s] " fmt, tag, ##__VA_ARGS__)
|
||||
#define AR_LOGI(tag, fmt, ...) log_i("[%s] " fmt, tag, ##__VA_ARGS__)
|
||||
#define AR_LOGD(tag, fmt, ...) log_d("[%s] " fmt, tag, ##__VA_ARGS__)
|
||||
#define AR_LOGV(tag, fmt, ...) log_v("[%s] " fmt, tag, ##__VA_ARGS__)
|
||||
@@ -0,0 +1,50 @@
|
||||
// =============================================================================
|
||||
// heartbeat.cpp -- LED + uptime heartbeat task
|
||||
// =============================================================================
|
||||
//
|
||||
// Blinks PIN_DO5_ENGAGED_LAMP at 1 Hz to give a visible "the firmware is
|
||||
// alive" signal at the bench. In Sprint 1 we co-opt this LED because there
|
||||
// is no pilot to engage yet; from Sprint 6 onwards the engaged lamp will be
|
||||
// driven by the actual pilot state and the heartbeat will move to an
|
||||
// internal counter only.
|
||||
//
|
||||
// Also logs uptime + free heap once per second so a terminal observer can
|
||||
// see the system is healthy.
|
||||
// =============================================================================
|
||||
|
||||
#include <Arduino.h>
|
||||
|
||||
#include "../hal/pinout.h"
|
||||
#include "ar_log.h"
|
||||
#include "task_config.h"
|
||||
|
||||
namespace {
|
||||
constexpr const char* TAG = "AR/SYS";
|
||||
} // namespace
|
||||
|
||||
static void HeartbeatTask(void* /*pv*/) {
|
||||
pinMode(PIN_DO5_ENGAGED_LAMP, OUTPUT);
|
||||
bool led_on = false;
|
||||
uint32_t tick = 0;
|
||||
|
||||
AR_LOGI(TAG, "heartbeat task started on core %d, pin %d", xPortGetCoreID(),
|
||||
PIN_DO5_ENGAGED_LAMP);
|
||||
|
||||
TickType_t last_wake = xTaskGetTickCount();
|
||||
for (;;) {
|
||||
led_on = !led_on;
|
||||
digitalWrite(PIN_DO5_ENGAGED_LAMP, led_on ? HIGH : LOW);
|
||||
|
||||
AR_LOGD(TAG, "tick=%u uptime=%lus free_heap=%u min_free=%u", tick,
|
||||
millis() / 1000U, ESP.getFreeHeap(), ESP.getMinFreeHeap());
|
||||
|
||||
++tick;
|
||||
vTaskDelayUntil(&last_wake, pdMS_TO_TICKS(AR_PERIOD_MS_HEARTBEAT));
|
||||
}
|
||||
}
|
||||
|
||||
void ar_start_heartbeat_task() {
|
||||
xTaskCreatePinnedToCore(HeartbeatTask, "heartbeat", AR_TASK_STACK_HEARTBEAT,
|
||||
nullptr, AR_TASK_PRIO_HEARTBEAT, nullptr,
|
||||
AR_TASK_CORE_COMMS);
|
||||
}
|
||||
@@ -0,0 +1,68 @@
|
||||
// =============================================================================
|
||||
// task_config.h -- FreeRTOS task layout for AR-Autopilot
|
||||
// =============================================================================
|
||||
//
|
||||
// Single source of truth for stack sizes, priorities, and core pinning of
|
||||
// every long-running task in the firmware. Centralising this here makes the
|
||||
// real-time profile of the system reviewable at a glance.
|
||||
//
|
||||
// Pinning policy (brief section 6, rule #11 -- "deterministic latency"):
|
||||
//
|
||||
// Core 1 (APP_CPU) -- safety-critical real-time:
|
||||
// AR_TASK_CORE_REALTIME = 1
|
||||
// - PID inner loop (Sprint 2; stub in Sprint 1)
|
||||
// - PID outer loop (Sprint 3; stub in Sprint 1)
|
||||
// - Rudder sensor (Sprint 1: 100 Hz median filter)
|
||||
// - Safety monitor (Sprint 1: limit switches, watchdog feed)
|
||||
//
|
||||
// Core 0 (PRO_CPU) -- communications + housekeeping:
|
||||
// AR_TASK_CORE_COMMS = 0
|
||||
// - NMEA 2000 RX (Sprint 1: PGN 127250 / 127251)
|
||||
// - Modbus slave (Sprint 1: eModbus internals already async)
|
||||
// - Health reporter (Sprint 1: 1 Hz log)
|
||||
//
|
||||
// This split guarantees the real-time control loops cannot be starved or
|
||||
// jittered by bus traffic, even if NMEA 2000 saturates or the Modbus client
|
||||
// bursts.
|
||||
//
|
||||
// Priorities use the standard ESP32 FreeRTOS scale (0 idle .. 24 max).
|
||||
// configMAX_PRIORITIES is 25 on default ESP32 Arduino builds.
|
||||
// =============================================================================
|
||||
|
||||
#pragma once
|
||||
|
||||
// Core assignment
|
||||
#define AR_TASK_CORE_REALTIME 1
|
||||
#define AR_TASK_CORE_COMMS 0
|
||||
|
||||
// Priorities (higher = more priority)
|
||||
#define AR_TASK_PRIO_PID_INNER 24 // hard real-time, 50 Hz
|
||||
#define AR_TASK_PRIO_RUDDER_SENSOR 23 // 100 Hz ADC, must feed PID fresh data
|
||||
#define AR_TASK_PRIO_PID_OUTER 22 // 10 Hz heading control
|
||||
#define AR_TASK_PRIO_SAFETY 21 // limit switches, watchdog feed
|
||||
#define AR_TASK_PRIO_N2K_RX 15 // CAN polling, event-driven
|
||||
#define AR_TASK_PRIO_MODBUS 14 // eModbus internal tasks (delegated)
|
||||
#define AR_TASK_PRIO_HEARTBEAT 10 // LED blink + uptime log
|
||||
#define AR_TASK_PRIO_HEALTH 5 // periodic stats, low priority
|
||||
|
||||
// Stack sizes (bytes). Tune these once we see real high-water marks via
|
||||
// uxTaskGetStackHighWaterMark() in the health reporter.
|
||||
#define AR_TASK_STACK_PID_INNER 4096
|
||||
#define AR_TASK_STACK_PID_OUTER 4096
|
||||
#define AR_TASK_STACK_RUDDER_SENSOR 3072
|
||||
#define AR_TASK_STACK_SAFETY 3072
|
||||
#define AR_TASK_STACK_N2K_RX 6144 // NMEA2000 parsing is heap-heavy
|
||||
#define AR_TASK_STACK_MODBUS 4096
|
||||
#define AR_TASK_STACK_HEARTBEAT 2048
|
||||
#define AR_TASK_STACK_HEALTH 3072
|
||||
|
||||
// Loop periods (ms). Convert with pdMS_TO_TICKS() at the use site.
|
||||
#define AR_PERIOD_MS_PID_INNER 20 // 50 Hz
|
||||
#define AR_PERIOD_MS_PID_OUTER 100 // 10 Hz
|
||||
#define AR_PERIOD_MS_RUDDER_SENSOR 10 // 100 Hz
|
||||
#define AR_PERIOD_MS_SAFETY 20 // 50 Hz
|
||||
#define AR_PERIOD_MS_HEARTBEAT 1000 // 1 Hz LED blink
|
||||
#define AR_PERIOD_MS_HEALTH 5000 // every 5 s
|
||||
|
||||
// Watchdog (brief section 7)
|
||||
#define AR_WATCHDOG_TIMEOUT_S 2
|
||||
Reference in New Issue
Block a user