Устранение неполадок при разработке ESP32

Центр документации XiaoZhi AI чат-бота | 小智AI.Dev

Страница упорядочена по симптомам и показывает, с чего начинать диагностику. Каждая рекомендация основана на исходном коде прошивки, документации upstream или проверенных страницах сайта; эмпирические утверждения без опоры в источниках не включены. Для вопросов использования (настройка сети, активация, привязка) сначала откройте Первый запуск и FAQ.

1. Сборка и окружение

Симптом	Что проверить	Что делать
Сборка завершается ошибкой, связанной с ESP-IDF	`idf.py --version`	Прошивке нужен ESP-IDF v6.0.1 или новее, рекомендуется v6.1; IDF 5.x не поддерживается. См. Настройку среды ESP-IDF
Не собирается вариант для ESP32-S31	Версия IDF	Вариантам этого чипа нужен ESP-IDF 6.1 или новее; при самостоятельной сборке рекомендуется ветка `release/v6.1`
Не найдено имя платы или варианта	Написание имени	Выполните `python3 scripts/build.py --list-boards`, чтобы узнать точные каталоги плат и имена вариантов, затем соберите командой `python3 scripts/build.py <каталог-платы> --name <имя-варианта>`
Странная конфигурация после смены платы	Локальное состояние сборки	`scripts/build.py` перезаписывает `sdkconfig` и состояние сборки; не считайте, что старый каталог сборки соответствует прежней цели, пересоберите через скрипт
Определение платы дублируется или отсутствует	`DECLARE_BOARD`	В сборке должен экспортироваться ровно один `DECLARE_BOARD(...)`, см. руководство по своей плате
Странное поведение после ручного редактирования сгенерированных файлов	`build/`, `managed_components/`, `sdkconfig*`, `main/assets/lang_config.h`	Это сгенерированные файлы или вывод сторонних компонентов, вручную их менять нельзя; восстановите их и пересоберите

2. Прошивка

Готовая прошивка записывает объединённый образ по адресу 0x0; шаги описаны в разделе Загрузка и установка прошивки.
Если запись или стирание не удаётся, снимите плату с макетной платы, подключите её к компьютеру отдельно и повторите попытку.
Имена последовательных портов зависят от системы: в Linux обычно /dev/ttyACM0 или /dev/ttyUSB0, в macOS — /dev/cu.usbmodem*, в Windows — COMx; при необходимости укажите порт через -p <порт>.
Для некоторых плат есть отдельное описание параметров флеш-памяти; смотрите README в каталоге этой платы в репозитории upstream.

3. Нет звука или не записывается

Проверяйте в таком порядке:

Подключение: сверьте каждый провод с таблицами выводов в руководстве по сборке оборудования и перед включением питания убедитесь мультиметром, что между GND и 3,3 В нет замыкания.
Объявление платы: объявление канала микрофона (M или MR) в config.h платы должно совпадать с чередующимся PCM, который возвращает кодек; канал R может нести только опорный сигнал воспроизведения и не должен использоваться как второй микрофон (см. upstream main/audio/README.md).
Режим I2S: у Simplex и Duplex разные выводы; при переходе с одного режима на другой меняйте и определения выводов в config.h.
Частота дискретизации: в большинстве конфигураций плат вход 16 кГц, выход 24 кГц; пользовательская плата должна соответствовать своему кодеку.

Захват звука через Audio Debugger

Прошивка может отправлять захваченный звук на компьютер по UDP, чтобы понять, где проблема — в захвате или на последующих этапах:

Включите USE_AUDIO_DEBUGGER в menuconfig (по умолчанию выключено) и задайте в AUDIO_DEBUG_UDP_SERVER значение IP:порт вашего компьютера (по умолчанию 192.168.2.100:8000).
Запустите на компьютере скрипт из upstream: он слушает UDP-порт 8000 и пишет WAV-файлы:

python3 scripts/audio_debug_server.py --samplerate 16000 --channels 2

По умолчанию --samplerate равен 16000, а --channels равен 2; значения должны соответствовать формату захватываемых данных.

4. Не срабатывает пробуждение

Платы без PSRAM: локальное слово пробуждения по умолчанию отключено. Используйте кнопку или внешний модуль пробуждения, см. Бюджетная версия на ESP32.
Несоответствие чипа: слова пробуждения AFE и пользовательские слова MultiNet поддерживаются только на ESP32-S3 / P4 / S31 с PSRAM. C3, C5, C6 и ESP32 с PSRAM используют WakeNet без AFE, см. Поддержку чипов и спецификации хранилища.
Пользовательское слово пробуждения срабатывает плохо: CUSTOM_WAKE_WORD_THRESHOLD лежит в диапазоне 1–99, чем меньше значение, тем выше чувствительность, по умолчанию 20; китайское слово пробуждения нужно записывать пиньинем через пробел.
Модель слова пробуждения в Assets: см. замечания о контрольной сумме и версии в руководстве по пользовательским Assets.

5. Сеть, активация и обновление

Вопросы настройки сети и активации разобраны в Первом запуске и Настройке сети; если /activate возвращает 202, устройство ждёт и повторяет запрос — это не неисправность.
Если проверка версии не удалась, устройство повторит её после интервала повтора, перезагружать вручную не нужно.
Если вы развернули собственный сервер, сверьте рукопожатие и форматы сообщений с разделами Протокол связи WebSocket и Гибридный протокол MQTT + UDP.

6. Проблемы с ресурсами assets

Лог	Значение
`No assets partition found` / `Assets partition is disabled`	В таблице разделов нет раздела `assets`
Несовпадение контрольной суммы	`assets.bin` повреждён или записан по неверному смещению
`The assets version N is not supported, please upgrade the firmware`	Версия индекса выше, чем поддерживает прошивка
`Assets file size ... is larger than partition size`	Файл больше раздела

Способы решения см. в руководстве по пользовательским Assets.

7. Что приложить к отчёту о проблеме

Версию прошивки, каталог платы и имя варианта (например, bread-compact-wifi), а также модель чипа;
Версию ESP-IDF (вывод idf.py --version);
Полный лог последовательного порта от запуска до ошибки;
Шаги воспроизведения и сведения о том, проверяли ли вы это на реальном оборудовании.

О проблемах прошивки можно сообщать в upstream GitHub Issues.

Связанные материалы

Источники: AGENTS.md, main/audio/README.md, main/Kconfig.projbuild, main/assets.cc и scripts/audio_debug_server.py в 78/xiaozhi-esp32 v2.5.2.

Точки расширения: типы сетей, слова пробуждения, MCP и настройка ресурсов