GxEPD2-esphome/CONTRIBUTING.md

Contributing to gxepd2

A native ESPHome display platform for Good Display / Waveshare SPI e-paper panels. Instead of running GxEPD2's own C++ (or an Arduino-API shim) on the device, it replays a captured GxEPD2 command sequence as a non-blocking, loop()-stepped state machine. One GxEPD2 driver's exact on-wire behaviour is reproduced byte-for-byte, without its blocking single-call-stack control flow and without any vendored driver code at runtime.

This document is the model to work against when adding a panel or changing the engine. If something here no longer matches the code, the code is the source of truth — please fix the doc in the same change.

Architecture

Three parts:

• EpdPanelDescriptor (components/gxepd2/panel_*.h) — plain data for one panel: its reset/init/window/refresh command sequences, plane layout, bit depth, palette, and timing. No logic.
• CycleEngine (cycle_engine.h) — a loop()-stepped state machine that walks a descriptor to drive one full-frame update.
• display.py — ESPHome codegen. model: selects the descriptor; the descriptor headers are all #included unconditionally by gxepd2_display.h, so any model is selectable with no extra wiring.

No GxEPD2 code, vendored or otherwise, runs on the device.

Bringing up a panel: capture, not transcription

A descriptor is generated by observing a real GxEPD2 driver run on a host, not written by hand. The tooling lives in tools/gxepd2_harness/.

1. Rigging the capture

spy/Arduino.h, spy/SPI.h (+ Adafruit_GFX.h, pgmspace.h) are minimal host stand-ins for the Arduino APIs a GxEPD2 driver expects — just enough to compile and run one driver class (from the vendored source in third_party/GxEPD2/) natively. Every digitalWrite, SPI byte (command vs data, by the DC line), delay, and busy-pin read is recorded instead of touching hardware (trace.h). A run_<panel>_emit.cpp is a 4-line main that instantiates the vendor driver and hands it to the emitter.

2. First pass — the descriptor emitter (emit_descriptor.h)

The emitter drives a fixed lifecycle (writeScreenBuffer() → writeImage() → refresh()) and turns the recorded event stream into a candidate panel_*.h. It phase-segments at the public-API boundary — the burst of pixel data is the plane write — and from that recovers:

