| name | card-wifi-setup |
| description | Walk a user through provisioning Wi-Fi on their AI Desk Card device.
After provisioning, device joins the user's home Wi-Fi, advertises via
mDNS, and the daemon HTTP-pushes frames in ~0.2 s instead of USB's
32 s. Use whenever the user says "配 wifi" / "card 上 wifi" / "我想用
无线" / "怎么连 Wi-Fi" / when card-onboard's branch E recommends Wi-Fi.
|
| trigger_keywords | ["配 wifi","配 wi-fi","card 上 wifi","卡片连 wifi","无线连接","wifi setup","card wifi"] |
| allowed-tools | ["Bash","AskUserQuestion"] |
card-wifi-setup — 把设备搬上 Wi-Fi
把 SSID + 密码喂到设备 NVS，设备自动连，daemon 通过 mDNS 发现 → 后续推帧
0.2 秒到位。
先决条件
- 设备能跟 daemon 通信（USB serial OR BLE 已 pair）。如果两条路都没有，
先去
/card-onboard。
- daemon 在跑（
/card-status 确认）
流程
1) 跟用户要 SSID + 密码
关键安全提示先说：
密码会通过本地 daemon 一次性写到设备 NVS。不会写进 daemon 日志、
git 仓库、或者上传到任何远程服务。
然后问：
告诉我你家 Wi-Fi 的名称（SSID）和密码。
注意：SSID 就是 Wi-Fi 名称 — 用户在手机 Wi-Fi 列表里看到的那个字符串。
不是 MAC 地址、IP 地址、或者其他什么。如果用户给了一串看起来像 MAC
（xx:xx:xx:xx:xx:xx），礼貌地纠正：
那看起来像 MAC 地址。我要的是 Wi-Fi 名称 — 手机里看到的那串字。
2) 推送
收到 SSID + password 后：
$CLAUDE_PLUGIN_ROOT/scripts/wifi_setup.sh "<SSID>" "<password>"
注意 SSID 一定要加双引号（可能含空格 / 中文 / 特殊字符）。脚本里走 daemon
的 /provision-wifi HTTP endpoint，daemon 转发为 cmd:wifi_set 给设备。
3) 等 15-20 秒看结果
跑 probe：
bash $CLAUDE_PLUGIN_ROOT/skills/card-onboard/scripts/probe.sh --quick
期望 mdns_peer != null，里面有 IP。
或者直接看 daemon 日志：
tail -20 "${TMPDIR:-/tmp}/ai_desk_card_daemon.log" | grep -i wifi
成功的话有 [dev<] {..."wifi_connected":true,"wifi_ip":"192.168.x.y",...} 行。
4) 重启 daemon 切到 Wi-Fi transport
/card-stop && /card-start
新 daemon 启动时会 mDNS 扫到 Wi-Fi peer，自动选 Wi-Fi。看到 [transport] found Wi-Fi peer X.X.X.X:9880, using Wi-Fi 即成功。
失败诊断
设备 status 长期 wifi_connected:false 不上 Wi-Fi → 看错误 code。daemon
日志里设备会打 [wifi] connect timeout (status=N):
| status | 意义 | 处理 |
|---|
| 1 | SSID 未找到 | 检查 SSID 拼写；ESP32 不支持 5GHz，确保是 2.4 GHz |
| 4 | 鉴权失败（密码错） | 让用户确认密码，重新跑 wifi-setup |
| 6 | DHCP 失败 | 路由器问题；可能是 MAC 过滤、或客户端数已满 |
| 其他 | 各种 | 把 daemon 日志最后 20 行给用户看 |
最常见的：用户家是双频路由器，给的密码对应 5GHz 网络。让用户在路由器后
台单独建一个 2.4GHz SSID 或者用 2.4GHz 频段的那个 SSID。
架构提示
写完凭据后，设备的"什么时候连 Wi-Fi"由电源状态决定（固件自己判断）：
- 架构 A（USB 接着）：开机自动连，永远在线
- 架构 C（电池供电）：连完一次后会断开，等 daemon 的
cmd:wifi_wake_now
按需唤醒（daemon 自动发，用户不用操心）
两种模式下用户都不用做额外操作。
不要做的事
- ❌ 不要把 SSID/密码记到 daemon 日志、屏幕、或 git
- ❌ 不要鼓励用户用复杂密码绕过 ESP32 的 WPA2 限制 — ESP32 支持 WPA2/WPA3，
够用；但有些新 router 默认 WPA3 而 ESP32 老固件兼容性差。如果反复
连不上，建议路由器设回"WPA2/WPA3 mixed"。
- ❌ 不要默认密码长度 ≥ 8。让 ESP32 自己判断；过短的密码也能工作的网络
确实存在（开发场景）。
- ❌ 不要跳过 step 4（daemon 重启）。Daemon 启动时才扫 mDNS，运行中不会
自动切 transport。
