Руководство по разработке

Документация по разработке XiaoZhi AI

Эта документация предназначена для разработчиков, которые хотят сами собрать или изменить программу XiaoZhi AI. В ней описаны настройка среды разработки, основные протоколы связи и способы реализации расширенных функций.

Среда разработки

• Настройка среды ESP-IDF и компиляция XiaoZhi — требуется ESP-IDF v6.0.1 или новее
• Руководство по пользовательским платам — добавление своей платы, config.json и scripts/build.py
• Руководство по пользовательским Assets — сборка assets.bin: слово пробуждения, шрифты, эмодзи и фон чата
• Экосистема: серверы, клиенты и порты — серверы, клиенты и порты сообщества
• Руководство по настройке BluFi — настройка Wi-Fi через BLE
• Руководство по стилю кода — clang-format и правила C++ времени выполнения

Документация по протоколам связи

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

Подробное описание реализации связи WebSocket между устройством и сервером: установка соединения, формат сообщений, передача аудио и другие основные функции.

Гибридный протокол MQTT + UDP

Управляющий канал MQTT в сочетании с зашифрованным аудиоканалом UDP.

Протокол MCP

Поток MCP между устройством и бэкендом на основе JSON-RPC 2.0: обнаружение инструментов, вызовы инструментов и инструменты только для пользователя.

Использование MCP для управления IoT

Регистрация инструментов на стороне устройства, встроенные инструменты и типичные примеры вызовов.

Расширение Glyph Push для динамического текста

Сервер присылает растровые глифы, которых нет в шрифте устройства; WebSocket и MQTT/UDP используют один формат.

Асинхронные голосовые уведомления

Пока устройство простаивает, облако проигрывает одностороннее голосовое уведомление: потоковое аудио Ogg Opus с субтитрами по таймлайну.

Отображение эмоций Emoji

Как большие языковые модели выражают эмоциональные состояния с помощью Emoji, а также связанные форматы данных и инструкции по использованию.

Структура исходного кода проекта

Проект XiaoZhi AI состоит из следующих основных частей:

1. Прошивка: работает на чипах серии ESP32
2. Серверная часть: обрабатывает подключения устройств и передачу голоса
3. Веб-интерфейс: страница настройки сети и параметров

Подробная структура исходного кода и описание функций — в репозитории GitHub.

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

• Ошибки компиляции: обычно связаны с несовпадением версии ESP-IDF; используйте версию ESP-IDF, рекомендованную в документации
• Тайм-аут соединения: проверьте настройки сервера WebSocket и сетевое подключение
• Нехватка памяти: платы разработки ESP32-S3 производительнее и рекомендуются

Указатель документации