|
|
@@ -0,0 +1,237 @@
|
|
|
+# 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 `#include`d 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 1bpp row ordering
|
|
|
+ (`row_interleave`), 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`). `row_interleave` maps each wire byte through an
|
|
|
+interleaved row order for panels that scan from both edges toward the middle.
|
|
|
+
|
|
|
+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`; `row_interleave`; 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_290c_GDEY029F51` | GDEY029F51 | JD79667 | 4-color | ⚪ structural |
|
|
|
+| `GxEPD2_579c_GDEY0579F51` | GDEY0579F51 | HX8717 | 4-color | ⚪ structural |
|
|
|
+| `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 confirmed `row_interleave`), 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.
|
