# 07 — Phased emulation plan

## North-star architecture

**One Web Component**, **one simulation hook**, **one state machine** —
parameterised by panel kind. The state machine internally branches per
controller family (SSD168x, UC81xx, Spectra6) but exposes a single
`metadataId = 'epaper-<panel-kind>'` for ComponentRegistry.

```
┌─────────────────── frontend/src/components/velxio-components ──────────────┐
│                                                                             │
│   EPaperElement.ts          (Web Component <velxio-epaper panel-kind=…>)    │
│   EPaper.tsx                (React wrapper — thin)                          │
│                                                                             │
└──────────────────────────────────┬──────────────────────────────────────────┘
                                   │ pinInfo + canvas
                                   ▼
┌────────────────── frontend/src/simulation/parts/EPaperPart.ts ─────────────┐
│                                                                             │
│   const familyDecoders = {                                                  │
│     'ssd168x': new SSD168xDecoder(panel),                                   │
│     'uc81xx':  new UC81xxDecoder(panel),                                    │
│     'spectra6': new Spectra6Decoder(panel),                                 │
│   }                                                                         │
│                                                                             │
│   spi.onByte = (b) => decoder.feed(b, dcState)                              │
│   onActivate() → composeAndFlush() → pulseBusy(REFRESH_MS)                  │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Phase 1 — SSD168x mono (1.54", 2.13", 2.9", 4.2", 7.5")

Smallest scope that ships something useful. Five metadata IDs, one
decoder, one Web Component.

**Deliverables:**
1. `EPaperElement.ts` — Web Component supporting `panel-kind` ∈
   `epaper-1in54-bw | epaper-2in13-bw | epaper-2in9-bw | epaper-4in2-bw |
    epaper-7in5-bw`. SVG body + active area canvas + FPC pins.
2. `EPaper.tsx` — React wrapper, forwards canvas readiness via
   `canvas-ready` custom event (mirrors ILI9341).
3. `EPaperPart.ts` — registers all 5 metadata IDs with the same
   `ssd168x` decoder + a per-panel resolution + bezel config.
4. `ComponentRegistry.ts` — wire the IDs.
5. Library auto-install: ensure GxEPD2 + Adafruit_GFX trigger via the
   sketch's `#include`.
6. Pixel-buffer fingerprint test (one per panel size).

**Decoder scope:** the 17 SSD168x commands listed in `02_controllers.md` ×
two RAM planes × the 0x20 ACTIVATION trigger. Anything else (LUT writes
0x32, gate driving voltage 0x03, etc.) is **silently consumed** so the
init sequence completes without warnings.

**Acceptance test:**
- Compile `GxEPD2_HelloWorld.ino` for the 1.54" panel against ESP32, Pi
  Pico, and Arduino Uno. Compile success on all three.
- Run on ESP32 + Pi Pico in the simulator. After ~50 ms BUSY pulse the
  canvas shows "Hello World" with a sharp 200×200 buffer.

## Phase 2 — Tri-colour SSD168x (B/W/Red 2.13" + 2.9")

Reuses 90% of Phase 1. Adds:

- Two-plane composition (`0x24` black + `0x26` red).
- Two new metadata IDs: `epaper-2in13-bwr`, `epaper-2in9-bwr`.
- Web Component palette change.

## Phase 3 — UC81xx (4.2" UC8176, 7.5" UC8179, 5.65" 7-colour ACeP UC8159c)

New decoder. Different command set (0x10 DTM1, 0x12 DRF, etc.) but
**same wiring + same Web Component**. Scope:

- `UC81xxDecoder.ts` for mono 4.2" / 7.5".
- `ACePDecoder.ts` for 7-colour 5.65" (4 px / byte palette).

## Phase 4 — Spectra 6 (the user's 13.3" 1200×1600)

New decoder; different command set again. Slowest refresh (12 s real,
emulator default 200 ms). Massive framebuffer (1.2 MB raw at 6 colours;
~470 KB packed) — make sure the canvas downscales properly for gallery
preview thumbnails.

## Phase 5 — IT8951 (Carta 6"–10.3" greyscale)

Different beast. Command-packet protocol over SPI. Deferred until a
concrete user asks.

## Out-of-scope forever (probably)

- LUT-driven custom waveforms — accept silently, never validate.
- Real-time partial-window updates — Phase 1 just full-frames.
- Capacitive touch overlay — different component (EPD has no touch panel
  built in; touch is an upper layer in some bundles like Waveshare's CFAF).

## Risk register

| Risk | Mitigation |
|---|---|
| GxEPD2 + Adafruit_GFX too big for AVR (Uno) at 4.2"+ | Ship the small panels (1.54", 2.13") for AVR; the rest get an "AVR not supported" hint in the Library Manager modal. |
| Spectra 6 reverse-engineering may be incomplete | Ship Phase 1–3 first; Spectra 6 can land after we capture real SPI traces from a Seeed EE02 via Saleae and adjust. |
| BUSY emulation timing too short → firmware loops never see HIGH | Default to 50 ms refresh. Add a `refresh-ms` attribute on the Web Component. |
| Controller silently differs across panel revisions | Fingerprint commands: log to `chip_log` events whenever an unknown opcode is seen so users can report panel quirks. |

## What can ship today

Just the dossier (this folder), a couple of pure-state-machine Python
unit tests (next file), and one canonical sketch in `sketches/`. Real
emulator code is a separate PR — explicitly **deferred** until the user
greenlights phase 1.