IoT Platform provides the 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. It describes how a device reports OTA module versions and update progress, and requests to obtain the latest update package information. It also describes how IoT Platform sends update package information.

For more information about how to implement OTA updates, see Update devices by using OTA and Push firmware files to devices.

Report OTA module versions to IoT Platform

A device reports a OTA module version to a topic in the following format:

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

Note The topic allows the device to report only the version of a module at a time. If the device reports the versions of multiple modules, the device must report these versions in batches.

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 message ID. 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.

Send update package information to the device

IoT Platform sends update package information to a topic in the following format:

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

The 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 Value Description
id String The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
message String The result.
code String The HTTP status code.
version String The version of the update package.
size Long The size of the update package. Unit: bytes.
url String The endpoint of the Object Storage Service (OSS) bucket that stores the update package.
isDiff Long If the update package type is differential, the message includes the isDiff parameter that is set to 1. The value 1 indicates that the update package file is 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 form the new update package. If the update package type is full, this parameter is not included.
sign String The update package signature.
signMethod String The signature algorithm. Valid values:
  • SHA256
  • Md5
The MD5 algorithm is available only for Android differential packages.
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 belongs.
Note If the name of the default module is specified, IoT Platform does not send the module parameter.
extData Object Tag list of the update batch.

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

Report the update progress

During OTA updates, the device reports the update progress to a topic in the following format. Percentages are used to indicate the update progress.

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

Sample request in the Alink JSON format:

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

The progress information of the OTA update.

Valid values:
  • 1 to 100: indicates a percentage of 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 writing failed.
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 belongs.
Note If the device reports the update package version of the default module, the module parameter is optional.

Request the latest update package information

You can use topics in the following formats to implement requests for update package information.

Request topic: /sys/{productKey}/{deviceName}/thing/config/get

Response topic: /sys/{productKey}/{deviceName}/thing/property/desired/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 Value Description
id String The message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
version String The version of the Alink protocol. Valid value: 1.0.
params String The request parameters.
module String The name of the module to which the update package belongs.
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 device request, it sends a response.

  • IoT Platform sends update package information. 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 message ID. Valid values: 0 to 4294967295. Each message ID must be unique for the device.
    code Integer The HTTP status code. The value 200 indicates a successful request.
    version String The version of the update package.
    isDiff Long If the update package type is differential, the message includes the isDiff parameter that is set to 1. The 1 value indicates that the update package file is 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 form the new 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 endpoint of the OSS bucket that is used to store the update package.
    sign String The update package signature.
    signMethod String The signature algorithm. Valid values:
    • SHA256
    • Md5
    The MD5 algorithm is available only for Android differential packages.
    md5 String If the signature algorithm is MD5, you must specify the required values for the sign and md5 parameters.
    module String The name of the module to which the update package belongs.
    Note If the device requests the update package information of the default module, IoT Platform does not send the module parameter.
    extData Object Tag list 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": {
      }
    }