IoT Platform provides the over-the-air (OTA) update and management feature. This article describes the topics that are used to transmit OTA update messages. These messages are transmitted in the Alink JSON format. This article describes the format of messages that are used by a device to report OTA module versions, report the update progress, and request the information about the latest update package. It also describes the format of messages that are used by IoT Platform to send the information about update packages.

For more information about how to implement an OTA update, see Update devices by using OTA and Overview.

Report OTA module versions to IoT Platform

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

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

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

Note This topic allows the device to report the version of only one module at a time. If the device needs to report the versions of multiple OTA modules, the device must send multiple messages to report 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 reports the version of the default module, the module parameter is optional.
  • The version of the default module indicates the version of the device firmware.

Send update package information to a device

The following topic is used when IoT Platform sends requests 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.

Sample request in the Alink JSON format:

{
  "code": "1000",
  "data": {
    "size": 432945,
    "version": "2.0.0",
    "isDiff": 1,
    "url": "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",
    "md5": "93230c3bde425a9d7984a594ac55ea1e",
    "sign": "93230c3bde425a9d7984a594ac55****",
    "signMethod": "Md5",
    "module": "MCU",
    "extData":{
        "key1":"value1",
        "key2":"value2"
     }
  },
  "id": "1507707025",
  "message": "success"
}
Table 2. 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.
message String The returned message.
code String The status code.
version String The version of the update package.
size Long The size of the update package. Unit: bytes.
url String The Object Storage Service (OSS) URL of the update package.
isDiff Long Species whether the update package file is a differential package. If the update package type is differential, the message includes the isDiff parameter that is set to 1. A value of 1 indicates a differential package. The differential package includes only the differences between the original update package and the new update package. The device must integrate the differential package with the original update package to generate the complete update package. If the update package type is full, this parameter is not included.
sign String The signature of the update package.
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.
module String The name of the module to which the update package applies.
Note If the update package applies to the default, IoT Platform does not send the module parameter.
extData Object The tags of the update batch.

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

Report the update progress to IoT Platform

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

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

During an OTA update, the device reports 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 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 fails.
  • -2: indicates that the download fails.
  • -3: indicates that the verification fails.
  • -4: indicate that the burning fails.
desc String The description of the step parameter. If an exception occurs, this parameter contains the error message.
module String The name of the module to which the update package applies.
Note If the device reports the update progress of the default module, the module parameter is optional.

Request the information about the latest update package from IoT Platform

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 protocol. Valid value: 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. Valid value: 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. Sample response:
    {
      "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"
         }
      }
    }
    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.
    code Integer The status code. A value of 200 indicates that the request was successful.
    version String The version of the update package.
    isDiff Long Species whether the update package file is a differential package. If the update package type is differential, the message includes the isDiff parameter that is set to 1. The value 1 indicates a differential package. The differential package includes only the differences between the original update package and the new update package. The device must integrate the differential package with the original update package to generate the complete update package. If the update package type is full, this parameter is not included.
    size Long The size of the update package. Unit: bytes.
    url String The OSS URL of the update package.
    sign String The signature of the update package.
    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.
    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.

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

  • IoT Platform sends a response if no update package information exists. Sample response:
    {
      "id": "123",
      "code": 200,
      "data": {
      }
    }