run-on-testbox

name	run-on-testbox
description	Deploy and run DSVita on the remote ARM test box (raspberry pi class, native armhf speed) — use when asked to test a build on the pi/test box, run a game at real speed, take remote screenshots, or inject button presses remotely.

Run DSVita on the remote ARM test box

Prerequisite: .env in the repo root with DSVITA_PI_HOST (ssh, key auth). Optional: DSVITA_PI_BIN (default ~/claude/dsvita/dsvita). Never use sudo on the box without asking.

Working directory & roms. The dev machine is x86 and can't run the armhf binary natively, so the pi5 is where all roms/games run. Roms live on the box at ~/nds. Do every box-side thing — deployed binaries, logs, traces, savestates — under a ~/claude/dsvita/ working directory so you don't pollute the home dir; keep DSVITA_PI_BIN pointed into it.

Deploy

cargo build --profile release-debug --target thumbv7neon-unknown-linux-gnueabihf
ssh "$DSVITA_PI_HOST" 'mkdir -p ~/claude/dsvita'
scp target/thumbv7neon-unknown-linux-gnueabihf/release-debug/dsvita "$DSVITA_PI_HOST:~/claude/dsvita/dsvita"

When testing multiple build variants, give each binary a DISTINCT name on the box and md5sum them locally first to prove they differ (a chained sed && cargo build can silently skip the recompile — see DEVELOPMENT.md §4 pitfalls).

Run / observe / drive

action	command
Kill + relaunch with args	tools/pi_run.sh '-e 2 -f 1 ~/nds/<rom>.nds'
Screenshot (wayland grim)	tools/pi_shot.sh <local.png>
Press a key	tools/pi_key.sh <xkb-key> [hold_ms]
Check alive	ssh $DSVITA_PI_HOST 'pgrep -x <binary-name>'

Keyboard map: WASD = dpad, K = A, J = B, I = X, U = Y, B = Start, V = Select, 8/9 = L/R.

Debug command port (debug/release-debug builds) — the headless control channel; needs no wayland virtual keyboard (so it works even where wtype/pi_key.sh is absent). Launch with DSVITA_DBG_PORT=<port> and send newline-delimited commands to 127.0.0.1:<port> on the box, e.g. printf 'buttons a\n' | nc -q0 127.0.0.1 5555:

• press/release <btn> | buttons [<btn>...] (exact held set) — btn: a b x y up down left right start select l r. A held button = held on the DS.
• touch <x> <y> (DS coords, x 0..256 y 0..192) | touch off — drives "touch to start" gates and touch menus (Zelda PH, HG title). No drag path, so rub/drag minigames can't be driven.
• framelimit <0..9> (0 = uncapped) | savestate (quick-save at vblank) | inst-log (arm a --inst-log-lazy capture) | quit.

Sequence timing in ONE ssh session (loop the nc sends with short sleeps); a command per ssh round-trip is too slow and the game "heals" between them.

Input-free verify loop: the port's savestate (or the F11 key) quick-saves at vblank; relaunch with -s <savestate> to resume — lets you A/B or re-test a scene deterministically without re-driving inputs.

Rules that bite:

• ALWAYS launch with LIBGL_ALWAYS_SOFTWARE=1 — the box's GPU driver renders incorrectly (garbled 2D layers); software GL is the reference. Never diagnose rendering from a GPU-driver run.
• ALWAYS pass a framelimit: -f 1 for interaction, -f 5/-f 9 to fast-forward through boot/loading. Uncapped (-f 0) is uninteractable.
• pkill -f / pgrep -f over ssh match the remote shell's own command line and kill your session — use -x <exact-binary-name> and name binaries distinctly.
• The box's /tmp is a small tmpfs: redirect big logs (DEBUG_LOG stdout, traces) to the home directory, never /tmp. A full /tmp kills the cpu thread with a StorageFull panic while the UI keeps rendering — looks exactly like an emulation hang.
• The box's V3D GL driver has a known cosmetic tile/glyph rendering offset; verify suspected rendering bugs against a pure-jit build or another renderer before blaming emulation.