# xiaozhi-esp32-music
**Repository Path**: leeos/xiaozhi-esp32
## Basic Information
- **Project Name**: xiaozhi-esp32-music
- **Description**: Otto机器人基于小智AI的源码
- **Primary Language**: C++
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-10
- **Last Updated**: 2026-05-18
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 小智 AI 聊天机器人 - ESP32 固件
（[English](README.md) | 中文 | [日本語](README_ja.md)）
## 简介
👉 [人类：给 AI 装摄像头 vs AI：当场发现主人三天没洗头【bilibili】](https://www.bilibili.com/video/BV1bpjgzKEhd/)
👉 [手工打造你的 AI 女友，新手入门教程【bilibili】](https://www.bilibili.com/video/BV1XnmFYLEJN/)
小智 AI 聊天机器人是一个基于 ESP32 的语音交互设备，利用 Qwen / DeepSeek 等大模型的 AI 能力，通过 MCP 协议实现多端控制。
---
## 目录
- [功能特性](#功能特性)
- [硬件支持](#硬件支持)
- [目录结构](#目录结构)
- [各模块功能说明](#各模块功能说明)
- [音乐播放模块](#音乐播放模块)
- [动作控制系统](#动作控制系统)
- [开发环境搭建](#开发环境搭建)
- [编译固件](#编译固件)
- [烧录固件](#烧录固件)
- [分区表说明](#分区表说明)
- [开发者文档](#开发者文档)
- [大模型配置](#大模型配置)
- [相关开源项目](#相关开源项目)
- [关于项目](#关于项目)
---
## 功能特性
### 核心功能
- **Wi-Fi / 4G 网络**：支持 Wi-Fi 和 ML307 Cat.1 4G 模组
- **离线语音唤醒**：基于 [ESP-SR](https://github.com/espressif/esp-sr) 的离线唤醒词检测，支持音乐播放期间唤醒
- **双通信协议**：支持 [WebSocket](docs/websocket.md) 或 MQTT+UDP 协议
- **Opus 音频编解码**：低带宽高质量音频传输
- **流式语音交互**：基于流式 ASR + LLM + TTS 架构
- **声纹识别**：识别当前说话人身份 [3D Speaker](https://github.com/modelscope/3D-Speaker)
- **OLED/LCD 显示**：支持表情显示和状态信息
- **电池管理**：电量显示与电源管理
- **多语言支持**：中文、英文、日文等
### 芯片平台
- ESP32
- ESP32-C3
- ESP32-C5
- ESP32-C6
- ESP32-S3
- ESP32-P4
### 扩展功能
- **设备端 MCP**：控制音量、LED、舵机、GPIO 等
- **云端 MCP**：扩展大模型能力（智能家居、PC 控制、知识搜索、邮件等）
- **酷狗音乐播放**：通过酷狗音乐 API 搜索并在线流式播放音乐，支持 MP3 硬件解码，播放结束后自动恢复唤醒词检测
- **音乐与对话协调**：AI 说话期间自动排队等待音乐请求，说话完成后再播放音乐，避免网络带宽争抢
- **自定义资源**：支持自定义唤醒词、字体、表情、背景 ([自定义资源生成器](https://github.com/78/xiaozhi-assets-generator))
### 版本说明
- 当前 v2 版本与 v1 版本分区表不兼容，无法从 v1 通过 OTA 升级到 v2
- 分区表说明参见 [partitions/v2/README.md](partitions/v2/README.md)
- 使用 v1 版本的所有硬件，可以通过手动烧录固件升级到 v2
- v1 的稳定版本为 1.9.2，可通过 `git checkout v1` 切换
---
## 硬件支持
### 面包板 DIY
详见飞书文档教程：👉 [《小智 AI 聊天机器人百科全书》](https://ccnphfhqs21z.feishu.cn/wiki/F5krwD16viZoF0kKkvDcrZNYnhb)
### 支持 70+ 开源硬件（部分展示）
- [立创·实战派 ESP32-S3 开发板](https://oshwhub.com/li-chuang-kai-fa-ban/li-chuang-shi-zhan-pai-esp32-s3-kai-fa-ban)
- [乐鑫 ESP32-S3-BOX3](https://github.com/espressif/esp-box)
- [M5Stack CoreS3](https://docs.m5stack.com/zh_CN/core/CoreS3)
- [M5Stack AtomS3R + Echo Base](https://docs.m5stack.com/en/atom/Atomic%20Echo%20Base)
- [微雪电子 ESP32-S3-Touch-AMOLED-1.8](https://www.waveshare.net/shop/ESP32-S3-Touch-AMOLED-1.8.htm)
- [LILYGO T-Circle-S3](https://github.com/Xinyuan-LilyGO/T-Circle-S3)
- [SenseCAP Watcher](https://www.seeedstudio.com/SenseCAP-Watcher-W1-A-p-5979.html)
- [ESP-HI 超低成本机器狗](https://www.bilibili.com/video/BV1BHJtz6E2S/)
---
## 目录结构
```
xiaozhi-esp32/
├── CMakeLists.txt # 项目根级 CMake 构建配置
├── sdkconfig.defaults* # 多平台 SDK 默认配置
├── README*.md # 多语言文档
├── LICENSE # Apache 2.0 许可证
│
├── main/ # 主要源代码目录
│ ├── main.cc # 固件入口点
│ ├── application.h/cc # 核心应用类（状态机、事件处理）
│ ├── device_state.h # 设备状态枚举定义
│ ├── device_state_machine.* # 设备状态机实现
│ ├── ota.h/cc # OTA 远程升级模块
│ ├── settings.h/cc # NVS 配置存储管理
│ ├── system_info.h/cc # 系统信息获取
│ ├── mcp_server.h/cc # MCP 协议服务器
│ ├── assets.h/cc # 资源文件管理
│ │
│ ├── audio/ # 音频处理模块
│ │ ├── audio_service.h/cc # 音频服务（编解码、队列管理）
│ │ ├── audio_codec.h # 音频编解码器基类
│ │ ├── wake_word.h # 唤醒词检测基类
│ │ ├── audio_processor.h # 音频处理器基类
│ │ ├── codecs/ # 各种音频编解码器实现
│ │ │ ├── es8311_audio_codec.cc # ES8311 编解码器
│ │ │ ├── es8388_audio_codec.cc # ES8388 编解码器
│ │ │ └── ...
│ │ ├── wake_words/ # 唤醒词检测实现
│ │ │ ├── esp_wake_word.cc # ESP 原生唤醒词
│ │ │ ├── afe_wake_word.cc # AFE 唤醒词（支持中断词）
│ │ │ └── custom_wake_word.cc # 自定义唤醒词
│ │ ├── processors/ # 音频处理器实现
│ │ │ ├── afe_audio_processor.cc # AFE 处理器（VAD/AEC/NS）
│ │ │ └── audio_debugger.cc # 音频调试工具
│ │ └── demuxer/ # 音频解封装
│ │
│ ├── protocols/ # 通信协议实现
│ │ ├── protocol.h # 协议基类
│ │ ├── mqtt_protocol.h/cc # MQTT+UDP 混合协议
│ │ └── websocket_protocol.h/cc # WebSocket 协议
│ │
│ ├── boards/ # 硬件板卡支持
│ │ ├── common/ # 通用硬件抽象与音乐播放
│ │ │ ├── board.h # 板卡基类
│ │ │ ├── wifi_board.cc # WiFi 网络板卡
│ │ │ ├── ml307_board.cc # 4G 模组板卡
│ │ │ ├── button.cc # 按钮输入
│ │ │ ├── music.h # 音乐播放基类接口
│ │ │ ├── play_music.h/cc # 酷狗音乐播放实现（搜索、下载、流式解码）
│ │ │ ├── led/ # LED 控制
│ │ │ └── backlight.cc # 背光控制
│ │ └── / # 各板卡特定实现（otto-robot 等）
│ │
│ ├── display/ # 显示驱动
│ │ ├── display.h # 显示基类
│ │ ├── lcd_display.cc # LCD 显示驱动
│ │ ├── oled_display.cc # OLED 显示驱动
│ │ ├── emote_display.cc # 表情显示
│ │ └── lvgl_display/ # LVGL 图形库驱动
│ │
│ ├── CMakeLists.txt # 主 CMake 构建文件
│ └── Kconfig.projbuild # ESP-IDF 配置菜单
│
├── scripts/ # 工具脚本
│ ├── build_default_assets.py # 构建默认资源文件
│ ├── release.py # 发布打包脚本
│ ├── gen_lang.py # 多语言配置生成
│ ├── download_github_runs.py # 下载 GitHub Actions 产物
│ └── sonic_wifi_config.html # WiFi 配置网页
│
├── docs/ # 文档
│ ├── websocket.md # WebSocket 协议文档
│ ├── mqtt-udp.md # MQTT+UDP 协议文档
│ ├── mcp-protocol.md # MCP 协议文档
│ └── custom-board.md # 自定义开发板指南
│
├── partitions/ # 分区表配置
│ ├── v2/ # v2 版本分区表
│ └── v1/ # v1 版本分区表
│
└── assets/ # 资源文件目录
├── locales/ # 多语言资源
│ ├── zh-CN/ # 中文语音文件
│ ├── en-US/ # 英文语音文件
│ └── ja-JP/ # 日文语音文件
└── common/ # 通用音效文件
```
---
## 各模块功能说明
### 核心模块
| 文件 | 功能说明 |
|------|----------|
| `main.cc` | 固件入口点，初始化 NVS Flash，获取 Application 单例并启动 |
| `application.h/cc` | 核心应用类，管理设备状态机、音频服务、网络协议、音乐协调和事件处理循环 |
| `device_state.h` | 定义设备状态枚举（Unknown, Starting, Idle, Connecting, Listening, Speaking 等） |
| `device_state_machine.cc` | 设备状态机实现，管理状态转换和状态变更通知 |
| `ota.h/cc` | OTA 在线升级，检查版本、下载固件、设备激活 |
| `settings.h/cc` | NVS 配置存储封装，持久化保存 WiFi 配置等参数 |
| `system_info.h/cc` | 系统信息获取（Flash 大小、内存、MAC 地址等） |
| `mcp_server.h/cc` | MCP 协议服务器实现，支持 AI 工具调用注册与分发 |
### 音频模块 (audio/)
| 文件 | 功能说明 |
|------|----------|
| `audio_service.h/cc` | 音频服务核心，管理音频 I/O、编解码、队列 |
| `audio_codec.h` | 音频编解码器基类，定义音量、增益、输入输出接口，支持动态采样率切换 |
| `wake_word.h` | 唤醒词检测基类，支持 ESP-WakeWord、AFE-WakeWord、自定义唤醒词 |
| `audio_processor.h` | 音频处理器基类，包含 VAD、AEC、噪声抑制 |
| `codecs/es8311_audio_codec.cc` | ES8311 单声道编解码器驱动 |
| `codecs/es8388_audio_codec.cc` | ES8388 双声道编解码器驱动 |
| `wake_words/esp_wake_word.cc` | ESP 原厂唤醒词（WakeNet）实现 |
| `wake_words/afe_wake_word.cc` | AFE 音频前端唤醒词（支持中断词） |
| `processors/afe_audio_processor.cc` | AFE 音频处理（VAD + AEC + 噪声抑制） |
### 通信协议 (protocols/)
| 文件 | 功能说明 |
|------|----------|
| `protocol.h` | 协议基类，定义音频/JSON 回调、通道管理接口 |
| `mqtt_protocol.h/cc` | MQTT+UDP 混合协议，MQTT 控制命令 + UDP 低延迟音频 |
| `websocket_protocol.h/cc` | WebSocket 实时通信协议 |
### 硬件抽象 (boards/)
| 文件 | 功能说明 |
|------|----------|
| `common/board.h` | 板卡基类，定义获取编解码器、显示器、网络、音乐播放器的接口 |
| `common/wifi_board.cc` | WiFi 网络板卡实现 |
| `common/ml307_board.cc` | 4G 模组板卡实现 |
| `common/button.cc` | 按钮输入驱动 |
| `common/backlight.cc` | 屏幕背光控制 |
| `common/adc_battery_monitor.cc` | ADC 电池电量监测 |
### 显示驱动 (display/)
| 文件 | 功能说明 |
|------|----------|
| `display.h` | 显示基类，定义状态显示、通知、表情、聊天消息接口 |
| `lcd_display.cc` | LCD 液晶显示器驱动 |
| `oled_display.cc` | OLED 有机发光显示器驱动 |
| `emote_display.cc` | AI 表情动画显示 |
| `lvgl_display/` | LVGL 图形库显示驱动，支持复杂 UI |
### 音乐播放模块 (boards/common/)
| 文件 | 功能说明 |
|------|----------|
| `music.h` | 音乐播放基类接口，定义搜索、播放、停止、状态查询等虚函数 |
| `play_music.h` | PlayMusic 类声明，MP3 解码、流式缓冲、歌词解析、等待队列管理 |
| `play_music.cc` | PlayMusic 实现，酷狗音乐 API 对接、音频流式下载、MP3 硬件解码、I2S 输出 |
#### MCP 音乐工具
| 工具名称 | 参数 | 说明 |
|----------|------|------|
| `self.music.search_play_music` | `msg` (string) - 搜索关键词 | 搜索歌曲并返回结果，用户选择后自动播放 |
| `self.kugou.search_music` | `msg` (string) | 搜索歌曲，返回搜索结果列表 |
| `self.kugou.play_music` | `msg` (string), `n` (int) | 播放指定序号的歌曲 |
#### 音乐播放架构
```
┌──────────────┐ MCP协议 ┌──────────────┐
│ AI 大模型 │ ──────────→ │ mcp_server │
│ (Qwen/DeepSeek)│ │ (工具注册/分发)│
└──────────────┘ └──────┬───────┘
│
▼
┌──────────────┐
│ PlayMusic │
│ (音乐控制) │
└──────┬───────┘
│
┌────────────────┼────────────────┐
▼ ▼ ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ 搜索线程 │ │ 下载线程 │ │ 播放线程 │
│ (API请求) │ │ (HTTP流) │ │ (MP3解码) │
└──────────┘ └────┬─────┘ └────┬─────┘
│ │
▼ ▼
┌──────────┐ ┌──────────┐
│ 音频缓冲区 │ │ AudioCodec│
│ (PSRAM) │ │ (I2S输出) │
└──────────┘ └──────────┘
```
#### 音乐播放特性
- **流式播放**：边下载边播放，无需等待整首歌下载完成
- **MP3 硬件解码**：基于 [esp-libhelix-mp3](https://github.com/chmorgan/esp-libhelix-mp3) 解码器，低 CPU 占用
- **动态采样率切换**：自动检测音频采样率（8k/11k/12k/16k/22k/24k/32k/44.1k/48k Hz）并切换 I2S 时钟
- **自适应缓冲**：最小 64KB / 最大 512KB 自适应缓冲，防止卡顿
- **电源管理协调**：播放期间持续更新输出时间戳，防止 AudioService 自动关闭 I2S 输出
- **状态联动**：设备进入监听/说话状态时自动停止音乐播放
- **智能排队**：AI 正在说话时，音乐请求自动排队等待，说话完成后自动开始播放，避免网络带宽争抢
- **唤醒词保持**：音乐播放结束后设备保持 Idle 状态，确保唤醒词检测可继续工作
#### 音乐与对话协调流程
```
用户点歌 → AI 正在说话？
│
┌──────┴──────┐
▼ ▼
否 (空闲) 是 (说话中)
│ │
▼ ▼
立即播放音乐 加入等待队列
│ │
│ AI 说完话
│ │
│ ▼
│ 自动开始播放
│ │
└──────┬───────┘
▼
音乐播放中
│
┌─────────┼─────────┐
▼ ▼ ▼
播放结束 用户唤醒 手动停止
│ │ │
▼ ▼ ▼
保持Idle 停止音乐 停止音乐
可再次唤醒 进入对话 进入Idle
```
### 动作控制系统
| 文件 | 功能说明 |
|------|----------|
| `movements.h` | Otto 动作控制类头文件，定义舵机索引和动作函数接口 |
| `movements.cc` | Otto 动作控制实现，包括手部、身体、头部动作 |
| `electron_bot_controller.cc` | Electron Bot 控制器，管理 MCP 工具注册和动作队列 |
| `oscillator.h` | 舵机振荡器控制类，用于平滑运动和周期性摆动 |
---
## 动作系统开发指南
### 系统架构
```
┌─────────────────────────────────────────────────────────────────┐
│ MCP 服务器 (mcp_server) │
│ 接收服务器端命令，注册并暴露工具给 AI 调用 │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ ElectronBotController │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ 动作队列 (FreeRTOS Queue) - 异步执行，不阻塞主任务 │ │
│ └──────────────────────────────────────────────────────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ ActionTask 后台任务 - 持续监听队列并执行动作 │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Otto 类 │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
│ │ HandAction │ │ BodyAction │ │ HeadAction │ │ Home │ │
│ └────────────┘ └────────────┘ └────────────┘ └──────────┘ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Oscillator[] - 6个舵机振荡器 (PWM 控制) │ │
│ │ RIGHT_PITCH | RIGHT_ROLL | LEFT_PITCH | LEFT_ROLL │ │
│ │ BODY | HEAD │ │
│ └──────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### 硬件结构
```
┌─────────────┐
│ HEAD │ ← 头部舵机 (上下摆动)
└──────┬──────┘
│
┌────────────────┼────────────────┐
│ │ │
┌───┴───┐ ┌─────┴─────┐ ┌────┴────┐
│RIGHT │ │ BODY │ │ LEFT │
│ARM │ │ 身体舵机 │ │ ARM │
│右臂 │ │ (左右转向) │ │ 左臂 │
└───┬───┘ └─────┬─────┘ └───┬────┘
│ │ │
┌───┴───┐ │ ┌───┴───┐
│PITCH │ │ │PITCH │
│旋转 │ │ │旋转 │
└───┬───┘ │ └───┬───┘
│ │ │
┌───┴───┐ │ ┌───┴───┐
│ ROLL │ │ │ ROLL │
│推拉 │ │ │推拉 │
└───────┘ │ └───────┘
```
### 舵机配置
| 索引 | 名称 | 引脚定义 | 初始位置 | 说明 |
|------|------|----------|----------|------|
| 0 | RIGHT_PITCH | Right_Pitch_Pin | 180° | 右臂旋转（前后摆动） |
| 1 | RIGHT_ROLL | Right_Roll_Pin | 180° | 右臂推拉（上下运动） |
| 2 | LEFT_PITCH | Left_Pitch_Pin | 0° | 左臂旋转（前后摆动） |
| 3 | LEFT_ROLL | Left_Roll_Pin | 0° | 左臂推拉（上下运动） |
| 4 | BODY | Body_Pin | 90° | 身体旋转（左右转向） |
| 5 | HEAD | Head_Pin | 90° | 头部（上下摆动） |
### 动作类型枚举
```cpp
enum ActionType {
// 手部动作 1-12
ACTION_HAND_LEFT_UP = 1, // 举左手
ACTION_HAND_RIGHT_UP = 2, // 举右手
ACTION_HAND_BOTH_UP = 3, // 举双手
ACTION_HAND_LEFT_DOWN = 4, // 放左手
ACTION_HAND_RIGHT_DOWN = 5, // 放右手
ACTION_HAND_BOTH_DOWN = 6, // 放双手
ACTION_HAND_LEFT_WAVE = 7, // 挥左手
ACTION_HAND_RIGHT_WAVE = 8, // 挥右手
ACTION_HAND_BOTH_WAVE = 9, // 挥双手
ACTION_HAND_LEFT_FLAP = 10, // 拍打左手
ACTION_HAND_RIGHT_FLAP = 11, // 拍打右手
ACTION_HAND_BOTH_FLAP = 12, // 拍打双手
// 身体动作 13-15
ACTION_BODY_TURN_LEFT = 13, // 左转
ACTION_BODY_TURN_RIGHT = 14, // 右转
ACTION_BODY_TURN_CENTER = 15, // 回中心
// 头部动作 16-20
ACTION_HEAD_UP = 16, // 抬头
ACTION_HEAD_DOWN = 17, // 低头
ACTION_HEAD_NOD_ONCE = 18, // 点头一次
ACTION_HEAD_CENTER = 19, // 回中心
ACTION_HEAD_NOD_REPEAT = 20, // 连续点头
// 系统动作 21
ACTION_HOME = 21 // 复位到初始位置
};
```
### MCP 工具接口
| 工具名称 | 参数 | 说明 |
|----------|------|------|
| `self.electron.hand_action` | action(1-4), hand(1-3), steps, speed, amount | 手部动作控制 |
| `self.electron.body_turn` | direction(1-3), steps, speed, angle | 身体转向控制 |
| `self.electron.head_move` | action(1-5), steps, speed, angle | 头部运动控制 |
| `self.electron.stop` | 无 | 停止所有动作 |
| `self.electron.get_status` | 无 | 获取状态 (moving/idle) |
| `self.electron.set_trim` | servo_type, trim_value | 校准舵机 |
| `self.electron.get_trims` | 无 | 获取校准值 |
| `self.battery.get_level` | 无 | 获取电池电量 |
### 新增动作开发
#### 方式一：新增机械动作
**步骤1**: 在 `movements.h` 中添加方法声明
```cpp
// 在 Otto 类中添加新方法声明
void CustomAction(int times, int amount, int period);
```
**步骤2**: 在 `movements.cc` 中实现
```cpp
void Otto::CustomAction(int times, int amount, int period) {
// 获取当前位置
int current_positions[SERVO_COUNT];
for (int i = 0; i < SERVO_COUNT; i++) {
if (servo_pins_[i] != -1) {
current_positions[i] = servo_[i].GetPosition();
} else {
current_positions[i] = servo_initial_[i];
}
}
// 自定义动作逻辑（例如：右转30度）
current_positions[BODY] = 90 + amount;
MoveServos(period, current_positions);
}
```
**步骤3**: 在 `electron_bot_controller.cc` 中添加动作处理
```cpp
// 在 ActionTask 的 switch 中添加
} else if (params.action_type == ACTION_CUSTOM) {
controller->electron_bot_.CustomAction(params.steps, params.amount, params.speed);
}
```
**步骤4**: 注册 MCP 工具
```cpp
mcp_server.AddTool(
"self.electron.custom_action",
"自定义动作描述",
PropertyList({
Property("steps", kPropertyTypeInteger, 1, 1, 10),
Property("amount", kPropertyTypeInteger, 30, 10, 50)
}),
[this](const PropertyList& props) -> ReturnValue {
int steps = props["steps"].value();
int amount = props["amount"].value();
QueueAction(ACTION_CUSTOM, steps, 1000, 0, amount);
return true;
});
```
#### 方式二：新增表情动画
在 `emote_display.cc` 中调用表情接口：
```cpp
// 支持的表情类型
display->SetEmotion("happy"); // 开心
display->SetEmotion("sad"); // 伤心
display->SetEmotion("angry"); // 生气
display->SetEmotion("surprised"); // 惊讶
display->SetEmotion("neutral"); // 中性
// 或发送显示事件
emote_set_event_msg(emote_handle_, EMOTE_MGR_EVT_LISTEN, NULL); // 监听中
emote_set_event_msg(emote_handle_, EMOTE_MGR_EVT_SPEAK, NULL); // 说话中
emote_set_event_msg(emote_handle_, EMOTE_MGR_EVT_IDLE, NULL); // 空闲
```
#### 方式三：服务器端触发
服务器端通过 MCP 协议调用已注册的工具：
```json
{
"tool": "self.electron.hand_action",
"params": {
"action": 3,
"hand": 3,
"steps": 2,
"speed": 1000,
"amount": 30
}
}
```
### 开发注意事项
1. **异步执行**: 所有动作通过 FreeRTOS 队列异步执行，不会阻塞主任务
2. **舵机限制**: 动作角度范围 0-180°，需注意参数边界检查
3. **任务优先级**: ActionTask 使用 `configMAX_PRIORITIES - 1`，确保及时响应
4. **队列容量**: 默认队列容量为 10，可根据需要调整
5. **NVS 存储**: 舵机校准值存储在 NVS 中，重启后保持
---
## 开发环境搭建
### 系统要求
- **推荐系统**：Linux（编译速度快，无驱动问题）
- **可选系统**：Windows、macOS（需要安装驱动）
### 工具链
1. **安装 ESP-IDF**
```bash
# 克隆 ESP-IDF（需要 5.4 或更高版本）
git clone -b v5.4 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh
source ./export.sh
```
2. **安装代码编辑器插件（推荐）**
- VSCode: 安装 "Espressif IDF" 插件
- Cursor: 安装 "Espressif IDF" 插件
### 代码规范
- 本项目使用 **Google C++ 代码风格**
- 提交代码前请确保符合规范
---
## 编译固件
### 方法一：命令行编译
```bash
# 1. 进入项目目录
cd xiaozhi-esp32
# 2. 设置 ESP-IDF 环境
source $IDF_PATH/export.sh
# 3. 配置项目（选择开发板类型）
idf.py set-target esp32s3 # 设置目标芯片
idf.py menuconfig # 打开配置菜单
# 4. 编译固件
idf.py build
```
### 方法二：VSCode/Cursor 插件
1. 按 `F1` 或 `Ctrl+Shift+P`
2. 选择 "ESP-IDF: Configure Project"
3. 选择开发板类型
4. 点击 "Build" 编译
### menuconfig 关键配置
```
CONFIG_BOARD_TYPE_XXX # 选择开发板类型
CONFIG_LANGUAGE_ZH_CN # 界面语言（中文）
CONFIG_WIFI_SSID # WiFi SSID
CONFIG_WIFI_PASSWORD # WiFi 密码
CONFIG_XIAOZHI_SERVER_URL # 小智服务器地址
```
---
## 烧录固件
### 1. 连接设备
使用 USB 数据线连接 ESP32 开发板到电脑。
### 2. 查看串口端口
**Linux/macOS:**
```bash
ls -l /dev/ttyUSB* # Linux
ls -l /dev/tty.usb* # macOS
```
**Windows:**
打开设备管理器，查看 "USB Serial Port"。
### 3. 烧录命令
```bash
# 烧录固件（自动检测端口）
idf.py -p /dev/ttyUSB0 flash
# 或指定端口和波特率
idf.py -p /dev/ttyUSB0 -b 921600 flash
```
### 4. 查看日志
```bash
idf.py -p /dev/ttyUSB0 monitor
```
按 `Ctrl+]` 退出日志查看。
### 5. 合并固件烧录（可选）
首次烧录需要烧录分区表：
```bash
idf.py -p /dev/ttyUSB0 flash monitor
idf.py partition_table
```
### 6. 常见问题
| 问题 | 解决方案 |
|------|----------|
| 找不到串口 | 检查 USB 驱动是否安装，尝试更换 USB 线 |
| 烧录失败 | 按住 BOOT 键再按 RESET 键进入下载模式 |
| 波特率低 | 使用更高波特率如 921600 加速烧录 |
---
## 分区表说明
### v2 分区表
- **bootloader**: 1MB
- **coredump**: 64KB
- **partition table**: 8KB
- **ota_0**: 2.5MB（应用固件）
- **ota_1**: 2.5MB（OTA 升级分区）
- **spiffs**: 2MB（文件系统）
- **assets**: 自定义大小（资源文件）
### v1 分区表
- **bootloader**: 24KB
- **partitions**: 3KB
- **ota_0**: 1.4MB
- **ota_1**: 1.4MB
- **nvs**: 20KB
- **spiffs**: 1MB
- **font**: 512KB
- **vadfeat**: 384KB
> **注意**：v1 和 v2 分区表不兼容，无法直接 OTA 升级。
---
## 开发者文档
### 自定义开发板
👉 [自定义开发板指南](docs/custom-board.md) - 学习如何为小智 AI 创建自定义开发板
### MCP 协议
- 👉 [MCP 协议物联网控制用法说明](docs/mcp-usage.md) - 通过 MCP 协议控制物联网设备
- 👉 [MCP 协议交互流程](docs/mcp-protocol.md) - 设备端 MCP 协议实现方式
### 通信协议
- 👉 [MQTT + UDP 混合通信协议文档](docs/mqtt-udp.md)
- 👉 [WebSocket 通信协议文档](docs/websocket.md)
---
## 大模型配置
如果你已经拥有小智 AI 设备并已接入官方服务器，可以登录 [xiaozhi.me](https://xiaozhi.me) 控制台进行配置。
👉 [后台操作视频教程（旧版界面）](https://www.bilibili.com/video/BV1jUCUY2EKM/)
---
## 相关开源项目
### 服务端部署
在个人电脑上部署服务器：
- [xinnan-tech/xiaozhi-esp32-server](https://github.com/xinnan-tech/xiaozhi-esp32-server) - Python 服务器
- [joey-zhou/xiaozhi-esp32-server-java](https://github.com/joey-zhou/xiaozhi-esp32-server-java) - Java 服务器
- [AnimeAIChat/xiaozhi-server-go](https://github.com/AnimeAIChat/xiaozhi-server-go) - Golang 服务器
- [hackers365/xiaozhi-esp32-server-golang](https://github.com/hackers365/xiaozhi-esp32-server-golang) - Golang 服务器
### 第三方客户端
- [huangjunsen0406/py-xiaozhi](https://github.com/huangjunsen0406/py-xiaozhi) - Python 客户端
- [TOM88812/xiaozhi-android-client](https://github.com/TOM88812/xiaozhi-android-client) - Android 客户端
- [100askTeam/xiaozhi-linux](http://github.com/100askTeam/xiaozhi-linux) - Linux 客户端
- [78/xiaozhi-sf32](https://github.com/78/xiaozhi-sf32) - 思澈科技蓝牙芯片固件
- [QuecPython/solution-xiaozhiAI](https://github.com/QuecPython/solution-xiaozhiAI) - 移远 QuecPython 固件
### 资源工具
- [78/xiaozhi-assets-generator](https://github.com/78/xiaozhi-assets-generator) - 自定义资源生成器（唤醒词、字体、表情、背景）
---
## 关于项目
这是一个由虾哥开源的 ESP32 项目，以 MIT 许可证发布，允许任何人免费使用，修改或用于商业用途。
我们希望通过这个项目，能够帮助大家了解 AI 硬件开发，将当下飞速发展的大语言模型应用到实际的硬件设备中。
如果你有任何想法或建议，请随时提出 Issues 或加入 [Discord](https://discord.gg/bXqgAfRm) 或 QQ 群：1011329060
---
## Star History
