Документация разработчика
Документация разработчика
🛠️ Документация разработчика
Добро пожаловать в раздел технической документации для разработчиков! Здесь вы найдете все необходимое для продвинутой работы с прошивкой XiaoZhi, создания собственных расширений и интеграции с внешними системами.
🎯 Для кого этот раздел
👨💻 Целевая аудитория
🔧 Embedded разработчики
- Опыт работы с ESP32/ESP-IDF
- Знание C/C++ программирования
- Понимание принципов IoT разработки
🌐 Backend разработчики
- Опыт создания API и веб-сервисов
- Знание протоколов WebSocket, MQTT
- Понимание AI/ML интеграции
🤖 AI/ML инженеры
- Опыт работы с языковыми моделями
- Знание API облачных AI сервисов
- Понимание edge computing
🏗️ Архитектура системы
Обзор компонентов
graph TB
subgraph "ESP32-S3 Firmware"
A[Audio Input/Output] --> B[Voice Processing]
B --> C[Command Router]
C --> D[Local Processing]
C --> E[Cloud AI Interface]
D --> F[Device Control]
E --> G[Response Generator]
end
subgraph "External Services"
H[ASR Services]
I[LLM APIs]
J[TTS Services]
K[IoT Platforms]
end
E --> H
E --> I
G --> J
F --> K
Ключевые модули
🎙️ Аудио подсистема
- Захват звука: I2S микрофон интерфейс
- Обработка: Фильтрация шума, нормализация
- Воспроизведение: I2S динамик/наушники
- Форматы: 16kHz PCM, 16-bit
🧠 AI интеграция
- Локальное пробуждение: Wake Word Engine
- Облачное ASR: Интеграция с внешними сервисами
- LLM интерфейс: RESTful API клиенты
- Кэширование: Локальное хранение часто используемых ответов
🌐 Сетевые протоколы
- Wi-Fi управление: Автоподключение, восстановление связи
- WebSocket сервер: Реальное время API
- MQTT клиент: IoT платформы интеграция
- HTTP клиент: RESTful API вызовы
🏠 Управление устройствами
- MCP протокол: Стандартизированное управление
- GPIO контроль: Прямое управление пинами
- I2C/SPI: Подключение датчиков и актуаторов
- PWM: Управление сервоприводами, LED
🔧 Среда разработки
Необходимые инструменты
ESP-IDF Framework
# Установка ESP-IDF v5.3+
git clone --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32s3
source export.shИнструменты сборки
- CMake: v3.16 или новее
- Python: v3.8+ с pip
- Git: для управления версиями
- VS Code: с расширением ESP-IDF
Структура проекта
xiaozhi-firmware/
├── main/ # Основной код приложения
│ ├── xiaozhi_main.c # Точка входа
│ ├── audio/ # Аудио подсистема
│ ├── ai/ # AI интеграция
│ ├── network/ # Сетевые модули
│ └── device/ # Управление устройствами
├── components/ # Переиспользуемые компоненты
│ ├── xiaozhi_core/ # Ядро системы
│ ├── voice_engine/ # Голосовой движок
│ └── mcp_client/ # MCP протокол клиент
├── examples/ # Примеры использования
├── docs/ # Техническая документация
└── tools/ # Утилиты разработки🚀 Быстрый старт разработки
1️⃣ Настройка проекта
# Клонирование репозитория
git clone https://github.com/xiaozhidev/xiaozhi-firmware.git
cd xiaozhi-firmware
# Настройка целевого устройства
idf.py set-target esp32s3
# Конфигурация проекта
idf.py menuconfig2️⃣ Базовая конфигурация
В idf.py menuconfig настройте:
- Component config > ESP32S3-Specific: Конфигурация процессора
- Component config > Wi-Fi: Настройки Wi-Fi
- Component config > Bluetooth: Bluetooth конфигурация
- XiaoZhi Configuration: Специфичные настройки
3️⃣ Сборка и прошивка
# Сборка проекта
idf.py build
# Прошивка устройства
idf.py -p /dev/ttyUSB0 flash
# Мониторинг логов
idf.py -p /dev/ttyUSB0 monitor🔌 API Интерфейсы
WebSocket API
Подключение
const ws = new WebSocket('ws://xiaozhi-device.local:8080/ws');
ws.onopen = function() {
console.log('Connected to XiaoZhi device');
};Отправка команд
const command = {
type: 'voice_command',
text: 'включи свет в спальне',
timestamp: Date.now()
};
ws.send(JSON.stringify(command));Обработка ответов
ws.onmessage = function(event) {
const response = JSON.parse(event.data);
switch(response.type) {
case 'device_status':
updateDeviceStatus(response.data);
break;
case 'ai_response':
displayAIResponse(response.text);
break;
}
};REST API
Статус устройства
GET /api/status{
"wifi": {
"connected": true,
"ssid": "home_network",
"signal_strength": -45
},
"audio": {
"microphone": "active",
"speaker": "ready"
},
"ai_services": {
"deepseek": "connected",
"speech_recognition": "ready"
}
}Настройка AI сервисов
POST /api/ai/config{
"provider": "deepseek",
"api_key": "sk-xxxxxxxxxxxxx",
"model": "deepseek-chat",
"temperature": 0.7
}MQTT интеграция
Топики подписки
xiaozhi/command- Входящие командыxiaozhi/config- Обновления конфигурацииhomeassistant/status- Статус Home Assistant
Топики публикации
xiaozhi/status- Статус устройстваxiaozhi/response- Ответы AIxiaozhi/logs- Логи системы
🧩 Расширения и плагины
Создание пользовательских компонентов
Структура компонента
components/my_sensor/
├── CMakeLists.txt
├── include/
│ └── my_sensor.h
└── my_sensor.cCMakeLists.txt
idf_component_register(
SRCS "my_sensor.c"
INCLUDE_DIRS "include"
REQUIRES "driver"
)Заголовочный файл
// include/my_sensor.h
#pragma once
#include "esp_err.h"
esp_err_t my_sensor_init(void);
float my_sensor_read_temperature(void);Реализация
// my_sensor.c
#include "my_sensor.h"
#include "driver/i2c.h"
esp_err_t my_sensor_init(void) {
// Инициализация датчика
return ESP_OK;
}
float my_sensor_read_temperature(void) {
// Чтение температуры
return 25.0;
}Интеграция с основной системой
// main/xiaozhi_main.c
#include "my_sensor.h"
void app_main(void) {
// Инициализация пользовательского датчика
my_sensor_init();
// Регистрация обработчика голосовых команд
xiaozhi_register_voice_handler("температура", handle_temperature_command);
}
void handle_temperature_command(const char* command) {
float temp = my_sensor_read_temperature();
char response[64];
snprintf(response, sizeof(response), "Температура %.1f градусов", temp);
xiaozhi_speak(response);
}🔍 Отладка и профилирование
Логирование
#include "esp_log.h"
static const char* TAG = "MY_COMPONENT";
ESP_LOGI(TAG, "Компонент инициализирован");
ESP_LOGW(TAG, "Предупреждение: низкий уровень батареи");
ESP_LOGE(TAG, "Ошибка: не удалось подключиться к сервису");Мониторинг производительности
#include "esp_timer.h"
uint64_t start_time = esp_timer_get_time();
// Выполнение операции
uint64_t end_time = esp_timer_get_time();
ESP_LOGI(TAG, "Операция заняла %lld мкс", end_time - start_time);Анализ памяти
#include "esp_heap_caps.h"
size_t free_heap = heap_caps_get_free_size(MALLOC_CAP_DEFAULT);
ESP_LOGI(TAG, "Свободная память: %d байт", free_heap);
// Проверка утечек памяти
heap_caps_check_integrity_all(true);📚 Дополнительные ресурсы
Документация ESP-IDF
Примеры проектов
Инструменты разработки
Для разработчиков: Присоединяйтесь к нашему сообществу разработчиков для обмена опытом, получения помощи и участия в развитии экосистемы XiaoZhi.
📧 Email: [email protected]
🐙 GitHub: https://github.com/xiaozhidev
💬 Discord: XiaoZhi Developers Community