把一块 ESP32 变成会说话的 AI 伙伴：xiaozhi-esp32 完整上手指南
【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32
想让家里那块闲置的 ESP32-S3 开发板，变成一个能被语音唤醒、会显示表情、还能反过来帮你按灯的 AI 小助手？xiaozhi-esp32（小智 AI 聊天机器人）就是为这件事准备的开源固件。它把离线唤醒、语音识别、大模型对话、MCP 多设备控制这些能力全部塞进几块钱的芯片里，覆盖 ESP32 到 S3、P4 共六类芯片平台，适配 130 多种开发板。
先想清楚：你拿它想做什么
在动手前，先按使用场景挑一条主线，后面选型、接线、写代码都会更顺。
三种典型玩法
- 桌面聊天伙伴：用带屏幕的开发板（M5Stack CoreS3、ESP32-S3-BOX-3、LILYGO T-Circle-S3 等），日常闲聊、问答、讲冷笑话，屏幕上同步显示表情与歌词。
- 机器人 / 舵机控制：参考 main/boards/otto-robot/ 示例，让大模型通过 MCP 调用
self.otto.jump这类工具，让机器狗真的跳起来。 - 智能家居入口：把固件跑在带 4G 的板子上，用语音控制家里的灯和插座，通过云端 MCP 扩展到桌面操作、邮件查询等能力。
它是什么：给 ESP32 装上"大脑"和"手脚"
xiaozhi-esp32 的核心思路是把设备端做成"薄客户端"，把算力压力留给云端。
架构分两层：
- 感官层（设备本地）：麦克风拾音、离线唤醒词检测（ESP-SR，默认"你好小智"，可自定义）、Opus 编码上行；同时负责 TTS 下行解码、OLED/LCD 表情渲染、电池与按键管理。相关源码集中在 main/audio/。
- 决策层（云端）：ASR、LLM（Qwen / DeepSeek 等）、TTS 全部放在服务端，设备只做流式收发，延迟低、对芯片算力要求小。
两种传输通道可选：WebSocket（默认，低延迟全双工）与MQTT + UDP（音频走 UDP、指令走 MQTT，弱网更稳）。详细说明见 docs/websocket.md 与 docs/mqtt-udp.md。
一次对话如何走完：协议与数据流
从"你好小智"到回答出声
- 本地 AFE 唤醒词引擎在静音/闲聊中命中唤醒词，触发 main/audio/wake_words/ 下的回调。
- 设备与后台握手，
hello消息里声明能力，例如"features": { "mcp": true, ... }。 - 你说话 → Opus 流上行 → 云端 ASR → LLM 推理 → TTS → Opus 流下行 → 扬声器播放。
- 大模型想调用设备能力时，通过
tools/call发起请求，设备执行后返回结果。
MCP：给大模型配一把"万能遥控器"
MCP（Model Context Protocol）本质是 JSON-RPC 2.0 的一套约定：设备把自己能做的事包装成"工具"（Tool），大模型通过工具名加参数就能"隔空遥控"你的硬件。想控制灯、想摇舵机、想读电池，都用同一套消息格式。完整消息结构见 docs/mcp-protocol.md，实战示例见 docs/mcp-usage.md。
三条上手路径，选一条就能开工
按你手上有什么、想改多深，走对应路径。
路径一：官方固件，5 分钟通电
最简单：注册官方控制台账号，下载对应板子的官方固件直接刷入。默认连官方服务器，个人免费使用 Qwen 实时模型，适合只想体验、不想搭环境的读者。
路径二：面包板 DIY，理解每一根线
没有成品开发板？用 ESP32-S3 模组加 I2S 麦克风、I2S 扬声器，杜邦线直连即可。
接线与音频链路细节见 docs/v0/ 与 docs/v1/ 里的示例图，麦克风和扬声器都是 I2S 接口，插对方向就能出声。
路径三：从源码构建，改到满意为止
需要 ESP-IDF v6.0.2（主线推荐）加 C/C++ 工具链，Linux 下编译更快、驱动问题更少。
git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32 cd xiaozhi-esp32选目标芯片，然后一键编译烧录：
idf.py set-target esp32s3 idf.py build flash monitor板子选型在 main/boards/，每个目录一份config.json加若干.cc文件，menuconfig里切一下目标板即可。
进阶玩法：让机器人听懂你的指令
注册一个 MCP 工具
想让大模型说"让 Otto 跳两次"时它真的跳，只需在板级代码里加一段：
mcp_server.AddTool("self.otto.jump", "让机器人跳跃", PropertyList({ Property("steps", kPropertyTypeInteger, 1, 5), Property("period", kPropertyTypeInteger, 1000, 3000) }), [](const PropertyList& p) { Otto().Jump(p["steps"].value<int>(), p["period"].value<int>()); return true; });云端调用长这样：
{ "jsonrpc": "2.0", "method": "tools/call", "params": { "name": "self.otto.jump", "arguments": { "steps": 2, "period": 1500 } }, "id": 1 }实现入口在 main/mcp_server.cc，完整机器人示例在 main/boards/otto-robot/otto_robot.cc。
自定义唤醒词与表情
- 唤醒词：用 ESP-SR 训练工具重训任意短语，替换 main/assets/locales/ 下对应语种的提示音。
- 表情 / 背景：LVGL 图像转换脚本在 scripts/Image_Converter/，OGG 语音打包在 scripts/ogg_converter/，改完重新编译即可替换。
常见问题排查
| 现象 | 大概率原因 | 处理 |
|---|---|---|
| 唤醒不到 | 麦克风太远或背景太吵 | 靠近声源，先在安静环境验证 |
| 语音卡顿 | 网络抖动 | 切到 MQTT+UDP 通道，或改走有线 |
| 舵机 / 灯不响应 | 工具未注册或参数类型错 | 先用tools/list确认工具存在 |
| 编译失败 | ESP-IDF 版本不对 | 升级到 v6.0.2，参考 docs/esp-idf-6-migration.md |
调试音频用 scripts/audio_debug_server.py，能实时看到唤醒与 VAD 状态；排查蓝牙配网看 docs/blufi_zh.md。
MIT 协议开源，免费商用。项目仓库：
GitHub_Trending/xia/xiaozhi-esp32
如果你也做出了有意思的玩法，欢迎提 Issue 或 PR，把新板子、新工具、新教程贡献进来，一起把 ESP32 的语音生态做大。
【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
