OTA 升级

流程

① 设备 ──▶ 平台：/ota/device/inform 上报当前版本
② 平台 ──▶ 设备：/ota/device/upgrade 推送升级指令（批次）
③ 设备 ──▶ 平台：/ota/device/progress step=0（升级开始）
④ 设备本地执行：下载固件并校验 MD5
⑤ 设备 ──▶ 平台：/ota/device/progress step=10..100（进度上报）
⑥ 设备 ──▶ 平台：/ota/device/inform 上报新版本
⑦ 平台：上报版本与目标版本匹配，批次设备状态置为成功

注意：升级是否「成功」以设备上报的新版本与批次目标版本匹配为准，progress step=100 本身不会把批次置为成功。

上报当前软件版本

Topic：/ota/device/inform/{pk}/{dn}

{ "id": "ver-0001", "params": { "version": "1.0.3", "module": "default" } }

module 省略时为 default。平台按 设备 + module 保存版本；若该设备存在进行中的批次，上报版本等于目标版本即判成功，不等于目标版本判失败（按批次重试次数处理）。版本串不能包含逗号，否则忽略。

上报升级进度

Topic：/ota/device/progress/{pk}/{dn}

{ "id": "prog-0001", "params": { "step": "50", "desc": "downloading", "module": "MCU" } }

step	含义
0	升级开始（若批次配置了超时，会注册超时任务）
1–99	百分比进度
100	下载/烧写完成（平台仅记录进度，完成判定见 inform）
-1	升级失败
-2	下载失败
-3	校验失败
-4	烧写失败

step 按字符串读取（数字也可），module 缺省 default，失败时 desc 会写入批次设备的失败原因。

设备主动查询固件

Topic：/sys/{pk}/{dn}/thing/ota/firmware/get

{ "id": "fw-0001", "version": "1.0", "params": { "module": "MCU" }, "method": "thing.ota.firmware.get" }

回复 Topic /sys/{pk}/{dn}/thing/ota/firmware/get_reply（QoS1）：

{
  "id": "fw-0001", "timestamp": 1700000000000, "code": 200,
  "data": {
    "version": "2.0.0", "isDiff": 1, "module": "MCU",
    "files": [
      { "fileSize": 432944, "fileName": "app.bin",
        "fileUrl": "https://…/app.bin?Expires=…&Signature=…",
        "fileMd5": "93230c3bde425a9d7984a594ac55ea1e",
        "fileSign": "93230c3bde425a9d7984a594ac55ea1e" }
    ],
    "extData": { "_package_udi": "{\"ota_notice\":\"修复联网问题\"}" }
  }
}

没有匹配到待升级批次或固件时，data 为 {}，设备据此判断「无升级任务」。

平台批量推送升级指令

Topic：/ota/device/upgrade/{pk}/{dn}（QoS1，注意 code 是字符串 "1000"）

单文件：

{
  "id": 1686406355090, "code": "1000", "message": "success",
  "data": {
    "size": 491856, "digestSign": "…", "sign": "59dc8bdc16564bec68b2c61334222c50",
    "version": "3.0.0", "signMethod": "Md5",
    "url": "https://…/firmware.bin?Expires=…", "md5": "59dc8bdc16564bec68b2c61334222c50"
  }
}

多文件：

{
  "id": 1686406355090, "code": "1000", "message": "success",
  "data": {
    "version": "2.0.0", "isDiff": 1, "module": "MCU", "signMethod": "Md5",
    "files": [ { "fileSize": 432944, "fileName": "boot.bin", "fileUrl": "https://…", "fileMd5": "…", "fileSign": "…" } ],
    "extData": { "_package_udi": "…", "自定义标签": "值" }
  }
}

设备侧要点：下载完成后必须按 md5 / fileMd5 校验，再烧写；升级指令可能在设备上线后被批次自动补推，因此要按 id 与 version 去重，避免重复下载。

遗留通道（勿用）

/{pk}/{dn}/firmware/upgrade（简易升级，payload {sign, signMethod, size, url}）与 /{pk}/{dn}/firmware/pull/reply 仍走早期 Mica Redis 流下发，在当前 EMQX 架构下通常不会送达设备。新项目请只使用本文的「主动查询」与「批量推送」方式。