如何让你的ESP32开发板听懂人话5步搭建小智AI语音助手完整教程【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32想让一块几十块钱的 ESP32 开发板真正听懂人话、开口回话xiaozhi-esp32小智 AI 聊天机器人做到了它是一个基于 MCPModel Context Protocol模型上下文协议一种让大模型发现并调用设备工具的 JSON-RPC 协议的开源语音助手固件内置离线语音唤醒上云后接上 Qwen、DeepSeek 等大模型就能实现自然对话还能反向控制灯光、电机、GPIO 等硬件。技术亮点速览先说结论这个项目不是能跑的 demo而是一套可以直接量产的语音交互框架。离线语音唤醒基于乐鑫 ESP-SR 语音框架唤醒词本地识别不用把 24 小时的音频流推上云省流量也省电费。MCP 双向控制设备端用AddTool注册工具音量、灯光、电机云端用同一套协议扩展能力智能家居、邮件、搜索大模型说话的同时就能动手。138 个板卡目录、171 个固件变体从 ESP32、C3、C5、C6 到 S3、P4Wi-Fi / 以太网 / USB RNDIS / ML307 4G 全覆盖主流开发板基本不用改代码。双传输协议WebSocket 直连和 MQTTUDP 两种链路可切换后者更适合网络质量差的部署环境。Opus 音频流 AEC支持流式 ASRLLMTTS 传统链路也支持 Realtime 端到端语音模型带硬件回声消除AEC让你说话时设备能听清自己正在播放的声音之外的新指令的板子可以实时全双工对话。硬件与环境准备开发板怎么挑、工具链装什么开发板推荐档位推荐型号关键规格适合阶段入门ESP32-S3 开发板 I2S 麦克风/功放面包板方案对应bread-compact-wifi板型8MB PSRAM、外置 ES8311 音频 Codec学习原理、第一次烧录进阶立创实战派 ESP32-S3 / LILYGO T-Circle-S316MB Flash、集成屏幕可加 4G 与摄像头功能开发、带屏交互调试产品级M5Stack CoreS3 / ESP32-S3-BOX-3工业级设计、内置麦克风阵列与扬声器最终产品部署面包板手工党的完整接法可以看仓库里的示意图麦克风、功放、按键的走线一目了然工具链最低版本ESP-IDFv6.0.2主线已迁到 v6.0最低 v5.5.2 仅用于文档标注的旧板型CMake 3.16、NinjaPython 3.8系统首选 Linux编译快且免驱环境安装git clone --recursive https://github.com/espressif/esp-idf.git cd esp-idf ./install.sh . ./export.sh idf.py --version # 确认输出版本号即安装成功新手第一次上手可以跳过编译环境直接烧录仓库发布页提供的免编译固件默认接入 xiaozhi.me 官方服务器个人账号可免费使用 Qwen 实时模型跑通后再回来搭环境。从零到跑通编译、烧录、联网一条龙第 1 步获取源码git clone https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32 cd xiaozhi-esp32第 2 步设置芯片目标并选板型idf.py set-target esp32s3 idf.py menuconfig在Component config XiaoZhi Configuration Board Type里选你的开发板。每个板型的引脚定义都放在 main/boards/ 下对应目录选错了只会表现为外设失灵编译本身不会报错。第 3 步编译idf.py build项目默认带 16MB 分区表见 partitions/v2/ 的 v2 布局预留了 8MB assets 分区用于在线下载唤醒词模型、字体和音效。如果你用的是小容量 Flash需要按板型文档调整分区。第 4 步烧录并打开串口监视idf.py -p /dev/ttyUSB0 flash monitorWindows 下串口号换成COMx。第 5 步联网与配网设备开机后默认走Wi-Fi 热点配网手机连设备热点填 SSID/密码或BluFi 蓝牙配网两种方式如果你用的是出厂已烧录配好网固件的板卡可跳过。想省事的用户也可以直接烧官方发布的成品固件。功能验证你应该看到……串口日志出现 Wi-Fi 连接成功、与服务器握手完成的输出说出唤醒词你好小智LED 亮起并播放提示音提问后扬声器流出语音回答带屏设备屏幕上同步出现表情与状态变化走到这一步基础链路唤醒 → ASR → LLM → TTS → 播放就全通了。进阶配置Wi-Fi、4G、内存与功耗怎么调问题家里只有 5GHz Wi-Fi设备连不上→ 对应配置ESP32 系列只支持 2.4GHz 频段把路由器开一个 2.4G SSID 或用热点过渡。这是 90% 连不上网的真实原因。问题无 Wi-Fi 环境户外、工业现场→ 对应配置选用支持 ML307 Cat.1 模块的板型main/boards/下带 4G 的目录如bread-compact-ml307在板级config.h中配置 APN如CMNET。部分硬件还支持 Wi-Fi 与 4G 自动切换见 main/boards/common/dual_network_board.cc。问题Flash/内存吃紧assets 空间不够→ 对应配置分区表按 Flash 大小选partitions/v2/4m.csv~32m.csvsdkconfig里CONFIG_ESPTOOLPY_FLASHSIZE_*与分区文件名必须一致。问题功耗过高电池设备续航短→ 对应配置利用main/boards/common/power_save_timer.cc、sleep_timer.cc的空闲深睡策略音频侧 Codec 的 ADC/DAC 通道会随活动状态自动开关无需额外处理。问题安静环境误唤醒、嘈杂环境唤醒不到→ 对应配置唤醒走本地 WakeNet/MultiNetESP-SR可调增益麦克风前端与 VAD语音活动检测阈值S3/P4 上 AFE 管线默认使用FD_LOW_COST低成本 AEC见 main/audio/README.md。排障手册连不上、喊不动、慢半拍怎么办症状一Wi-Fi 连接失败如果日志反复出现连接超时那么先确认 SSID/密码无误如果日志显示扫描到网络但认证失败那么多半是 5GHz 频段或路由器开启了 WPA3-only如果信号弱那么把设备挪近路由器再看 RSSI 输出。症状二唤醒成功率低如果喊你好小智没反应那么检查 I2S 麦克风接线与方向DIN/DOUT 接反是最常见事故如果唤醒时有爆音那么降低麦克风增益如果环境嘈杂那么先换安静环境验证再谈调阈值。症状三对话响应慢如果唤醒正常但回答很慢那么看串口日志定位卡在 ASR 上行、LLM 还是 TTS 下行上行慢优先怀疑网络切换 WebSocket 与 MQTTUDP 对比本地播放卡顿则检查 PSRAM 带宽与 Opus 解码任务优先级。二次开发从 MCP 工具注册到自定义开发板方向一给大模型加手——注册 MCP 工具这是整个项目最有价值的扩展点你在设备端注册一个工具大模型就能通过自然语言驱动它。注册入口是McpServer::AddTool实现见 main/mcp_server.ccauto mcp McpServer::GetInstance(); mcp.AddTool(self.light.set_rgb, 设置RGB颜色, PropertyList({ Property(r, kPropertyTypeInteger, 0, 255), Property(g, kPropertyTypeInteger, 0, 255), Property(b, kPropertyTypeInteger, 0, 255) }), [](const PropertyList p) - ReturnValue { SetLedColor(p[r].valueint(), p[g].valueint(), p[b].valueint()); return true; });工具名建议用模块.功能层级命名如self.dog.forward描述写清楚一点大模型调用会更准。完整交互流程initialize → tools/list → tools/call见 docs/mcp-protocol_zh.md。方向二自定义开发板新板子支持就三件事目录结构参考 docs/custom-board_zh.mdmain/boards/my-custom-board/ ├── my_custom_board.cc # 板级初始化实现 Board 接口 ├── config.h # 引脚映射I2S、I2C、按键、显示屏 └── config.json # 板型标识与编译/发布配置config.h里定义音频采样率、I2S 六根线、Codec 的 I2C 地址与按键引脚config.json里声明 target 和构建参数{ target: esp32s3, builds: [ { name: my-custom-board, sdkconfig_append: [ CONFIG_ESPTOOLPY_FLASHSIZE_16MBy, CONFIG_PARTITION_TABLE_CUSTOM_FILENAME\partitions/v2/16m.csv\ ] } ] }⚠️ 自定义板型务必用独立的 name 与构建标识不要直接覆盖现有板型配置——否则将来 OTA 升级时你的设备可能被标准固件覆盖直接变砖。最佳实践与延伸阅读开发阶段打开详细日志排障稳定后再收敛日志级别避免串口吞吐挤占音频时间片。自定义唤醒词、字体、表情与背景走 assets 分区在线更新不用重刷整包固件。提交代码前对照 docs/code_style_zh.md 检查项目采用 Google C 风格。换 ESP-IDF 6.x 的板卡兼容清单见 docs/esp-idf-6-migration.md。延伸阅读MCP 物联网控制用法、WebSocket 通信协议、MQTTUDP 混合协议。从面包板到量产硬件小智 ESP32 已经把语音交互最难的前后端管线铺平了——你只需要挑一块板子、烧一次固件剩下的都可以用对话解决。【免费下载链接】xiaozhi-esp32An MCP-based chatbot | 一个基于MCP的聊天机器人项目地址: https://gitcode.com/GitHub_Trending/xia/xiaozhi-esp32创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考