OTA升级 - 阿里云物联网平台

设备上报OTA模块版本

数据上行。

Topic：/ota/device/inform/${productKey}/${deviceName}。

设备通过这个Topic上报当前的OTA模块版本信息。

重要本Topic只支持单个模块的版本上报。如果设备需要上报多个模块的版本，请分多次上报，每次上报一个模块的版本信息。

请求数据格式：

{
    "id": "123",
    "params": {
        "version": "1.0.1",
        "module": "MCU"
    }
}

表 1. 参数说明
参数	类型	说明
id	String	消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
version	String	OTA模块版本。
module	String	OTA模块名。说明上报默认（default）模块的版本号时，可以不上报module参数。设备的默认（default）模块的版本号代表整个设备的固件版本号。

物联网平台推送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"
}

多个文件的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"
}

表 2. 参数说明
参数	类型	说明
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/device/progress/${productKey}/${deviceName}。

OTA升级过程中，设备可以通过这个Topic上报OTA升级的进度百分比。

说明建议设置设备端上报进度频率为3秒内最多一次。若设备上报进度频繁，在物联网平台控制台的OTA升级包详情的批次详情中，可能无法查看到上报的全部进度。

请求数据格式：

{
    "id": "123",
    "params": {
        "step": "-1",
        "desc": "OTA升级失败，请求不到升级包信息。",
        "module": "MCU"
    }
}

表 3. 参数说明
参数	类型	说明
id	String	消息ID号。String类型的数字，取值范围0~4294967295，且每个消息ID在当前设备中具有唯一性。
step	String	OTA升级进度。取值范围： 1~100的整数：升级进度百分比。 `-1`：升级失败。 `-2`：下载失败。 `-3`：校验失败。 `-4`：烧写失败。设备上报的进度值及其描述信息，可根据设备实际升级场景在设备端配置。设备端配置方法，请参见设备端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"
}

表 4. 参数说明
参数	类型	说明
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"
        }
    }
}

多个文件的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升级包信息的参数表。

无升级包信息下发。返回数据格式如下：

{
    "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
        }
    }
}

表 6. 参数说明
参数	类型	说明
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
    }
}

表 7. 参数说明
参数	类型	说明
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值相同。单位字节。

阿里云物联网平台：OTA升级

设备上报OTA模块版本

物联网平台推送OTA升级包信息

设备上报升级进度

设备请求OTA升级包信息

设备请求下载文件分片

相关文档