物联网平台提供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"
    }
}
表 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:升级包文件的名称。
  • fileUrlfileMd5fileSign:含义与urlmd5sign相同。

设备上报升级进度

数据上行。

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值相同。单位字节。

相关文档

错误码说明及解决办法,请参见设备端接收的错误码