44 lines
2.0 KiB
Markdown
44 lines
2.0 KiB
Markdown
# 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](./ROADMAP.md) for architecture and plan.
|
|
|
|
## Quick start (native QEMU)
|
|
|
|
```sh
|
|
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.
|