README.md
gxepd2 capture harness
Host-side tooling that generates a panel descriptor by observing a real GxEPD2 driver run, instead of hand-writing one. See ../../CONTRIBUTING.md for the full model; this is the how-to.
The vendored GxEPD2 source it compiles against lives in third_party/GxEPD2/.
Everything here runs on a dev machine with plain g++ — no ESP toolchain.
Emit a descriptor
One command (from the code/ root) resolves the driver, builds+runs the
harness, and prints a candidate descriptor:
tools/capture.py --list # capturable driver classes
tools/capture.py GxEPD2_154_Z90c # candidate -> stdout
tools/capture.py GxEPD2_154_Z90c -o /tmp/panel_154_z90c.h
tools/capture.py GxEPD2_154_Z90c --debug # also dump the capture structure
It finds the driver in catalog.json (or by globbing third_party/GxEPD2/ for
one the catalog doesn't list), so there's no build line to hand-write. Under
the hood it does exactly:
VSRC=third_party/GxEPD2/src
g++ -std=c++17 -I tools/gxepd2_harness/spy -I $VSRC -I tools/gxepd2_harness \
<generated emit main>.cpp \
$VSRC/GxEPD2_EPD.cpp $VSRC/<subdir>/GxEPD2_<Class>.cpp \
-o /tmp/emit_<panel>
emit_descriptor.h phase-segments the captured command stream into the
init / window / refresh sequences + plane-write command(s), reads
resolution / busy-polarity / timeout from the driver, and derives
plane_invert and 1bpp-vs-packed from a fill probe. For a 4-colour
(epd4c/) panel it goes further: emit_palette_4c.h drives the driver's own
GxEPD2_4C wrapper, reads the wire code for each named colour, validates it
against the engine's GXEPD2_PALETTE_4C, and fills bits_per_pixel /
palette / blank_code automatically (an unexpected code map stays a TODO
carrying the observed table). Review the result, add any packed-format fields
still left as TODO — bits_per_pixel / palette for a 7-colour panel (no
resolver yet) and plane_width / line_order for dual-region — then save it
as components/gxepd2/panel_<panel>.h. capture.py also prints the exact
PANELS line to paste into display.py (key / descriptor macro / format
filled from the capture; part / controller scraped from the driver header
to sanity-check, status starting at structural).
EMIT_DEBUG=1 /tmp/emit_<panel> dumps the image-stage command/burst structure.
Regression check (CI)
tools/check_descriptors.py re-emits every shipped panel from its GxEPD2
driver and structurally diffs the result against the committed panel_*.h
(command sequences + plane layout only, not the hand/diag-filled fields). It
exits non-zero on any unexpected mismatch, so wire it into CI as a plain step:
tools/check_descriptors.py # all panels; -v shows the diff on a mismatch
A DIFF means either an emitter regression or GxEPD2 upstream drift (a
vendor bump changed that driver — review the panel). Dual-region panels the
emitter doesn't fully model yet are listed in its KNOWN_DIFF and reported as
XFAIL; panels with no GxEPD2 driver source (the synthetic MASTER_ONLY
variant) are skipped. Run it after any third_party/GxEPD2/ update.
Other programs
run_<panel>.cpp+run_harness.h— bare-driver capture plus the window-encoder sweep (window_sweep.h), for deriving the coordinate → window-byte mapping.run_<panel>_probe.cpp+probe_plane_invert.h— print theplane_invertprobe result on its own.run_*diag*.cpp— the diagnostic-fill passes that derive pixel packing, palette codes, and row order for packed / multi-region panels.spy/— the host stand-ins for the Arduino/SPI APIs a GxEPD2 driver calls;trace.hrecords what the driver does.