evan/qemu-xteink
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat(skill): isolate firmware emulator invocation

Browse Source
This commit is contained in:
Evan Reichard
2026-07-24 17:30:09 -04:00
parent cc539e448f
commit 0da29e8871
3 changed files with 90 additions and 34 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.pi/skills/test-xteink-firmware/SKILL.md
+12 -34
View File
@@ -9,17 +9,7 @@ description: "Build and interactively test Xteink ESP32-C3 firmware in the nativ
Build firmware for an Xteink device, boot it in the native emulator, and validate behavior through serial logs, physical controls, screenshots, SD state, and network access.
## Prerequisites
Point `XTEINK_QEMU_REPO` at a prepared QEMU checkout containing `dist/qemu-native`:
```sh
export XTEINK_QEMU_REPO=${XTEINK_QEMU_REPO:-../qemu}
export XTEINK_EMU_STATE=/tmp/xteink-firmware-$UID
export XTEINK_EMU_SD=/tmp/xteink-firmware-$UID.img
```
The emulator exits with setup instructions when its native QEMU distribution is missing.
Resolve script paths relative to this skill directory. `scripts/xteink-emu.sh` stores the qemu-xteink checkout location, builds native QEMU when missing, and runs the emulator. If its location is unset, run the `variable.sh --set` command printed by the wrapper after asking the user for the checkout path.
## Workflow
@@ -28,6 +18,8 @@ The emulator exits with setup instructions when its native QEMU distribution is
```sh
pio run
export XTEINK_FIRMWARE=.pio/build/default/firmware.bin
export XTEINK_EMU_STATE=/tmp/xteink-firmware-$UID
export XTEINK_EMU_SD=/tmp/xteink-firmware-$UID.img
```
2. Create a persistent FAT32 SD image once, unless the test requires a fresh card:
@@ -40,9 +32,8 @@ The emulator exits with setup instructions when its native QEMU distribution is
3. Start a clean emulator process while preserving SD contents:
```sh
uv run --script "$XTEINK_QEMU_REPO/scripts/xteink-emu.py" stop \
--state-dir "$XTEINK_EMU_STATE" || true
uv run --script "$XTEINK_QEMU_REPO/scripts/xteink-emu.py" start \
scripts/xteink-emu.sh stop --state-dir "$XTEINK_EMU_STATE" || true
scripts/xteink-emu.sh start \
--state-dir "$XTEINK_EMU_STATE" \
--firmware "$XTEINK_FIRMWARE" \
--sdcard "$XTEINK_EMU_SD"
@@ -53,7 +44,7 @@ The emulator exits with setup instructions when its native QEMU distribution is
4. Observe serial behavior with either a persistent regex cursor or the raw log:
```sh
uv run --script "$XTEINK_QEMU_REPO/scripts/xteink-emu.py" wait \
scripts/xteink-emu.sh wait \
--state-dir "$XTEINK_EMU_STATE" --timeout 30 --match 'pattern'
tail -f "$XTEINK_EMU_STATE/serial.log"
```
@@ -61,12 +52,9 @@ The emulator exits with setup instructions when its native QEMU distribution is
5. Drive the physical controls:
```sh
uv run --script "$XTEINK_QEMU_REPO/scripts/xteink-emu.py" button \
--state-dir "$XTEINK_EMU_STATE" bottom-2
uv run --script "$XTEINK_QEMU_REPO/scripts/xteink-emu.py" button \
--state-dir "$XTEINK_EMU_STATE" power --down
uv run --script "$XTEINK_QEMU_REPO/scripts/xteink-emu.py" button \
--state-dir "$XTEINK_EMU_STATE" power --up
scripts/xteink-emu.sh button --state-dir "$XTEINK_EMU_STATE" bottom-2
scripts/xteink-emu.sh button --state-dir "$XTEINK_EMU_STATE" power --down
scripts/xteink-emu.sh button --state-dir "$XTEINK_EMU_STATE" power --up
```
Available buttons are `left`, `right`, `bottom-1` through `bottom-4`, and `power`. Use the labels rendered by the current screen as the authoritative mapping. Allow the e-ink panel to refresh after state-changing input.
@@ -74,20 +62,11 @@ The emulator exits with setup instructions when its native QEMU distribution is
6. Capture and inspect the screen after meaningful transitions:
```sh
uv run --script "$XTEINK_QEMU_REPO/scripts/xteink-emu.py" screenshot \
scripts/xteink-emu.sh screenshot \
--state-dir "$XTEINK_EMU_STATE" --output /tmp/xteink-screen.png
```
7. Enter text when the firmware's on-screen keyboard is focused:
```sh
uv run --script "$XTEINK_QEMU_REPO/scripts/xteink-type-keyboard.py" \
"$XTEINK_EMU_STATE" normal 'Example'
uv run --script "$XTEINK_QEMU_REPO/scripts/xteink-type-keyboard.py" \
"$XTEINK_EMU_STATE" url 'https://example.com'
```
8. For network tests, connect the firmware to the single open Wi-Fi network named `qemu`, then validate the feature's observable result.
7. For network tests, connect the firmware to the single open Wi-Fi network named `qemu`, then validate the feature's observable result.
## Diagnose Failures
@@ -100,6 +79,5 @@ The emulator exits with setup instructions when its native QEMU distribution is
## Cleanup
```sh
uv run --script "$XTEINK_QEMU_REPO/scripts/xteink-emu.py" stop \
--state-dir "$XTEINK_EMU_STATE"
scripts/xteink-emu.sh stop --state-dir "$XTEINK_EMU_STATE"
```