XiaoZhi AI Chatbot Documentation Center | XiaoZhi.Dev
ESP32 Development Guide
ESP32 Development Troubleshooting

ESP32 Development Troubleshooting

This page lists troubleshooting entry points by symptom. Every suggestion comes from the firmware source, upstream documents or site pages that have been checked; experience-based claims without a basis are not included. For usage problems (provisioning, activation, binding), start with First Boot and the FAQ.

1. Build and Environment

SymptomCheckAction
Build fails with ESP-IDF related errorsidf.py --versionThe firmware requires ESP-IDF v6.0.1 or later, v6.1 recommended; IDF 5.x is not supported. See ESP-IDF Development Environment Setup
ESP32-S31 variant fails to buildIDF versionVariants of this chip need ESP-IDF 6.1 or later; when building yourself, the release/v6.1 branch is recommended
Board or variant name not foundName spellingRun python3 scripts/build.py --list-boards for the exact board directories and variant names, then build with python3 scripts/build.py <board-directory> --name <variant-name>
Odd configuration after switching boardsLocal build statescripts/build.py rewrites sdkconfig and build state; do not assume the old build directory still matches the previous target, rebuild with the script
Board definition duplicated or missingDECLARE_BOARDA build must export exactly one DECLARE_BOARD(...), see the Custom Board Guide
Strange behavior after hand-editing generated filesbuild/, managed_components/, sdkconfig*, main/assets/lang_config.hThese are generated or third-party outputs and must not be edited by hand; restore them and rebuild

2. Flashing

  • The prebuilt firmware writes the merged image at address 0x0; for the steps see Firmware Download and Installation.
  • If flashing or erasing fails, take the board off the breadboard and connect it to the computer on its own, then try again.
  • Serial port names depend on the system: on Linux usually /dev/ttyACM0 or /dev/ttyUSB0, on macOS usually /dev/cu.usbmodem*, on Windows COMx; specify one with -p <port> when necessary.
  • Some boards have dedicated flash parameter notes; see the README in that board’s directory in the upstream repository.

3. No Sound or Cannot Record

Check in this order:

  1. Wiring: verify every wire against the pin tables in the Hardware Build Guide, and before powering on confirm with a multimeter that there is no short between GND and 3.3V.
  2. Board declaration: the microphone channel declaration (M or MR) in the board config.h must match the interleaved PCM returned by the codec; the R channel may only carry the playback reference and must not be used as a second microphone (see upstream main/audio/README.md).
  3. I2S mode: Simplex and Duplex use different pins; when you switch between them, change the pin definitions in config.h as well.
  4. Sample rate: most board configurations use 16 kHz input and 24 kHz output; a custom board must match its codec.

Capture Audio with the Audio Debugger

The firmware can send the captured audio to a computer over UDP, which tells you whether the problem is in capture or in a later stage:

  1. Enable USE_AUDIO_DEBUGGER in menuconfig (off by default), and set AUDIO_DEBUG_UDP_SERVER to the IP:port of your computer (default 192.168.2.100:8000).
  2. Run the upstream script on the computer; it listens on UDP port 8000 and writes WAV files:
python3 scripts/audio_debug_server.py --samplerate 16000 --channels 2

--samplerate defaults to 16000 and --channels defaults to 2; they must match the data format you capture.

4. Cannot Wake Up

  • Boards without PSRAM: the on-device wake word is disabled by default. Use a button or an external wake-up module, see ESP32 Budget Version.
  • Chip mismatch: AFE wake words and MultiNet custom wake words only support ESP32-S3 / P4 / S31 with PSRAM. C3, C5, C6 and ESP32 with PSRAM use WakeNet without AFE, see Chip Support and Storage Specs.
  • Custom wake word not sensitive: CUSTOM_WAKE_WORD_THRESHOLD ranges from 1 to 99, a smaller value is more sensitive, default 20; a Chinese wake word must be written as space-separated pinyin.
  • Assets wake word model: see the checksum and version notes in the Custom Assets Guide.

5. Networking, Activation and Upgrade

6. Assets Problems

LogMeaning
No assets partition found / Assets partition is disabledThe partition table has no assets partition
Checksum mismatchassets.bin is corrupted or written at the wrong offset
The assets version N is not supported, please upgrade the firmwareThe index version is higher than the firmware supports
Assets file size ... is larger than partition sizeThe file is larger than the partition

For how to fix these, see the Custom Assets Guide.

7. What to Include When Reporting a Problem

  • The firmware version, board directory and variant name (for example bread-compact-wifi), and the chip model;
  • The ESP-IDF version (the output of idf.py --version);
  • The complete serial log, from boot to the failure;
  • Reproduction steps, and whether you verified it on real hardware.

Report firmware problems at the upstream GitHub Issues.

Related Documents

Sources: AGENTS.md, main/audio/README.md, main/Kconfig.projbuild, main/assets.cc and scripts/audio_debug_server.py of 78/xiaozhi-esp32 v2.5.2.

Advanced Extension Points: Network Types, Wake Words, MCP and Asset Customization