Центр документации XiaoZhi AI чат-бота | 小智AI.Dev
Руководство по использованию
Загрузка прошивки XiaoZhi AI

Загрузка прошивки XiaoZhi AI

Официальная прошивка XiaoZhi AI публикуется в GitHub Releases репозитория 78/xiaozhi-esp32. Если вы начинаете с нуля, прошейте готовый образ, не настраивая среду разработки.

Последний релиз: v2.5.2

v2.5.2 опубликован 2026-10-11. Всю матрицу релиза собирает GitHub Actions:

  • 188 вариантов прошивки для 154 каталогов плат;
  • сборка на ESP-IDF 6.1.0;
  • платформы: ESP32, ESP32-C3, ESP32-C5, ESP32-C6, ESP32-S3, ESP32-S31 и ESP32-P4.

Полный список изменений — на странице релиза v2.5.2.

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

Что входит в релиз

Каждый вариант — это архив v<версия>_<вариант>.zip, например v2.5.2_bread-compact-wifi.zip. Внутри один файл:

  • merged-binary.bin — полный образ флеш-памяти (загрузчик, таблица разделов и приложение); записывается целиком по адресу 0x0.

К релизу приложены ещё два файла:

  • SHA256SUMS — контрольные суммы SHA-256 всех архивов;
  • release-manifest.json — исходный коммит, версия ESP-IDF и полный список вариантов с указанием чипа.

Выбор варианта для вашей платы

Имя варианта состоит из производителя, платы и необязательных частей (экран, сеть, ревизия) и соответствует каталогу в main/boards/ исходного репозитория. В сборках на макетной плате ml307 — версия с 4G-модулем ML307, 128x64 — разрешение OLED, lcd — версия с LCD-экраном.

В таблице приведены распространённые платы. Полный список — во вложениях релиза и в release-manifest.json.

ПлатаЧипВариант
Макетная плата, новая схема (Wi-Fi)ESP32-S3bread-compact-wifi
Макетная плата, новая схема (Wi-Fi, OLED 128x64)ESP32-S3bread-compact-wifi-128x64
Макетная плата, новая схема (Wi-Fi, LCD)ESP32-S3bread-compact-wifi-lcd
Макетная плата, новая схема (ML307 4G)ESP32-S3bread-compact-ml307
Макетная плата, ESP32 DevKitESP32bread-compact-esp32
XiaGe Mini C3ESP32-C3xmini-c3, xmini-c3-v3, xmini-c3-4g
LCSC ESP32-S3ESP32-S3lckfb-lichuang-dev
LCSC ESP32-C3ESP32-C3lckfb-lichuang-c3-dev
M5Stack CoreS3ESP32-S3m5stack-core-s3
M5Stack AtomS3R + Echo BaseESP32-S3m5stack-atoms3r-echo-base
Espressif ESP-BOX-3ESP32-S3espressif-esp-box-3
Espressif ESP-BOX / ESP-BOX-LiteESP32-S3espressif-esp-box, espressif-esp-box-lite
Espressif ESP-SparkBotESP32-S3espressif-esp-sparkbot
Espressif ESP-VoCatESP32-S3espressif-esp-vocat
Magiclick 2.4 / 2.5ESP32-S3magiclick-2p4, magiclick-2p5
Magiclick C3 / C3 v2ESP32-C3magiclick-c3, magiclick-c3-v2
Kevin Box 2ESP32-S3kevin-box-2
Nologo Xingzhi 0.96 OLED (Wi-Fi)ESP32-S3nologo-xingzhi-cube-0.96oled-wifi
Nologo Xingzhi 1.54 TFT (Wi-Fi)ESP32-S3nologo-xingzhi-cube-1.54tft-wifi
Seeed Studio SenseCAP WatcherESP32-S3sensecap-watcher
DFRobot Unihiker K10ESP32-S3dfrobot-df-k10
LILYGO T-Circle-S3ESP32-S3lilygo-t-circle-s3
ALIENTEK DNESP32S3 / DNESP32S3-BOXESP32-S3alientek-atk-dnesp32s3, alientek-atk-dnesp32s3-box
Movecall MojiESP32-S3movecall-moji-esp32s3
Waveshare ESP32-S3-Touch-AMOLED-1.8ESP32-S3waveshare-esp32-s3-touch-amoled-1.8
Waveshare ESP32-S3-Touch-LCD-1.85ESP32-S3waveshare-esp32-s3-touch-lcd-1.85

Прошивка

Способ 1: без среды разработки

Следуйте руководству для начинающих по прошивке, которое ведёт исходный проект. Устанавливать ESP-IDF не нужно.

Способ 2: esptool в командной строке

  1. Скачайте со страницы релиза архив нужного варианта и распакуйте его — получите merged-binary.bin;
  2. Подключите плату кабелем с передачей данных и при необходимости переведите её в режим загрузки;
  3. Запишите образ по адресу 0x0:
# Install esptool (requires Python)
pip install esptool

# Write the merged image at 0x0 (replace the serial port with your own)
esptool.py -b 460800 write_flash -z 0x0 merged-binary.bin

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

Проверка загруженных файлов

Поместите архивы и SHA256SUMS в один каталог и проверьте скачанные файлы:

# Linux
sha256sum -c SHA256SUMS --ignore-missing

# macOS
shasum -a 256 -c SHA256SUMS --ignore-missing

Самостоятельная сборка

Если вашей платы нет в списке, нужно изменить конфигурацию или вы адаптируете собственное оборудование, соберите прошивку локально:

  • Настройка ESP-IDF: прошивке нужен ESP-IDF v6.0.1 или новее, рекомендуется ветка release/v6.1;
  • сборка и упаковка одной командой скриптом из исходного репозитория: python scripts/build.py <плата> --zip.

Сервер и учётная запись

Официальная прошивка по умолчанию подключается к официальному серверу. Личные пользователи могут зарегистрироваться и бесплатно использовать realtime-модель Qwen, а устройства настраиваются в официальной консоли (точка входа указана в README upstream). Для собственного сервера см. проекты сообщества из README исходного репозитория, например xinnan-tech/xiaozhi-esp32-server (Python).

Источник: 78/xiaozhi-esp32 GitHub Releases, README.md и docs/releasing.md исходного репозитория.

Руководство по сборке оборудования XiaoZhi AI