322 lines
5.8 KiB
Markdown
Executable File
322 lines
5.8 KiB
Markdown
Executable File
# ESP32设备绑定功能使用指南
|
||
|
||
## 📋 功能概述
|
||
|
||
ESP32音乐播放器现在支持绑定到用户账号，实现个性化功能：
|
||
- ✅ 设备与用户账号绑定
|
||
- ✅ 安全的Token认证机制
|
||
- ✅ 通过语音命令完成绑定
|
||
- ✅ 为后续歌单功能奠定基础
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### **第1步：启动服务器**
|
||
|
||
```powershell
|
||
cd d:\esp32-music-server\Meow\MeowEmbeddedMusicServer
|
||
go run .
|
||
```
|
||
|
||
服务器将在 `http://localhost:2233` 启动
|
||
|
||
---
|
||
|
||
### **第2步：用户登录**
|
||
|
||
访问：`http://localhost:2233`
|
||
|
||
使用测试账号登录：
|
||
- 用户名：`test`
|
||
- 密码：`123456`
|
||
|
||
---
|
||
|
||
### **第3步：生成绑定码**
|
||
|
||
**方式1：使用命令行工具（临时）**
|
||
|
||
```powershell
|
||
# 向服务器请求生成绑定码
|
||
curl -X POST http://localhost:2233/api/device/generate-code `
|
||
-H "Content-Type: application/json" `
|
||
-H "Cookie: session_token=YOUR_SESSION_TOKEN"
|
||
```
|
||
|
||
**方式2：使用浏览器控制台（推荐）**
|
||
|
||
1. 登录后按 `F12` 打开开发者工具
|
||
2. 切换到 **Console** 标签
|
||
3. 输入以下代码：
|
||
|
||
```javascript
|
||
fetch('/api/device/generate-code', {
|
||
method: 'POST',
|
||
headers: {'Content-Type': 'application/json'}
|
||
})
|
||
.then(r => r.json())
|
||
.then(data => {
|
||
console.log('绑定码：', data.code);
|
||
alert('绑定码：' + data.code + '\n有效期：5分钟');
|
||
});
|
||
```
|
||
|
||
4. 记下显示的6位数字绑定码，例如：`123456`
|
||
|
||
---
|
||
|
||
### **第4步：ESP32端绑定**
|
||
|
||
对ESP32说：
|
||
|
||
```
|
||
"小智，绑定设备，绑定码123456"
|
||
```
|
||
|
||
或者：
|
||
|
||
```
|
||
"小智，bind device, binding code is 123456"
|
||
```
|
||
|
||
ESP32会回复：
|
||
|
||
```
|
||
✅ 设备绑定成功！
|
||
已绑定到用户: test
|
||
```
|
||
|
||
---
|
||
|
||
### **第5步：验证绑定状态**
|
||
|
||
对ESP32说：
|
||
|
||
```
|
||
"小智，查询设备状态"
|
||
```
|
||
|
||
ESP32会显示：
|
||
|
||
```
|
||
📱 设备信息:
|
||
|
||
MAC地址: AA:BB:CC:DD:EE:FF
|
||
绑定状态: ✅ 已绑定
|
||
绑定用户: test
|
||
服务器验证: ✅ 通过
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 高级功能
|
||
|
||
### **解绑设备**
|
||
|
||
对ESP32说：
|
||
|
||
```
|
||
"小智，解绑设备"
|
||
```
|
||
|
||
### **自定义设备名称**
|
||
|
||
对ESP32说：
|
||
|
||
```
|
||
"小智，绑定设备，绑定码123456，设备名称客厅音响"
|
||
```
|
||
|
||
---
|
||
|
||
## 📊 数据存储
|
||
|
||
### **服务器端**
|
||
|
||
设备信息存储在：`d:\esp32-music-server\Meow\MeowEmbeddedMusicServer\devices.json`
|
||
|
||
```json
|
||
{
|
||
"devices": {
|
||
"AA:BB:CC:DD:EE:FF": {
|
||
"mac": "AA:BB:CC:DD:EE:FF",
|
||
"username": "test",
|
||
"device_name": "ESP32音乐播放器",
|
||
"token": "a1b2c3d4e5f6...",
|
||
"bind_time": "2025-11-24T16:00:00Z",
|
||
"last_seen": "2025-11-24T16:30:00Z",
|
||
"is_active": true
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### **ESP32端**
|
||
|
||
Token存储在NVS（非易失性存储）中：
|
||
- 命名空间：`device`
|
||
- Key: `token` - 设备Token
|
||
- Key: `username` - 绑定的用户名
|
||
|
||
---
|
||
|
||
## 🔌 API文档
|
||
|
||
### **1. 生成绑定码**
|
||
|
||
```
|
||
POST /api/device/generate-code
|
||
Authorization: 需要登录
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": "123456",
|
||
"expires_in": 300
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### **2. ESP32绑定设备**
|
||
|
||
```
|
||
POST /api/esp32/bind
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"mac": "AA:BB:CC:DD:EE:FF",
|
||
"binding_code": "123456",
|
||
"device_name": "ESP32音乐播放器"
|
||
}
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "设备绑定成功",
|
||
"token": "a1b2c3d4e5f6...",
|
||
"username": "test"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### **3. 验证设备Token**
|
||
|
||
```
|
||
GET /api/esp32/verify
|
||
X-Device-Token: a1b2c3d4e5f6...
|
||
```
|
||
|
||
**响应：**
|
||
```json
|
||
{
|
||
"success": true,
|
||
"device": {
|
||
"mac": "AA:BB:CC:DD:EE:FF",
|
||
"username": "test",
|
||
"device_name": "ESP32音乐播放器",
|
||
"bind_time": "2025-11-24T16:00:00Z",
|
||
"last_seen": "2025-11-24T16:30:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🧪 测试流程
|
||
|
||
### **完整测试步骤**
|
||
|
||
1. **启动服务器**
|
||
```powershell
|
||
go run .
|
||
```
|
||
|
||
2. **生成绑定码**（使用浏览器控制台）
|
||
|
||
3. **ESP32绑定**
|
||
- 对ESP32说："小智，绑定设备，绑定码123456"
|
||
- 观察ESP32日志：
|
||
```
|
||
[DeviceManager] Starting device binding with code: 123456
|
||
[DeviceManager] Sending bind request to: http://...
|
||
[DeviceManager] Bind request status code: 200
|
||
[DeviceManager] Device successfully bound to user: test
|
||
```
|
||
|
||
4. **查询状态**
|
||
- 对ESP32说："小智，查询设备状态"
|
||
|
||
5. **验证服务器数据**
|
||
- 检查 `devices.json` 文件是否包含设备信息
|
||
|
||
6. **测试解绑**
|
||
- 对ESP32说："小智，解绑设备"
|
||
- 再次查询状态，应显示未绑定
|
||
|
||
---
|
||
|
||
## 🐛 故障排除
|
||
|
||
### **问题1：绑定码无效**
|
||
|
||
**现象**：ESP32提示"绑定失败"
|
||
|
||
**解决方案**：
|
||
- 检查绑定码是否输入正确
|
||
- 绑定码有效期为5分钟，请重新生成
|
||
- 确认网络连接正常
|
||
|
||
---
|
||
|
||
### **问题2：设备已绑定**
|
||
|
||
**现象**：提示"设备已绑定到用户XXX"
|
||
|
||
**解决方案**：
|
||
- 先解绑设备：对ESP32说"小智，解绑设备"
|
||
- 或者在服务器端删除 `devices.json` 中的设备记录
|
||
|
||
---
|
||
|
||
### **问题3：网络连接失败**
|
||
|
||
**现象**：ESP32无法连接到服务器
|
||
|
||
**解决方案**：
|
||
- 检查ESP32是否连接到WiFi
|
||
- 确认服务器地址是否正确：`http://http-embedded-music.miao-lab.top:2233`
|
||
- 检查防火墙设置
|
||
|
||
---
|
||
|
||
## 📝 下一步
|
||
|
||
绑定功能完成后，可以继续开发：
|
||
|
||
✅ **阶段1：基础绑定** - 已完成
|
||
⏳ **阶段2：歌单系统** - 待开发
|
||
⏳ **阶段3：Web管理界面** - 待开发
|
||
|
||
---
|
||
|
||
## 💡 提示
|
||
|
||
- 绑定码每次生成后只能使用一次
|
||
- 一个设备只能绑定到一个用户
|
||
- Token存储在ESP32的NVS中，断电不丢失
|
||
- 可以通过解绑并重新绑定来更换用户
|
||
|
||
---
|
||
|
||
**🎉 享受您的个性化ESP32音乐播放器！**
|