ESP32小智音乐助手：为智能音箱添加音乐播放和微信留言功能
开发日期：2025年11月6日
项目地址：https://github.com/xiaojieyahuhu/-xiaozhi-esp32-music-wechat
演示视频：点击观看
📖 项目背景
最近在折腾 ESP32 智能音箱，发现原版小智虽然功能强大，但缺少两个实用的功能：
- 音乐播放：无法播放在线音乐
- 微信留言：无法通过语音留言推送到微信
于是基于 Maggotxy/xiaozhi-esp32-music 进行了二次开发，添加了这两个核心功能。
✨ 核心功能
🎵 1. 音乐播放功能
集成了在线音乐播放能力，支持：
- 语音点歌："播放周杰伦的晴天"
- 歌词显示（如果设备支持屏幕）
- 播放控制：暂停、继续、切歌
- 基于 MCP 协议的
self.music.play_song工具
使用示例：
用户："小智小智，播放周杰伦的晴天"
小智："好的，正在为您播放《晴天》"
💬 2. 微信留言推送
通过 WxPusher 实现语音留言推送到微信，支持：
- 智能识别留言意图
- 自动提取留言内容
- 实时推送到微信（秒级送达）
- 支持 WiFi 和 ML307 4G 网络
使用示例：
用户："给小杰说，今天晚上不回家了"
小智："好的，已经发送留言"
[微信收到推送] "今天晚上不回家了"
🔧 技术实现
架构设计
项目采用 ESP-IDF 框架开发，主要模块包括：
xiaozhi-esp32-music-wechat/
├── main/
│ ├── boards/ # 硬件适配层
│ │ └── common/
│ │ ├── esp32_music.cc # 音乐播放实现
│ │ └── music.h # 音乐接口定义
│ ├── message_pusher.cc # 微信推送实现
│ ├── message_pusher.h
│ ├── mcp_server.cc # MCP 服务器
│ └── application.cc # 应用主逻辑
└── README.md
关键代码
1. 微信推送实现
最大的挑战是 ML307 4G 模块不支持标准的 ESP-IDF HTTP 客户端。解决方案是使用 Board 提供的网络接口：
// message_pusher.cc
bool MessagePusher::SendMessage(const std::string& content) {
// 获取网络接口（兼容 WiFi 和 ML307）
auto network = Board::GetInstance().GetNetwork();
if (!network) {
return false;
}
// 创建 HTTP 客户端
auto http_client = network->CreateHttp();
// URL 编码中文内容
std::string encoded_content = UrlEncode(content);
// 构建推送 URL
std::string url = "http://wxpusher.zjiecode.com/api/send/message"
"?appToken=" + app_token_ +
"&uid=" + uid_ +
"&content=" + encoded_content;
// 发送请求
return http_client->Get(url);
}2. MCP 工具注册
在 MCP 服务器中注册微信推送工具：
// mcp_server.cc
#ifdef CONFIG_ENABLE_MESSAGE_PUSHER
{
"name": "send_to_wechat",
"description": "发送留言到微信。参数：content（留言内容）",
"inputSchema": {
"type": "object",
"properties": {
"content": {"type": "string", "description": "留言内容"}
},
"required": ["content"]
}
}
#endif技术难点与解决
难点 1：ML307 HTTP 兼容性
- 问题：ML307 使用 AT 命令，不支持标准 HTTP 客户端
- 解决：抽象网络接口，统一 WiFi 和 ML307 的 HTTP 调用
难点 2：中文 URL 编码
- 问题：微信推送需要正确编码中文字符
- 解决：实现完整的 URL 编码函数，支持 UTF-8
难点 3：音乐播放集成
- 问题：需要在不影响原有功能的前提下添加音乐播放
- 解决：使用 MCP 协议扩展，保持架构清晰
📱 配置指南
1. 微信推送配置
编辑 sdkconfig 文件：
CONFIG_ENABLE_MESSAGE_PUSHER=y
CONFIG_MESSAGE_PUSHER_APP_TOKEN="你的AppToken"
CONFIG_MESSAGE_PUSHER_UID="你的UID"获取 AppToken 和 UID：
- 访问 WxPusher 官网
- 注册并创建应用，获取 AppToken
- 在"我的"页面获取 UID
2. 编译和烧录
# 配置环境
export IDF_PATH="$HOME/esp/esp-idf"
export PATH="$HOME/.espressif/python_env/idf5.4_py3.9_env/bin:$PATH"
# 编译固件
cd xiaozhi-esp32-music-wechat
idf.py build
# 烧录到设备
idf.py -p /dev/tty.usbmodem2101 flash monitor🎬 效果演示
演示内容：音乐播放和微信留言推送功能
📊 项目数据
- 开发周期：1 天
- 代码变更：753 个文件
新增模块：
message_pusher.cc/h：微信推送esp32_music.cc/h：音乐播放
- 支持设备：所有基于 ESP32-S3 的小智设备
- 网络支持：WiFi / ML307 4G
🚀 后续计划
- [ ] 添加歌单管理功能
- [ ] 支持本地音乐播放
- [ ] 优化留言识别准确率
- [ ] 添加更多语音指令
- [ ] 支持多人留言推送
💡 开发心得
- 抽象是关键：通过网络接口抽象，成功解决了 ML307 兼容性问题
- MCP 协议的威力：基于 MCP 扩展功能，不需要修改核心代码
- 文档很重要：完善的中英日三语文档，让项目更易用
- 测试要充分：WiFi 和 4G 都要测试，避免遗漏
🔗 相关链接
- 项目仓库：GitHub
- 基础项目：xiaozhi-esp32-music
- 原始项目：xiaozhi-esp32
- WxPusher：官网
📝 总结
这次开发让我深刻体会到 ESP32 的强大和 MCP 协议的优雅。通过合理的架构设计，成功在不破坏原有功能的前提下，添加了音乐播放和微信推送两大实用功能。
如果你也在使用小智 ESP32 设备，欢迎试用这个项目！有任何问题或建议，欢迎在 GitHub 提 Issue 或 PR。
License: MIT
Author: 小杰呀呼呼
Date: 2025-11-06
💡 提示：如果觉得这个项目有帮助，别忘了给个 Star ⭐ 哦！
