refactor(firmware): per-panel folder layout + parametrized config.h

Reorganizes the tree so adding a new panel is purely additive — drop in a
new src/panels/{vendor}/v{N}/ folder and a new platformio.ini env block,
no surgery to existing files.

Layout:
  src/                              shared across all panels
  src/panels/waveshare73/v1/        V1 driver, version, README
  data/waveshare73-v1/              LittleFS payload at this panel's size

src/config.h still defines the panel-agnostic bits (NVS keys, color
palette, network, sync-fail border) but EPD_WIDTH / EPD_HEIGHT / pin
assignments now come from each env's -D flags. Strict #error guards in
production builds; native tests get the V1 defaults via UNIT_TEST.

build_src_filter per env picks the right driver:
  waveshare73-v1   main + panels/waveshare73/v1/
  test-display     test_display + panels/waveshare73/v1/
  sim-yellow       sim_border + panels/waveshare73/v1/
  sim-red          sim_border + panels/waveshare73/v1/
  native-test      unchanged

When V2 hardware lands, the diff is a new env block, a new
src/panels/waveshare133/v1/epd_driver.cpp, and regenerated screens at
data/waveshare133-v1/. Existing V1 envs stay frozen — re-flashing old
units remains a one-liner.

scripts/gen_screens.py takes --panel to target the correct
data/{panel}/ subfolder; defaults to waveshare73-v1.

29/29 native tests pass. All four hardware envs build clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-07 12:31:23 -04:00
parent 27d01057e4
commit a6ed67a3f4
13 changed files with 229 additions and 66 deletions
+48
View File
@@ -0,0 +1,48 @@
# waveshare73 / v1
Driver for the Waveshare 7.3" 6-color e-ink panel (800×480, Spectra-6) on a
discrete ESP32 dev-board breakout. This is the original V1 firmware that
shipped on Matt's prototype unit.
## What lives here
- `epd_driver.cpp` — implements the `epd.h` interface for this panel:
`epd_init`, `epd_sleep`, `epd_fill`, `epd_draw_image_from_file`,
`epd_draw_image_with_border`, `epd_draw_qr`, `epd_draw_ap_screen`,
`epd_draw_setup_screen`. The init byte sequence at the top of `epd_init()`
is verified for this specific controller; do not blind-paste from another
panel.
- `version.h``PANEL_FW_VERSION` string transmitted during provisioning.
Bump when the driver changes in a way the server should know about.
## Per-panel data (lives elsewhere)
Pre-rendered LittleFS payloads for this panel size live at
`data/waveshare73-v1/`:
- `ap_bg.bin`, `setup_bg.bin` — captive-portal and account-binding
background screens at 800×480
- `img.bin`, `img_portrait.bin` — test images used by the `test-display`
build env
Regenerate with `scripts/gen_screens.py --width 800 --height 480` after
changing the source artwork.
## Build env
```bash
pio run -e waveshare73-v1 --target upload # production firmware
pio run -e test-display --target upload # single-image hardware test
pio run -e sim-yellow --target upload # sync-fail border test
pio run -e sim-red --target upload # no-WiFi border test
```
The build flags supplied by `platformio.ini` parametrize `src/config.h`
this folder doesn't redefine pins or dimensions itself.
## QR positions
`epd_draw_ap_screen` and `epd_draw_setup_screen` have hardcoded QR
coordinates (cell size, x, y) tuned for 800×480 + the bg screens at
`data/waveshare73-v1/`. If the bg art changes, the matching constants
in `gen_screens.py` and the driver must be re-tuned together.