fix(cli): add Wi-Fi discovery recovery steps

Author: RealWhyKnot

bridge/src/cmd_doctor.rs

@@ -341,12 +341,7 @@ pub async fn check_discover() -> CheckResult {
         ),
         Err(_) => CheckResult::Fail(
             "no Pico replied within 3 s on UDP/4242".into(),
-            "Confirm the Pico is powered, joined your Wi-Fi, and on the same \
-             LAN as this PC. Common causes: AP isolation enabled on the router \
-             (see wiki/Troubleshooting.md), Pico on a different SSID, or this \
-             PC is multi-homed and the broadcast went out the wrong NIC. If \
-             unsure, run `couchlink configure-wifi` to re-provision."
-                .into(),
+            support::no_pico_wifi_short_hint().into(),
         ),
     }
 }

bridge/src/cmd_home.rs

@@ -7,7 +7,9 @@ use anyhow::{Context, Result};
 use dialoguer::theme::ColorfulTheme;
 use dialoguer::{Confirm, MultiSelect, Select};
 
-use crate::{cmd_configure_wifi, cmd_doctor, cmd_flash, cmd_run, cmd_setup, config, xinput};
+use crate::{
+    cmd_configure_wifi, cmd_doctor, cmd_flash, cmd_run, cmd_setup, config, support, xinput,
+};
 
 pub async fn run() -> Result<()> {
     loop {
@@ -43,11 +45,19 @@ async fn start_routing() -> Result<()> {
         println!("Looking for running Pico boards on Wi-Fi...");
         let picos = cmd_run::discover_picos(Duration::from_secs(5)).await?;
         if picos.is_empty() {
-            println!("No Pico replied on Wi-Fi.");
-            let choices = vec!["Try again", "Flash/update firmware", "Back"];
+            support::print_no_pico_wifi_help(5);
+            let choices = vec![
+                "Try discovery again",
+                "Set or change Wi-Fi",
+                "Run diagnostics",
+                "Flash/update firmware",
+                "Back",
+            ];
             match select("Next step", &choices, 0).await? {
                 0 => continue,
-                1 => flash_menu().await?,
+                1 => cmd_configure_wifi::run().await?,
+                2 => cmd_doctor::run().await?,
+                3 => flash_menu().await?,
                 _ => return Ok(()),
             }
             continue;

bridge/src/cmd_run.rs

@@ -13,7 +13,7 @@ use tokio::sync::mpsc;
 use tokio::time::{interval, MissedTickBehavior};
 
 use crate::protocol::{self, GamepadState, Packet, PacketKind, FLAG_PARSEC_CONNECTED};
-use crate::{config, discovery, journal, xinput};
+use crate::{config, discovery, journal, support, xinput};
 
 const DEFAULT_DISCOVER_SECONDS: u64 = 5;
 const DEFAULT_STATUS_SECONDS: u64 = 2;
@@ -144,10 +144,7 @@ pub async fn run(options: RunOptions) -> Result<()> {
 
     let picos = discover_picos(Duration::from_secs(options.discover_seconds)).await?;
     if picos.is_empty() {
-        bail!(
-            "no Pico replied within {} s. Run `couchlink` for the guided menu or `couchlink test discover --all` for details.",
-            options.discover_seconds
-        );
+        bail!("{}", support::no_pico_wifi_help(options.discover_seconds));
     }
 
     let routes = if !options.routes.is_empty() {

bridge/src/cmd_test.rs

@@ -10,7 +10,7 @@ use crate::cmd_doctor::{
     check_24ghz_warning, check_cdc, check_discover, check_firewall, check_paths,
     check_startup_shortcut, check_xinput, CheckResult,
 };
-use crate::{discovery, protocol};
+use crate::{discovery, support};
 
 pub async fn run(which: &str, all: bool, reboot_to_run: bool) -> Result<()> {
     if reboot_to_run && which != "cdc" {
@@ -168,10 +168,7 @@ async fn run_discover_all() -> Result<()> {
     let socket = UdpSocket::bind("0.0.0.0:0").await?;
     let replies = discovery::collect(&socket, Duration::from_secs(8)).await?;
     if replies.is_empty() {
-        return Err(anyhow!(
-            "no Pico replied within 8 s on UDP/{}",
-            protocol::PORT
-        ));
+        return Err(anyhow!("{}", support::no_pico_wifi_help(8)));
     }
 
     for (peer, info) in &replies {

bridge/src/support.rs

@@ -21,3 +21,47 @@ pub fn print_help_footer() {
     eprintln!("  bundle: couchlink bundle");
     eprintln!("  report: {}", issue_url());
 }
+
+pub fn no_pico_wifi_help(timeout_seconds: u64) -> String {
+    format!(
+        "No Pico replied on Wi-Fi within {timeout_seconds} s.\n\
+         This is a Pico/network discovery problem, not a controller problem.\n\
+         Try this in order:\n\
+           1. Confirm the Pico is powered and not sitting in BOOTSEL. If it appears as setup-mode USB, use `couchlink configure-wifi` first.\n\
+           2. Run `couchlink test discover --all` to retry discovery.\n\
+           3. If the router, SSID, or password changed, run `couchlink configure-wifi`.\n\
+           4. If configure-wifi cannot find setup mode, use the BOOTSEL-button credential wipe from the wiki, then run configure-wifi again.\n\
+           5. Run `couchlink doctor`; check Windows Firewall, router client isolation, and whether the PC and Pico are on the same LAN.\n\
+           6. Run `couchlink bundle` and send the zip if it still fails."
+    )
+}
+
+pub fn print_no_pico_wifi_help(timeout_seconds: u64) {
+    println!("{}", no_pico_wifi_help(timeout_seconds));
+}
+
+pub fn no_pico_wifi_short_hint() -> &'static str {
+    "Confirm the Pico is powered, not in BOOTSEL, and on the same LAN, then run `couchlink test discover --all`. If Wi-Fi changed or the Pico is in setup-mode USB, run `couchlink configure-wifi`. If it still fails, run `couchlink doctor` and `couchlink bundle`."
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{no_pico_wifi_help, no_pico_wifi_short_hint};
+
+    #[test]
+    fn no_pico_wifi_help_points_to_recovery_commands() {
+        let help = no_pico_wifi_help(5);
+        assert!(help.contains("No Pico replied on Wi-Fi within 5 s."));
+        assert!(help.contains("not a controller problem"));
+        assert!(help.contains("couchlink configure-wifi"));
+        assert!(help.contains("couchlink doctor"));
+        assert!(help.contains("couchlink bundle"));
+    }
+
+    #[test]
+    fn no_pico_wifi_short_hint_is_actionable() {
+        let hint = no_pico_wifi_short_hint();
+        assert!(hint.contains("same LAN"));
+        assert!(hint.contains("couchlink test discover --all"));
+    }
+}

wiki/Troubleshooting.md

@@ -75,6 +75,22 @@ Run:
 .\couchlink.exe test discover
 ```
 
+If the guided menu says `No Pico replied on Wi-Fi`, that is not a
+controller problem. It means the PC did not receive a UDP discovery reply
+from a running Pico.
+
+Try this in order:
+
+1. Confirm the Pico is powered and not sitting in BOOTSEL. If it appears
+   as setup-mode USB, use `configure-wifi` first.
+2. Run `.\couchlink.exe test discover --all`.
+3. If the router name or password changed, run `.\couchlink.exe
+   configure-wifi`.
+4. If `configure-wifi` cannot find the Pico, use the credential-wipe
+   recovery in [[Setup and Flashing]], then run `configure-wifi` again.
+5. Run `.\couchlink.exe doctor`.
+6. Run `.\couchlink.exe bundle` and attach the ZIP to a bug report.
+
 Common causes:
 
 - Windows Firewall blocks UDP broadcast. The bridge will print a