evan
08f5e342b0
--tls generates a self-signed cert (SANs: localhost, 127.0.0.1, LAN IP) so a headless box is reachable directly over HTTPS, which browsers treat as a secure context (required for cross-origin isolation). make web now defaults to TLS.
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 and WebAssembly builds provide one xteink machine that
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. A basic static
browser UI now loads local firmware, renders the panel, and drives the physical
buttons. 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.
WebAssembly build
Podman or Docker is required. The build is limited to riscv32-softmmu and the
X3/X4 device graph; networking, audio, virtfs, tools, docs, and unrelated boards
are disabled.
make qemu-wasm
# dist/wasm/qemu-system-riscv32.{js,wasm,worker.js} + esp32c3-rom.bin
The build runs Node smoke checks when Node is available.
Browser interface
make web
# Open http://127.0.0.1:8000/web/
Choose a CrossPoint firmware .bin — either the ~5 MB release app image (it is
merged in-browser with the bundled bootloader and partition table into a 16 MB
flash) or a full 16 MB image — select X3 or X4, and boot. The controls
map to the device's ADC button ladders and active-low Power GPIO. make web
serves the required COOP/COEP headers for Emscripten pthreads; a generic static
server without those headers will not work.
Real firmware now boots in WASM: it runs past the earlier allocator and function-pointer signature crashes and initializes the X3 panel (528×792). It still stalls before painting a full home screen (the display generation counter freezes after early init), so end-to-end boot is not complete. X4 remains a white display stub, and browser SD storage is not implemented yet.
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.qemu/patches/0002-qemu-wasm.patchandqemu/wasm/Dockerfile— the pinned qemu-wasm host backend port and minimal Emscripten dependency environment, built byscripts/build-qemu-wasm.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.