Repository navigation
Feature: PlatformIO migration + hardware abstraction layer #151
Description
Recreated from Strycher/Field_Compass-archive#151 — originally opened by @Strycher on 2026-08-09. Credentials redacted where present.
Umbrella feature issue. Child epics are created after the design plan is approved.
Problem
Two problems that share one solution path:
-
The build is not reproducible. Four project-critical files live outside git in the Arduino sketchbook:
lv_conf.h, the active TFT_eSPI setup header,User_Setup_Select.h, and — worst —TFT_Drivers/ST7796_Rotation.h, which is a patched vendor source file that any library upgrade silently reverts. The firmware currently builds on exactly one machine. This is also what blocks ci: no arduino-cli compile gate exists — CLAUDE.md claims one that was never built #150. -
The firmware is welded to one hardware stack. Components are about to change. Today a component swap means editing an 8,700-line
.inoand hoping. 162 top-level functions, ~1,550lv_*call sites, every pin and I2C address scattered inline.
Approach
Five epics, strictly sequenced. Design plan lands in docs/plans/2026-08-09-platformio-hal-design.md.
E1 vendor config --> E2 PlatformIO --> E3 CI gate --> E4 translation units --> E5 HAL
|
+--> #147 credential provisioning (needs build flags)
The one sequencing choice that matters: the CI gate lands before the refactoring epics, not after. E4 and E5 move thousands of lines of working firmware; doing that with no automated compile gate means every mistake is caught by a human flashing a board.
arduino-cli keeps working in parallel until E2's integration test passes, so there is always a path back.
Blocked on input
Epic 5 tasks cannot be fully specified until the newly-purchased components are known. If it is input hardware (buttons / joystick / MCP23017) the epic is moderate; if the display or MCU changed, display abstraction becomes its own epic and LovyanGFX should be evaluated against TFT_eSPI.
Related
- ci: no arduino-cli compile gate exists — CLAUDE.md claims one that was never built #150 — CI compile gate (becomes E3)
- security: WiFi credentials hardcoded in Field_Compass.ino — needs a provisioning mechanism #147 — WiFi credentials in firmware (sequenced after E2)
- docs: CLAUDE.md GPS pinout is wrong (says GPIO5/6, actual is GPIO38/39) #149 — CLAUDE.md pin table (settled naturally by E5 task 5.1)
Activity
Strycher commentedon Sep 7, 2026
@Strycher — 2026-08-09
Agent: IndigoForge (session b5521fc0)
Strycher commentedon Sep 7, 2026
@Strycher — 2026-08-09
Epics created
Plan approved 2026-08-09 and narrowed. Design doc: PR #152 →
docs/plans/2026-08-09-platformio-hal-design.mdField_Compass-owuEpic A children — actionable now
setRotation(3)Field_Compass-ac2lv_conf.hField_Compass-r7iField_Compass-0ejField_Compass-fc7Later epics' integration tests
#161 (B7), #162 (C5), #163 (D6) — created up front so the dependency chain is mechanically enforced from day one, per CLAUDE-BASE § Epic Completion Protocol. Each epic's remaining child tasks get created when that epic is groomed, rather than sitting stale in the backlog.
Scope changes from the first draft
.inosplit and full HAL deferred, with rationale recorded in the plan's Deferred table.Agent: IndigoForge (session b5521fc0)
Strycher commentedon Sep 8, 2026
E4 status (translation units, Epic #212), 2026-09-07: bands 1–3 are merged (#266–#269, #275–#279);
src/src.inoonmainis 4,387 lines with 17 domain units beside it. Band 4 (#265, the LVGL screens) is PR #280, open and waiting for hardware verification before merge per its acceptance; after it,src.inois 750 lines ofsetup/loop/initLVGL/buttons and the firmware is 25 translation units. Every move was proven behaviour-neutral by symbol set and reference set (docs/e4-proofs/); nothing was flashed. The decision log for the autonomous session that did bands 2–4 isdocs/e4-session-2026-09-07.md. E5 (HAL, #156) is unblocked once #280 merges; #99 (runtime credentials) can start now — the placeholders are insrc/web.cpp.Strycher commentedon Sep 8, 2026
Progress 2026-09-08: PR #288 adds the UM FeatherS3D env (um_feathers3) with the board pin profile in src/fc_config.h and per-env TFT flags, fixes #284 and #285, and locks the bench wiring in docs/um-bench-wiring.md. Filed under this feature tonight: #282, #283, #284, #285, #286 (OLED boot glitch/layout), #287 (fuel gauge 140 %). The Adafruit env feather_s3 builds unchanged.