banban/docs/OTA进度上报协议与后端接入说明.md

OTA 下载进度上报协议说明

1. 目的

在当前 OTA 协议基础上增加下载进度上报。

本次只增加进度，不修改以下内容：

• OTA 下发主题不变；
• OTA 下发报文不变；
• OTA 响应主题不变；
• msg_id 继续使用 003；
• 当前的 accepted 和 success 响应保持不变；
• 不增加任务 ID、错误码、新主题或新的 OTA 状态机。

设备端可以先发布。后端尚未处理进度消息时，不影响设备执行 OTA；后端后续只需增加对 status=updating 的解析。

2. 当前 OTA 下发协议

下发主题：

device/{imei}/command

下发报文保持不变：

{
  "msg_id": "003",
  "time": "1791853200000",
  "params": {
    "url": "http://banban.api.talkingq.com:8080/path/fota.bin",
    "version": "2.0.4"
  }
}

3. OTA 上报主题

设备继续使用当前响应主题：

device/{imei}/response

4. 接受 OTA

设备接受 OTA 命令后，继续发送当前报文：

{
  "msg_id": "003",
  "status": "accepted",
  "data": {
    "current_version": "2.0.3",
    "target_version": "2.0.4"
  }
}

该报文表示设备已经接受 OTA 命令，不表示下载已经完成。

5. 新增下载进度上报

设备下载 FOTA 包时，每增加 10% 上报一次：

{
  "msg_id": "003",
  "status": "updating",
  "data": {
    "target_version": "2.0.4",
    "progress": 30
  }
}

字段说明：

字段	类型	说明
msg_id	string	固定为 003
status	string	下载进度消息固定为 updating
data.target_version	string	本次 OTA 目标版本
data.progress	number	FOTA 包下载百分比，范围为 0～100

设备建议上报以下进度值：

10、20、30、40、50、60、70、80、90、100

不需要每下载一个数据块就上报，避免产生过多 MQTT 消息。

示例：

{"msg_id":"003","status":"updating","data":{"target_version":"2.0.4","progress":10}}

{"msg_id":"003","status":"updating","data":{"target_version":"2.0.4","progress":50}}

{"msg_id":"003","status":"updating","data":{"target_version":"2.0.4","progress":100}}

注意：progress=100 只表示 FOTA 包下载完成，不表示新固件已经启动成功。

6. OTA 成功

设备下载、校验、重启并进入新 APP 后，继续发送当前成功报文：

{
  "msg_id": "003",
  "status": "success",
  "data": {
    "new_version": "2.0.4"
  }
}

后端只有收到 status=success 时，才能将本次 OTA 判断为最终成功。

7. 后端需要修改的内容

后端只需要在现有 003 响应解析中增加一种状态：

status = updating

解析逻辑：

1. 收到 accepted：记录设备已接受 OTA。
2. 收到 updating：读取 data.progress 并更新下载进度。
3. 收到 success：记录设备已经进入目标版本，OTA 最终成功。

MQTT 当前使用 QoS 1，同一条进度消息可能重复到达。后端收到重复进度时直接覆盖原进度即可，不要重复创建 OTA 任务。

如果后端收到的进度小于已经保存的进度，可以忽略较小的进度，避免进度倒退。

8. 设备端实现约定

1. 当前 accepted 和 success 报文不修改。
2. 下载任务每达到一个新的 10% 档位，上报一次 updating。
3. 进度上报仍发送到当前 response 主题。
4. 进度上报失败只记录日志，不中止 OTA 下载。
5. 下载完成后上报 progress=100。
6. progress=100 后设备继续执行文件校验和重启。
7. 新 APP 启动后仍使用当前 success 报文确认最终成功。

9. 完整交互示例

后端 -> 设备：003 OTA 命令
设备 -> 后端：003 accepted
设备 -> 后端：003 updating progress=10
设备 -> 后端：003 updating progress=20
设备 -> 后端：003 updating progress=30
...
设备 -> 后端：003 updating progress=100
设备重启并安装新 APP
设备 -> 后端：003 success