xiaozhi-esp32 完整指南：用 ESP-SparkBot 把 ESP32 变成能听会动的 AI 机器人

xiaozhi-esp32 完整指南：用 ESP-SparkBot 把 ESP32 变成能听会动的 AI 机器人

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

xiaozhi-esp32（小智 AI 聊天机器人）给一块 ESP32 开发板装上"耳朵"和"嘴"，让它用自然语音接住大模型，并通过 MCP（让大模型直接调用设备能力的协议）操控底盘、灯光和摄像头。本文以官方 ESP-SparkBot 为例，走完从硬件准备、固件烧录到自研工具的完整流程，你读完就能让机器人听懂指令并完成一次实体动作。

xiaozhi-esp32 项目概览：一个固件，171 种硬件形态

小智 AI 聊天机器人的定位很直接：一个语音交互入口。它把 Qwen / DeepSeek 等大模型的能力接到硬件上，设备端通过 MCP 协议暴露自己的"工具"（音量、灯光、电机、GPIO），云端 MCP 还能反向扩展能力（智能家居、知识搜索、邮件收发等）。

核心能力速览：

• 语音唤醒基于 ESP-SR，支持自定义唤醒词；Opus 音频流，具备 AEC（回声消除）的硬件可做到实时全双工
• 通信支持两种传输：WebSocket 与 MQTT + UDP（混合通信），协议细节见 websocket_zh.md、mqtt-udp_zh.md
• OLED / LCD 屏显示表情与情绪，部分硬件带摄像头视觉输入
• 支持 Wi-Fi、以太网、USB RNDIS 与 Cat.1 4G 网络；热点和 BluFi 两种配网方式
• 已适配 138 个板卡目录、171 个固件变体，覆盖 ESP32、C3、C5、C6、S3、P4 平台，界面提供 38 种语言

硬件准备：ESP-SparkBot 有哪些零件

ESP-SparkBot 由乐鑫官方提供板级适配（代码位于 main/boards/espressif/esp-sparkbot/），硬件由两部分组成：

• ESP32-S3 主控板：搭载 ES8311 音频编解码芯片（16kHz 采样）、OV2640 摄像头（240×240 @ 25FPS）、240×240 SPI 屏（ST7789 驱动）
• 履带底盘：自带双直流电机与灯光，通过 UART1 与主控通信，波特率 115200

板级代码里，主控启动时先初始化 I2C、SPI、屏幕、按键和摄像头，再打通串口、注册 MCP 工具，顺序都写在 esp_sparkbot_board.cc 里，读一遍这个文件就理解了整机的装配逻辑。引脚映射单独放在 config.h，音频、显示、摄像头、串口四组管脚一目了然。

三步烧录固件：免开发环境也能跑

第一次上手，官方建议先不搭开发环境，直接烧录预编译固件：

1. 到固件发布区下载对应板型的固件，默认接入官方服务器，注册账号即可免费使用 Qwen 实时模型
2. 按住开发板 BOOT 键（ESP-SparkBot 为 GPIO0）插入 USB，进入下载模式
3. 用烧录工具把固件写入开发板，上电后对着麦克风说唤醒词，验证语音问答是否通

烧通之后，你手上就有一个能对话、会做表情的 AI 设备；如果它带底盘，还能被指挥移动。

核心能力拆解：MCP 协议怎么让机器人听指令

MCP（Model Context Protocol，让大模型调用设备能力的协议）是小智控制设备的主通道，底层走 JSON-RPC 2.0，完整流程见 mcp-protocol_zh.md。

交互流程：四次握手就开工

1. 设备与后台建立连接（WebSocket 或 MQTT）
2. 设备在 hello 消息里通告mcp: true，后台发起initialize初始化会话
3. 后台用tools/list拉取设备支持的全部工具及参数说明
4. 后台用tools/call点名调用某个工具，设备执行并返回结果

工具注册：一段回调，设备能力即插即用

设备端只需调用McpServer::AddTool注册"工具"，大模型看到的就是一个带描述、带参数的函数：

