Feed the SSID + password into the device NVS, the device connects automatically, the daemon discovers it via mDNS → then pushes frames in place in 0.2 seconds.
Prerequisites
- The device can communicate with the daemon (USB serial OR BLE already paired). If neither path is available,
first go to
/card-onboard。 - the daemon is running (
/card-statusto confirm)
Procedure
1) Ask the user for SSID + password
Key security noteFirst say:
The password will be written to the device NVS in one shot through the local daemon.It will notbe written to the daemon logs, the git repository, or uploaded to any remote service.
Then ask:
Tell me your home Wi-Fi name (SSID) and password.
Note: SSID is the Wi-Fi name — the string the user sees in the Wi-Fi list on their phone.
It is not a MAC address, IP address, or anything else. If the user gives a string that looks like a MAC
(xx:xx:xx:xx:xx:xx), politely correct them:
That looks like a MAC address. What I want is the Wi-Fi name — the string you see on your phone.
2) Push
After receiving the SSID + password:
$CLAUDE_PLUGIN_ROOT/scripts/wifi_setup.sh "<SSID>" "<password>"
Note that the SSID must be enclosed in double quotes (it may contain spaces / Chinese / special characters). In the script, go through the daemon's /provision-wifi HTTP endpoint, and the daemon forwards it as cmd:wifi_set to the device.
3) Wait 15-20 seconds to see the result
Run probe:
bash $CLAUDE_PLUGIN_ROOT/skills/card-onboard/scripts/probe.sh --quick
Expect mdns_peer != null, with an IP in it.
Or just look at the daemon logs:
tail -20 "${TMPDIR:-/tmp}/ai_desk_card_daemon.log" | grep -i wifi
If successful, there will be a [dev<] {..."wifi_connected":true,"wifi_ip":"192.168.x.y",...} line.
4) Restart the daemon to switch to the Wi-Fi transport
/card-stop && /card-start
When the new daemon starts, it will scan for the Wi-Fi peer via mDNS and automatically choose Wi-Fi. Seeing [transport] found Wi-Fi peer X.X.X.X:9880, using Wi-Fi means success.
Failure diagnosis
The device status stays wifi_connected:false and does not get onto Wi-Fi → look at the error code. In the daemon
logs, the device will print [wifi] connect timeout (status=N):
| status | Meaning | Handling |
|---|---|---|
| 1 | SSID not found | Check the SSID spelling;ESP32 does not support 5GHz, make sure it is 2.4 GHz |
| 4 | Authentication failed (wrong password) | Have the user confirm the password and run wifi-setup again |
| 6 | DHCP failed | Router problem; possibly MAC filtering, or the client limit is full |
| Other | Various | Show the user the last 20 lines of the daemon logs |
The most common: the user's home has a dual-band router, and the password they gave corresponds to the 5GHz network. Have the user, in the router admin panel,create a separate 2.4GHz SSID or use the SSID for the 2.4GHz band.
Architecture note
After the credentials are written, "when the device connects to Wi-Fi" is determined by the power state (the firmware decides on its own):
- Architecture A (USB connected): connects automatically on boot, always online
- Architecture C (battery powered): after connecting once it will disconnect, waiting for the daemon's
cmd:wifi_wake_nowwake on demand (the daemon sends it automatically, the user does not need to worry about it)
In both modes the user does not need to do anything extra.
Things not to do
- ❌ Do not record the SSID/password in daemon logs, on screen, or in git
- ❌ Do not encourage users to bypass the ESP32's WPA2 limitations with complex passwords — the ESP32 supports WPA2/WPA3, which is sufficient; but somenew routers default to WPA3, and ESP32 old firmware has poor compatibility. If it repeatedly fails to connect, it is recommended to set the router back to "WPA2/WPA3 mixed".
- ❌ Do not default to a password length ≥ 8. Let the ESP32 decide for itself; networks where a shorter password still works do exist (development scenarios).
- ❌ Do not skip step 4 (daemon restart). The daemon only scans mDNS at startup and will not automatically switch transport while running.