Pifinder Remote

Driving PiFinder headlessly

PiFinder normally renders to a physical OLED/LCD (or a pygame emulator window) and is driven by a hardware keypad. This skill runs it in a headless mode — no pygame, no SDL window, no hardware — while still rendering every frame, and drives it entirely over PiFinder's HTTP API. That lets you launch the app, navigate its menus, see exactly what's on screen, read its live state, and shut it down, all from the command line.

Everything goes through one helper: scripts/pf_remote.py (Python standard library only — runs under any python3; it finds and uses the PiFinder venv itself when launching). Run python3 <skill>/scripts/pf_remote.py -h for the full command list.

The loop

S=.claude/skills/pifinder-remote/scripts/pf_remote.py   # adjust path as needed

python3 $S launch            # start cedar + headless PiFinder (rev4, 176x176), wait for API
python3 $S launch -fb        # ...with the rev4 battery icon + a simulated discharge
python3 $S launch --display headless   # the 128x128 v3/v2.5 panel instead
python3 $S screen -o /tmp/pf.png   # capture the current screen as PNG
python3 $S key DOWN DOWN RIGHT     # send keypad presses, in order
python3 $S status            # aggregated live state as JSON
python3 $S stop              # graceful shutdown, then guaranteed teardown

After launch succeeds, the other commands find the running instance (URL + PIDs) from a small state file in the temp dir — you don't need to pass the URL. Read the PNG that screen writes (use the Read tool on the path it prints) to see the UI; that is how you "look at" PiFinder.

Commands

Keypad buttons

PiFinder has a small keypad. Pass these names to key (case-sensitive), or a raw integer keycode:

• Directions / actions: UP DOWN LEFT RIGHT PLUS MINUS SQUARE
• Long press (held): LNG_LEFT LNG_UP LNG_DOWN LNG_RIGHT LNG_SQUARE
• Alt (function) variants: ALT_UP ALT_DOWN ALT_LEFT ALT_RIGHT ALT_PLUS ALT_MINUS ALT_SQUARE ALT_0
• Number keys: pass the digit as an integer, e.g. key 1 2 3

Navigation model: RIGHT (or SQUARE) generally drills into the highlighted item, LEFT goes back, UP/DOWN move the selection, LNG_LEFT returns to the top menu. After any input, take a fresh screen to confirm what happened — the screen is the ground truth, menu order changes between versions.

How it works (and why stop is built this way)

• Headless rendering. The launch passes --display headless_176, which selects the in-memory DisplayHeadless176 driver (python/PiFinder/displays.py, backed by luma.core.device.dummy). It renders at 176×176 with rev4's Layout176 font and spacing profile, so what you capture matches the real rev4 panel rather than merely being scaled up. --display headless gives the 128×128 DisplayHeadless used by v3/v2.5. The UI render loop already calls shared_state.set_screen() beside every hardware draw, so the current frame is always available at GET /api/screen regardless of display driver. No pygame/SDL/X is needed.
• Input. --keyboard none runs a no-op keyboard process; POST /api/key injects into the same keyboard_queue the main loop reads, so menu navigation behaves exactly as with the real keypad.
• Solving works headless. With --camera debug, PiFinder cycles through sample frames and cedar-detect-server + the solver produce real plate solves, so status/solution return live RA/Dec/constellation.
• Stopping is deliberately two-stage. PiFinder is multi-process; its workers run bare while True loops, aren't daemonized, and don't watch a stop flag. Clean shutdown depends on SIGINT reaching the whole process group at once (what a terminal Ctrl-C does). POST /api/stop does that from inside the app, which reliably stops the worker processes — but the main process can still hang in its teardown (a multiprocessing-manager shutdown race). So launch starts PiFinder in its own session/process group, isolated from the launcher, and stop escalates with SIGTERM→SIGKILL on that group after a short grace period. stop returns as soon as the process is actually gone. This guarantees no orphaned processes even when the graceful path stalls.