evan
ca07c02e02
Model the ESP32-C3 I2C fingerprint path for stock firmware detection. Add a blank X4 panel stub, live GPIO inputs, and pin the exact QEMU revision.
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: one native xteink machine selects X3 or X4 at launch. Unmodified
canonical firmware
auto-detects the selected variant: X3 boots with its UC8253 display and SD card;
X4 reaches its SSD1677 driver through a blank protocol stub. The browser (WASM)
port is next. See ROADMAP.md for architecture and plan.
Quick start (native QEMU)
git clone --recursive https://github.com/crosspoint-reader/crosspoint-reader ../crosspoint-reader
# Build ../crosspoint-reader's PlatformIO `default` environment first.
nix develop
make qemu # clone espressif/qemu @ pinned commit, apply patch, build (JOBS=2)
make firmware sdimage # 16 MB flash.bin + FAT32 sd.img from the PlatformIO build
make run # X3 (default)
make run VARIANT=x4 # X4 detection + blank SSD1677 stub
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-machine.patch— thexteink,variant=x3|x4machine and its device models (I²C fingerprints, ADC, GPIO, SPI2, X3 UC8253, X4 panel stub, SD-over-SPI fix), applied onto the pinned espressif/qemu commit byscripts/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 testruns 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.