mcp_server.AddTool("self.chassis.go_forward", "前进", PropertyList(), this -> ReturnValue { SendUartMessage("x0.0 y1.0"); return true; });

命名建议"模块.功能"风格（如self.light.set_rgb），description 写成人话，方便大模型理解何时该调用。

ESP-SparkBot 内置工具：一句话指挥底盘

ESP-SparkBot 通过串口向底盘发短指令，已注册的工具包括：

• self.chassis.go_forward/go_back/turn_left/turn_right：对应发送x0.0 y1.0等速度向量
• self.chassis.dance：发d1让机器人跳舞，同时点亮灯光
• self.chassis.switch_light_mode：带 1–6 参数，切换 9 种灯光效果（呼吸、闪烁、流光等）
• self.camera.set_camera_flipped：翻转摄像头镜像方向，设置会持久保存
• self.chassis.get_light_mode：读取当前灯光编号

工具清单与参数类型（布尔、整数、字符串）以设备端注册为准，mcp-usage_zh.md 有完整的 JSON-RPC 调用示例。

搭建开发环境：ESP-IDF 6 与编译全流程

需要自改固件时，按下面步骤搭建环境：

1. 安装 ESP-IDF：最低 v6.0.1，推荐 v6.1（v5.x 已不再支持）；Linux 编译更快也更省驱动麻烦
2. 用 VSCode 或 Cursor + ESP-IDF 插件打开仓库：

git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32

3. 配置目标芯片并编译：

idf.py set-target esp32s3 idf.py build

4. 选择 SparkBot 板型：menuconfig 中指定espressif/esp-sparkbot，其 config.json 会追加 OV2640 的 DVP 摄像头宏

项目代码遵循 Google C++ 风格规范（code_style_zh.md），改完先自查再提交。

三个真实使用场景

• 语音遥控小车：说"往前开""左转""跳个舞"，大模型匹配到对应工具，底盘立刻动作，灯光同步变化
• 第一视角观察：通过摄像头把画面送回后台，问一句"你现在看到什么"就能获得视觉描述；镜像方向不合心意时直接语音翻转
• 桌面陪伴：240×240 屏上实时显示表情和情绪，配合声纹识别区分不同说话人，适合放在书桌上当聊天搭子

常见坑与排查：编译失败、画面颠倒、语音无响应

• 编译报一堆依赖错误：十有八九是 IDF 版本旧了，确认是 6.0.1 以上；仍不行就idf.py fullclean后重新idf.py reconfigure，用idf.py build -v看详细日志
• 摄像头画面上下左右颠倒：不同复刻版的摄像头朝向不一，用self.camera.set_camera_flipped工具翻转一次即可，设置会保存
• 底盘不动：先查串口连通性（UART1，115200），再看底盘供电；主控侧串口初始化代码在InitializeEchoUart里
• 唤醒不灵敏：确认唤醒词是官方支持词或已生成自定义唤醒词资产；环境噪音大时先换安静位置测试，再调整麦克风增益
• 自定义板型被 OTA 覆盖：改 IO 配置不要直接覆盖原有板子目录，必须新建板型或改config.json的 builds 区分，详见 custom-board_zh.md

参与与扩展：从改一行代码到造一块新板

上手之后，你可以沿三条线深入：

1. 加自己的工具：参考 mcp-usage_zh.md 的注册方法，给传感器、继电器等外设各写一个AddTool，大模型立刻多一项本领
2. 适配新开发板：按 custom-board_zh.md 在main/boards/下建目录，补全config.h、config.json与板级.cc即可接入
3. 读协议自己搭服务端：对照 mcp-protocol_zh.md、websocket_zh.md、mqtt-udp_zh.md 三份文档，可以用任意语言写自己的后台

有想法或遇到卡点，直接到仓库提 Issue，或加入 README 里列出的 Discord / QQ 群与作者和同行讨论。下一步就动手吧：把固件烧进 ESP-SparkBot，对它说第一句唤醒词。

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