ai-desk-card

A 540×960 e-ink panel sitting next to the user's monitor. AI agents push widgets to it; the daemon renders frames server-side and ships pixels over Wi-Fi / USB / BLE. This Skill is the only thing an agent needs to call — it auto-detects state and routes to the right flow.

Before doing anything, run the state probe. Do not ask the user "have you done X" — find out by checking. `bash bash $SKILL_DIR/scripts/state.sh ` ($SKILL_DIR is wherever this Skill is installed. If your agent runtime sets $CLAUDE_PLUGIN_ROOT, use that. Otherwise use the repo root.) Output is JSON with this shape: `jsonc { "hardware": { "pio_installed": bool, "m5paper_usb": str|null }, "firmware": { "flashed": bool, "ours": bool, "version": str|null }, "daemon": { "running": bool, "pid": int|null }, "transport": { "connected": bool, "type": "BLETransport|SerialTransport|WiFiTransport|null" }, "device": { "alive": bool, "last_seen_seconds": int|null, "active_transport": "Wi-Fi|USB|BLE|null", "battery_pct": int|null, "uptime": str|null }, "wifi": { "provisioned": bool, "ip": str|null }, "interests": { "configured": bool, "path": str|null } } ` The most important field is device.alive. It tells you whether the device has sent a status report in the last ~90 s. transport.connected only says "daemon picked a transport class"; device.alive says "we're actually hearing back from the device right now."

The Skill supports two devices with different panels + daemons: • M5Paper V1.1 (540×960 grayscale, GT911 touch, BLE pair) — original • M5Paper Color (600×400 Spectra 6 color, 3 physical buttons, audio + SHT40) — new in v0.10 If GET /heartbeat returns device_status.device == "M5PaperColor" (via color_daemon.py running), use the Color path described in flows/08_paper_color.md: • env: pio run -e paper-color • daemon: python3 daemon/color_daemon.py --device-ip <IP> • Wi-Fi provision: Serial JSON cmd:wifi_set (no BLE pairing UX) • slot names: top-left / top-right / bottom-left / bottom-right • extra widgets: ambient (SHT40 temp+humid) • physical buttons: 顶=sleep / 下左=refresh / 下中=settings Otherwise (default) use the V1.1 path through the routing table below. The two daemons can't run on the same port simultaneously — pick one based on which device is in front of the user. The Skill flows below work for V1.1 unless explicitly noted.

Walk the decision tree in this order. First mismatch wins; fix it, then re-probe. | Condition | Next action | Detail flow | |---|---|---| | firmware.flashed == false AND no device.alive | First-time hardware setup | flows/01_install.md | | daemon.running == false | Start the daemon | bash $SKILL_DIR/plugin/scripts/start.sh | | device.alive == false AND transport.connected == false | Device unreachable — could be asleep, off, BLE not paired. Tell user, suggest physical wake (tap rotary / plug USB) | flows/02_transport.md | | device.alive == false AND transport.connected == true (daemon connected something but no status_report in 90s) | Device transport up but not responding — restart daemon, then probe | flows/02_transport.md | | wifi.provisioned == false (and user wants always-on or battery mode) | Provision Wi-Fi | flows/03_wifi.md | | interests.configured == false AND user just asked for "auto-refresh" or "定时推送" | Ask about interests, write ~/.ai-desk-card/interests.yaml | flows/04_interests.md | | device.alive == true + user said "push X" | Build widget JSON, POST to daemon | flows/05_push.md | | device.alive == true + user said "schedule" / "每 N 分钟" / "auto" | Set up scheduled push | flows/06_schedule.md | | device.alive == true + user said "sleep" / "息屏" | Push business card + deep sleep | flows/07_sleep.md | Always tell the user which step you're on. Don't operate silently.