• the init / window / refresh command sequences and the plane-write command(s);
• resolution, busy polarity, refresh timeout (read directly from the driver's static const members, not the trace);
• plane_count and, for multi-plane panels, whether the per-plane window sets are identical (shared region → window_per_plane = false) or differ (separate physical regions → window_per_plane = true).

A delay() immediately before a busy-wait is the vendor poll loop's, not a command delay, so it folds into wait_busy_after. The emitter reproduces every shipped single-plane and shared-region (3-colour) descriptor byte-for-byte.

3. What must be checked dynamically

Some descriptor facts aren't visible in one straight capture; they're derived by probing with distinctive inputs and reading the transform back out:

• Window encoder (screen coords → window-register bytes). window_sweep.h calls refresh(x,y,w,h) at several in-bounds rects and fits the per- controller mapping by observation, cross-checked against the full-frame window — catching byte-math errors a command-skeleton trace can't (right command, right byte count, one wrong byte value). See the encoder table below.
• Pixel packing, palette codes, row order. Diag harnesses (run_diag*_harness.h) replace the uniform fill with positional/value tags and read the exact wire bytes: Pattern A recovers row ordering (line_order), Pattern B recovers packing + palette codes (bits_per_pixel + palette), and a native-path variant handles packed panels whose re-pack doesn't preserve byte identity.
• plane_invert (whether each plane's wire byte is the bit-complement of the engine's buffer byte). The fill-capture probe (probe_plane_invert.h, also used inside the emitter) drives white/black/red writeScreenBuffer fills and reconciles each plane's wire byte against the engine's fixed buffer convention (plane 0 bit = white, plane 1 bit = red).
• bits_per_pixel (1bpp vs packed). The same probe: a white fill whose wire byte is all-bits (0x00/0xFF) is a 1bpp plane model; anything else (e.g. 0x55) is packed, and depth/palette come from Pattern B.

4. Capturing nothing is sometimes correct

A minimal driver is a valid descriptor, not a failed capture. Controllers that load their configuration from on-chip OTP need almost no register setup. GDEY0213F52 (JD79676) is the example: its whole init is 0xE9 + power-on, it issues no window command (OTP defaults to the panel's native frame), and refresh is a bare trigger. The emitter captures exactly that; an empty window is emitted as window_sequence = {nullptr, nullptr}, which the engine skips.

5. Limits — what capture can not derive

These are hardware facts no command trace contains:

• Whether the chosen vendor driver is correct for the physical panel. The harness faithfully reproduces whatever driver it's given; a driver that's wrong for the panel propagates the error. The mitigation is a capture-input decision — pick the most authoritative source driver (e.g. a vendor's own reference over a community driver) — plus an on-hardware visual check. No amount of probing substitutes for it. Equally, a bench symptom is not proof the driver is wrong: rule out the physical layer first (supply current, wiring, a marginal unit), since an under-powered panel can mimic a command-sequence bug.
• Busy polarity and post-reset timing. Busy polarity comes from the driver's busy_level; it, and OTP/post-reset busy behaviour, are only confirmable on hardware. The engine always does a busy wait after the reset pulse, because controllers that load from OTP hold BUSY during that load and silently drop any command sent before it clears.
• True dual-region command structure. Dual-chip panels (master/slave) carry 0xA2-style region selects in init and refresh that the emitter's single/shared-region segmentation doesn't yet model; those descriptors still take manual assembly for the region layer.

Execution engine (cycle_engine.h)

A loop()-stepped state machine, not a port of GxEPD2's synchronous update(). States: RESET_LOW → RESET_LOW_WAIT → RESET_HIGH_WAIT → RESET_SETTLE → WAIT_BUSY (post-reset) → INIT_CMD → SET_WINDOW → WRITE_PLANE → REFRESH_CMD → DONE, with POST_DELAY/WAIT_BUSY as reusable sub-states and ABORTED as a hard bailout on a busy timeout (pressing on past a timed-out wait only obscures which step failed).

step() runs once per loop() tick and always does one small bounded unit of work: one EpdCommand per command-table step, at most BYTE_BUDGET bytes of a plane burst, and deadline (millis()-based) delays and busy-waits — never a blocking call. Nothing here can starve another task or need a watchdog subscription.

Multi-plane and multi-region are one mechanism: after writing plane k, if more planes remain the engine writes the next (shared window) or re-enters SET_WINDOW for window_sequence[k] (window_per_plane, separate regions, each sized by plane_width). line_order controls how a plane's wire lines map to buffer rows: SEQUENTIAL (line i = row i) or PAIRED_EDGES, which emits 2*height lines (line 2i = row H-1-i, line 2i+1 = row i) to fill the 2x-height RAM of a controller that scans from both edges toward the middle - reproducing GxEPD2's own doubled line emission, orientation included.

Every command and data byte is its own SPI transaction with CS toggled around it — wasteful versus a burst transfer, but deliberate: matching the vendor _writeCommand()/_writeData() cycle byte-for-byte is the point.

Descriptor format (epd_command.h)

EpdPanelDescriptor fields: width/height; busy_active_level + busy_timeout_ms; init_sequence / window_sequence[2] / refresh_sequence (arrays of EpdCommand{cmd, data, len, delay_before, delay_after, wait_busy}); window_per_plane; plane_count, plane_write_cmd[2], plane_invert[2], plane_width; line_order; and the pixel format — bits_per_pixel (1 = 1bpp plane model; 2/4 = packed code-per-pixel) with palette + blank_code for packed panels. "Is it packed" is bits_per_pixel > 1 and "which codes" is data, so a 4bpp 7-colour (ACeP) panel is just a palette plus bits_per_pixel: 4 with no new engine flag (GXEPD2_PALETTE_7C is written, awaiting a captured descriptor).

Color and bit-depth model

Buffers map color literally. For 1bpp panels draw_absolute_pixel_internal sets plane 0 for a bright color (white/blank) and routes a red/accent pixel to plane 1 when the panel has one. For packed panels each pixel's wire code is the nearest palette entry to the drawn RGB (exact matches win, so named colors are deterministic). Buffer size is width*height*bits_per_pixel/8, heap- allocated via ESPHome's RAMAllocator — so anything above 1bpp effectively wants PSRAM.

invert_mono: false|true (1bpp only) handles ESPHome's COLOR_ON = white default. With the literal mapping (false, native) a default-color it.print() is white-on-white and draws nothing; true flips the mono sense so bright = ink (the waveshare_epaper-compatible convention), easing migration from that component. The red/accent plane is unaffected either way.

Window encoders by controller

Derived by the sweep (screen coords x,y,w,h):

Controller	Panels	Window encoding
SSD1680	213_Z98c, 154_Z90c	0x11=0x03; 0x44=[x/8,(x+w-1)/8] byte-X; 0x45=[y,y+h-1] 16-bit LE; 0x4E/0x4F cursors
SSD1677	426_GDEQ0426T82	0x11=0x01; 0x44=[x,x+w-1] raw-pixel 16-bit LE; 0x45=[H-1-y, H-1-(y+h-1)] reversed-Y 16-bit LE
UC8179	583_GDEQ0583T31	0x90=[x,x+w-1,y,y+h-1] raw-pixel 16-bit big-endian + flag, bracketed by 0x91/0x92
JD79667	290c_GDEY029F51	0x83=[x,x+w-1,y,y+h-1] raw-pixel 16-bit BE + mode byte
JD79676	213c_GDEY0213F52	none — OTP-default frame
HX8717 dual	579c_GDEY0579F51	per-region fixed full-frame 0x83 (sweep shows the rect is ignored)

Supported panels

The registry is display.py's PANELS dict (the single source of truth for which panels ship and their status); tools/panel_table.py renders this table from it, and a non-verified panel logs a warning in its boot dump_config.

model:	Panel	Controller	Format	Status
GxEPD2_154_Z90c	GDEH0154Z90	SSD1681	3-color	✅ verified
GxEPD2_213_Z98C	GDEY0213Z98	SSD1680	3-color	✅ verified
GxEPD2_213c_GDEY0213F51	GDEY0213F51	JD79661	4-color	⚪ structural
GxEPD2_213c_GDEY0213F52	GDEY0213F52	JD79676	4-color	✅ verified
GxEPD2_426_GDEQ0426T82	GDEQ0426T82	SSD1677	mono	✅ verified
GxEPD2_583_GDEQ0583T31	GDEQ0583T31	UC8179	mono	✅ verified
GxEPD2_750_GDEY075T7	GDEY075T7	UC8179	mono	✅ verified
GxEPD2_290c_GDEY029F51	GDEY029F51	JD79667	4-color	⚪ structural
GxEPD2_579c_GDEY0579F51	GDEY0579F51	HX8717	4-color	✅ verified
GxEPD2_579c_GDEY0579F51_MASTER_ONLY	GDEY0579F51	HX8717	4-color	🔧 diagnostic

✅ rendered correctly on real hardware · ⚪ captured, not yet bench-confirmed · 🔧 diagnostic variant.

Bench test pattern

GxEPD2Display::test_pattern(font?) is the canonical visual check; prefer it over a plain fill/text for bring-up. It reads the descriptor, so it is bit-depth aware: the color-bar count, ladder cycle, and corner markers scale to the colors the panel can show (2 mono, 3 BW+accent, 4/7 packed). A dithered grey ramp gives 1bpp panels a graded sweep rather than two flat blocks, a corner-to-corner diagonal catches coordinate-transform bugs (a dashed diagonal is the row-reorder signature that pins down a panel's line_order), and the border + corner markers catch clipped/offset origins and rotation/mirror errors.

Pass a font to label the panel with its model (the Good Display part number minus its series prefix, e.g. 0583T31); call test_pattern() with no argument for an unlabelled pattern that needs no font in the config. tests/test_pattern_bar_ladder_diagonal.esp32-idf.yaml is the reference fixture.

Footprint

Same strategy as ESPHome's own epaper_spi: a heap buffer sized by resolution × depth, minimal static footprint. For the same resolution the buffer byte-count is identical, and a full build lands within noise of an epaper_spi build in flash and static DRAM (both dominated by the common ESP-IDF/framework floor). The only extra cost is a few hundred const bytes of command table per captured panel.

Target frameworks

IDF-first; ESP32-Arduino is supported. ESP8266-Arduino compiles but is resolution-limited at 1bpp and lacks the PSRAM that >1bpp panels need.