物联网平台提供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：升级包文件的名称。
  • fileUrl、fileMd5、fileSign：含义与url、md5、sign相同。

设备上报升级进度

数据上行。

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：烧写失败。

设备上报的进度值及其描述信息，可根据设备实际升级场景在设备端配置。设备端配置方法，请参见设备端Link SDK的OTA升级。

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：升级包文件的名称。
    • fileUrl、fileMd5、fileSign：含义与url、md5、sign相同。
  • 无升级包信息下发。返回数据格式如下： 
    {
  "id": "123",
  "code": 200,
  "data": {
  }
}