消息格式 上报版本号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）模块代表整个设备的固件版本号。
主动拉取升级包设备发布消息到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。
物联网平台收到请求后，通过响应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时，包含该参数。
streamFileId
Integer
单个升级包文件的唯一标识。
仅升级包下载协议为MQTT时，包含该参数。
isDiff
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相同。
MQTT协议下载升级包下载协议为MQTT时，只支持单文件包下载。设备端获取OTA升级包信息后，可以选择整包下载或分片下载。
整包下载
消息格式
{
"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"
}
}
}参数说明
参数
类型
说明
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
签名方法。取值：
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升级包文件。
请求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。
响应消息格式
{
"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/sys/${productKey}/${deviceName}/thing/file/download数据中的id。
code
Integer
状态码，200表示成功。
msg
String
请求失败时，返回的错误信息。
data
Object
返回设备端的数据。
fileToken
String
文件的唯一标识Token。若请求参数传入了fileToken值，则返回该参数。
fileLength
Integer
文件的总大小，单位字节。
bSize
Integer
当前文件分片的大小，单位字节。
bOffset
Integer
当前文件分片对应字节的起始地址，与请求数据中的offset值相同。单位字节。
上报升级进度设备发布消息到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参数。