物联网平台提供OTA升级与管理服务。本文介绍OTA升级消息的Topic和数据格式，包括设备上报OTA模块版本、物联网平台推送升级包信息、设备上报升级进度和设备请求获取最新升级包信息。
设备进行OTA升级的完成流程，请参见OTA升级流程。
设备上报OTA模块版本
数据上行。
Topic：/ota/device/inform/${productKey}/${deviceName}。
设备通过这个Topic上报当前的OTA模块版本信息。
重要 本Topic只支持单个模块的版本上报。如果设备需要上报多个模块的版本，请分多次上报，每次上报一个模块的版本信息。
请求数据格式：
{
"id": "123",
"params": {
"version": "1.0.1",
"module": "MCU"
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | OTA模块版本。 |
| module | String | OTA模块名。 说明
|
物联网平台推送OTA升级包信息
数据下行。
Topic：/ota/device/upgrade/${productKey}/${deviceName}。
物联网平台通过这个Topic推送OTA升级包信息， 设备订阅该Topic可以获得升级包信息。
- 单个文件的OTA升级包信息：
- 升级包下载协议为HTTPS：
{ "code": "1000", "data": { "size": 432945, "version": "2.0.0", "isDiff": 1, "url": "https://***/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P6DW***qAKU%3D&security-token=***Tz2IHtIf3***", "md5": "93230c3bde425a9d***", "digestsign":"A4WOP***SYHJ6DDDJD9***", "sign": "93230c3bde425a9d***", "signMethod": "MD5", "module": "MCU", "extData":{ "key1":"value1", "key2":"value2", "_package_udi":"{\"ota_notice\":\"升级底层摄像头驱动，解决视频图像模糊的问题。\"}" } }, "id": 1626969597470, "message": "success" } - 升级包下载协议为MQTT：
{ "code":"1000", "data":{ "size":432945, "version":"2.0.0", "isDiff":1, "signMethod":"MD5", "dProtocol":"mqtt", "streamId":1397345, "streamFileId":1, "md5":"93230c3bde425***", "digestsign":"A4WOP***SYHJ6DDDJD9***", "sign":"93230c3bde425***", "module":"MCU", "extData":{ "key1":"value1", "key2":"value2" } }, "id":1507707025, "message":"success" }
- 升级包下载协议为HTTPS：
- 多个文件的OTA升级包仅支持HTTP下载协议，信息如下：
{ "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时，包含该参数。 |
| streamFileId | Integer | 单个升级包文件的唯一标识。 仅升级包下载协议为MQTT时，包含该参数。 |
| isDiff | Long | 仅当升级包类型为差分时，消息包含此参数。 取值为1，表示仅包含新版本升级包与之前版本的差异部分，需要设备进行差分还原。 |
| digestsign | String | OTA升级包文件安全升级后的签名。仅当OTA升级包开启安全升级功能，才有此参数。开启OTA升级包安全升级功能的方法，请参见安全升级。 |
| sign | String | OTA升级包文件的签名。 OTA升级包中仅有一个升级包文件时，包含该参数。 |
| signMethod | String | 签名方法。取值：
|
| md5 | String | 当签名方法为MD5时，除了会给sign赋值外还会给md5赋值。 OTA升级包中仅有一个升级包文件时，包含该参数。 |
| module | String | 升级包所属的模块名。 说明 模块名为default时，物联网平台不下发module参数。 |
| extData | Object | 升级批次标签列表和推送给设备的自定义信息。 _package_udi表示自定义信息的字段。 单个标签格式： |
| files | Array | 多个升级包文件的信息列表。 OTA升级包中有多个文件时，包含该参数。每个升级包文件信息如下：
|
设备上报升级进度
数据上行。
Topic：/ota/device/progress/${productKey}/${deviceName}。
OTA升级过程中，设备可以通过这个Topic上报OTA升级的进度百分比。
说明 建议设置设备端上报进度频率为3秒内最多一次。若设备上报进度频繁，在物联网平台控制台的OTA升级包详情的批次详情中，可能无法查看到上报的全部进度。
请求数据格式：
{
"id": "123",
"params": {
"step": "-1",
"desc": "OTA升级失败，请求不到升级包信息。",
"module": "MCU"
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| step | String | OTA升级进度。 取值范围：
设备上报的进度值及其描述信息，可根据设备实际升级场景在设备端配置。设备端配置方法，请参见设备端Link SDK的OTA升级。 |
| desc | String | 当前步骤的描述信息，长度不超过128个字符。如果发生异常，此字段可承载错误信息。 |
| module | String | 升级包所属的模块名。模块的更多信息，请参见添加升级包。 说明 上报默认（default）模块的OTA升级进度时，可以不上报module参数。 |
设备请求OTA升级包信息
数据上行。
请求Topic：/sys/${productKey}/${deviceName}/thing/ota/firmware/get。
响应Topic：/sys/${productKey}/${deviceName}/thing/ota/firmware/get_reply。
请求数据格式：
{
"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。 |
物联网平台收到设备请求后，响应请求。
- 下发升级包信息。返回数据格式如下：
- 单个文件的OTA升级包信息：
- 升级包下载协议为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\":\"升级底层摄像头驱动，解决视频图像模糊的问题。\"}" } } } - 升级包下载协议为MQTT：
{ "id": "123", "code": 200, "data":{ "size":432945, "digestsign":"A4WOP***SYHJ6DDDJD9***", "version":"2.0.0", "isDiff":1, "signMethod":"MD5", "dProtocol":"mqtt", "streamId":1397345, "streamFileId":1, "md5":"93230c3bde***", "sign":"93230c3bde42***", "module":"MCU", "extData":{ "key1":"value1", "key2":"value2" } } }
- 升级包下载协议为HTTPS：
- 多个文件的OTA升级包仅支持HTTP下载协议，信息如下：
{ "id": "123", "code": 200, "data": { "version": "2.0.0", "isDiff": 1, "signMethod": "MD5", "files":[ { "fileSize":432944, "fileName":"file1-name", "fileUrl":"https://iotx***.aliyuncs.com/nop***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7***U%3D&security-token=CAISu***", "fileMd5":"93230c3bde425a9d7984a594ac55ea1e", "fileSign":"93230c3bde425a9d7984a594ac55****" }, { "fileSize":432945, "fileName":"file2-name", "fileUrl":"https://iotx-***.aliyuncs.com/no***.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P***KU%3D&security-token=CAISuQJ***", "fileMd5":"93230c3bde425a9d7984a594ac56ea1f", "fileSign":"93230c3bde425a9d7984a594ac56****" } ], "module": "MCU", "extData":{ "key1":"value1", "key2":"value2", "_package_udi":"{\"ota_notice\":\"升级底层摄像头驱动，解决视频图像模糊的问题。\"}" } } }
表 5. 参数说明 参数 类型 说明 id String 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 此处消息ID返回的是设备请求中的消息ID，即请求Topic
/sys/${productKey}/${deviceName}/thing/ota/firmware/get数据中的id。code Integer 状态码，200表示成功。 data Object 升级包信息，其中参数说明，请参见物联网平台推送OTA升级包信息的参数表。 - 单个文件的OTA升级包信息：
- 无升级包信息下发。返回数据格式如下：
{ "id": "123", "code": 200, "data": { } }
设备请求下载文件分片
升级包下载协议为MQTT时，设备端获取OTA升级包信息后，可通过以下Topic分片下载OTA升级包文件。
重要 设备端通过MQTT协议下载的单个文件大小不能超过16 MB。
- 请求Topic：
/sys/${productKey}/${deviceName}/thing/file/download - 响应Topic：
/sys/${productKey}/${deviceName}/thing/file/download_reply
请求数据格式：
{
"id": "123456",
"version": "1.0",
"params": {
"fileToken":"1bb8***",
"fileInfo":{
"streamId":1234565,
"fileId":1
},
"fileBlock":{
"size":256,
"offset":2
}
}
}| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 |
| version | String | 协议版本，固定为1.0。 |
| params | Object | 请求参数。 |
| fileToken | String | 文件的唯一标识Token，非必填参数。支持数字、英文字母、下划线（_）和英文句号（.），不超过16个字符。 使用说明：
|
| fileInfo | Object | OTA升级包文件信息。 |
| streamId | Long | 通过MQTT协议下载OTA升级包时的唯一标识。 |
| fileId | Integer | 单个升级包文件的唯一标识。 |
| fileBlock | Object | 文件分片信息。 |
| size | Integer | 请求下载的文件分片大小，单位字节，取值范围为256~131072。若为最后一个文件分片，取值范围为1~131072。 |
| offset | Integer | 文件分片对应字节的起始地址。取值范围为0~16777216。 |
响应数据格式：
- 结构如下图：
结构项 说明 JSON Bytes Length 表示响应数据中JSON字符串对应的字节数组长度，必须占位2个字节，高位字节在前，低位字节在后。 例如，响应的JSON字符串使用UTF-8编码转码成字节数组的长度为十进制的87，对应十六进制57，则高位字节为0x00，低位字节为0x57。
JSON String Bytes 表示响应数据中JSON字符串对应的字节数组，编码格式为UTF-8。具体内容，请参见下文的“响应的JSON数据格式”。 File Block Bytes 表示当前文件分片的字节数组，字节顺序按照相对于文件头的偏移量从小至大排列。 CRC16/IBM 表示文件分片的校验值，仅支持CRC16/IBM，占位2个字节，低位字节在前，高位字节在后。 例如，文件分片的校验值为0x0809，则低位字节为0x09，高位字节为0x08。
- 响应的JSON数据格式：
{ "id": "123456", "code":200, "msg":"file size has exceeded the limit 16 MB", "data": { "fileToken":"1bb8***", "fileLength":1238848, "bSize":1491, "bOffset":2 } }
| 参数 | 类型 | 说明 |
|---|---|---|
| id | String | 消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。 此处消息ID返回的是设备请求中的消息ID，即请求Topic |
| code | Integer | 状态码，200表示成功。 |
| msg | String | 请求失败时，返回的错误信息。 |
| data | Object | 返回设备端的数据。 |
| fileToken | String | 文件的唯一标识Token。若请求参数传入了fileToken值，则返回该参数。 |
| fileLength | Integer | 文件的总大小，单位字节。 |
| bSize | Integer | 当前文件分片的大小，单位字节。 |
| bOffset | Integer | 当前文件分片对应字节的起始地址，与请求数据中的offset值相同。单位字节。 |
相关文档
错误码说明及解决办法，请参见设备端接收的错误码。