Troubleshooting¶
Symptom-driven table for connecting and running a device. If you haven't yet, read First boot and the host setup guide for your OS (Windows / Linux) first — most of these symptoms are covered there in more detail.
| Symptom | Likely cause | What to do |
|---|---|---|
| Nothing enumerates on the host at all (no new adapter, no COM/serial port) | Charge-only cable, wrong port, or device not fully booted | Try a known-good data-capable cable; confirm you're using the OTG port (Zero 2 W: micro-USB marked "USB", not "PWR IN"; Pi 4/5: the USB-C power connector) — see Hardware; give the device its full boot time (up to ~30 s on Zero 2 W) before concluding it's not enumerating |
| Network adapter appears, but never gets an IP address | Host-side software claiming the interface, or the device didn't finish starting its DHCP server | Wait a few seconds after enumeration; on Windows, check the adapter isn't disabled or set to a static IP by another tool; on Linux, check nmcli device status / journalctl -u NetworkManager for the interface being managed |
10.99.0.1 unreachable even though the adapter has an address |
Host firewall blocking the new adapter, or VPN software binding all traffic away from it | Temporarily disable host firewall/VPN and retest; if that fixes it, add a firewall exception for the device's subnet (10.99.0.0/24) or exclude that adapter from the VPN's tunnel-all policy |
COM port / /dev/ttyACM* opens but you see garbage or nothing readable |
Terminal program local echo, or wrong line-ending handling | NDJSON frames are newline-terminated (\n) plain JSON — use a terminal that doesn't insert local echo or translate line endings (or use a proper client instead of an interactive terminal); confirm you see the hello line first, sent automatically on open |
| Device boots, then reboots repeatedly (boot loop) | Power supply/cable can't sustain the board under load (undervoltage), typically on Pi 4/5 with a screen and peripherals attached | Use a powered hub with data passthrough, a Y-cable to a separate power source, or a Power-Delivery-capable host port — see Hardware → Power; once reachable, GET /api/v1/device/health reports throttled/undervoltage flags confirming the cause |
| Need to see what the device is doing / file a bug report | — | GET /api/v1/device/logs?since=&limit= returns the agent's structured logs (also kept on the data partition); the last kernel boot log is available as /data/log/boot.log on the device (readable via the recovery shell — see below, or via a future log-download convenience once available) |
| Device unreachable entirely and you need to recover it | Bad configuration, corrupted state, or you just want a clean slate | Two options: POST /api/v1/device/factory-reset over the API if it's still reachable, or the offline recovery path — remove the SD card, mount its small boot (FAT32) partition on any PC, and create an empty file named factory-reset at its root; on next boot the device wipes its data partition back to defaults. See Factory reset for the full procedure |
| Serial port opens fine but you want a root shell for field debugging | — | Send the exact line {"type":"shell"} on the open serial connection to switch it to an interactive root BusyBox shell; type exit to return to NDJSON mode (a fresh hello line is sent) |
| Two devices plugged into the same host — can't tell which is which | Both present near-identical adapter/port names | Match by serial number: shown in GET /api/v1/device / the hello frame, and in the OS's device properties (Windows: hardware IDs in Device Manager; Linux: /dev/serial/by-id/... path, udevadm info on the network interface). The Go client library does this matching automatically |
Status LEDs¶
The boards use the Raspberry Pi's own standard power/activity LEDs (a lit power LED
means the board has power; the activity LED flickers during SD card access,
especially at boot). MyCustomerDisplay does not define any custom LED codes beyond
this standard Raspberry Pi behavior — the on-screen waiting page and the
GET /api/v1/device/health endpoint are the supported ways to check device status.
Still stuck?¶
Check the FAQ, or re-read the relevant host setup guide end to end — most first-time issues are a cable, a port, or a firewall/VPN rule.