Device Connection Failures: Diagnose from Scratch
A device that “won’t connect” can fail at any layer: boot, provisioning, Wi-Fi, activation, server connection or conversation. Walk the layers in order, confirm where it breaks, then follow the matching fix. Each step says how to check it and where to fix it.
Step 1: does the device boot
Check: after power-on the display or LED reacts (an emoji, a provisioning prompt, or LED changes).
| Symptom | Most likely cause | Fix |
|---|---|---|
| No reaction at all | Insufficient power or miswiring (candidates); in a flashing scenario possibly a charge-only USB cable | Check wiring and power in the Hardware Setup Guide; on the breadboard build confirm VDD/GND are not swapped; when flashing fails, try a cable confirmed to carry data |
| Boot loops | Firmware variant does not match the board, unstable power | Confirm the flashed variant matches the board (see Firmware Download), then try another power source |
Step 2: does it enter provisioning
Check: on first power-up the display shows the Xiaozhi-XXXX hotspot prompt.
- No hotspot found: the device may have saved Wi-Fi; hold the button to re-enter provisioning (FAQ Q10/Q11);
- Hotspot connects but
192.168.4.1won’t open: try another phone browser or disable mobile data; - Full steps and failure handling: First Boot and Network Setup.
Step 3: does it join Wi-Fi
Check: after picking the router and entering the password, the device reboots and shows it is online (clock or status on screen).
| Symptom | Most likely cause | Fix |
|---|---|---|
| Stuck “connecting”, then fails | Wrong password; band is one candidate cause | Most XiaoZhi chips are 2.4GHz-only and may fail to associate when the router shares one SSID across bands (dual-band chips like ESP32-C5 are exempt); give 2.4G its own SSID and retry |
| Connects, then drops | Weak signal, router rejects new devices | Move closer; check router access control and MAC filtering |
| 4G module won’t connect | 4G requires a secure connection | For self-hosted servers see the 4G note in Self-Hosted Server |
Step 4: does it activate
Check: once online the device shows and reads out a 6-digit activation code; entering it in the official console binds the device.
| Symptom | Most likely cause | Fix |
|---|---|---|
| No activation code shown | The device is not actually online, or points at a different server | Back to step 3; for self-hosting confirm the OTA URL took effect |
| Console says binding failed | Code expired, or the device is bound to another account | Reboot for a new code; unbind first |
| Full checklist | — | The troubleshooting table at the end of First Boot |
Step 5: does it reach the server
Check: after binding, wake the device and watch for a response (official service: voice and emoji feedback; self-hosted: server logs).
- Official service: first confirm the service itself is up (console logs in, other devices work), then check the device’s OTA URL;
- Self-hosted: the device’s OTA URL points at your server; opening the OTA URL in a browser should return a normal message, and the WebSocket address must use the LAN IP, not
localhost; if server logs show no dialogue, follow the “common situations” in Self-Hosted Server; - 4G devices to a self-hosted server: TLS is required (nginx + certificate), see that project’s FAQ.
Step 6: does it converse
Only when the server chain is fully normal (the staged checks in step 5 pass) but the device still does not respond or has no sound, move on to audio-layer checks:
- No wake reaction: microphone issue, or the wake word does not apply to this board (FAQ Q9);
- Responds but silent: speaker wiring and volume (FAQ Q6/Q8);
- Distorted audio: FAQ Q7.
Verified community cases (source-bound)
These come from high-engagement closed issues on the upstream repo; they hold only within the stated firmware version and hardware combination and are not reproduced by this site. Whether newer versions fix them follows the issue and release notes:
| Symptom | Scope | Reports & conditions (not a general fix) | Source |
|---|---|---|---|
Screen locks after a voice photo request; next wake reports AFE: ringbuffer is full, reproducible | bread-compact-wifi-s3cam + OV3660, reporter firmware v2.0.5-20-gf408817 (log line 2.1.0) | One reporter’s conditional finding: XCLK at 24 MHz with 240x240 made photos work (Dec 23 comment); closed Dec 24 as “24M suits, 240x240 or 640x480 fine” (closing summary). However, on Dec 30 another user with the same settings (240x240/24M) still failed (comment); the maintainer asked whether OV3660 support was enabled in menuconfig (comment) and that user confirmed enabled-but-still-failing (comment). OV2640 working in the same setup and the #1245 esp_video migration are background facts, not a general root cause or verified fix; the parameter change was validated only on the reporter’s own board. Not reproduced by this site | Issue #1588 (closed 2025-12-24, 31 comments) |
Principles
- Layer first, then depth: boot → provisioning → Wi-Fi → activation → server → conversation, confirm layer by layer;
- Version and variant first: a board/firmware-variant mismatch is one common candidate behind “weird” behavior (not the only source, and not a statistical claim);
- Change one thing at a time: verify immediately after each change.
Unsolved problems: see the FAQ and Development & Debugging; when reporting, follow the “what to provide” section there.