docs(wiki): refresh setup and lab coverage (2026.6.14.0-BED1)

Author: RealWhyKnot

README.md

@@ -4,7 +4,7 @@ Parsec CouchLink lets a remote Parsec player use a real retro console as player
 
 The Windows host reads the Parsec virtual Xbox controller, sends the button state over Wi-Fi, and a Raspberry Pi Pico 2 W or Pico W presents that input as a wired Xbox 360 controller to a USB-to-console adapter such as USB4MAPLE.
 
-**[Wiki](https://github.com/RealWhyKnot/ParsecCouchLink/wiki)** | **[Quick Start](https://github.com/RealWhyKnot/ParsecCouchLink/wiki/Quick-Start)** | **[Troubleshooting](https://github.com/RealWhyKnot/ParsecCouchLink/wiki/Troubleshooting)**
+**[Releases](https://github.com/RealWhyKnot/ParsecCouchLink/releases)** | **[Wiki](https://github.com/RealWhyKnot/ParsecCouchLink/wiki)** | **[Quick Start](https://github.com/RealWhyKnot/ParsecCouchLink/wiki/Quick-Start)** | **[Troubleshooting](https://github.com/RealWhyKnot/ParsecCouchLink/wiki/Troubleshooting)**
 
 ## What You Need
 
@@ -61,6 +61,7 @@ Useful commands:
 .\couchlink.exe debug --to-wifi --port COM3
 .\couchlink.exe bootsel --port COM3
 .\couchlink.exe lab --scenario status
+.\couchlink.exe lab --scenario full --power pnp-remove --no-flash --json .\lab-report.json
 .\couchlink.exe test discover --ip 192.168.50.4
 .\couchlink.exe test usb --all
 .\couchlink.exe bundle
@@ -71,6 +72,12 @@ Pico into setup-mode USB before asking for new credentials. If the existing
 Wi-Fi is still correct after a firmware update, keep the current Wi-Fi and
 start streaming.
 
+`couchlink lab` is for development benches with the Pico plugged into the
+Windows host. `--power pnp-remove` asks Windows to remove and rescan the
+CouchLink Pico devices, including the run-mode XInput controller, which is
+useful for checking reconnect handling. It is not a physical cable pull or a
+USB power cut; use an external power backend for that.
+
 ## Reporting bugs
 
 If something went wrong, the fastest path is:
@@ -98,7 +105,9 @@ page for the full version.
 - `build.ps1` - local build and release zip staging.
 - `wiki/` - source-controlled GitHub Wiki pages.
 
-The project is pre-release. Runtime protocol v1 and setup protocol v1 are documented in the [Protocol](wiki/Protocol.md) wiki page.
+Runtime protocol v1 and setup protocol v1 are documented in the
+[Protocol](wiki/Protocol.md) wiki page. Hardware bench coverage is documented
+in [Hardware Lab](wiki/Hardware-Lab.md).
 
 ## License
 

wiki/Build.md

@@ -74,6 +74,32 @@ pico-bridge\dist\couchlink-picow.uf2
 
 The pico-sdk clone is shared across per-board build directories (`build-pico2w/`, `build-picow/`) via a sibling `build-_pico_sdk/` folder, so a dual-board build only fetches the SDK once.
 
+## Tests
+
+Run the Rust bridge tests:
+
+```powershell
+cargo test --manifest-path bridge\Cargo.toml
+```
+
+Run the C host tests for firmware setup and boot-mode policy code:
+
+```powershell
+cmake -S pico-bridge -B build-host-tests -DPICO_BRIDGE_HOST_TESTS=ON
+cmake --build build-host-tests --config Debug
+ctest --test-dir build-host-tests -C Debug --output-on-failure
+```
+
+Run the formatting and lint wrapper used locally before commits:
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File .\tools\lint.ps1
+```
+
+For plugged-in Pico benches, see [[Hardware Lab]]. The lab harness can produce
+a JSON report and can exercise setup-mode reconnects, BOOTSEL flash cycles,
+run-mode XInput enumeration, and controller signal checks.
+
 ## GitHub Workflows
 
 - `ci.yml` checks the Rust bridge and builds the Pico firmware.

wiki/Changelog.md

@@ -1,25 +1,22 @@
 # Changelog
 
-## Unreleased
+## Current Release
 
-- The no-argument guided menu now opens on a **Basic** tab with one card per saved or detected Pico. Each Pico card exposes only commands for that Pico, such as streaming, Wi-Fi setup, recovery, firmware flashing, USB diagnostics, saving, or removal. One-off diagnostics and fixes are grouped under the **Advanced** tab.
-- Direct `couchlink run` can auto-recover setup-mode USB Picos that already have saved Wi-Fi by rebooting them back to Wi-Fi/controller mode and retrying discovery. The **Basic** tab exposes targeted recovery under each USB Pico, the **Advanced** tab exposes **Auto recover for streaming**, and `couchlink recover` runs the same check directly.
-- Guided menus now include short inline hints for each choice. The **Advanced** tab adds firmware update, Wi-Fi setup, a quick status dashboard, Wi-Fi finder/manual-IP probe, Windows controller check, Pico recovery, USB adapter diagnostics, logs, support bundles, and a command reference grouped by setup, streaming, recovery, and diagnostics.
-- `couchlink debug` adds a guided Pico recovery menu and direct mode-switch commands for Wi-Fi/controller mode, USB debug mode, and BOOTSEL firmware mode. `couchlink bootsel` is the fast direct command for moving a setup-mode USB Pico into BOOTSEL.
-- `couchlink test usb` asks run-mode firmware over Wi-Fi for USB/XInput status, including mount/configuration state, descriptor counters, accepted IN reports, and host OUT traffic. The guided **Basic** and **Advanced** tabs expose the same check for console-adapter troubleshooting.
-- Release packaging describes only the current CouchLink setup, streaming, diagnostic, flashing, and Wi-Fi configuration tools. Protocol docs list the active setup and runtime commands.
-- Firmware writes one heartbeat line every 5 seconds while running, covering USB mount/suspend state, Wi-Fi state with IP and RSSI, peer presence, and tx/rx packet counters. A quiet system used to leave the diag ring with no recent entries; the heartbeat guarantees there is always state to reason about in `pico-diag.txt`.
-- Firmware fault context expanded. On HardFault / BusFault / UsageFault / MemManage the breadcrumb now captures the full hardware-stacked basic exception frame (R0-R3, R12, LR, PC, xPSR) plus SP and -- on Cortex-M33 / Pico 2 W -- the CFSR / HFSR / MMFAR / BFAR. The next boot's log names the cause directly (divide-by-zero, unaligned-access, precise-bus-error, etc.) rather than just an address.
-- Bridge writes a `state-journal.log` next to the rotating log: one short operator-readable line per high-signal event (wizard stage transitions, CDC open + line state, HELLO timeouts with byte counts, discovery, peer transitions, bundle outcomes). Included in `couchlink bundle`. Survives across program restarts.
-- `couchlink bundle` captures the last 15 minutes of Windows event log entries from the System and Kernel-PnP/Configuration logs, filtered to USB-relevant providers. Catches driver-bind failures, surprise removals, and descriptor-request timeouts that pnputil cannot show.
-- Setup-mode CDC HELLO probe in `couchlink bundle` now uses a 10-second read deadline instead of 3 seconds. The wizard's faster budget still applies during interactive setup; the bundle path is "something is wrong, gather everything" and waits longer for late-arriving bytes from a slow-booting firmware.
-- `pico-diag.txt` now leads with a `Suggested next step` block: a one-sentence root cause and an ordered "Try this (in order)" list specific to the failure shape (write / read+0bytes / read+somebytes / decode / get_log_buffer / no_setup_port / setup_open_failed / no_last_pico_in_config / udp_discovery_failed / udp_probe_failed / udp_unsupported). The raw captured fields follow in a `Diagnostic details` block so an operator reading top-down hits an action before they hit jargon.
-- Bridge log files are no longer empty by default. The tracing filter directive matched a crate-name prefix that the binary's actual crate identifier did not satisfy, so every `info!` / `warn!` / `error!` call dropped silently on both stderr and the rotating file. `couchlink run` is no longer a silent console window; bundles now carry readable bridge logs.
-- `couchlink bundle` can now pull the firmware's diag-log ring over UDP from a running Pico. The bundle tries setup-mode USB-CDC first and falls back to a unicast UDP probe against the last-known address. `pico-diag.txt` and the manifest now name which source produced the log (`setup-cdc` or `run-udp`).
-- When CDC capture fails, `pico-diag.txt` now names the specific step that broke -- port enumeration, port open, HELLO write, HELLO read, or frame decode -- with bytes-received count and a hex dump of any pre-magic bytes seen on the wire. The previous stub said "couldn't capture, see the bridge log" without distinguishing which path failed.
-- `couchlink flash` refuses to write a UF2 whose family ID does not match the detected BOOTSEL drive. The previous behavior was a warning that continued the copy, which produced a Pico that silently never re-enumerated when an RP2040 image was dropped onto an RP2350 (or vice versa).
-- `couchlink setup` stage 4 waits up to 120 s (was 60 s) for the setup-mode CDC port to appear and prints a progress line every 10 s while it waits. The previous 60 s budget was tight when the host went through USB passthrough (VM, WSL2) or a first-time driver bind.
-- `couchlink setup` stage 4 treats a port-disappeared event right after `REBOOT_TO_RUN` as success rather than a hard error. The firmware always reboots after handling that command, so a missing reply is the expected outcome of a fast reboot, not a failure.
-- Firmware CDC `bcdDevice` follows the generated firmware build date, so Windows re-binds `usbser.sys` after a CDC-protocol break instead of reusing a cached binding from an older interface layout.
-- Release zip stages `setup.ps1`, `couchlink.exe`, and both board-specific UF2 files together.
-- Wiki pages now hold setup, flashing, troubleshooting, build, and protocol notes.
+See the repository changelog for the generated release list:
+
+https://github.com/RealWhyKnot/ParsecCouchLink/blob/main/CHANGELOG.md
+
+Latest published release:
+
+https://github.com/RealWhyKnot/ParsecCouchLink/releases/latest
+
+## Current Highlights
+
+- `v2026.6.14.1` keeps provisioned Picos in run mode on normal replug so they enumerate as Xbox 360 controllers instead of falling back to setup-mode USB.
+- The no-argument guided menu opens on a **Basic** tab with one entry per saved or detected Pico. Each entry exposes only commands for that Pico, such as streaming, Wi-Fi setup, recovery, firmware flashing, USB diagnostics, saving, or removal.
+- Direct `couchlink run` can auto-recover setup-mode USB Picos that already have saved Wi-Fi by rebooting them back to Wi-Fi/controller mode and retrying discovery.
+- `couchlink debug` provides guided Pico recovery plus direct mode-switch commands for Wi-Fi/controller mode, USB debug mode, and BOOTSEL firmware mode.
+- `couchlink test usb` asks run-mode firmware over Wi-Fi for USB/XInput status, including mount/configuration state, descriptor counters, accepted IN reports, and host OUT traffic.
+- `couchlink lab` runs unattended plugged-in Pico bench scenarios, including `--power pnp-remove` for Windows PnP remove/rescan reconnect coverage.
+- `couchlink bundle` gathers logs, doctor output, Windows USB event-log snippets, bridge state journal entries, and firmware diagnostics when reachable by setup USB, vendor control, or run-mode UDP.
+- Release zips include `setup.ps1`, `couchlink.exe`, both board-specific UF2 files, support wrappers, and a manifest.

wiki/Hardware-Lab.md

@@ -0,0 +1,118 @@
+# Hardware Lab
+
+`couchlink lab` is an unattended bench harness for development and release
+checks. It is meant for plugged-in Picos on a Windows host, not for normal
+console play.
+
+Run the current status snapshot first:
+
+```powershell
+.\couchlink.exe lab --scenario status
+```
+
+The status snapshot records visible setup-mode USB Picos, Wi-Fi/controller-mode
+Picos, BOOTSEL drives, Windows XInput slots, and problem USB devices.
+
+## Scenarios
+
+| Scenario | What it checks |
+|---|---|
+| `status` | Snapshot only; no mode changes. |
+| `mode-cycle` | Setup USB -> Wi-Fi/controller mode -> setup USB. |
+| `flash-cycle` | Setup USB -> BOOTSEL -> flash matching UF2 -> setup USB or Wi-Fi recovery. |
+| `power-cycle` | Selected reconnect backend only. |
+| `full` | Status, mode cycle, reconnect cycle, flash cycle, final Wi-Fi/controller check, and signal checks. |
+
+Run the full scenario once:
+
+```powershell
+.\couchlink.exe lab --scenario full --cycles 1
+```
+
+By default, `--power auto` uses an external power backend only when one is
+configured and its probe command passes. Otherwise it falls back to firmware
+reset re-enumeration.
+
+## Reconnect Backends
+
+| Power value | Behavior |
+|---|---|
+| `auto` | Use configured external power only when its probe passes; otherwise use `reset`. |
+| `reset` | Reboot firmware between setup and run modes. USB power is not cut. |
+| `external` | Run configured off/on commands and wait for selected boards to disappear and return. |
+| `pnp-restart` | Use `pnputil /disable-device` and `/enable-device` on CouchLink setup USB instances. |
+| `pnp-remove` | Use `pnputil /remove-device <id> /subtree`, then `pnputil /scan-devices`, on CouchLink PnP instances. |
+
+`pnp-remove` is the strongest built-in Windows reconnect simulation. During the
+full scenario it removes/rescans setup-mode USB instances, returns the Pico to
+run mode, verifies the XInput controller persona, removes/rescans that XInput
+PnP instance, then verifies Wi-Fi/controller detection and signal delivery
+again.
+
+`pnp-remove` still does not physically cut USB power. Use an external power
+backend when the test must prove a real power loss or cable pull.
+
+Example full reconnect run without reflashing:
+
+```powershell
+.\couchlink.exe lab --scenario full --cycles 1 --power pnp-remove --no-flash --json .\lab-report.json
+```
+
+## Select Boards
+
+With no selector, the lab probes every visible Pico:
+
+```powershell
+.\couchlink.exe lab --all
+```
+
+Select one or more boards by UID, IP, or board name:
+
+```powershell
+.\couchlink.exe lab --pico 07D37EB6 --pico 192.168.50.4
+```
+
+## Firmware Inputs
+
+The flash cycle resolves the matching UF2 for the detected board. Point `--uf2`
+at either a specific UF2 or a directory containing board-specific release files:
+
+```powershell
+.\couchlink.exe lab --scenario flash-cycle --uf2 .\dist\ParsecCouchLink
+```
+
+Use `--no-flash` when the bench should exercise mode and reconnect paths
+without writing firmware.
+
+## External Power Backend
+
+External power commands live in the per-user config file:
+
+```text
+%APPDATA%\ParsecCouchLink\config\config.toml
+```
+
+The command arrays use the first item as the executable and the remaining items
+as arguments:
+
+```toml
+[lab_power]
+off = ["powershell", "-NoProfile", "-File", "D:\\tools\\pico-power.ps1", "off"]
+on = ["powershell", "-NoProfile", "-File", "D:\\tools\\pico-power.ps1", "on"]
+probe = ["powershell", "-NoProfile", "-File", "D:\\tools\\pico-power.ps1", "probe"]
+```
+
+When `--power auto` is used, the probe must pass before the external backend is
+selected.
+
+## Reports
+
+Add `--json` to save a machine-readable report:
+
+```powershell
+.\couchlink.exe lab --scenario full --power pnp-remove --json .\lab-report.json
+```
+
+The JSON report records selected scenario, requested and selected power backend,
+visible devices, and each pass/fail/skip step with timing. A nonzero failure
+count makes the command exit with an error.

wiki/Home.md

@@ -27,6 +27,7 @@ Console player 2
 - [[Controller Routing]] - choose which controller goes to which Pico.
 - [[Setup and Flashing]] - what the script does and how to recover a Pico.
 - [[Troubleshooting]] - what to run when setup or discovery fails.
+- [[Hardware Lab]] - unattended bench checks for firmware, reconnects, and controller output.
 - [[Reporting-Bugs]] - how to make a bundle and what to include in an issue.
 - [[Build]] - build the release zip from source.
 - [[Protocol]] - short runtime and setup protocol reference.
@@ -53,3 +54,7 @@ Console player 2
 7. Run `couchlink.exe`, choose the Pico on the **Basic** tab, start streaming, then start a Parsec session and play.
 
 The Wi-Fi password is sent to the Pico over USB setup mode. It is not saved on the PC.
+
+For development benches with the Pico plugged into the Windows host, `couchlink lab`
+can cycle setup mode, BOOTSEL flashing, run-mode controller enumeration, and
+signal checks. See [[Hardware Lab]].

wiki/Quick-Start.md

@@ -103,6 +103,7 @@ Each subcommand also has a one-shot PowerShell wrapper in the release folder. Ri
 .\couchlink.exe debug --status  # show whether the Pico is on Wi-Fi, USB debug, or BOOTSEL
 .\couchlink.exe debug --to-wifi --port COM3  # switch one USB debug Pico back to Wi-Fi
 .\couchlink.exe bootsel --port COM3  # switch one USB debug Pico to BOOTSEL
+.\couchlink.exe lab --scenario status  # development bench status snapshot
 .\couchlink.exe test <name>  # run one diagnostic check by name
 ```
 

wiki/Troubleshooting.md

@@ -225,6 +225,13 @@ The result tells you where USB stopped:
 - `configured, but the host has not accepted an XInput report`: unplug and replug the Pico, then update firmware if it repeats.
 - `host is polling the XInput endpoint`: the adapter accepted the Pico as a controller. Some adapters do not send rumble or LED OUT traffic until a game starts.
 
+On a development bench where the Pico is plugged into the Windows host, use
+[[Hardware Lab]] for repeatable reconnect checks. `couchlink lab --scenario full
+--power pnp-remove --no-flash` removes and rescans the CouchLink setup and
+XInput PnP instances, then verifies Wi-Fi/controller detection and signal
+delivery after reconnect. It is still a Windows PnP simulation, not a physical
+power cut.
+
 ## Logs
 
 Log location is printed by:

wiki/_Sidebar.md

@@ -3,6 +3,8 @@
 - [Controller Routing](Controller-Routing)
 - [Setup and Flashing](Setup-and-Flashing)
 - [Troubleshooting](Troubleshooting)
+- [Hardware Lab](Hardware-Lab)
+- [Reporting Bugs](Reporting-Bugs)
 - [Build](Build)
 - [Protocol](Protocol)
 - [Changelog](Changelog)