文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>物联网开发平台>设备端开发指南>设备通信协议介绍>OTA 升级协议

OTA 升级协议

最近更新时间：2025-10-11 15:44:42

我的收藏

本页目录：

物联网开发平台提供 OTA 升级与管理服务。本文介绍 OTA 升级消息的 Topic 和数据格式，包括设备上报 OTA 模块版本、平台下发升级任务、设备上报升级进度和设备请求获取最新升级包信息等。

操作场景

设备固件升级又称 OTA，是物联网通信服务的重要组成部分。当物联设备有新功能或者需要修复漏洞时，设备可以通过 OTA 服务快速的进行固件升级。

实现原理

固件升级的过程中，需要设备订阅下面两个 Topic 来实现与云端的通信，如下图所示：


操作流程

设备的升级流程如下所示：
OTA 时序图
OTA 时序图

1. 设备上报当前版本号。设备端通过 MQTT 协议发布一条消息到 Topic $ota/report/${productID}/${deviceName}，进行版本号的上报，消息为 JSON 格式，内容如下：
{
	"type": "report_version",
	"report": {
		"fw_type": "mcu",
		"version": "0.1"
	}
}
// type：消息类型
// version：上报的版本号
// fw_type: 上报的模块名
2. 然后您可以在控制台上传固件，以及将指定的设备升级到指定的版本。具体操作方法可参见：OTA 升级概述
3. 版本上报回复$ota/update/${productID}/${deviceName}
{
  "type": "report_version_rsp",
  "version": "2.0",
  "result_code": 0,
  "result_msg": "success",
  "fw_type": "mcu"
}
4. 平台下发升级任务$ota/update/${productID}/${deviceName}
{
	"file_size": 708482,
	"md5sum": "36eb5951179db14a63****a37a9322a2",
	"type": "update_firmware",
	"url": "https://ota-1255858890.cos.ap-guangzhou.myqcloud.com",
	"version": "0.2",
	"task_id": 123456,
	"fw_type": "mcu"
}
// type：消息类型为 update_firmware
// version：升级版本
// url：下载固件的 url
// md5sum：固件的 MD5值
// file_size：固件大小，单位为字节
// fw_type: 上报模块
// task_id: 任务 ID
5. 上报下载进度$ota/report/${productId}/${deviceName} 
{
	"type": "report_progress",
	"report": {
		"progress": {
			"state": "downloading",
			"percent": "10",
			"result_code": "0",
			"result_msg": ""
		},
		"version": "0.2",
		"fw_type": "mcu",
		"task_id": 123456
	}
}
// state：downloading：表示正在下载中
// result_code：0：下载成功
// result_msg：错误消息
6. 上报设备升级状态$ota/report/${productId}/${deviceName} 
{
	"type": "report_progress",
	"report": {
		"progress": {
			"state": "burning",
			"result_code": "0",
			"result_msg": ""
		},
		"version": "0.2",
		"fw_type": "mcu",
		"task_id": 123456
	}
}
// result_code：0：下载成功；
7. 上报升级成功$ota/report/${productId}/${deviceName} 
{
	"type": "report_progress",
	"report": {
		"progress": {
			"state": "fail",
			"result_code": "-1",
			"result_msg": "time_out"
		},
		"version": "0.2",
		"fw_type": "mcu",
		"task_id": 123456
	}
}
// state： downloading、burning、fail、done、updating
// result_code：-1：下载超时；
// result_msg：错误消息

参数说明

参数名称
参数描述
type
消息类型。
fw_type
上报的模块名。
version
当前设备的固件版本号。
state
downloading：表示正在下载中。
burning：表示烧录中。
done：表示完成。
fail：表示失败 。
result_code
错误码：
0：下载成功。
-1：下载超时。
-2：文件不存在。
-3：签名过期。
-4：MD5 不匹配。
-5：更新固件失败。
result_msg
错误消息。
url
下载固件的 url。
md5sum
固件的 MD5 值。
file_size
固件大小，单位为字节。
task_id
任务 ID。

OTA 断点续传

物联网设备有部分场景处于弱网环境，在这个场景下连接会不稳定，固件下载会中断的情况出现。如果每次都从0偏移开始下载固件，则弱网环境有可能一直无法完成全部固件下载，因此固件的断点续传功能特别必要。
断点续传指从文件上次中断的地方开始重新下载或上传，要实现断点续传的功能，需要设备端记录固件下载的中断位置，同时记录下载固件的 MD5、文件大小、版本信息。
平台针对 OTA 中断的场景，设备侧 report 设备的版本，如果上报的版本号与要升级的目标版本号不一致，则平台会再次下发固件升级消息，设备获取到升级的目标固件的信息与本地记录的中断的固件信息比较，确定为同一固件后，基于断点继续下载。
带断点续传的 OTA 升级流程如下：
OTA 断点续传时序图
OTA 断点续传时序图


中国站
目录