IoT Platform provides the over-the-air (OTA) update and management feature. This article describes the topics and Alink data formats that are used to transmit messages during OTA updates. The messages are transmitted when devices submit OTA module versions, IoT Platform pushes update packages to devices, devices submit update progresses, and devices request the information about the latest update packages.

For more information about how to perform OTA updates, see Procedure.

Submit OTA module versions to IoT Platform

The following topic is used when a device sends data to IoT Platform:

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

A device submits the version of an OTA module to this topic.

Notice This topic allows the device to submit the version of only one module at a time. If the device needs to submit the versions of multiple OTA modules, the device must send multiple messages to submit these versions. Each message contains the version of one module.

Sample request in the Alink JSON format:

{
  "id": "123",
  "params": {
    "version": "1.0.1",
    "module": "MCU"
  }
}
Table 1. Parameters
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version String The version of the OTA module.
module String The name of the OTA module.
Note
  • If the device submits the version of the default module, the module parameter is optional.
  • The version of the default module indicates the version of the device firmware.

Push OTA update package information to a device

The following topic is used when IoT Platform sends data to a device:

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

IoT Platform sends update package information to the preceding topic. A device can subscribe to the topic to obtain the update package information.

  • Information about an OTA update package that contains a single file:
    {
      "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":" Update the underlying camera driver to prevent blurry videos."}"
         }
      },
      "id": 1626969597470,
      "message": "success"
    }
  • Information about an OTA update package that contains multiple files:
    {
      "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":" Update the underlying camera driver to prevent blurry videos."}"
         }
      },
      "id": 1626969597470,
      "message": "success"
    }
Table 2. Parameters
Parameter Type Description
id Long The ID of the message. Each message ID is unique for the device.
message String The returned message.
code String The response code.
version String The version of the update package.
size Long The size of the update package. Unit: bytes.

This parameter is available when the OTA update package contains a single file.

url String The Object Storage Service (OSS) URL of the update package.

This parameter is available when the OTA update package contains a single file.

isDiff Long This parameter is available only if the update package is a differential package.

Set the value to 1. This value indicates that the update package contains only the differences between the new version and the previous version. In this case, a differential update is performed.

sign String The signature of the update package.

This parameter is available when the OTA update package contains a single file.

signMethod String The signature algorithm. Valid values:
  • SHA256
  • MD5
Android differential packages support only the MD5 algorithm.
md5 String If the signature algorithm is MD5, IoT Platform assigns values to the sign and md5 parameters.

This parameter is available when the OTA update package contains a single file.

module String The name of the module to which the update package applies.
Note If the update package applies to the default module, IoT Platform does not send the module parameter.
extData Object The tags of the update batch and the custom information that is pushed to the device.

_package_udi indicates the custom information.

Format of each tag: "key":"value".

files Array The information about multiple update files.

This parameter is available when the OTA update package contains multiple files.

Information about a single update file:

  • fileSize: the size of the file.
  • fileName: the name of the file.
  • fileUrl, fileMd5, and fileSign: These parameters correspond to the url, md5, and sign parameters in this table.

Submit the update progress to IoT Platform

The following topic is used when a device sends data to IoT Platform:

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

During an OTA update, the device submits the update progress as a percentage to the preceding topic.

Sample request in the Alink JSON format:

{
  "id": "123",
  "params": {
    "step": "-1",
    "desc": "The OTA update failed. No update package is found. ",
    "module": "MCU"
  }
}
Table 3. Parameters
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
step String

The progress of the OTA update.

Valid values:
  • An integer from 1 to 100: indicates a percentage that represents the update progress.
  • -1: indicates that the update failed.
  • -2: indicates that the download failed.
  • -3: indicates that the verification failed.
  • -4: indicate that the burning failed.
desc String The description of the current step. The description cannot exceed 128 characters in length. If an exception occurs, this parameter contains the error message.
module String The name of the module to which the update package applies. For more information, see Add an update package.
Note If the device submits the update progress of the default module, the module parameter is optional.

Request OTA update package information

The following topics are used when a device sends requests to IoT Platform and IoT Platform sends responses to the device:

Request topic: /sys/{productKey}/{deviceName}/thing/ota/firmware/get

Response topic: /sys/{productKey}/{deviceName}/thing/ota/firmware/get_reply

Sample request in the Alink JSON format:

{
  "id": "123",
  "version": "1.0",
  "params": {
      "module": "MCU"
  },
  "method": "thing.ota.firmware.get"
}
Table 4. Parameters
Parameter Type Description
id String The ID of the message. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version String The version of the Alink protocol. Set the value to 1.0.
params String The request parameters.
module String The name of the module to which the update package applies.
Note If you do not specify this parameter, the update package information of the default module is requested.
method String The request method. Set the value to thing.ota.firmware.get.

After IoT Platform receives a request from the device, IoT Platform sends a response.

  • IoT Platform sends the information about the latest update package to the device. Sample response:
    • Information about an OTA update package that contains a single file:
      {
        "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":" Update the underlying camera driver to prevent blurry videos."}"
           }
        }
      }
    • Information about an OTA update package that contains multiple files:
      {
        "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":" Update the underlying camera driver to prevent blurry videos."}"
           }
        }
      }
    Table 5. Parameters
    Parameter Type Description
    id String The ID of the message. Valid values: 0 to 4294967295. Each message ID is unique for the device.

    The message ID in the response is the same as that in the request. You can view the id parameter in the data that is submitted to the /sys/{YourProductKey}/{YourDeviceName}/thing/ota/firmware/get topic.

    code Integer The response code. The value 200 indicates a successful request.
    version String The version of the update package.
    isDiff Long This parameter is available only if an update package is a differential package.

    Set the value to 1. This value indicates that the update package contains only the differences between the new version and the previous version. In this case, a differential update is performed.

    size Long The size of the update package. Unit: bytes.
    url String The OSS URL of the update package.

    This parameter is available when the OTA update package contains a single file.

    sign String The signature of the update package.

    This parameter is available when the OTA update package contains a single file.

    signMethod String The signature algorithm. Valid values:
    • SHA256
    • MD5
    Android differential packages support only the MD5 algorithm.
    md5 String If the signature algorithm is MD5, IoT Platform assigns values to the sign and md5 parameters.

    This parameter is available when the OTA update package contains a single file.

    module String The name of the module to which the update package applies.
    Note If the update package applies to the default module, IoT Platform does not send the module parameter.
    extData Object The tags of the update batch and the custom information that is pushed to the device.

    _package_udi indicates the custom information.

    Format of each tag: "key":"value".

    files Array The information about multiple update files.

    This parameter is available when the OTA update package contains multiple files.

    Information about a single update file:

    • fileSize: the size of the file.
    • fileName: the name of the file.
    • fileUrl, fileMd5, and fileSign: These parameters correspond to the url, md5, and sign parameters in this table.
  • IoT Platform sends a response if no update package information exists. Sample response:
    {
      "id": "123",
      "code": 200,
      "data": {
      }
    }