evan
1174ef0e5d
Browse, edit, upload, and delete files on the FAT32 image with mtools, mirroring the wasm emulator's Files tab. Mutations stop the emulator first because QEMU caches the card, so host writes to a live image would be lost.
63 lines
2.6 KiB
Markdown
63 lines
2.6 KiB
Markdown
# xteink QEMU fork
|
||
|
||
Espressif's QEMU fork carrying the xteink X3/X4 (ESP32-C3) machine model and a
|
||
wasm32 TCG backend (ported from [ktock/qemu-wasm](https://github.com/ktock/qemu-wasm)),
|
||
used by [xteink-web-emulator](../xteink-web-emulator) to run CrossPoint firmware
|
||
in the browser.
|
||
|
||
## Branch
|
||
|
||
- `main` — the working branch. Base is Espressif's `esp-develop-9.2.2-20260417`
|
||
(`40edccac`).
|
||
|
||
## Remotes
|
||
|
||
- `origin` — https://ssh.gitea.va.reichard.io/evan/qemu-xteink
|
||
- `upstream` — https://github.com/espressif/qemu
|
||
- `qemu-wasm` — https://github.com/ktock/qemu-wasm (source of the wasm32 backend)
|
||
|
||
## Building
|
||
|
||
### Native (parity check — authoritative)
|
||
|
||
```sh
|
||
nix develop
|
||
./configure --target-list=riscv32-softmmu --with-devices-riscv32=xteink --enable-gcrypt
|
||
ninja -C build qemu-system-riscv32
|
||
```
|
||
|
||
Or build the native xteink target into `dist/qemu-native` for direct script use:
|
||
|
||
```sh
|
||
make xteink
|
||
uv run --script scripts/xteink-emu.py --help
|
||
```
|
||
|
||
### Agent emulator
|
||
|
||
```sh
|
||
nix run .#xteink-emu -- start --firmware firmware.bin --sdcard sdcard.img
|
||
nix run .#xteink-emu -- interactive --firmware firmware.bin --sdcard sdcard.img
|
||
nix run .#xteink-emu -- wait --timeout 30 --match 'ready'
|
||
nix run .#xteink-emu -- button bottom-2 --hold-ms 100
|
||
nix run .#xteink-emu -- screenshot --output screen.png
|
||
nix run .#xteink-emu -- stop
|
||
nix run .#xteink-emu -- web --host 127.0.0.1 --port 8080
|
||
```
|
||
|
||
The code lives in `scripts/xteink/` (`emu.py` drives QEMU, `cli.py` is the command line, `web/` is the browser UI); `scripts/xteink-emu.py` is the entry point. `web` serves a page that uploads firmware and an SD image, boots them, drives the buttons, streams the panel and serial log, and browses or edits the SD card through mtools. Card edits stop the emulator first, since QEMU caches the image; use *Apply & Reboot* to bring it back. The screen redraws off the panel's `frame-generation` counter, so it updates on each real e-ink refresh rather than on a timer.
|
||
|
||
State defaults to `/tmp/xteink-emu-$UID`; pass `--state-dir` to any subcommand for parallel instances. `interactive` opens the display and maps Left/Right, 1–4, and P to the matching device buttons. Hold P for a long power press and close the window to stop. `wait` advances a persistent log cursor after each match. The emulator exposes the open Wi-Fi network `qemu`; guest traffic uses QEMU's user-mode NAT.
|
||
|
||
### WebAssembly
|
||
|
||
Driven by the parent repo, not here:
|
||
|
||
```sh
|
||
cd ../xteink-web-emulator
|
||
make web-dev # incremental build straight from this tree
|
||
```
|
||
|
||
The parent's `scripts/build-qemu-wasm.sh` compiles this checkout inside the
|
||
emsdk Docker image defined in `xteink-web-emulator/qemu/wasm/Dockerfile`.
|