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

xiaozhi-esp32 ESP32语音AI助手使用指南从固件烧录到MCP设备控制【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32xiaozhi-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 实时语音模型。这条路径适合验证功能和体验交互效果。编译源码固件需要改配置或做二次开发时按下面的步骤来准备 VSCode 或 Cursor安装 ESP-IDF 插件。首选 v6.0.2Linux 环境编译更快、驱动问题更少获取代码git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32用构建脚本列出所有板卡并编译目标变体python3 scripts/build.py --list-boards python3 scripts/build.py 板卡目录名 --name 变体名WebSocket 与 MQTTUDP 通信方式对比选型固件端内置两种传输通道编译和部署前可以先看清差异对比项WebSocketMQTT UDP控制消息与音频走同一连接由 MQTT 通道承载支持断线自动重连音频传输同一 WebSocket 通道独立 UDP 通道AES-CTR 加密带序列号防重放乱序适用场景部署简单、链路稳定的环境控制与数据分离、对实时性和可靠性要求更高的环境协议细节分别在 WebSocket 协议文档 和 MQTTUDP 协议文档 中两者都以 JSON 消息定义hello握手、会话参数和状态同步接入自己的后台时照文档实现即可。MCP 协议设备控制在 ESP32 上注册硬件工具这是项目最有特色的部分设备作为 MCP 服务器后台作为 MCP 客户端。连接建立后设备在hello消息里声明mcp: true后台依次发送initialize、tools/list、tools/callJSON-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_rgbdescription 用自然语言写清楚大模型据此决定何时调用。参数支持布尔、整数、字符串类型可声明范围和默认值。完整流程含摄像头能力声明、工具调用响应格式见 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 默认使用轻量唤醒引擎LiteS3/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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考