115 lines
4.9 KiB
Markdown
115 lines
4.9 KiB
Markdown
|
# 03 — ePaper SPI protocol details (what we have to decode)
|
|||
|
|
|
|||
|
|
## Wiring (the 8-wire interface every Velxio panel will share)
|
|||
|
|
|
|||
|
|
Even across families (SSD1681 / UC8159 / Spectra 6) the **physical
|
|||
|
|
interface is the same six signals** plus power:
|
|||
|
|
|
|||
|
|
| Pin name | Direction (host → panel) | Purpose |
|
|||
|
|
|---|---|---|
|
|||
|
|
| **VCC** | power | 3.3 V |
|
|||
|
|
| **GND** | power | ground |
|
|||
|
|
| **CLK** (SCK) | host → panel | SPI clock, mode 0, 4–20 MHz |
|
|||
|
|
| **DIN** (MOSI) | host → panel | SPI data |
|
|||
|
|
| **CS** | host → panel | active low chip select |
|
|||
|
|
| **DC** (D/C, RS) | host → panel | **LOW = command byte, HIGH = data byte** |
|
|||
|
|
| **RST** | host → panel | active-low hardware reset (>200 µs) |
|
|||
|
|
| **BUSY** | panel → host | **HIGH while controller is working** (poll before next op) |
|
|||
|
|
|
|||
|
|
Some panels (the Solomon family with red ink) also expose a MISO line, but
|
|||
|
|
neither GxEPD2 nor Adafruit_EPD reads back from it in practice.
|
|||
|
|
|
|||
|
|
## Frame in vs. command in
|
|||
|
|
|
|||
|
|
The DC pin distinguishes:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌── CS asserted ──────────────────────────────────────────────────┐
|
|||
|
|
│ │
|
|||
|
|
│ DC = LOW 1 byte → command opcode │
|
|||
|
|
│ DC = HIGH N bytes → command parameters / pixel data │
|
|||
|
|
│ │
|
|||
|
|
│ CS may stay asserted across the cmd→data transition; many │
|
|||
|
|
│ drivers lower CS once per (cmd, data...) pair instead. │
|
|||
|
|
└──────────────────────────────────────────────────────────────────┘
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
The state machine the emulator needs:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
state ∈ { IDLE, WAIT_CMD, COLLECT_DATA(cmd) }
|
|||
|
|
|
|||
|
|
on CS falling edge: state ← WAIT_CMD
|
|||
|
|
on DC sample at SCK: if DC=LOW → state ← WAIT_CMD
|
|||
|
|
if DC=HIGH → state ← COLLECT_DATA(cmd)
|
|||
|
|
on byte received:
|
|||
|
|
if state == WAIT_CMD: cmd ← byte; state ← COLLECT_DATA(cmd)
|
|||
|
|
if state == COLLECT_DATA(cmd): apply parameter or pixel data
|
|||
|
|
on CS rising edge: state ← IDLE
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Note the GxEPD2 / Adafruit_EPD libraries actually re-toggle DC for every
|
|||
|
|
write — they don't keep CS asserted for long bursts — so a per-byte DC
|
|||
|
|
sample is sufficient.
|
|||
|
|
|
|||
|
|
## BUSY pin semantics
|
|||
|
|
|
|||
|
|
After almost every command that triggers physical movement of pigment,
|
|||
|
|
the controller pulls BUSY **high**. The libraries poll BUSY in a tight
|
|||
|
|
loop (with a 10 ms `delay()` between samples). The emulator must:
|
|||
|
|
|
|||
|
|
1. After accepting `0x20` ACTIVE_DISPLAY_UPDATE: drive BUSY high.
|
|||
|
|
2. After a configurable refresh duration (1 s mono, 12 s Spectra 6),
|
|||
|
|
drive BUSY low.
|
|||
|
|
3. During HW reset (RST low) the controller re-asserts BUSY high until it
|
|||
|
|
finishes its internal init (~10 ms).
|
|||
|
|
|
|||
|
|
For the emulator, "configurable refresh duration" doesn't have to be real
|
|||
|
|
seconds — we can shrink it to ~50 ms for snappy testing as long as it's
|
|||
|
|
**non-zero** so the firmware's busy-wait loop sees a transition.
|
|||
|
|
|
|||
|
|
## Two independent RAM planes (B/W/R panels)
|
|||
|
|
|
|||
|
|
Tri-colour SSD1675/1680 panels have **two** RAM planes:
|
|||
|
|
|
|||
|
|
- `0x24` WRITE_BLACK_VRAM — black/white plane (1 = white, 0 = black)
|
|||
|
|
- `0x26` WRITE_RED_VRAM — red plane (1 = red, 0 = transparent / underlying B/W)
|
|||
|
|
|
|||
|
|
Compositing rule used by every SSD168x driver: **red wins over black**.
|
|||
|
|
On flush, for each pixel:
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
if red_plane[x,y] == 1: pixel = RED
|
|||
|
|
elif bw_plane[x,y] == 1: pixel = WHITE
|
|||
|
|
else: pixel = BLACK
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
UC8159c (5.65" 7-colour ACeP) is different: **single plane, 4 bits/pixel
|
|||
|
|
packed 2 px/byte**, mapped to a 7-colour palette. Spectra 6 uses 3
|
|||
|
|
bits/pixel packed 2 px/byte (with a 6-colour palette).
|
|||
|
|
|
|||
|
|
## RAM addressing model (Solomon family)
|
|||
|
|
|
|||
|
|
Pixels live in a rectangular window selected by:
|
|||
|
|
|
|||
|
|
- `0x44 SET_RAMX_RANGE` — start_col, end_col (bytes; 1 byte = 8 horizontal pixels)
|
|||
|
|
- `0x45 SET_RAMY_RANGE` — start_row, end_row (in scanlines; 16 bits each)
|
|||
|
|
- `0x4E SET_RAMX_COUNTER` — current X (bytes)
|
|||
|
|
- `0x4F SET_RAMY_COUNTER` — current Y (scanlines)
|
|||
|
|
- `0x11 DATA_ENTRY_MODE` — bit 0: Y direction (0 = decrement, 1 = increment)
|
|||
|
|
bit 1: X direction (0 = decrement, 1 = increment)
|
|||
|
|
bit 2: address counter update direction (0 = X first, 1 = Y first)
|
|||
|
|
|
|||
|
|
Most drivers use `0x03` (X+, Y+, X-first) which means the RAM auto-increments
|
|||
|
|
column-by-column, then jumps to the next row. So a 200×200 panel needs
|
|||
|
|
200/8 = 25 bytes/row × 200 rows = 5000 bytes per `0x24` WRITE.
|
|||
|
|
|
|||
|
|
## Sources
|
|||
|
|
|
|||
|
|
- SSD1681 datasheet (commands 0x00–0x4F): see `02_controllers.md`
|
|||
|
|
- ESPHome `waveshare_epaper.cpp` (canonical reference for many panels):
|
|||
|
|
<https://api-docs.esphome.io/waveshare__epaper_8cpp_source>
|
|||
|
|
- GxEPD2 source: <https://github.com/ZinggJM/GxEPD2/tree/master/src>
|
|||
|
|
- Solomon Systech SSD1681 product page:
|
|||
|
|
<https://www.solomon-systech.com/product/ssd1681/>
|