物联网平台提供OTA升级与管理服务。本文介绍OTA升级消息的Topic和Alink数据格式,包括设备上报OTA模块版本、物联网平台推送升级包信息、设备上报升级进度和设备请求获取最新升级包信息。

设备进行OTA升级的完成流程,请参见OTA升级流程

设备上报OTA模块版本

数据上行。

Topic:/ota/device/inform/${YourProductKey}/${YourDeviceName}

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

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

Alink请求数据格式:

{
  "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/${YourProductKey}/${YourDeviceName}

物联网平台通过这个Topic推送OTA升级包信息, 设备订阅该Topic可以获得升级包信息。

  • 单个文件的OTA升级包信息:
    {
      "code": "1000",
      "data": {
        "size": 432945,
        "version": "2.0.0",
        "isDiff": 1,
        "url": "https://***/nopoll_0.4.4.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=XfgJu7P6DW***qAKU%3D&security-token=***Tz2IHtIf3***",
        "md5": "93230c3bde425a9d***",
        "sign": "93230c3bde425a9d****",
        "signMethod": "MD5",
        "module": "MCU",
        "extData":{
            "key1":"value1",
            "key2":"value2",
            "_package_udi":"{"ota_notice":"升级底层摄像头驱动,解决视频图像模糊的问题。"}"
         }
      },
      "id": 1626969597470,
      "message": "success"
    }
  • 多个文件的OTA升级包信息:
    {
      "code": "1000",
      "data": {
        "version": "2.0.0",
        "isDiff": 1,
        "signMethod": "MD5",
        "files":[
                    {
                        "fileSize":432944,
                        "fileName":"file1-name",
                        "fileUrl":"https://***/nopoll_0.4.3.tar.gz?Expires=1502955804&OSSAccessKeyId=***&Signature=***XJEH0qAKU%3D&security-token=CAISuQJ***",
                        "fileMd5":"93230c3bde425a9d***",
                        "fileSign":"93230c3bde425a9d****"
                    },
                    {
                        "fileSize":432945,
                        "fileName":"file2-name",
                        "fileUrl":"https://***/nopoll_0.4.4.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升级包中仅有一个升级包文件时,包含该参数。

isDiff Long 仅当升级包类型为差分时,消息包含此参数。

取值为1,表示仅包含新版本升级包与之前版本的差异部分,需要设备进行差分还原。

sign String 升级包签名。

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/${YourProductKey}/${YourDeviceName}

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

Alink请求数据格式:

{
  "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:烧写失败。
desc String 当前步骤的描述信息,长度不超过128个字符。如果发生异常,此字段可承载错误信息。
module String 升级包所属的模块名。模块的更多信息,请参见添加升级包
说明 上报默认(default)模块的OTA升级进度时,可以不上报module参数。

设备请求OTA升级包信息

数据上行。

请求Topic:/sys/{YourProductKey}/{YourDeviceName}/thing/ota/firmware/get

响应Topic:/sys/{YourProductKey}/{YourDeviceName}/thing/ota/firmware/get_reply

Alink请求数据格式:

{
  "id": "123",
  "version": "1.0",
  "params": {
      "module": "MCU"
  },
  "method": "thing.ota.firmware.get"
}
表 4. 参数说明
参数 类型 说明
id String 消息ID号。String类型的数字,取值范围0~4294967295,且每个消息ID在当前设备中具有唯一性。
version String Alink协议版本,固定为1.0。
params String 请求参数。
module String 升级包所属的模块名。
说明 不指定则表示请求默认(default)模块的升级包信息。
method String 请求方法,取值thing.ota.firmware.get

物联网平台收到设备请求后,响应请求。

  • 下发升级包信息。返回数据格式如下:
    • 单个文件的OTA升级包信息:
      {
        "id": "123",
        "code": 200,
        "data": {
          "size": 93796291,
          "sign": "f8d85b250d4d787a9f483d89a974****",
          "version": "1.0.1.9.20171112.1432",
          "isDiff": 1,
          "url": "https://the_firmware_url",
          "signMethod": "MD5",
          "md5": "f8d85b250d4d787a9f483d89a9747348",
          "module": "MCU",
          "extData":{
              "key1":"value1",
              "key2":"value2",
              "_package_udi":"{"ota_notice":"升级底层摄像头驱动,解决视频图像模糊的问题。"}"
           }
        }
      }
    • 多个文件的OTA升级包信息:
      {
        "id": "123",
        "code": 200,
        "data": {
          "version": "2.0.0",
          "isDiff": 1,
          "signMethod": "MD5",
          "files":[
                      {
                          "fileSize":432944,
                          "fileName":"file1-name",
                          "fileUrl":"https://iotx-ota-pre.oss-cn-shanghai.aliyuncs.com/nopoll_0.4.3.tar.gz?Expires=1502955804&OSSAccessKeyId=XXXXXXXXXXXXXXXXXXXX&Signature=XfgJu7P6DWWejstKJgXJEH0qAKU%3D&security-token=CAISuQJ1q6Ft5B2yfSjIpK6MGsyN1Jx5jo6mVnfBglIPTvlvt5D50Tz2IHtIf3NpAusdsv03nWxT7v4flqFyTINVAEvYZJOPKGrGR0DzDbDasumZsJbo4f%2FMQBqEaXPS2MvVfJ%2BzLrf0ceusbFbpjzJ6xaCAGxypQ12iN%2B%2Fr6%2F5gdc9FcQSkL0B8ZrFsKxBltdUROFbIKP%2BpKWSKuGfLC1dysQcO1wEP4K%2BkkMqH8Uic3h%2Boy%2BgJt8H2PpHhd9NhXuV2WMzn2%2FdtJOiTknxR7ARasaBqhelc4zqA%2FPPlWgAKvkXba7aIoo01fV4jN5JXQfAU8KLO8tRjofHWmojNzBJAAPpYSSy3Rvr7m5efQrrybY1lLO6iZy%2BVio2VSZDxshI5Z3McKARWct06MWV9ABA2TTXXOi40BOxuq%2B3JGoABXC54TOlo7%2F1wTLTsCUqzzeIiXVOK8CfNOkfTucMGHkeYeCdFkm%2FkADhXAnrnGf5a4FbmKMQph2cKsr8y8UfWLC6IzvJsClXTnbJBMeuWIqo5zIynS1pm7gf%2F9N3hVc6%2BEeIk0xfl2tycsUpbL2FoaGk6BAF8hWSWYUXsv59d5Uk%3D",
                          "fileMd5":"93230c3bde425a9d7984a594ac55ea1e",
                          "fileSign":"93230c3bde425a9d7984a594ac55****"
                      },
                      {
                          "fileSize":432945,
                          "fileName":"file2-name",
                          "fileUrl":"https://iotx-ota-pre.oss-cn-shanghai.aliyuncs.com/nopoll_0.4.4.tar.gz?Expires=1502955804&OSSAccessKeyId=XXXXXXXXXXXXXXXXXXXX&Signature=XfgJu7P6DWWejstKJgXJEH0qAKU%3D&security-token=CAISuQJ1q6Ft5B2yfSjIpK6MGsyN1Jx5jo6mVnfBglIPTvlvt5D50Tz2IHtIf3NpAusdsv03nWxT7v4flqFyTINVAEvYZJOPKGrGR0DzDbDasumZsJbo4f%2FMQBqEaXPS2MvVfJ%2BzLrf0ceusbFbpjzJ6xaCAGxypQ12iN%2B%2Fr6%2F5gdc9FcQSkL0B8ZrFsKxBltdUROFbIKP%2BpKWSKuGfLC1dysQcO1wEP4K%2BkkMqH8Uic3h%2Boy%2BgJt8H2PpHhd9NhXuV2WMzn2%2FdtJOiTknxR7ARasaBqhelc4zqA%2FPPlWgAKvkXba7aIoo01fV4jN5JXQfAU8KLO8tRjofHWmojNzBJAAPpYSSy3Rvr7m5efQrrybY1lLO6iZy%2BVio2VSZDxshI5Z3McKARWct06MWV9ABA2TTXXOi40BOxuq%2B3JGoABXC54TOlo7%2F1wTLTsCUqzzeIiXVOK8CfNOkfTucMGHkeYeCdFkm%2FkADhXAnrnGf5a4FbmKMQph2cKsr8y8UfWLC6IzvJsClXTnbJBMeuWIqo5zIynS1pm7gf%2F9N3hVc6%2BEeIk0xfl2tycsUpbL2FoaGk6BAF8hWSWYUXsv59d5Uk%3D",
                          "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/{YourProductKey}/{YourDeviceName}/thing/ota/firmware/get数据中的id

    code Integer 状态码,200表示成功。
    version String 设备升级包的版本信息。
    isDiff Long 仅当升级包类型为差分时,消息包含此参数。

    取值为1,表示仅包含新版本升级包与之前版本的差异部分,需要设备进行差分还原。

    size Long 升级包文件总大小,单位:字节。
    url String 升级包在对象存储(OSS)上的存储地址。

    OTA升级包中仅有一个升级包文件时,包含该参数。

    sign String 升级包签名。

    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相同。
  • 无升级包信息下发。返回数据格式如下:
    {
      "id": "123",
      "code": 200,
      "data": {
      }
    }