企业官网建设流程全解析

xiaozhi-esp32 ESP32语音AI助手使用指南：从固件烧录到MCP设备控制

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32

xiaozhi-esp32 是一个开源的 ESP32 语音 AI 聊天机器人：支持离线语音唤醒、Opus 实时语音对话，并通过 MCP 协议调用设备上的舵机、灯光、GPIO 等硬件能力。一块开发板就能变成能听会说、还能动手的 AI 终端。

xiaozhi-esp32 语音助手功能清单与支持的硬件

这个项目的核心是把大模型的对话能力和 ESP32 的本地硬件能力连起来。固件端主要做了这些事：

• 芯片覆盖广：支持 ESP32、ESP32-C3、ESP32-C5、ESP32-C6、ESP32-S3、ESP32-P4 六个平台
• 联网方式多：Wi-Fi、有线以太网、USB RNDIS，以及 ML307/NT26 等 Cat.1 4G 模块，部分硬件支持 Wi-Fi 与 4G 切换
• 离线语音唤醒：基于乐鑫 ESP-SR，支持自定义唤醒词
• 音频链路：Opus 流式传输，兼容"流式 ASR + LLM + TTS"传统管线和 Realtime 端到端语音模型；带 AEC 的硬件可做到实时全双工对话
• 声纹识别：识别当前说话人身份
• 显示与视觉：OLED/LCD 屏幕支持 emoji 表情动画，部分板卡支持摄像头输入
• MCP 双向能力：设备端 MCP 控制本地硬件（音量、灯光、电机、GPIO），云端 MCP 扩展智能家居、桌面操作、知识搜索等能力
• 配网：热点和 BluFi 两种方式
• 国际化：38 种界面语言，语音提示缺失时自动回退英文

仓库当前维护 138 个板卡目录、171 个固件发布变体，从乐鑫官方开发板到 M5Stack、微雪、LilyGO 等常见板卡都有对应配置。没有现成板卡也可以动手，官方给出了面包板手工接线方案：

两种烧录路径：免开发环境固件与源码编译

免环境烧录成品固件

第一次上手不建议直接搭开发环境。项目提供免开发环境烧录的固件，刷入后设备默认接入官方服务器，注册个人账号即可免费使用 Qwen 实时语音模型。这条路径适合验证功能和体验交互效果。

编译源码固件

需要改配置或做二次开发时，按下面的步骤来：

1. 准备 VSCode 或 Cursor，安装 ESP-IDF 插件。首选 v6.0.2，Linux 环境编译更快、驱动问题更少
2. 获取代码：git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32
3. 用构建脚本列出所有板卡并编译目标变体：

python3 scripts/build.py --list-boards python3 scripts/build.py <板卡目录名> --name <变体名>

WebSocket 与 MQTT+UDP 通信方式对比选型

固件端内置两种传输通道，编译和部署前可以先看清差异：

协议细节分别在 WebSocket 协议文档 和 MQTT+UDP 协议文档 中，两者都以 JSON 消息定义hello握手、会话参数和状态同步，接入自己的后台时照文档实现即可。

MCP 协议设备控制：在 ESP32 上注册硬件工具

这是项目最有特色的部分：设备作为 MCP 服务器，后台作为 MCP 客户端。连接建立后，设备在hello消息里声明"mcp": true，后台依次发送initialize、tools/list、tools/call（JSON-RPC 2.0 格式）来发现和调用设备上的工具。

设备端注册一个工具只需一次AddTool调用，比如让机器狗前进：

mcp_server.AddTool("self.dog.forward", "机器人向前移动", PropertyList(), this -> ReturnValue { servo_dog_ctrl_send(DOG_STATE_FORWARD, NULL); return true; });

工具名建议用"模块.功能"的层级命名（如self.dog.forward、self.light.set_rgb），description 用自然语言写清楚，大模型据此决定何时调用。参数支持布尔、整数、字符串类型，可声明范围和默认值。

完整流程（含摄像头能力声明、工具调用响应格式）见 MCP 协议交互文档 和 MCP 物联网控制用法，实现代码在 main/mcp_server.cc。

为自己的开发板添加 xiaozhi-esp32 支持

板卡初始化代码全部集中在 main/boards/ 下，每块板子一个目录，通常包含三个文件：

• config.h：引脚与硬件参数（I2S 音频、Codec 地址、按钮、屏幕）
• xxx_board.cc：板级初始化逻辑
• config.json：开发板类型标识与构建配置，供 CMake 和构建脚本使用

新板卡的做法是新建目录（命名建议"品牌-板卡类型"），参照现有板卡写这三个文件，再用python3 scripts/build.py <板卡目录名>编译验证。

有一个容易踩的坑：IO 配置不同时，不要直接覆盖已有板卡的配置文件。每块板有唯一的 OTA 升级通道，覆盖会导致你烧录的自定义固件将来被标准固件覆盖。正确做法是新增独立板卡类型。详细步骤见 自定义开发板指南。

编译与烧录常见问题：IDF 版本和自定义板卡注意点

• 用哪个 ESP-IDF 版本：主线基于 v6.0 及以上，首选 v6.0.2。v5.5.2 仅保留给文档标注的旧版板卡；ESP32-S31 变体需要 IDF 6.1 或更高。各变体的完整兼容矩阵见 ESP-IDF 6.0 迁移文档
• 烧录失败：先确认 USB 连接和串口驱动，必要时按住 BOOT 键手动进入下载模式再重新烧录
• 小内存芯片注意唤醒方案：C3/C5/C6 默认使用轻量唤醒引擎（Lite），S3/P4/S31 使用 AFE 引擎，资源紧张时优先保证唤醒灵敏度与内存的平衡
• 本地化语音资源：界面语言音频是 OGG 格式，仓库提供 scripts/ogg_converter/ 批量转换和响度调整工具，P3 私有格式的批量转换工具在 scripts/p3_tools/

下一步：文档与源码入口

• 核心固件代码：main/，音频链路在 main/audio/，协议实现在 main/protocols/
• 想接后台服务：先读 docs/websocket_zh.md 或 docs/mqtt-udp_zh.md，再按 docs/mcp-usage_zh.md 实现工具调用
• 想换硬件：从 docs/custom-board_zh.md 入手，在main/boards/下新建目录
• 想加自己的 MCP 工具：参考 main/mcp_server.cc 中AddTool的注册写法

MIT 协议开源，代码可直接用于商业场景。从刷一块现成固件开始，到注册自己的第一个 MCP 工具，整个过程不需要改动项目主干。

【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32