Pulls the scattered refresh-strategy facts (1-in-20 ghost-flush, defer to
idle ≥ 1 s, full refresh on Ctrl-S/Ctrl-G) into one user-facing paragraph
so future readers know what scroll actually looks like on this panel and
the periodic ~1 s flash is documented intent, not a bug to chase.
The old ADR documented the specific panel choice (GDEY0579T93 + DESPI-c579)
as if it were a freshly weighed option, but the hardware was already on
hand — the real architectural decision was choosing the medium (e-ink over
FSTN graphical / Sharp Memory LCD / OLED-TFT). Rewrite the ADR around the
medium with the panel as instantiation, note the Freewrite Alpha (2023)
data point as honest expectation-setting, and propagate the anchor /
narrative changes through qfd.md, v0.1-mvp-product.md, and README.md.
2026-05-14 21:49:01 +02:00
4 changed files with 98 additions and 36 deletions
| Power | **USB-C wall power for MVP**, 18650 + IP5306 in Phase 3 | Measure power profile on real hardware before sizing the battery. E-ink + sleep should give multi-day battery life but battery introduces charging, safety, and BMS complexity we don't need on day one. |
| **GDEY0579T93 + DESPI-c579** | 5.79" / 792×272 | 2.9:1 strip | SPI, partial refresh, small framebuffer (~27 KB), Freewrite-style narrow viewport, low power, low GPIO use. | Only ~11 visible lines of edit area; less context on screen. |
| **Waveshare 7.5" V2** | 7.5" / 800×480 | 5:3 page | More lines visible, well-supported by `epd-waveshare` out of the box. | Bigger BOM, bigger framebuffer (~48 KB), more conventional / less typewriter-feeling. |
| **Waveshare 10.3" + IT8951** | 10.3" / 1872×1404 | 4:3 | Real "page" experience; great for long-form. | +$80 BOM; parallel bus eats GPIO; IT8951 adds a controller board; overkill for v0.1. |
| **2.9" / 4.2" smaller panels** | varied | varied | Cheap, common. | Too cramped for a typewriter; status bars eat the screen. |
| **E-ink (reflective, image-persistent)** | ~100–300 ms partial / ~700–1000 ms full / persists at 0 W | Paper aesthetic; persists at zero idle power; no backlight (no glare, no eye strain); category convention (Freewrite, reMarkable, Kindle Scribe, Boox); medium enforces writing posture | Slow per-keystroke feedback; ghosting accumulates → periodic full-refresh flash; scroll is the worst-case refresh op (full edit-area redraw); requires waveform / refresh-cadence tuning; Astrohaus retreated from e-ink in Freewrite Alpha (2023) on typing-latency grounds |
| **FSTN graphical LCD (monochrome)**| <16 ms, no refresh quirks | Cheap (~$5–15); trivial render code; snappy scroll | Backlit (always-on power), unreadable indoors without it; no image persistence; calculator / feature-phone aesthetic; writing-grade resolution (≥600 px wide at ≥6") effectively unavailable as a hobbyist part |
| **Sharp Memory LCD (monochrome, reflective)** | ~20 ms, persists at near-0 W | Persists *and* refreshes fast (best technical combo); sun-readable; ghost-free | Caps around 4.4" before getting rare and expensive; reflective-only feels like a screen, not paper; niche sourcing; lower DPI than e-ink at writing size |
| **TFT / OLED (color, self-lit or backlit)** | <16 ms, persists only at full power | Bright, fast, plentiful | Backlit / self-lit → screen-feel, not paper; OLED burns in static text (status line, header); defeats the writing-tool posture; not seriously a contender |
### Decision
**GDEY0579T93 driven over SPI via the DESPI-c579 breakout.** The strip
aspect biases UX toward "current line + recent context" — the writing
posture we actually want. Small framebuffer keeps PSRAM free for git pack
data. The DESPI-c579 is a passive level-shifter / FPC adapter, not an active
controller — same SPI driver model as any other e-paper.
**E-ink as the display medium**, instantiated with the **GDEY0579T93 (5.79",
792×272, SSD1683-class) driven over SPI through the DESPI-c579 breakout** —
which is already on hand. The DESPI-c579 is a passive level-shifter / FPC
adapter, not an active controller — same SPI driver model as any other
e-paper.
The medium is chosen for: paper aesthetic, zero-idle-power persistence
(which makes [ADR-008]'s battery deferral structurally cheap to revisit at
v0.8), the category convention users have a mental model for, and alignment
with the "writing tool, not screen" posture pinned in
[`CONTEXT.md`](../CONTEXT.md). The slow refresh and scroll cost are accepted
as the price of those properties.
### Consequences
- Visible edit area is ~11 lines. UI design must embrace this (no
multi-pane, no large headers). See
- Visible edit area on this panel is ~11 lines. UI must embrace the
| **`std::thread` + channels** | Boring, debuggable, stack traces work, no executor to tune; ESP-IDF FreeRTOS underneath is well-understood. | Each thread costs 8–32 KB stack depending on workload; not zero-cost like async. |
| **`embassy` async** | Trendy, ergonomic, low memory per task. | `esp-idf-rs` and `embassy` don't mix cleanly; adopting embassy means dropping `std` and rewriting against `esp-hal` (ADR-001 reversed). |
| **`embassy` async** | Trendy, ergonomic, low memory per task. | `esp-idf-rs` and `embassy` don't mix cleanly; adopting embassy means dropping `std` and rewriting against `esp-hal` ([ADR-001] reversed). |
| **`tokio` on `esp-idf-rs`** | Familiar async. | Heavy executor, oversized for ≤ 8 tasks, mbedtls/`gitoxide` integration would need a lot of glue. |
`Ctrl-S` and `Ctrl-G` also force a full refresh. Net user experience:
smooth-ish line scrolling while typing, occasional ~1 s flash on a pause or
a save.
## Error UX
| Failure | What the user sees |
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
