banban/talkingq-url/docs/ota_flow.md

TalkingQ OTA 固件升级流程

本文档详细描述了TalkingQ设备固件OTA升级的完整流程，涉及到APP、后台服务器和ESP32设备端三方的交互。

流程概述

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

{
  "code": 0,
  "msg": "success",
  "data": {
    "status": "success",
    "need_update": true|false,
    "current_version": "x.y.z",
    "latest_version": "a.b.c"
  }
}

如果出错则返回：

{
  "code": -1,
  "msg": "错误信息",
  "data": {}
}

2. 启动固件升级

APP → 后台服务器

POST /api/ota/start/{device_id}
Headers:
  X-Device-ID: {device_id}
  X-Device-Serial: {serial_number}

后台服务器 → APP

{
  "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

{
  "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链接
   • 设备应验证固件的完整性和来源