OTA升级概述
更新时间：2024-09-10 11:06:57下载pdf
OTA（Over-the-Air Technology）即空中下载技术，是指通过无线网络从远程服务器中下载最新的应用或系统，从而对设备固件实现升级。主要有两个应用场景：修复已知 Bug 和增加新功能。
本文主要从设备与云端的交互逻辑，介绍 OTA 升级消息的 Topic 和数据格式，包括设备上报固件版本、云端下发 OTA 升级、设备定时拉取 OTA 升级、设备上报升级状态或进度、设备升级完成上报版本等。
使用限制
使用OTA功能的设备必须使用MQTT协议接入物联网平台，设备可以选择HTTPS协议下载升级包。
升级包的数量、大小、格式限制。
HTTPS协议下载：可以包括一个或多个文件，单个文件最大为1,000 MB。仅支持.bin、.dav、.tar、.gz、.zip、.gzip、.apk、.tar.gz、.tar.xz、.pack格式的文件。
工作原理
OTA升级步骤
步骤一：设备上报版本号
1、配置OTA
a、设备接入物联网平台。
b、设备初始化OTA功能。
c、设备配置OTA功能。
2、设备上报版本号，设备需要在首次升级前上报版本号，建议只在系统启动过程中上报一次，不需要周期循环上报。仅支持每次上报一个模块及对应的模块版本，如果需要上报多个模块的版本，请分次上报。上报的Topic和消息格式参见文末的消息格式。
步骤二、推送升级包信息
1、添加升级包，为产品添加OTA模块和升级包。
模块：由用户自定义，是同产品下设备的不同可升级模块，例如固件、软件、驱动等。默认（default）模块表示整个设备的固件。
整包：完整的升级文件，可以添加单个或多个升级包，如果添加多个示例包必须使用C语言的Link SDK。整包升级前，设备可不上报OTA模块版本。如不上报，配置批量升级时不能针对指定版本进行升级，具体说明，请参见发起升级批次任务。
差分包：仅包含新版本升级包与之前版本的差异部分，设备需要本地进行差分还原，并还原为完整升级包进行升级，差分升级可有效降低OTA升级次数消耗和设备下载差分包的流量消耗。差分升级前，设备必须上报OTA模块版本。
2、验证升级包
添加升级包时选择升级包是否需要平台验证为是，则在批量升级前，需选择部分设备用于测试。测试设备升级成功后，才能使用升级包。
3、发起升级批次任务
物联网平台向设备批量下发升级相关信息（升级包URL、版本、大小等）。发起批量升级后，在控制台显示的设备状态是待升级或待确认。当物联网平台接收到设备上报的升级进度时，设备升级正式开始，在控制台显示的设备状态是升级中。
步骤三：设备下载升级包
1、设备获取升级包信息
设备离线时不能接收OTA服务端推送的升级消息，设备再次上线后，OTA服务端验证该设备是否需要升级。如果需要升级，物联网平台再次推送升级消息给设备，否则不推送消息。
-
物联网平台推送升级包信息。设备订阅Topic：/ota/device/upgrade/${YourProductKey}/${YourDeviceName}，物联网平台对设备发起OTA升级请求后，设备通过该Topic收到升级信息。具体有以下两种情况：
a、发起升级任务时设备在线，物联网平台会直接推送升级相关信息。
b、发起升级任务时设备离线，之后设备上线，物联网平台会推送一次升级相关信息。 -
设备主动拉取升级包信息。设备向Topic发布消息，物联网平台收到消息并通过另一Topic返回升级包信息。拉取升级包的Topic和消息格式参见文末的消息格式。
-
物联网平台发给设备的HTTPS协议、MQTT协议的下载消息格式参见文末的消息格式。
2、设备使用HTTPS协议或MQTT协议下载升级包。
3、设备上报升级进度。上报进度的Topic和消息格式参见文末的消息格式。
如果设备上报进度的间隔低于3秒，在物联网平台控制台的OTA升级包详情的批次详情中，可能无法查看到上报的全部进度。
4、设备上报最新版本号。设备升级完成后，建议立即重启设备，设备上线后，立即上报新的版本号。设备上线请求和上报版本请求间隔不能超过2秒。
如果设备上报的版本与OTA服务要求的版本一致就认为升级成功，反之认为失败，这是物联网平台判断设备升级成功的唯一条件。即使升级进度上报为100%，如果不上报新的版本号，可能因为超过设备升级超时时间导致升级失败。
- Topic：/ota/device/inform/${YourProductKey}/${YourDeviceName}
消息格式
{
"id": 1,
"params": {
"version": "2.0.0"
}
}
步骤四：查看升级结果
1、查看升级情况：查看目标设备升级状态、升级包信息等。
2、查看升级包版本和成功率：查看升级后的版本分布和成功率分布统计，分析OTA升级失败原因，进而提升设备升级成功率。
消息格式
上报版本号
- Topic：/ota/device/inform/${YourProductKey}/${YourDeviceName}
- 消息格式
{
"id": 1,
"params": {
"version": "1.0.0",
"module":"mcu" //该参数如果不填，表示默认版本号default
}
}
- 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。数字可为String或Long类型，以设备端上报的数据类型为准。取值范围为0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | OTA模块版本。 |
| module | String | OTA模块名。上报默认（default）模块的版本号时，可以不上报module参数。默认（default）模块代表整个设备的固件版本号。 |
主动拉取升级包
1、设备发布消息到Topic：/sys/{productKey}/{deviceName}/thing/ota/firmware/get。
- 消息格式
{
"id": "123",
"version": "1.0",
"params": {
"module": "MCU"
},
"method": "thing.ota.firmware.get"
}
- 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本，固定为1.0。 |
| params | Object | 请求参数。 |
| module | String | 升级包所属的模块名。不指定则表示请求默认（default）模块的升级包信息。 |
| method | String | 请求方法，取值thing.ota.firmware.get |
2、物联网平台收到请求后，通过响应Topic：/sys/{productKey}/{deviceName}/thing/ota/firmware/get_reply，向设备端返回升级包信息。
HTTPS协议下载
单文件包下载
{
"id": "123",
"code": 200,
"data": {
"size": 93796291,
"sign": "f8d85b250d4d787a9f483d89a974***",
"version": "10.0.1.9.20171112.1432",
"isDiff": 1,
"url": "https://the_firmware_url",
"signMethod": "MD5",
"md5": "f8d85b250d4d787a9f48***",
"module": "MCU",
"extData":{
"key1":"value1",
"key2":"value2",
"_package_udi":"{\"ota_notice\":\"升级底层摄像头驱动，解决视频图像模糊的问题。\"}"
}
}
}
多文件包下载
{
"code": "1000",
"data": {
"version": "2.0.0",
"isDiff": 1,
"signMethod": "MD5",
"files":[
{
"fileSize":432944,
"fileName":"file1-name",
"fileUrl":"https://***/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***XJEH0qAKU%3D&security-token=CAISuQJ***",
"fileMd5":"93230c3bde425a9d***",
"fileSign":"93230c3bde425a9d****"
},
{
"fileSize":432945,
"fileName":"file2-name",
"fileUrl":"https://***/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***qAKU%3D&security-token=***q6Ft5B2y***",
"fileMd5":"93230c3bde425a92***",
"fileSign":"93230c3bde425a92****"
}
],
"module": "MCU",
"extData":{
"key1":"value1",
"key2":"value2",
"_package_udi":"{\"ota_notice\":\"升级底层摄像头驱动，解决视频图像模糊的问题。\"}"
}
},
"id": 1626969597470,
"message": "success"
}
| 参数 | 类型 | 说明 |
|---|---|---|
| id | Long | 消息ID号。每个消息ID在当前设备中具有唯一性。 |
| message | String | 结果信息。 |
| code | String | 状态码。 |
| version | String | 设备升级包的版本信息。 |
| size | Long | 升级包文件大小，单位：字节。OTA升级包中仅有一个升级包文件时，包含该参数。 |
| url | String | 升级包在对象存储（OSS）上的存储地址。OTA升级包中仅有一个升级包文件，且下载协议为HTTPS时，包含该参数。 |
| dProtocol | String | 升级包下载协议。仅升级包下载协议为MQTT时，包含该参数。 |
| streamId | Long | 通过MQTT协议下载OTA升级包时的唯一标识。仅升级包下载协议为MQTT时，包含该参数。 |
| streamField | Integer | 单个升级包文件的唯一标识。仅升级包下载协议为MQTT时，包含该参数。 |
| idDiff | Long | 仅当升级包类型为差分时，消息包含此参数。取值为1，表示仅包含新版本升级包与之前版本的差异部分，需要设备进行差分还原。 |
| digestSign | String | OTA升级包文件安全升级后的签名。仅当OTA升级包开启安全升级功能，才有此参数。开启OTA升级包安全升级功能的方法 |
| sign | String | OTA升级包文件的签名。OTA升级包中仅有一个升级包文件时，包含该参数。 |
| signMethod | String | 签名方法。取值：SHA256、MD5，对于Android差分升级包类型，仅支持MD5签名方法。 |
| md5 | String | 当签名方法为MD5时，除了会给sign赋值外还会给md5赋值。OTA升级包中仅有一个升级包文件时，包含该参数。 |
| module | String | 升级包所属的模块名。模块名为default时，物联网平台不下发module参数。 |
| extData | Object | 升级批次标签列表和推送给设备的自定义信息。_package_udi表示自定义信息的字段。单个标签格式：“key”:“value”。 |
| files | Array | 多个升级包文件的信息列表。OTA升级包中有多个文件时，包含该参数。每个升级包文件信息如下：fileSize：升级包文件大小。fileName：升级包文件的名称。fileUrl、fileMd5、fileSign：含义与url、md5、sign相同。 |
上报升级进度
- 设备发布消息到Topic：/ota/device/progress/${YourProductKey}/${YourDeviceName}。
- 消息格式
{
"id": "123",
"params": {
"step": "-1",
"desc": "OTA升级失败，请求不到升级包信息。",
"module": "MCU"
}
}
- 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| step | String | OTA升级进度。设备上报的进度值及其描述信息，可根据设备实际升级场景在设备端配置。设备端配置方法，请参见示例代码说明。1~100的整数：升级进度百分比。-1：升级失败。-2：下载失败。-3：校验失败。-4：烧写失败。 |
| desc | String | 当前步骤的描述信息，长度不超过128个字符。如果发生异常，此字段可承载错误信息。 |
| module | String | 升级包所属的模块名。上报默认（default）模块的OTA升级进度时，可以不上报module参数。 |
