xteink-web-emulator

An offline, in-browser emulator for the xteink X3/X4 (ESP32-C3 + e-ink): upload a firmware .bin, run the real machine code client-side, see the screen, press buttons, mount a virtual SD — no server, no proprietary engine.

Status: native peripheral models done for the X3. Unmodified canonical firmware boots to the home screen, mounts a FAT32 SD image, lists its files, and responds to button presses under a patched espressif-qemu. The browser (WASM) port is next. See ROADMAP.md for architecture and plan.

Quick start (native QEMU)

nix develop
make qemu             # clone espressif/qemu @ pinned tag, apply patch, build (JOBS=2)
make firmware sdimage # 16 MB flash.bin + FAT32 sd.img from a PlatformIO build
make run              # boot the xteink-x3 machine (add `-display none` for headless)

Point at a firmware build with make firmware FIRMWARE_DIR=/path/to/.pio/build/gh_release. make qemu is a long compile on modest hardware — set JOBS to taste.

Contents

• qemu/patches/0001-xteink-x3-machine.patch — the xteink-x3 machine and its device models (ADC, GPIO, SPI2, UC8253 e-ink, SD-over-SPI fix), applied onto the pinned espressif/qemu tag by scripts/build-qemu.sh.
• flake.nix — the espressif-qemu release binary as the fast generic baseline (nix run .#run-upstream -- flash.bin), plus a devShell with QEMU's full build environment. Makefile — qemu, firmware, sdimage, run, chip.
• scripts/mksd.sh — build the FAT32 SD backing image (local-disk impl of the SD block interface).
• chip/eink-x3.chip.c — the reverse-engineered X3 e-ink protocol, first written as a Wokwi chip and now the reference for the QEMU display device. make -C chip test runs its host self-check.

Why not Wokwi

Wokwi runs any bin in a browser and we had the e-ink chip working — but its simulation engine is proprietary and gated behind a license/service, so it can't be self-hosted or run airgapped. QEMU is the open path; the e-ink protocol work carried straight over.