Центр документации XiaoZhi AI чат-бота | 小智AI.Dev
Руководство по разработке
Настройка среды разработки ESP-IDF и компиляция XiaoZhi

Настройка среды разработки ESP-IDF и компиляция XiaoZhi

В этом руководстве описано, как настроить среду ESP-IDF и собрать прошивку XiaoZhi. Примеры приведены для Windows; команды командной строки в Linux те же.

Требования к версии (из README xiaozhi-esp32, v2.5.x)

  • Минимальная версия — ESP-IDF v6.0.1, рекомендуется ветка release/v6.1.
  • ESP-IDF 5.x больше не поддерживается. С 5.x сборка завершается ошибкой на этапе разрешения зависимостей.
  • Используйте ветку release/v6.1 и избегайте релизного тега v6.1: для этого тега есть сообщения о сбое инициализации Wi-Fi на ESP32-C3, см. issue #2344.

Выбор среды разработки

  • Редактор: Cursor или VSCode с расширением ESP-IDF, версия SDK — v6.0.1 или новее.
  • ОС: проект рекомендует Linux (быстрее сборка, нет проблем с драйверами последовательного порта); Windows тоже подходит.
  • Стиль кода: проект использует стиль Google C++, перед отправкой кода см. руководство по стилю кода.

Установка ESP-IDF

1. Загрузка установщика

В Windows установщик ESP-IDF можно получить здесь:

Выберите v6.0.1 или новее. Чтобы использовать рекомендуемую ветку release/v6.1, получите её через Git:

git clone -b release/v6.1 --recursive https://github.com/espressif/esp-idf.git

2. Шаги установки

  1. Запустите загруженный установщик
  2. Примите лицензионное соглашение
  3. Выберите путь установки (избегайте диска C: и нелатинских символов в пути)
  4. Завершите работу мастера

3. Проверка установки

  1. Откройте ярлык ESP-IDF PowerShell, созданный установщиком (название немного зависит от выбранной версии)
  2. Терминал автоматически импортирует окружение IDF
  3. Убедитесь, что версия не ниже 6.0.1:
idf.py --version
  1. Соберите пример проекта:
cd examples/get-started/hello_world/
idf.py build

Сборка прошивки XiaoZhi

1. Получение исходного кода 

# Клонирование через Git (рекомендуется)
git clone https://github.com/78/xiaozhi-esp32

# Или загрузите ZIP-архив с GitHub

2. Настройка платы

  1. Задайте целевой чип:
# ESP32-S3
idf.py set-target esp32s3

# ESP32-C3
idf.py set-target esp32c3
  1. Выберите плату:
idf.py menuconfig
# Перейдите в Xiaozhi Assistant -> Target Board
Если в каталоге платы есть config.json, целевой чип и плату можно настроить одним шагом с помощью входящего в проект скрипта: python scripts/build.py <имя-каталога-платы>. Язык и слово пробуждения задаются параметрами --language и --wake-word; подробности — в руководстве по пользовательским платам.

3. Сборка и прошивка

Основные команды:

# Только сборка
idf.py build

# Сборка и прошивка
idf.py build flash monitor

# Более высокая скорость прошивки
idf.py -b 2000000 build flash monitor

# Указать последовательный порт
idf.py -p COM5 build flash monitor

4. Частые изменения конфигурации

Изменение слова пробуждения 

idf.py menuconfig
# Перейдите в ESP Speech Recognition -> Wake Word

Изменение WebSocket API 

idf.py menuconfig
# Перейдите в Xiaozhi Assistant -> Websocket -> Websocket URL

Обязательные шаги после смены версии ESP-IDF

После перехода с 5.x (или другой версии) на v6.0.1+ необходимо привести зависимости и кэш в соответствие с новым SDK:

# Обновите подмодули в каталоге ESP-IDF
cd <каталог esp-idf>
git submodule update --init --recursive

Затем заново загрузите export.sh из этого каталога (в Windows используйте соответствующее окружение ESP-IDF PowerShell), вернитесь в каталог проекта XiaoZhi и выполните:

idf.py fullclean
idf.py build

Частые проблемы

1. Ускорение компиляции

  • Отключите антивирус (включая Windows Defender)
  • Удалите папку build и выполните сборку заново

2. Проблемы с драйвером последовательного порта

Если последовательный порт не определяется, установите USB-драйвер для вашего чипа.

3. Конфликты I2C

Если возникает конфликт I2C:

  1. Выполните idf.py menuconfig
  2. Выберите Component config -> Audio Codec Device Configuration
  3. Отключите первый параметр
  4. Выполните сборку заново

4. Ошибка: project depends on idf (>=6.0.1)

Если вы видите ошибку вида:

ERROR: Because project depends on idf (>=6.0.1) which doesn't match any versions, version solving failed.

версия ESP-IDF в текущем окружении слишком старая (например, 5.x). Проект объявляет idf: '>=6.0.1' в main/idf_component.yml. Установите ESP-IDF v6.0.1 или новее (рекомендуется ветка release/v6.1), убедитесь, что терминал загрузил новое окружение, и повторите:

idf.py set-target esp32s3
idf.py build

5. Сбой инициализации Wi-Fi на ESP32-C3

Если вы используете релизный тег v6.1 и на ESP32-C3 не инициализируется Wi-Fi, перейдите на ветку release/v6.1, см. issue #2344.

6. Windows: слишком длинная командная строка

Если Ninja сообщает об ошибке CreateProcess (команда компилятора превышает лимит в 32 767 символов), выполните в том же каталоге проекта и в том же терминале ESP-IDF:

idf.py -D CMAKE_NINJA_FORCE_RESPONSE_FILE=ON reconfigure
idf.py build

После idf.py fullclean или очистки кэша CMake команду reconfigure нужно выполнить снова. Помочь может и перенос проекта в более короткий путь (например, E:\xz). См. обходной путь в issue #2340.

Примечания

  1. Не используйте нелатинские символы в пути к проекту
  2. При переносе проекта удаляйте папку build
  3. Убедитесь, что выбрана правильная модель чипа
  4. Регулярно очищайте каталог build, чтобы избежать проблем со сборкой

Дополнительные материалы

Протокол связи WebSocket