SC-F001/TODO.md

SC-F001 Firmware — TODO

1. • [clauded] sdkconfig audit
   • [clauded] Enable CONFIG_ESP_TASK_WDT_PANIC=y — added to sdkconfig.defaults and sdkconfig
   • [clauded] Verify CONFIG_FREERTOS_CHECK_STACKOVERFLOW=2 — confirmed canary method active
   • [clauded] Verify CONFIG_ESP_SYSTEM_PANIC_PRINT_REBOOT — confirmed active
   • [clauded] Confirm brownout detector level — ~2.43V is correct (ESP32 rail protection; battery low-V handled by FSM's LOW_PROTECTION_V)
   • [clauded] Research sdkconfig management best practices — documented in CLAUDE.md "sdkconfig Management" section
2. • [clauded] Fix managed_components: removed unused littlefs and tca95x5 deps, pinned mdns to ~1.9.1, bumped IDF min to >=5.0; documented in CLAUDE.md
3. • [clauded] OTA rollback via consecutive-reset counter
   • [clauded] Add RTC_DATA_ATTR uint8_t ota_reset_counter — incremented on panic/WDT resets, cleared on power-on/ext reset
   • [clauded] On counter ≥ 5, call esp_ota_mark_app_invalid_rollback_and_reboot()
   • [clauded] After POST passes and FSM starts, call esp_ota_mark_app_valid_cancel_rollback() and clear counter
   • [clauded] Health check = POST passes + all critical inits + FSM task started + non-critical inits attempted
4. • [clauded] Critical init failures (ADC, storage, log, I2C, FSM, UART) → init_critical() retries 3×, then esp_restart()
5. • [clauded] Non-critical init failures (RF, BT, webserver) → log error, continue booting
   • [clauded] WiFi/BT/RF retry once on init failure at boot (200ms delay for RF/BT, 500ms for WiFi), then log and continue
6. • [clauded] Power-on self-test (POST) — init_critical() wrapper + dedicated POST checks after init
   • [clauded] ADC: adc_post() reads all 4 channels twice with 5ms delay, warns if frozen
   • [clauded] I2C: i2c_post() verifies TCA9555 responds (read port 0)
   • [clauded] Flash: storage_post() write-read-verify on last sector of storage partition
7. • [clauded] Parameter validation
   • [clauded] Add per-param bounds to PARAM_LIST macro (min, max) — extended PARAM_DEF 6-arg macro
   • [clauded] NaN/Inf → reset to default; out-of-range → clamp to min/max — validate_param() in storage.c
   • [clauded] Enforce validation in storage_init() (after flash load) and commit_params() (before flash write)
   • [clauded] Audit set_param_value_t calls outside comms.c — deleted dead code: rf_433_set_keycode(), FSM_CMD_CALIBRATE_*_FINISH handlers + FSM cases + fsm_set_cal_val() (web JS does cal math client-side, commits via standard param POST)
   • [clauded] Audit abandoned parameters — JACK_IS_DOWN marked deprecated (may duplicate JACK_I_DOWN); BOOT_TIME is informational-only
8. • [clauded] Factory reset: erases params + log + post_test partitions, requires 10s button hold on cold boot, LEDs flash during hold → solid when triggered
9. • [clauded] Ensure RTC_DATA_ATTR variables survive panics/WDT resets
   • [clauded] Verified sync_unix_us, sync_rtc_us, rtc_set — no init path zeroes them; rtc_restore_time() recovers via RTC HW counter
   • [clauded] Verified remaining_distance, fsm_error — fsm_init() does not touch them; only cleared by explicit user action
   • [clauded] Verified log_head_offset, log_tail_offset — log_init() always recovers from flash scan; RTC_DATA_ATTR is historical/harmless
10. • [clauded] Measure flash log write duration — test_log_write_timing() in log_test.c, runs 200 iterations of 39-byte writes, reports min/max/avg/sector-crossing times, compares to 5s WDT
11. • [clauded] WiFi STA mode with event-group signaling
    • [clauded] STA-first with softAP fallback was already implemented in start_wifi()
    • [clauded] Added EventGroupHandle_t comms_event_group in comms_events.h with WIFI_READY_BIT / BT_READY_BIT
    • [clauded] Replaced blind 500ms vTaskDelay on alarm wake with xEventGroupWaitBits(COMMS_ALL_BITS, 5s timeout)
    • [clauded] soft_idle_exit() → webserver_restart_wifi() / bt_hid_resume() set bits; webserver_stop() / bt_hid_stop() clear bits
    • [clauded] Bits set even on permanent init failure so alarm-wake never blocks forever
12. • [clauded] Verify sensors_init() placement and ISR safety
    • [clauded] Moved sensors_init() to main.c as init_critical("SENSORS", sensors_init) — runs before FSM
    • [clauded] Removed dead commented-out sensors_init() / sensors_stop() from sensors.c
    • [clauded] Audited ISR: sensor_isr_handler is IRAM_ATTR, uses only esp_timer_get_time() (IRAM-safe), gpio_get_level(), xQueueSendFromISR() — no logging/malloc/flash
    • [clauded] sensors_init() failure is now critical (→ reboot via init_critical)
13. • [clauded] External 32kHz crystal not needed (deep sleep disabled, soft idle instead) — removed crystal config from sdkconfig.defaults; rtc_xtal_init() already a no-op; crystal remains on PCB but unused
14. • [clauded] Removed rtc_wakeup_cause() — was unused (informational only, never called)
15. • [clauded] Confirmed rtc_check_shutdown_timer() uses unsigned TickType_t subtraction — wraps correctly; removed esp_timer overflow TODO comment from main.c
16. • [test] Logtool GUI output (matplotlib)
17. • [test] Verify naming convention adherence across codebase
18. • [test] Verify WiFi SSID rename triggers comms reboot
19. • [clauded] Documentation restructure
    • [clauded] Move project/hardware documentation from CLAUDE.md → README.md; keep CLAUDE.md for AI-specific instructions and conventions only
    • [clauded] Document all FreeRTOS tasks and priorities in README.md
    • [clauded] Add terse comments to FSM state transitions in control_fsm.c (focus on "why", not "what")
20. • [clauded] Fix compile warnings — unused vars (uart_comms.c, rf_433.c), const-correctness (log_write signatures), fallthrough annotation (control_fsm.c)
21. • [clauded] NVS is required: WiFi blob stores RF cal data (CONFIG_ESP_WIFI_NVS_ENABLED), Bluedroid stores bonding/GATT cache unconditionally, bt_hid.c stores last-connected BDA. Cannot remove nvs_flash_init().
22. • [clauded] NVS vs custom params: NVS serves WiFi/BT internals + BDA storage; custom flash partition serves app params with CRC32 protection. Different purposes, no consolidation needed.
23. • [clauded] BUG FIX: FSM_CMD_START fallthrough was overwriting this_move_dist = MIN(...) with unconditional DRIVE_DIST — replaced fallthrough with goto to shared start logic so leash limit is preserved
24. • [clauded] General bug scan (FSM, power, sensors, storage, comms, RTC, peripherals)
    • Ran 4 parallel deep-dive reviews across entire codebase. Findings below.
    • False positives eliminated: override fallthrough (breaks present), soft idle during motor ops (FSM resets timer), JACK_DOWN_TIME uninitialized first move (jack_finish_us always set before use)

Suspected Bugs (from item 24 scan)

28. • BUG [CRITICAL]: get_is_safe() hardcoded return true — safety sensor completely bypassed
    • sensors.c:182 — return true; with //return is_safe; commented out below
    • All FSM safety checks (STATE_JACK_UP_START, JACK_UP, DRIVE_START_DELAY, DRIVE, DRIVE_END_DELAY, calibration states) are no-ops
    • Safety break will NOT trigger STATE_UNDO_JACK_START — machine runs through hazard conditions
    • Debounce logic in sensors_check() still runs but output is discarded
29. • BUG [CRITICAL]: E-fuse INOM params allow min=0.0 → division by zero
    • power_mgmt.c:380 — float I_norm = fabsf(channel->current / I_nominal);
    • storage.h EFUSE_INOM_1/2/3 bounds: min=0.0, max=200.0
    • If param=0 → I_norm=Inf → instant trip on any current (motor won't run)
    • If param=NaN (flash corruption) → I_norm=NaN → all comparisons false → e-fuse NEVER trips (motor can burn)
    • Fix: raise min bound to 0.1 or add explicit NaN/zero guard before division
30. • BUG [HIGH]: No timeout on STATE_UNDO_JACK_START
    • control_fsm.c:486-493 — waits for !efuse_get(BRIDGE_JACK) with no max wait
    • If jack efuse never cools (hardware fault, thermal runaway), FSM stuck indefinitely
    • User CAN send FSM_CMD_STOP to escape, but no automatic recovery
    • Fix: add timeout (e.g. 30-60s) before forcing transition to IDLE with error
31. • BUG [HIGH]: No e-fuse checks in calibration movement states
    • control_fsm.c:495-512 — STATE_CALIBRATE_JACK_MOVE and STATE_CALIBRATE_DRIVE_MOVE
    • Only check get_is_safe() and timer_done(), NOT efuse_get()
    • Relay outputs (lines 625-640) drive motors regardless of efuse status
    • Jack cal runs up to 3s, drive cal up to 6s without overcurrent protection
    • Fix: add efuse_get() check and abort calibration on trip
32. • BUG [HIGH]: BLE HID scan task missing watchdog registration
    • bt_hid.c — bt_hid_scan_task() never calls esp_task_wdt_add(NULL)
    • Task blocks on xSemaphoreTake(s_scan_sem, portMAX_DELAY) — if GAP callback never signals, hangs forever
    • Unlike rf_433 task (which registers WDT), BT task has no WDT coverage
    • Fix: add esp_task_wdt_add(NULL) and periodic esp_task_wdt_reset() (or use timeout on semaphore)
33. • BUG [HIGH]: ISR sensor queue full → events silently dropped
    • sensors.c:57 — queue size 16, xQueueSendFromISR() return value not checked
    • If sensors_check() consumer falls behind (4 sensors firing edges), events lost
    • Encoder counts become inaccurate → drive distance wrong
    • Fix: check return value, optionally increment a dropped-event counter for diagnostics
34. • BUG [HIGH]: Params not validated on set, only on commit — FSM reads unvalidated values
    • storage.c:268-273 — set_param_value_t() writes directly to parameter_table[] with no bounds check
    • validate_param() only called in commit_params() (before flash write)
    • Between POST and commit, FSM can read out-of-range values (e.g. DRIVE_DIST=999999)
    • Fix: call validate_param() inside set_param_value_t(), or at least in comms.c after setting
35. • BUG [MEDIUM]: Solar FSM timer uninitialized
    • solar.c:17 — RTC_DATA_ATTR int64_t timer; has no initializer
    • RTC memory may contain garbage on first cold boot before solar_reset_fsm() sets it to -1
    • solar_run_fsm() is called (main.c:253) before solar_reset_fsm() has run on first boot path
    • Fix: initialize to -1 in declaration: RTC_DATA_ATTR int64_t timer = -1;
36. • BUG [MEDIUM]: E-fuse param bounds too loose
    • EFUSE_HEAT_THRESH min=0.0 — allows instant trip on any current draw (storage.h)
    • EFUSE_INRUSH_US max=10000000 (10s) — allows 10s of unlimited current with no e-fuse protection
    • Fix: tighten bounds (e.g. HEAT_THRESH min=1.0, INRUSH_US max=2000000)
37. • BUG [MEDIUM]: No mutex on parameter_table[] — concurrent access from HTTP/UART/FSM tasks
    • storage.c — parameter_table[] read/written by HTTP POST handlers, UART handlers, and FSM task
    • 32-bit aligned reads/writes are atomic on ESP32, so u16/u32/i16/i32/f32 are safe
    • f64 (8 bytes) and str16 (16 bytes) could be torn reads — but no f64 or str params are read by FSM in hot path
    • Severity is low in practice but architecturally unsound
38. • Extract pure logic (e-fuse thermal model, param serialization, sensor debounce) into host-testable modules with Unity/CMock?
39. • UART integration test framework: Python runner + ESP-side test commands
40. • Bug: WiFi won't want to connect to STA except at first boot