326 lines
8.9 KiB
Markdown
Executable File
326 lines
8.9 KiB
Markdown
Executable File
# Web端设备绑定指南
|
||
|
||
## 🎉 **简化的绑定流程**
|
||
|
||
不需要语音绑定码！直接在Web界面输入MAC地址即可。
|
||
|
||
---
|
||
|
||
## 🚀 **快速开始**
|
||
|
||
### **步骤1：启动服务器**
|
||
|
||
```powershell
|
||
cd d:\esp32-music-server\Meow\MeowEmbeddedMusicServer
|
||
go run .
|
||
```
|
||
|
||
### **步骤2：登录Web界面**
|
||
|
||
访问：`http://localhost:2233`
|
||
|
||
登录账号：
|
||
- 用户名：`test`
|
||
- 密码：`123456`
|
||
|
||
### **步骤3：打开设备绑定页面**
|
||
|
||
访问：`http://localhost:2233/device-bind`
|
||
|
||
或者在登录后，点击导航菜单中的"设备管理"。
|
||
|
||
### **步骤4：查看ESP32的MAC地址**
|
||
|
||
ESP32启动时会在串口日志中显示MAC地址：
|
||
|
||
```
|
||
I (1024) wifi:mode : sta (80:b5:4e:d4:fa:80)
|
||
↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑↑
|
||
这就是MAC地址！
|
||
```
|
||
|
||
在您的日志中找到这一行：
|
||
```
|
||
I (1024) wifi:mode : sta (80:b5:4e:d4:fa:80)
|
||
```
|
||
|
||
MAC地址是：`80:b5:4e:d4:fa:80`
|
||
|
||
### **步骤5：在Web界面输入MAC地址**
|
||
|
||
1. 在"MAC地址"输入框中输入：`80:b5:4e:d4:fa:80`
|
||
2. （可选）在"设备名称"输入框中输入设备名称，例如：`客厅音响`
|
||
3. 点击"绑定设备"按钮
|
||
|
||
### **步骤6：完成！**
|
||
|
||
绑定成功后，页面会显示：
|
||
```
|
||
✅ 设备绑定成功！
|
||
```
|
||
|
||
已绑定设备列表会自动刷新，显示您的设备。
|
||
|
||
---
|
||
|
||
## 📱 **设备管理功能**
|
||
|
||
### **查看已绑定设备**
|
||
|
||
在设备绑定页面下方，会显示所有已绑定的设备：
|
||
|
||
```
|
||
┌──────────────────────────────────────┐
|
||
│ 客厅音响 │
|
||
│ MAC: 80:b5:4e:d4:fa:80 │
|
||
│ 🟢 在线 [解绑] │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
### **解绑设备**
|
||
|
||
点击设备卡片右侧的"解绑"按钮，确认后即可解绑。
|
||
|
||
### **刷新设备列表**
|
||
|
||
点击"刷新设备列表"按钮，更新设备状态。
|
||
|
||
---
|
||
|
||
## 🆚 **新旧方案对比**
|
||
|
||
### **旧方案（语音绑定码）**
|
||
|
||
```
|
||
1. Web端生成绑定码 → 123456
|
||
2. 对ESP32说："小智，绑定设备，绑定码123456"
|
||
3. ESP32识别语音 → 调用MCP工具 → 发送请求
|
||
4. 完成绑定
|
||
```
|
||
|
||
**缺点**：
|
||
- ❌ 语音识别可能出错
|
||
- ❌ 绑定码需要记忆5分钟
|
||
- ❌ 流程复杂，容易失败
|
||
|
||
### **新方案（Web直接绑定）**
|
||
|
||
```
|
||
1. 查看ESP32串口日志 → 复制MAC地址
|
||
2. 在Web界面粘贴MAC地址
|
||
3. 点击绑定按钮
|
||
4. 完成！
|
||
```
|
||
|
||
**优点**：
|
||
- ✅ 一次复制粘贴搞定
|
||
- ✅ 不需要语音识别
|
||
- ✅ 操作简单明了
|
||
- ✅ 立即生效，无需等待
|
||
|
||
---
|
||
|
||
## 📋 **API文档**
|
||
|
||
### **1. 直接绑定设备**
|
||
|
||
```
|
||
POST /api/device/bind-direct
|
||
Authorization: 需要登录
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"mac": "80:b5:4e:d4:fa:80",
|
||
"device_name": "客厅音响"
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "设备绑定成功",
|
||
"device": {
|
||
"mac": "80:b5:4e:d4:fa:80",
|
||
"device_name": "客厅音响",
|
||
"bind_time": "2025-11-24T17:00:00Z"
|
||
}
|
||
}
|
||
```
|
||
|
||
### **2. 列出用户设备**
|
||
|
||
```
|
||
GET /api/device/list
|
||
Authorization: 需要登录
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"devices": [
|
||
{
|
||
"mac": "80:b5:4e:d4:fa:80",
|
||
"username": "test",
|
||
"device_name": "客厅音响",
|
||
"token": "a1b2c3...",
|
||
"bind_time": "2025-11-24T17:00:00Z",
|
||
"last_seen": "2025-11-24T17:30:00Z",
|
||
"is_active": true
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### **3. 解绑设备**
|
||
|
||
```
|
||
POST /api/device/unbind
|
||
Authorization: 需要登录
|
||
Content-Type: application/json
|
||
```
|
||
|
||
**请求体**：
|
||
```json
|
||
{
|
||
"mac": "80:b5:4e:d4:fa:80"
|
||
}
|
||
```
|
||
|
||
**响应**：
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "设备已解绑"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 🔍 **如何查看ESP32的MAC地址**
|
||
|
||
### **方法1：串口监视器（推荐）**
|
||
|
||
使用ESP-IDF监视器：
|
||
```bash
|
||
idf.py monitor
|
||
```
|
||
|
||
或者任何串口工具（PuTTY、Arduino Serial Monitor等），波特率115200。
|
||
|
||
启动日志中会显示：
|
||
```
|
||
I (1024) wifi:mode : sta (80:b5:4e:d4:fa:80)
|
||
```
|
||
|
||
### **方法2：Web API查询**
|
||
|
||
如果ESP32已连接到网络，可以通过API查询（需要先知道IP）：
|
||
```
|
||
http://ESP32的IP地址/api/system/info
|
||
```
|
||
|
||
### **方法3：标签贴纸**
|
||
|
||
在ESP32开发板上贴一个标签，写上MAC地址，方便以后查找。
|
||
|
||
---
|
||
|
||
## 💡 **常见问题**
|
||
|
||
### **Q1：MAC地址格式错误**
|
||
|
||
**A**：MAC地址应该是6组2位十六进制数，用冒号分隔，例如：
|
||
- ✅ 正确：`80:b5:4e:d4:fa:80`
|
||
- ✅ 正确：`80:B5:4E:D4:FA:80` （大小写都可以）
|
||
- ❌ 错误：`80b54ed4fa80` （缺少冒号）
|
||
- ❌ 错误：`80-b5-4e-d4-fa-80` （使用了连字符）
|
||
|
||
Web界面会自动格式化MAC地址。
|
||
|
||
### **Q2：提示"设备已绑定"**
|
||
|
||
**A**：这个MAC地址已经绑定到某个账号了。
|
||
|
||
解决方法：
|
||
1. 登录原账号，解绑设备
|
||
2. 或者在设备管理页面删除旧绑定
|
||
3. 然后重新绑定
|
||
|
||
### **Q3：未登录提示**
|
||
|
||
**A**：请先登录系统，然后访问设备绑定页面。
|
||
|
||
### **Q4：设备显示离线**
|
||
|
||
**A**：
|
||
- 检查ESP32是否开机
|
||
- 检查WiFi连接
|
||
- 查看ESP32串口日志是否有错误
|
||
|
||
---
|
||
|
||
## 🎨 **页面截图说明**
|
||
|
||
### **绑定页面**
|
||
|
||
```
|
||
┌────────────────────────────────────────────┐
|
||
│ 🎵 设备绑定 │
|
||
│ 将您的ESP32音乐播放器绑定到账号 │
|
||
├────────────────────────────────────────────┤
|
||
│ │
|
||
│ MAC地址 * │
|
||
│ ┌──────────────────────────────────────┐ │
|
||
│ │ 例如: AA:BB:CC:DD:EE:FF │ │
|
||
│ └──────────────────────────────────────┘ │
|
||
│ 💡 在ESP32串口日志中查找 │
|
||
│ │
|
||
│ 设备名称（可选） │
|
||
│ ┌──────────────────────────────────────┐ │
|
||
│ │ 例如: 客厅音响 │ │
|
||
│ └──────────────────────────────────────┘ │
|
||
│ 给设备起个名字，方便识别 │
|
||
│ │
|
||
│ ┌──────────────────────────────────────┐ │
|
||
│ │ 绑定设备 │ │
|
||
│ └──────────────────────────────────────┘ │
|
||
│ │
|
||
│ ┌──────────────────────────────────────┐ │
|
||
│ │ 刷新设备列表 │ │
|
||
│ └──────────────────────────────────────┘ │
|
||
│ │
|
||
├────────────────────────────────────────────┤
|
||
│ 已绑定设备 │
|
||
│ │
|
||
│ ┌──────────────────────────────────────┐ │
|
||
│ │ 客厅音响 │ │
|
||
│ │ MAC: 80:b5:4e:d4:fa:80 │ │
|
||
│ │ 🟢 在线 [解绑] │ │
|
||
│ └──────────────────────────────────────┘ │
|
||
│ │
|
||
│ ← 返回首页 │
|
||
└────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## ✅ **总结**
|
||
|
||
**新的Web绑定方式让设备管理变得超级简单！**
|
||
|
||
1. 📋 复制ESP32的MAC地址
|
||
2. 🖱️ 在Web界面粘贴
|
||
3. ✅ 点击绑定
|
||
4. 🎉 完成！
|
||
|
||
不需要语音，不需要绑定码，一次复制粘贴搞定！
|
||
|
||
---
|
||
|
||
**喵波音律QQ交流群：865754861** 🎵
|