IoT Platform provides the over-the-air (OTA) update and management feature. This topic describes the topics and 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 the update progress, and devices request information about the latest update packages.

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

Submit OTA module versions to IoT Platform

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

Topic: /ota/device/inform/${productKey}/${deviceName}.

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

Important 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:

{
    "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 the information about an OTA update package to a device

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

Topic: /ota/device/upgrade/${productKey}/${deviceName}.

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

  • Sample information about an OTA update package that contains a single file:
    • Download the OTA update package over 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\":\"Update the camera driver to prevent blurry videos. \"}"
              }
          },
          "id": 1626969597470,
          "message": "success"
      }
    • Download the OTA update package over 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"
      }
  • You can download an OTA update package that contains multiple files only over HTTP. Sample information:
    {
        "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\":\"Update the 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 response message.
code String The HTTP status code.
version String The version of the OTA update package.
size Long The size of the update package. Unit: bytes.

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

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

This parameter is available if the OTA update package contains a single file and the download protocol is HTTPS.

dProtocol String The protocol that is used to download the OTA update package.

This parameter is available if the download protocol is MQTT.

streamId Long The unique ID generated when you download the OTA update package over MQTT.

This parameter is available if the download protocol is MQTT.

streamFileId Integer The unique ID of the OTA update package that contains a single file.

This parameter is available if the download protocol is MQTT.

isDiff Long This parameter is available if an update package is a delta update package.

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

digestsign String The signature of the OTA update package after a secure update is performed. This parameter is available if the secure update feature is enabled for an OTA update package. For more information about how to enable the secure update feature, see Add an update package.
sign String The signature of the OTA update package.

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

signMethod String The signature algorithm. Valid values:
  • SHA256
  • MD5
Delta update packages for Android support only the MD5 algorithm.
md5 String If the signature algorithm is MD5, IoT Platform specifies values for the sign and md5 parameters.

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

module String The name of the module to which the OTA update package is applied.
Note If the OTA update package is applied 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 you want IoT Platform to push to the device.

_package_udi specifies the custom information.

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

files Array The information about files in an update package.

This parameter is available if the OTA update package contains multiple files. Information about a single 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/${productKey}/${deviceName}.

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

Note We recommend that you set the progress reporting frequency to a maximum of once every 3 seconds. If the actual frequency exceeds the limit, you may fail to view all the progress information on the Batch Details page of the OTA update package in the IoT Platform console.

Sample request:

{
    "id": "123",
    "params": {
        "step": "-1",
        "desc": "OTA update failed because no update package information 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: indicates that the firmware flashing failed.

The progress value and description of OTA updates can be configured in the device based on actual requirements. For more information about how to develop the OTA update feature in a device, see Sample code.

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 OTA update package is applied. 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 the information about an OTA update package

The following topics are used when a device sends data to IoT Platform:

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

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

Sample request:

{
    "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 protocol. Set the value to 1.0.
params Object The request parameters.
module String The name of the module to which the OTA update package is applied.
Note If you do not configure 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 responses:
    • Sample information about an OTA update package that contains a single file:
      • Download the OTA update package over 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\":\"Update the camera driver to prevent blurry videos. \"}"
                }
            }
        }
      • Download the OTA update package over 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"
                }
            }
        }
    • You can download an OTA update package that contains multiple files only over HTTP. Sample information:
      {
          "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\":\"Update the 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 must be 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/${productKey}/${deviceName}/thing/ota/firmware/get topic.

    code Integer The status code. A value of 200 indicates a successful request.
    data Object The information about the OTA update package. For more information, see Push the information about an OTA update package to a device.
  • IoT Platform sends a response if no update package information exists. Sample response:
    {
        "id": "123",
        "code": 200,
        "data": {
        }
    }

Initiate requests to download package segments

If the download protocol of the OTA update package is MQTT, a device can download the OTA update package by segment. The following topics are used:

Important An update package downloaded by using the MQTT protocol can be up to 16 MB in size.
  • Request topic: /sys/${productKey}/${deviceName}/thing/file/download.
  • Response topic: /sys/${productKey}/${deviceName}/thing/file/download_reply.

Sample request:

{
    "id": "123456",
    "version": "1.0",
    "params": {
        "fileToken":"1bb8***",
        "fileInfo":{
            "streamId":1234565,
            "fileId":1
        },
        "fileBlock":{
            "size":256,
            "offset":2
        }
    }
}
Table 6. 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 protocol. Set the value to 1.0.
params Object The request parameters.
fileToken String Optional. The unique token that is used to identify the update package. The value can be up to 16 characters in length and can contain digits, letters, underscores (_), and periods (.).

Usage notes:

  • If you configure this parameter, IoT Platform returns this parameter in the response. This allows you to identify different update packages when you download multiple update packages to the device.
  • If you do not need to download multiple update packages at the same time, you can leave this parameter empty.
fileInfo Object The information about the OTA update package.
streamId Long The unique ID generated when you download the OTA update package over MQTT.
fileId Integer The unique ID of the OTA update package.
fileBlock Object The information about each segment.
size Integer The size of each segment to be downloaded. Unit: bytes. Valid values: 256 to 131072. For the last segment, the value ranges from 1 to 131072.
offset Integer The starting position of the last segment on the update package that is downloaded by segment. Unit: bytes. Valid values: 0 to 16777216.

Sample responses:

  • The following figure shows the data structure of a response.Data structure
    Field Description
    JSON Bytes Length Specifies the length of the byte array that is converted from the JSON string in the response. The byte array must be two bytes in length. The first byte is the high byte and the second byte is the low byte.

    For example, the UTF-8-encoded JSON string in the response is converted to a byte array. The length of the byte array is a decimal digit 87, which corresponds to a hexadecimal digit 57. The high byte is 0x00 and the low byte is 0x57.

    JSON String Bytes Specifies the byte array that is converted from the JSON string in the response. The encoding format is UTF-8. For more information, see the "Sample JSON response" section of this topic.
    File Block Bytes Specifies the byte array of the segment. The bytes are sorted in ascending order based on the offset between each byte and the package header.
    CRC16/IBM Specifies the check value of the segment. The check value must be two bytes in length. Only CRC-16-IBM is supported. The first byte is the high byte and the second byte is the low byte.

    For example, if the check value of a segment is 0x0809, the high byte is 0x08 and the low byte is 0x09.

  • Sample JSON response:
    {
        "id": "123456",
        "code":200,
        "msg":"file size has exceeded the limit 16 MB",
        "data": {
            "fileToken":"1bb8***",
            "fileLength":1238848,
            "bSize":1491,
            "bOffset":2
        }
    }
Table 7. 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.

The message ID in the response is the same as the message ID in the request. You can view the message ID in the id parameter in the data that is submitted to the /sys/${productKey}/${deviceName}/thing/file/download topic.

code Integer The status code. The value 200 indicates a successful request.
msg String The error message returned if the call fails.
data Object The data returned to the device.
fileToken String The unique token of the update package. If you specify a value for the fileToken parameter, this parameter is returned.
fileLength Integer The total size of the update package. Unit: bytes.
bSize Integer The size of the current segment. Unit: bytes.
bOffset Integer The starting position of the current segment on the update package. This value is the same as the value of the offset request parameter. Unit: bytes.

References

For more information about error codes and troubleshooting methods, see Error codes for devices.