Build Your Own
XiaoZhi AI Voice Chatbot
with Custom Wake Word

First verify the device is powered on and connected to Wi-Fi (the OLED should show the face animation or status). Ensure the INMP441 microphone is wired correctly: VDD→3.3V, GND→GND, SD→GPIO32, WS→GPIO25, SCK→GPIO26, L/R→GND on the mic module itself. Speak clearly at 30–100 cm distance. If using an ESP32 (non-S3), wake word is NOT supported — you must use ESP32-S3 for MultiNet hardware wake word detection. Try rebooting the device. If still not working, re-generate assets.bin with the wake word and flash it again via OTA. Check that the recognition model is set to "MultiNet6 (English)" for English commands in the XiaoZhi Customize tool.

Check the I2C wiring: OLED VCC→3.3V, GND→GND, SCL→GPIO15, SDA→GPIO4. Ensure the OLED address matches the firmware default (0x3C for most SSD1306 displays). Try adjusting the I2C contrast or enable the OLED reset pin in the firmware configuration. If the display worked before but stopped, check for loose Dupont wires on the breadboard. For 128×32 OLEDs, make sure you selected the correct screen resolution in the Customize tool — 128×64 is the standard for this tutorial. If the OLED shows data but no face animation, the emoji assets may not have been flashed correctly — regenerate and re-flash assets.bin.

Verify the MAX98357A wiring: VIN→3.3V or 5V (check module specs), GND→GND, LRC→GPIO33, DIN→GPIO27, BCLK→GPIO14. The speaker must be connected to SPK+ and SPK− terminals — not to GND. For distorted audio, reduce the volume by saying "Set volume to 30%" or lower the gain in the audio codec configuration. Ensure the power supply can deliver at least 1A — a weak power source causes audio crackling. Keep audio signal wires (DIN, BCLK, LRC) away from power wires to reduce interference. If there is static noise, try adding a 100µF capacitor across the amplifier VIN and GND.

Continuous reboots are usually caused by insufficient power or memory overflow. Use a USB port that can deliver at least 1A — avoid USB hubs and front-panel ports. If using an ESP32 (budget version) without PSRAM, disconnect the OLED display to free memory. For ESP32-S3, ensure PSRAM is properly configured: the board must have at least 8MB PSRAM (N16R8 module). Check that the partition table matches your firmware version — v2 firmware requires v2 partition tables (8MB or 16MB). If you see "Brownout detector was triggered" in the serial monitor, the power supply is insufficient. Try reflashing the firmware with the "Erase Device" option checked.

ESP32-S3 supports only 2.4 GHz Wi-Fi — it cannot connect to 5 GHz networks. If your router broadcasts both bands under the same SSID, the device may try to connect to the 5 GHz band and fail. Temporarily disable the 5 GHz band on your router, or create a separate 2.4 GHz SSID. Ensure the Wi-Fi password is correct (there is no show/hide toggle in the portal). If the captive portal at 192.168.4.1 does not load, disable mobile data on your phone and reconnect to the XiaoZhi-XXXX hotspot. For persistent issues, try rebooting the router and the device. If the error says "Network Error" or "Unable to Connect", the cloud server at xiaozhi.me may be temporarily unreachable — check your internet connection.

This error occurs when the srmodels.bin file is too large for the allocated partition space. It typically happens when using a 4 MB flash chip with v2 firmware — v2 requires 8 MB or 16 MB flash. If you are using the v1 firmware branch, make sure you selected the correct partition table (v1/4m.csv for 4 MB flash). For ESP32-S3 boards with 2 MB PSRAM (like Super Mini S3), disable the English Speech Commands Model in menuconfig and set PSRAM to Quad Mode. The simplest fix is to use the pre-compiled firmware from the GitHub releases page that matches your board type exactly.

Audio interruptions during TTS playback are often network-related. The device uses streaming audio — if the Wi-Fi signal is weak or unstable, audio packets may arrive out of sequence or timeout. Move the ESP32-S3 closer to the router and ensure it is on a dedicated 2.4 GHz network. Check for MQTT audio packet sequence warnings in the serial monitor — these indicate packet loss. If using a custom MCP tool that returns large responses, the TTS buffer may overflow; try keeping responses concise. On rare occasions, the cloud TTS engine may have a transient issue — try asking the same question again. If the problem persists, test on a different network to rule out ISP issues.

If the OLED remains stuck on the connecting screen, the device is unable to establish a Wi-Fi connection. Reset the Wi-Fi configuration by holding the BOOT button for 5 seconds — this clears the stored credentials and restarts the captive portal. Reconnect to the XiaoZhi-XXXX hotspot and re-enter your Wi-Fi details. Make sure your router is broadcasting on the 2.4 GHz band and is within range. If you changed your Wi-Fi password recently, the device still has the old password stored — use the BOOT long-press reset to clear it. For enterprise networks (WPA2-Enterprise), XiaoZhi does not support captive portal login — use a personal hotspot instead.