vcctrl

Every vcctrld instance actually running on this host, discovered by socket presence (bin/vcctrl-client's own `profiles` command) -- not a maintained list that can drift out of sync with what is real. Always includes "default", the primary instance every tool targets unless told otherwise.

Change which profile a tool call's OMITTED `profile` argument resolves to, for the rest of this MCP server's session -- so a sequence of calls can target modernpc (say) without passing profile="modernpc" on every single one. An explicit `profile` argument on any individual call always overrides this…

Device paths, USB4VC hold state, LED state -- the Pi's own end of the wire. Does not prove anything reached the target; see vcctrl_verify_input for that.

Which USB4VC protocol board is installed, and therefore which machine input reaches. `unknown` is a real, honest answer -- never guessed as the IBM PC. Always `id: null` on a profile with no swappable protocol board (e.g. modernpc) -- that is the correct answer for a target that was never on a board…

The DOS target's own hardware -- CPU, memory, video, sound -- as a dinspect report last pulled off the card. A READING, not a live poll: `age_s` says how old it is and `source: null` means none has ever been pulled. `stale: true` means the USB4VC board changed since this reading was taken; `stale: f…

Aggregate, non-identifying usage stats for the public read-only KVM mirror (kvm-ro, e.g. straylight): visit counts by day, first-frame load-time samples (ms), and client-side error counts by message. No per-visitor data of any kind -- no IP, no user-agent, no cookie, no session id -- is ever collect…

Capability health across input, leds, power, video, audio, files.

Set the one-sentence 'what's happening right now' shown on the public read-only KVM page -- e.g. "rebooting into NET profile to copy log files for review". Not gated by the input lock: it touches no hardware, so it needs no --as arbitration beyond attribution. No expiry of its own, but the next gate…

What the RUNNING daemon actually resolved at start, with source and any VCCTRL_* overrides -- different from reading the file, and the one worth asking when something behaves oddly.

Key names this daemon accepts, chord modifier order, and the alias table -- read this before building a combo. Does NOT say which keys reach the target; only a measured sweep at the machine can.

PS/2 LED return channel snapshot. `available: false` with `why: "unsupported"` on ADB (the Mac Plus) is working hardware, not a fault -- see `why` for which of the (open-ended) set of reasons this is. Always empty on a hid-gadget profile (e.g. modernpc) -- there is no PS/2 return channel over a gene…

Block until LED state changes, or timeout_s elapses.

The last n LED transitions, newest first. Shows that an intermittent left a trace -- does NOT establish a reading is current, since the byte only arrives on a lock-key change and an idle machine publishes nothing.

Smart-plug identity and last known relay state. A read, never gated -- diagnosing a stuck run must never require the input lock or knowing which board is seated. `board_match` (added alongside the board-scoped power fix) says whether a WRITE to this plug would be honoured right now for the installed…

Append-only record of every mains action taken, across daemon restarts.

Capture device state.

One selected (judged) frame, written to a local file on THIS machine, or an explicit 'no picture'. Two-valued: the file exists iff the daemon says picture; a failed shot removes any stale file at that path rather than leaving it for a caller to mistake for this run's.

State of the second, discretionary UVC webcam pointed at the physical target itself (the room/hardware), not its captured video signal -- a photographic companion view, independent of the analog capture stick's own ring/lock/frozen-frame machinery, so it can still answer when vcctrl_video_state cann…

The single latest frame from the second camera, written to a local file, or an explicit no-frame-yet. RAW, like vcctrl_frame/vcctrl_burst, not judged like vcctrl_shot -- CameraCapability keeps no ring and makes no picture/no-lock judgement (a UVC webcam either delivers frames or the process exits, u…

The last frame that was positively picture, aged. Same two-valued --out contract as vcctrl_shot.

One RAW frame by sequence number (from vcctrl_timeline). RAW means the daemon passes no picture judgement on it -- use vcctrl_shot for a judged frame.

n RAW frames at once, written to a local directory. All or nothing -- a burst with silent holes in it would look like a complete capture and is not, so a failure leaves no partial directory behind.

Index of every frame in the scrub buffer: seq, timestamp, size. No pixels, so cheap to poll -- use this to find a seq for vcctrl_frame.

Duplicate-hash stats over the last n frames.

Stop the ring evicting frames while you examine them: action is status, on, or off. Auto-releases after 300s daemon-side regardless, so an interrupted session cannot wedge it.

The scrub buffer as an AVI, written to a local file.

ALSA capture device state.

Mean/peak dBFS over the last ms, from the PCM ring.

Per-band energy and active_bands over the last ms, from the PCM ring.

Is music/SFX playing right now -- one call, no thresholds to know.

What is running, for how long, and who holds input -- check this before acting, not only for a human watching the rig.

Activity log since a sequence number (omit for the recent window).

Input-lock status: who holds it, for how long. Never gated -- an observation, not an action. Each profile has its OWN lock (its own vcctrld instance, its own Arbiter) -- a lock held on the primary instance says nothing about whether modernpc's is free, and vice versa.

Tap keys in sequence (e.g. ["enter"], ["esc","f1"]). Acquires the input lock first; refuses (does not force) if a human or peer holds it.

Type literal text, shifted characters handled.

Press, dwell ms, release -- the primitive gameplay/interactive testing needs; a keystroke with no duration cannot hold a direction.

Press and hold, no release -- pair with vcctrl_keyup or vcctrl_release_all.

Release a key held by vcctrl_keydown.

Release every key currently held by vcctrl_keydown.

Chord (e.g. ["ctrl","alt","delete"]). Keys press modifiers-first regardless of the order given, release in reverse; the reply echoes the order actually sent.

Relative move. PS/2 and ADB mice, and the hid-gadget backend, are all relative-only -- there is no absolute positioning; home the cursor by moving into a screen corner first if you need a known starting point. Movement is silently clamped at screen edges.

Click left, right, or middle.

Press and hold a mouse button, for a drag. The matching vcctrl_mouse_up may never come from your side -- a disconnect (or the web KVM releasing capture) still releases it, the same guarantee release_all already gives a key left down by vcctrl_keydown.

Release a mouse button held by vcctrl_mouse_down.

Release every mouse button vcctrl_mouse_down left held. Separate from vcctrl_release_all (the keyboard's own version): a viewer can hold keyboard and mouse capture independently, and giving up one must not silently drop whatever the other is mid-operation on.

Scroll. Confirmed live 2026-09-02 over the hid-gadget backend (a terminal window on modernpc visibly scrolled). Unmeasured on PS/2 -- see docs/MOUSE.md sec 7 -- whether it reaches DOS at all.

Prove the input path by PS/2 LED round trip -- the only check that says anything about the FAR end of the wire; every other input status describes the Pi's own end. Refuses (exit 2, available: false) on boards with no LED channel (ADB / the Mac Plus) rather than reporting a false alarm about working…

Explicitly take the input lock AND KEEP IT HELD across every subsequent gated call against this SAME profile, until vcctrl_lock_release(profile) or the 300s idle timer. Most tools acquire the lock automatically on first need and release it again as soon as that one action finishes (see _gated_run); …

Release the input lock now (and clear any sticky hold from vcctrl_lock_acquire) for this profile, without waiting for the idle timeout -- use this when you know you're done with input for a while and want to let a human, peer, or one of your own in-flight jobs back in. Releasing one profile's lock h…

Mains control. action is "on", "off", or "cycle" -- each REQUIRES confirm to equal the action name exactly (confirm="cycle" for a cycle), the same discipline as vcctrl_combo's reboot gate: a named confirmation that has to be typed on purpose, not a bare boolean one accidental True turns into nothing…

Can the currently attached machine be sent a file at all? A WORD, not a boolean: available, unsupported (e.g. the Mac Plus -- no packet driver, working hardware, nothing to fix), unknown, not-configured, unreachable, or unchecked.

Is the file server actually answering? Run BEFORE a transfer, not after -- a dead server discovered post-reboot has cost the target's whole environment for nothing. Four-valued exit code like vcctrl_verify_input: 0 ready, 1 not answering, 2 could-not-look, 3 this machine cannot receive files at all.

Queue a LOCAL file (on this control host) for the next transfer. Nothing is sent to the target yet -- this only stages it. `path` must exist on the machine running this MCP server; bin/vcctrl handles the copy to the daemon host itself (the same --out-style host-boundary handling as every capture too…

What is staged: action is "list" or "clear". `clear` with no name drops everything staged; a name drops just that one. Never touches anything this MCP session did not stage itself... actually it is daemon-global, so `clear` drops what ANY caller staged -- check vcctrl_file_queue("list") first if tha…

What `name` becomes on the target: DOS 8.3, uppercase. The rename happens here because the target cannot rename in transit -- check this before staging if the shortened name matters.

The CONTENTS of the two batch files this rig's CF card needs (VCGET.BAT, VCCHK.BAT), carrying this rig's own server address and login -- returned as text, not written anywhere. Deliberately no output-directory option: the CLI's `file-bats DIR` form writes on whichever host runs the command, and unli…

Send everything staged to the target. mode is "return" (reboot back to the measurement-clean menu default afterward) or "stay" (leave the machine in NET -- no measured run may start from there). REBOOTS THE TARGET TWICE and destroys its environment, so this requires confirm="send". Returns at once -…

How the running transfer (send/refresh/get) is getting on, with the last n log lines. Exit 0 while still running -- nothing has failed yet; 0 also means fully done and verified. 1 means at least one file did not. 2 means it finished but work was left (cancelled or stopped early) -- `remaining` names…

Stop after the file currently in flight. NOT mid-transfer -- the target's FTP client cannot be interrupted from here, so between files is the only honest boundary.

What the target's OUT directory held when it was LAST READ, with the age of that reading. Touches nothing -- reading it for real means rebooting, which is what vcctrl_file_refresh is for.

Go and actually read the target's OUT directory. mode is "return" or "stay", same meaning as vcctrl_send_file. REBOOTS THE TARGET, so this requires confirm="refresh". already_net skips the reboot but NOT the arrival proof -- being wrong about where the machine already is costs a refusal, not a comma…

Fetch files out of the target's OUT directory. Pass either fetch_all=True or a names list (from vcctrl_file_list) -- a name not currently listed there is refused here rather than typed at the machine. REBOOTS THE TARGET (unless already_net), so this requires confirm="get". paranoid fetches each file…

Take a fresh dinspect reading of the DOS target's own hardware. REBOOTS THE TARGET TWICE: once to the menu default (typed blind -- nothing here can confirm the machine is at a usable prompt first, so only call this when you know it is not mid-boot or mid-something-else) to run DINSPECT.EXE there, th…

What has been fetched off the target and is sitting on the daemon host: action is "list" or "clear" (+name). Use vcctrl_pulled_save to copy one to THIS machine.

Copy one previously-fetched file to a local path on this machine (via bin/vcctrl's normal --out host-boundary handling).

ONE gate for "is this rig fit to run": caps, board, power, video, scrub ring, the input lock, and (unless no_input) the input round trip. Exit codes like vcctrl_verify_input: 0 fit to run, 1 a real fault named in decided_by, 2 could not tell, 3 the tool itself failed. Scope is the HARNESS, not the t…

Poll a job launched by vcctrl_run_cell / vcctrl_run_sweep / vcctrl_collect: running state, exit code once finished, and the last `tail` lines of its combined stdout/stderr.

Every job this MCP server has launched this session, with status.

Terminate a running job (SIGTERM). LAST RESORT, NOT GRACEFUL: unlike vcctrl_file_cancel (which waits for a clean file boundary), this can land mid-keystroke or mid-reboot on the target, because the harness scripts have no external stop signal designed in -- see docs/PLAN.md/vcctrl-sweep's own docstr…

Does the live audio resemble a reference file's frequency shape?

Every sweep name this rig's profile knows, with its cell count and timeout -- from profiles/doskutsu.yaml. Safe, fast, no hardware touched.

Run ONE doskutsu cell by hand -- the diagnostic single-cell shape, not a sweep. Launched detached; poll with vcctrl_job_status(job_id).

Run a full unattended QA sweep -- 12 to 23 minutes per profiles/doskutsu.yaml, one of the sweep names from vcctrl_sweep_list. Launched detached; poll with vcctrl_job_status(job_id). Ties up the rig for its full duration, so this requires confirm="run".

Bring a sweep's logs back off the target, unattended. Pass either (sweep, machine_digit) or tags (a list like ["GMN","GMF"]). Reboots the target (unless already_net) -- CONFIRMATION COMES FROM THE FILESYSTEM, not the screen: arrival of each log in the FTP server's incoming/ is what's checked, which …