velxio/test/test_epaper/autosearch/00_overview.md

00 — ePaper / e-Ink overview (why emulation is non-trivial)

What an ePaper panel is

Electrophoretic display panels use charged pigment particles in microcapsules that move in response to an electric field. Unlike OLED or TFT-LCD:

Property	TFT/OLED (ILI9341, SSD1306)	ePaper (SSD1681, UC8159, …)
Refresh model	Continuous (per-frame)	One-shot per update
Latency	µs per pixel	0.5 – 30 s per frame
Power when idle	Backlight on	Zero (image is bistable)
Framebuffer	Driver IC RAM (volatile)	Driver IC RAM (also volatile, but only flushed on update command)
Per-pixel data	16/24-bit colour	1-bit (B/W), 2-bit (red/yellow), 3-bit (Spectra 6 / 7-colour ACeP)
Update granularity	Pixel-level	Whole-frame (most chips) or coarse partial-window (SSD1681 etc.)
BUSY pin	None	Required — host MUST poll it before/after each refresh

Implication for Velxio's emulator

A correct ePaper component needs four things our existing display emulation (ili9341, ssd1306) doesn't have:

1. Latched framebuffer. Pixels written via the WRITE_RAM command (0x24 for SSD1681) only become visible when the host issues MASTER_ACTIVATION (0x20) after DISPLAY_UPDATE_CONTROL_2 (0x22). We must hold the writes off-screen and only flush on the activation pulse.
2. Driveable BUSY pin. A real panel pulls BUSY high during refresh; the driver libraries (GxEPD2, Adafruit_EPD) busy-wait on it. The emulator must drive BUSY high for a configurable duration (~1 s mono, ~12 s Spectra 6) so polling firmware sees realistic timing.
3. DC + RST + CS + BUSY — four extra pins beyond the standard SPI trio. Our pin_map must surface them so the user can wire them via their chosen GPIOs.
4. Multi-RAM colour planes. SSD1675/SSD1681 black/red have two separate RAM commands (0x24 black, 0x26 red); UC8159c packs four pixels per byte into a single plane. The emulator must maintain N independent planes and combine them at flush time.

Out of scope (initially)

• Greyscale / waveform tables (LUT 0x32). Real panels accept a 70+ byte LUT that defines voltage levels per timing slot. We'll accept the bytes silently and snap to nearest displayable colour.
• Partial refresh. Our first cut renders the whole frame on every MASTER_ACTIVATION; partial-window mode (SSD1681 LUT_RED) is a Phase 2 refinement.
• IT8951 large-panel parallel mode. That's a 4/8/16-bit parallel interface, not SPI — out of scope until someone asks for it.

Goal of this folder

Pin down the data we need (datasheets, command lists, library quirks) so a single epaper-element.ts Web Component + EPaperPart simulation hook can support every Seeed XIAO ePaper kit and the standard GxEPD2 panel zoo with one unified controller-aware decoder.