Take the user from "just got the device / nothing installed" to "four widgets on screen, Wi-Fi online, frame push in place in 0.2 seconds".
One-shot principle
- Always run probe first, don't ask out of thin air "is your daemon started?".
scripts/probe.shGet all state in one go. - At each step tell the user the current progress: "I see the daemon is running, but no device is connected yet, now checking the serial port...". Don't operate silently.
- On failure, don't retry in a loop. If stuck, stop, give the user the diagnostic results, and let them decide.
- Prefer Wi-Fi, don't default to USB-serial or BLE. Wi-Fi is 0.2 seconds per frame, USB 1-32 seconds, BLE commands work but frames don't (known issue).
Probe entry point
bash $CLAUDE_PLUGIN_ROOT/skills/card-onboard/scripts/probe.sh
Output structure (JSON):
{
"daemon": { "running": bool, "pid": int|null },
"transport": { "connected": bool,
"type": "SerialTransport|BLETransport|WiFiTransport|null" },
"firmware": { "our": bool, "note": str, "banner": str|null },
"serial_ports": [ "/dev/cu.usbserial-..." ],
"mdns_peer": { "ip": "192.168.x.y", "port": 9880,
"txt": { "fw": "0.8.0", "proto": "1" } } | null
}
firmware.our=true = what's running on the device is our firmware (daemon sent cmd:owner
received within 2.5 seconds ack:owner)。
mdns_peer != null = The device is already broadcasting Wi-Fi on the LAN, this is the most ideal state.
Decision tree (handle in order; if a branch is hit, fix it first, then go back to probe to verify)
G — mdns_peer != null and transport.type != "WiFiTransport"
The most ideal state was missed. The device is already on Wi-Fi, but the daemon isn't using Wi-Fi. Tell the user:
The device is on Wi-Fi
<ip>is already online. Your daemon isn't using it, probably because the daemon hasn't been restarted before.
Run:
/card-stop && /card-start
Go back to probe, you should see transport.type == "WiFiTransport"。
A — daemon.running == false
Daemon isn't running. Run /card-start(automatically selects Wi-Fi > USB > BLE). Wait 1-2 seconds and probe
again.
B — daemon.running == true && serial_ports == [] && mdns_peer == null
The device is completely offline — USB isn't plugged in, and Wi-Fi isn't up either. Possible scenarios:
- The device isn't powered on at all: the battery is dead, or it isn't turned on. Have the user press the power button.
- The device is powered on but Wi-Fi has never been configured: first boot or the NVS credentials were cleared. You need to first
connect the daemon via USB, then go through BLE pair →
/card-wifi-setupto feed in the credentials. Have the user plug in a USB-C data cable(note: not a charging cable). - The device is on Wi-Fi but on a different subnet: the Mac running the daemon and the device aren't on the same local network. Have the user check whether the Wi-Fi is a phone hotspot or a corporate guest network.
C — transport.connected == false but serial_ports != []
The USB port is there but the daemon isn't connected. Most common cause: the daemon wasn't released cleanly last time, or the USB on the M5Paper side is still booting. Run:
/card-stop && /card-start
Still not working → show me probe + tail -20 "${TMPDIR:-/tmp}/ai_desk_card_daemon.log"。
D — transport.connected == true && firmware.our == false
USB is connected but the firmware isn't ours (bare board / M5 factory demo / old buddy firmware). Ask:
The device is connected, but what's running isn't the AI Desk Card firmware. Do you want to flash it now? (Flashing firmware will erase other programs on the device, completes within 30 seconds)
User agrees → /card-install flash, wait 5 seconds and probe again.
E — transport.connected == true && firmware.our == true but mdns_peer == null
The firmware is in place but Wi-Fi has never been configured. Strongly recommend configuring Wi-Fi (afterward a single widget is 0.2 seconds). Have the user provide SSID + password:
The device is ready. Do you want to configure Wi-Fi now? That way pushing widgets will be 0.2 seconds per frame, 100 times faster than USB. Tell me the SSID and password, and I'll write them to the device NVS (credentials are only stored locally on the device, not committed to git).
Credentials received → run:
/card-wifi-setup "<SSID>" "<密码>"
Wait 15 seconds and probe again, see mdns_peer.ip → success.
If the user doesn't want to set up Wi-Fi ("just want to see how it looks"), go directly to branch F。
F — all green, whether to push the default widget
✅ Everything is in place. Ask the user:
Push a set of default widgets up to take a look? Default layout: top-left = weather, top-right = ai-status, middle = focus, bottom = todo
Agree → switch to card-widget skill。
Z — user explicitly wants BLE only (not recommended)
Scenarios where neither USB nor Wi-Fi is wanted.Note: pushing widget data over BLE is unstable(known issue, small commands work, large blocks of data don't trigger onWrite on the device side). After warning the user:
- Unplug USB, daemon automatically falls back to BLE
/card-stop && /card-start- daemon automatically scans
Card-*device → connects in 1-2 minutes - Re-probe →
transport.type == "BLETransport" - When pushing widgets fails, return to this branch and suggest setting up Wi-Fi
Reassurance script
- "Why is the e-ink display so slow" → USB serial 32s/frame is the physical limit of 115200 baud.Wi-Fi is 0.2 seconds. Strongly recommend setting up Wi-Fi.
- "Why does the screen keep showing the previous content" → e-ink retains the last frame at 0 power consumption, it's a feature not a bug.
- "Why is the battery level inaccurate" → "USB is charging" is determined by battery voltage > 4150 mV. Right after unplugging USB with a full battery it will also show USB mode, and it will return to normal after a few minutes.
- "I want to change the displayed name/QR code" → edit
ai-desk-card/assets/profile.yaml, run/card-sleepto push the business card frame.
Things not to do
- ❌ Do not automatically
/card-install flash— always ask the user first - ❌ Do not proactively restart the daemon or device unless the user agrees (or go through /card-stop+start)
- ❌ Do not try to parse the serial protocol yourself — go through
/firmware-probeHTTP endpoint - ❌ Do not skip the mDNS branch and push directly over USB / BLE — Wi-Fi is the preferred path
- ❌ Do not record the SSID/password in the daemon log or write it into git — only write it to the device NVS in one shot via
/card-wifi-setupWrite to device NVS in one go
Troubleshooting information collection
If the user gets stuck at a certain step:
bash $CLAUDE_PLUGIN_ROOT/skills/card-onboard/scripts/probe.sh
tail -30 "${TMPDIR:-/tmp}/ai_desk_card_daemon.log"
ioreg -p IOUSB | grep -i 'usb\|m5\|silab\|ftdi' | head -10
Gather these for the user and ask whether to file an issue at https://github.com/op7418/m5-paper-buddy