add banbanmini backend
This commit is contained in:
HycJack
229
talkingq-url/docs/ota_flow.md
Normal file
229
talkingq-url/docs/ota_flow.md
Normal file
@@ -0,0 +1,229 @@
|
||||
# TalkingQ OTA 固件升级流程
|
||||
|
||||
本文档详细描述了TalkingQ设备固件OTA升级的完整流程，涉及到APP、后台服务器和ESP32设备端三方的交互。
|
||||
|
||||
## 流程概述
|
||||
|
||||
```mermaid
|
||||
sequenceDiagram
|
||||
participant APP
|
||||
participant 后台服务器
|
||||
participant ESP32设备端
|
||||
|
||||
APP->>后台服务器: /api/ota/check/{device_id}: 检查更新
|
||||
后台服务器->>ESP32设备端: WebSocket: GET_FIRMWARE_VERSION
|
||||
ESP32设备端->>后台服务器: WebSocket: FIRMWARE_VERSION:{version}
|
||||
后台服务器->>后台服务器: 比较版本判断是否需要更新
|
||||
后台服务器->>APP: 返回检查结果与版本信息
|
||||
|
||||
alt 不需要更新
|
||||
APP->>用户: 提示当前已是最新版本
|
||||
else 需要更新
|
||||
APP->>后台服务器: /api/ota/start/{device_id}: 发起升级请求
|
||||
后台服务器->>ESP32设备端: WebSocket: UPDATE_FIRMWARE:{url}
|
||||
ESP32设备端->>ESP32设备端: 下载固件并校验
|
||||
ESP32设备端->>后台服务器: WebSocket: FIRMWARE_UPDATE_STATUS
|
||||
|
||||
loop 进度更新
|
||||
ESP32设备端->>后台服务器: FIRMWARE_UPDATE_STATUS:status=updating,progress=45.5,version=1.0.0
|
||||
后台服务器->>后台服务器: 数据库更新升级状态与进度
|
||||
APP->>后台服务器: /api/ota/status/{device_id}: 查询升级状态
|
||||
后台服务器->>APP: 返回当前升级状态、进度和设备在线状态
|
||||
APP->>用户: 显示升级进度
|
||||
end
|
||||
|
||||
ESP32设备端->>ESP32设备端: 升级完成后重启
|
||||
ESP32设备端->>后台服务器: WebSocket重连后上报: FIRMWARE_VERSION:{new_version}
|
||||
后台服务器->>后台服务器: 更新设备固件版本记录
|
||||
APP->>后台服务器: /api/ota/status/{device_id}: 确认升级完成
|
||||
APP->>用户: 提示升级完成
|
||||
end
|
||||
```
|
||||
|
||||
## 详细API说明
|
||||
|
||||
### 1. 检查更新
|
||||
|
||||
**APP → 后台服务器**
|
||||
|
||||
```
|
||||
GET /api/ota/check/{device_id}
|
||||
Headers:
|
||||
X-Device-ID: {device_id}
|
||||
X-Device-Serial: {serial_number}
|
||||
```
|
||||
|
||||
**后台服务器 → APP**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"status": "success",
|
||||
"need_update": true|false,
|
||||
"current_version": "x.y.z",
|
||||
"latest_version": "a.b.c"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
如果出错则返回：
|
||||
|
||||
```json
|
||||
{
|
||||
"code": -1,
|
||||
"msg": "错误信息",
|
||||
"data": {}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 启动固件升级
|
||||
|
||||
**APP → 后台服务器**
|
||||
|
||||
```
|
||||
POST /api/ota/start/{device_id}
|
||||
Headers:
|
||||
X-Device-ID: {device_id}
|
||||
X-Device-Serial: {serial_number}
|
||||
```
|
||||
|
||||
**后台服务器 → APP**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"updating": true
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. 获取升级状态和进度
|
||||
|
||||
**APP → 后台服务器**
|
||||
|
||||
```
|
||||
GET /api/ota/status/{device_id}
|
||||
Headers:
|
||||
X-Device-ID: {device_id}
|
||||
X-Device-Serial: {serial_number}
|
||||
```
|
||||
|
||||
**后台服务器 → APP**
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"msg": "success",
|
||||
"data": {
|
||||
"status": "updating|success|failed|unknown",
|
||||
"progress": 45.5,
|
||||
"version": "1.0.0",
|
||||
"device_online": true|false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. 管理固件配置信息（管理员接口）
|
||||
|
||||
**获取固件配置**
|
||||
|
||||
```
|
||||
GET /api/ota/config/firmware
|
||||
Headers:
|
||||
X-Device-ID: {device_id}
|
||||
X-Device-Serial: {serial_number}
|
||||
```
|
||||
|
||||
**设置固件配置**
|
||||
|
||||
```
|
||||
POST /api/ota/config/firmware
|
||||
Headers:
|
||||
X-Device-ID: {device_id}
|
||||
X-Device-Serial: {serial_number}
|
||||
Body:
|
||||
{
|
||||
"version": "1.2.3",
|
||||
"url": "https://example.com/firmware/v1.2.3.bin"
|
||||
}
|
||||
```
|
||||
|
||||
## WebSocket消息格式
|
||||
|
||||
### 1. 服务器向设备请求固件版本
|
||||
|
||||
```
|
||||
GET_FIRMWARE_VERSION
|
||||
```
|
||||
|
||||
### 2. 设备返回固件版本
|
||||
|
||||
```
|
||||
FIRMWARE_VERSION:1.0.0
|
||||
```
|
||||
|
||||
### 3. 服务器向设备发送升级指令
|
||||
|
||||
```
|
||||
UPDATE_FIRMWARE:https://example.com/firmware/v1.2.3.bin
|
||||
```
|
||||
|
||||
### 4. 设备上报升级状态
|
||||
|
||||
```
|
||||
FIRMWARE_UPDATE_STATUS:status=updating,progress=45.5,version=1.0.0
|
||||
```
|
||||
|
||||
其中status可以是：
|
||||
- `updating`: 升级进行中
|
||||
- `success`: 升级成功完成
|
||||
- `failed`: 升级失败
|
||||
- `completed`: 升级完成（等效于success）
|
||||
|
||||
## 实现细节
|
||||
|
||||
### 固件管理机制
|
||||
|
||||
1. **自动扫描固件目录**：系统在启动时会自动扫描 `assets/firmware` 目录，识别所有格式为 `{version}.bin` 的固件文件。
|
||||
|
||||
2. **版本识别机制**：固件文件命名必须符合 `x.y.z.bin` 格式，其中 x.y.z 为版本号（例如：`1.2.3.bin`）。
|
||||
|
||||
3. **自动更新系统配置**：系统会自动识别最新版本的固件，并更新系统配置中的 `latest_firmware_version` 和 `update_firmware_url`。
|
||||
|
||||
4. **简化部署流程**：管理员只需将新固件上传到 `assets/firmware` 目录，系统会自动完成后续配置。
|
||||
|
||||
### 后台服务实现特点
|
||||
|
||||
1. **版本比较机制**：服务器代码使用特定的版本比较逻辑。当设备版本为`unknown`或`0.0.0`时，会被视为需要更新。
|
||||
|
||||
2. **数据库存储**：
|
||||
- 使用`DeviceFirmwareUpdate`表记录设备固件版本和更新状态
|
||||
- 使用`SystemConfig`表存储最新固件版本(`latest_firmware_version`)和下载URL(`update_firmware_url`)
|
||||
|
||||
3. **缓存机制**：设备固件信息使用内存缓存减少数据库查询，缓存有过期时间控制
|
||||
|
||||
4. **进度控制**：升级进度以0-100的浮点数表示，由设备上报，服务器保存
|
||||
|
||||
5. **设备在线状态**：status接口会返回设备是否在线，通过检查WebSocket连接状态判断
|
||||
|
||||
### 注意事项
|
||||
|
||||
1. **设备认证**：所有API请求需要设备ID和序列号认证
|
||||
|
||||
2. **重启后自动上报**：设备重启后，应在WebSocket连接建立后主动上报固件版本
|
||||
|
||||
3. **错误处理**：
|
||||
- 设备不在线时，服务器会返回相应的错误信息
|
||||
- 版本获取失败时，服务器会尝试等待一段时间后再判断升级状态
|
||||
|
||||
4. **进度报告**：
|
||||
- 设备应该定期上报升级进度，特别是在状态发生变化时
|
||||
- 每个百分比变化或每5%的进度变化应上报一次
|
||||
|
||||
5. **安全性**：
|
||||
- 固件URL应该是安全的HTTPS链接
|
||||
- 设备应验证固件的完整性和来源
|
||||
Reference in New Issue
Block a user