小智 AI 聊天机器人 xiaozhi-esp32 固件教程让 ESP32-S3 机器人听懂话、会走路、能看路的完整指南【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32xiaozhi-esp32小智 AI 聊天机器人是一套跑在 ESP32 系列芯片上的语音助手固件你说话它用大模型回答并通过 MCP 协议直接控制设备本身——音量、灯光、电机、摄像头翻转全都能用一句往前走解决。它适合三类人手里有一块 ESP32-S3 开发板想接大模型的玩家、想理解语音 大模型 硬件控制这条链路怎么打通的开发者以及基于 ESP-SparkBot 这类带底盘、摄像头、屏幕的机器人硬件想快速落地的新手。全文以 ESP-SparkBot 为主例讲清从零上手到二次开发的路径。5 分钟跑起来ESP-SparkBot 固件构建与烧录最短路径第一次上手不建议直接搭开发环境官方提供了免开发环境的预编译固件默认接入 xiaozhi.me 服务器个人注册账号可免费使用实时语音模型。想自己编译最短路径如下安装 ESP-IDF。注意版本项目当前要求ESP-IDF v6.0.1 及以上推荐 v6.1不再支持 5.x。Linux 上编译更快也更省心。克隆源码git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32 cd xiaozhi-esp32确认工具链并列出所有可编译的板卡共 138 个板卡目录、171 个固件变体source /path/to/esp-idf/export.sh python3 scripts/build.py --list-boards编译 ESP-SparkBot 固件脚本会帮你选对芯片目标、分区表和资产python3 scripts/build.py espressif/esp-sparkbot --name esp-sparkbot烧录并打开串口日志idf.py -p /dev/ttyUSB0 flash monitor看到设备连上 Wi-Fi、注册成功说声唤醒词机器人开始对话这一步就算通了。项目采用 Google C 代码风格后面要改代码的话先养成格式化习惯。一次讲清核心机制MCP 协议是怎么让大模型遥控机器人的先解释名词MCPModel Context Protocol可以理解为给大模型发的遥控器说明书——设备把自己的功能包装成一个个工具Tool上报给后台大模型在对话中决定调用哪个工具设备端执行。整条链路是这样的你说话 → 离线唤醒 → Opus 编码 → WebSocket/MQTT 上传 → 后台 LLM 决策 → MCP tools/call 下发 → 设备执行前进/开灯/翻转摄像头→ 语音反馈关键在两点设备端注册工具。以 esp_sparkbot_board.cc 为例底盘控制就是一段AddTool注册mcp_server.AddTool(self.chassis.go_forward, 前进, PropertyList(), this - ReturnValue { SendUartMessage(x0.0 y1.0); // 通过 UART 发给底盘 return true; });调用走标准 JSON-RPC 2.0。后台发来的前进指令长这样设备收到后在回调里执行真实硬件动作{ jsonrpc: 2.0, method: tools/call, params: { name: self.chassis.go_forward, arguments: {} }, id: 2 }音频链路同样清晰麦克风采集 16 kHz PCM → 离线唤醒词检测基于 ESP-SR 的 WakeNet支持自定义唤醒词→ Opus 编码上传 → 云端 TTS 的 Opus 流解码回放进喇叭。有 AEC回声消除即设备说话时也能听见你的硬件还能做到实时全双工对话。更多细节可看 MCP 协议交互流程文档、MCP 用法说明、音频架构说明。硬件构成ESP-SparkBot 由哪些模块组成ESP-SparkBot 由乐鑫官方推出主体是 ESP32-S3外设通过 I2C、SPI、I2S、UART、DVP 五类总线挂接。各模块与规格如下引脚定义见 config.h模块规格总线与关键配置主控ESP32-S3双核 240MHz配 PSRAM音频ES8311 编解码 喇叭I2SMCLK 45 / BCLK 39 / WS 41 / DIN 40 / DOUT 4216kHz 采样显示240×240 ST7789 SPI 屏CS 44 / DC 43 / SCK 21 / MOSI 47背光 PWM 46摄像头OV2640240×24025fpsDVP 8bitXCLK 15 / PCLK 13构建时启用CONFIG_CAMERA_OV2640底盘双电机UART 协议控制UART1 115200TX 38 / RX 48按键BOOT 键GPIO0单击切换对话、启动时长按进配网音频引脚片段示意#define AUDIO_I2S_GPIO_MCLK GPIO_NUM_45 #define AUDIO_I2S_GPIO_BCLK GPIO_NUM_39 #define AUDIO_I2S_GPIO_DIN GPIO_NUM_40 // ... 完整 5 脚映射见 config.h注意一个硬件细节功放PA引脚和屏幕 IO 复用了所以代码里EnableOutput(false)时是有意为空的改引脚前先看 esp_sparkbot_board.cc 里的注释。典型玩法三个能直接照抄的场景1. 语音遥控机器人。唤醒后直接说往前走转个圈跳支舞。对应工具self.chassis.go_forward、turn_left、dance等跳舞还会同步把灯光切到演示模式mcp_server.AddTool(self.chassis.dance, 跳舞, PropertyList(), this - ReturnValue { SendUartMessage(d1); light_mode_ LIGHT_MODE_MAX; return true; });2. 灯光表达情绪。设备内置 9 种灯光模式充电呼吸、低电量告警、常亮、闪烁、快/慢呼吸、流光、演示、睡眠大模型可通过self.chassis.switch_light_mode带参数调用mcp_server.AddTool(self.chassis.switch_light_mode, 打开灯光效果, PropertyList({Property(light_mode, kPropertyTypeInteger, 1, 6)}), this - ToolResult { /* 拼 wN 命令发 UART */ });3. 摄像头当眼睛。说把摄像头镜像翻转一下即可切换画面方向self.camera.set_camera_flipped设置会写入 NVS 掉电保存配合后台的视觉能力MCPinitialize时上报 vision 地址还能让模型直接看摄像头图像。二次开发给自己的机器人加一个 MCP 工具加功能的最小路径就三步在板卡代码里注册工具 → 写执行逻辑 → 重新烧录。以带参数的 RGB 灯为例摘自 MCP 用法说明mcp_server.AddTool(self.light.set_rgb, 设置RGB颜色, PropertyList({ Property(r, kPropertyTypeInteger, 0, 255), Property(g, kPropertyTypeInteger, 0, 255), Property(b, kPropertyTypeInteger, 0, 255) }), this - ReturnValue { SetLedColor(p[r].valueint(), p[g].valueint(), p[b].valueint()); return true; });工具命名建议用模块.功能风格如self.dog.forwarddescription 写人话大模型靠它做决策。如果你要适配的是全新硬件需要按 自定义开发板指南 走完整链条config.json→scripts/build.py→Kconfig.projbuild→CMakeLists.txt→ 板卡源码必须恰好一个DECLARE_BOARD且不要动现有板卡的引脚来迁就新硬件——板卡身份影响 OTA 兼容性宁可新加一个变体。踩坑实录现象、原因与排查现象编译报版本不兼容 / 组件拉不下来。原因项目已放弃 ESP-IDF 5.x最低 v6.0.1。 排查idf.py --version确认版本旧 5.x 环境彻底换掉。现象切换板卡后编译失败或行为异常。原因构建脚本会改写本地sdkconfig和构建状态build 目录残留上一个目标。 排查换一个板卡前先idf.py fullclean再用python3 scripts/build.py board --name variant重新生成。现象说唤醒词没反应。排查顺序先确认唤醒词音频资源存在本地化缺失会回退英文见 main/assets/locales/再看 音频架构中的输入链路——AudioInputTask是否出数据、AFE 引擎是否初始化最后检查麦克风 I2S 引脚是否与 config.h 一致。现象屏幕不亮或显示花屏。排查检查 SPI 屏 4 根信号线 背光是否接对确认bits_per_pixel 16与invert_color配置和实际屏体一致本板 ST7789 需要颜色反转。现象摄像头画面左右/上下颠倒。原因部分复刻版摄像头是固定安装的。 排查说翻转摄像头即可切换该设置已持久化也可以改camera-flipped默认值。现象编译通过但烧录后没反应。排查确认烧录分区表与固件匹配partitions/ 下按容量分档串口 monitor 无输出时优先查 TX/RX 是否反接、波特率是否为 115200。性能调优几个有实际收益的旋钮优化项做法预期收益唤醒词录音上传项目已把最近 2 秒 PCM 放进 64KB PSRAM 环形缓冲Opus 逐帧读取不再临时拼接避免内部 SRAM 抖动减少丢帧队列内存音频队列用编译期固定容量存储不再动态扩容 deque消除音频路径上的堆分配尖峰摄像头帧缓冲帧缓存走外部 PSRAMCONFIG_CAMERA_OV2640_DVP_YUV422_240X240_25FPS240×24025fps 下省出大量内部 RAM音频功耗AudioPowerSaveTimer按活动启停 codec ADC/DAC 通道空闲电流明显下降睡眠策略结合 sleep_timer.cc 与背光调节进入浅睡桌面常驻场景续航更好显示SPI 屏 PCLK 40MHz 10 级传输队列刷新不占满主循环改音频路径时的通用纪律来自 AGENTS.md不在主事件循环和音频任务里阻塞、不养无界队列、回调里改状态要走Application::Schedule()。参与贡献与学习路线贡献方向按门槛从低到高给冷门板卡补文档和图片新增一块板卡照 custom-board_zh.md 走五步链条音频引擎和 AEC 调参看 main/audio/协议层改造改动 main/protocols/ 时要同时验证 WebSocket 和 MQTT/UDP 两条通路。社区入口是仓库 Issues 和官方 QQ 群群号见 README_zh.md。学习路线建议先烧通预编译固件 → 读懂一块最简板卡如 xmini c3→ 再啃 ESP-SparkBot 的 I2C/SPI/UART 三总线初始化 → 最后按 音频架构文档 走一遍数据流。项目以 MIT 许可证发布固件默认接入官方服务器也可自行部署第三方开源服务器对接同一套协议。小智把大模型从屏幕里拽到了桌面上剩下的——你的机器人长什么样、会什么技能——由你定义。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考