MeowMusicServer/DEVICE_BINDING_GUIDE.md

ESP32设备绑定功能使用指南

📋 功能概述

ESP32音乐播放器现在支持绑定到用户账号，实现个性化功能：

• ✅ 设备与用户账号绑定
• ✅ 安全的Token认证机制
• ✅ 通过语音命令完成绑定
• ✅ 为后续歌单功能奠定基础

---

🚀 快速开始

第1步：启动服务器

cd d:\esp32-music-server\Meow\MeowEmbeddedMusicServer
go run .

服务器将在 http://localhost:2233 启动

---

第2步：用户登录

访问：http://localhost:2233

使用测试账号登录：

• 用户名：test
• 密码：123456

---

第3步：生成绑定码

方式1：使用命令行工具（临时）

# 向服务器请求生成绑定码
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. 输入以下代码：

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

{
  "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: 需要登录

响应：

{
  "success": true,
  "code": "123456",
  "expires_in": 300
}

---

2. ESP32绑定设备

POST /api/esp32/bind
Content-Type: application/json

请求体：

{
  "mac": "AA:BB:CC:DD:EE:FF",
  "binding_code": "123456",
  "device_name": "ESP32音乐播放器"
}

响应：

{
  "success": true,
  "message": "设备绑定成功",
  "token": "a1b2c3d4e5f6...",
  "username": "test"
}

---

3. 验证设备Token

GET /api/esp32/verify
X-Device-Token: a1b2c3d4e5f6...

响应：

{
  "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. 启动服务器

   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音乐播放器！