IoT Platform provides the firmware update and management feature. This topic describes upstream and downstream topics and Alink protocol-based data formats when devices submit firmware versions, IoT Platform pushes firmware information, devices submit update progress, and devices query the latest firmware information during firmware updates.

For information about how to configure firmware updates, see OTA updates and Push firmware to devices.

Devices submit firmware versions

The following topic is used to submit data:

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

Devices use this topic to submit the current firmware versions.

Note This topic only supports submitting the firmware version of a single module. A device must submit the firmware versions of multiple modules separately, and submit the firmware version of a single module at a time.

Alink request format:

{
  "id": "123",
  "params": {
    "version": "1.0.1",
    "module": "MCU"
  }
}
Table 1. Parameters
Parameter Value 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 firmware.
module String The name of the module to which the firmware belongs.
Note
  • When submitting the firmware version of the default module, you do not need to specify the module parameter.
  • The firmware version of the default module indicates the firmware version of the device.

IoT Platform pushes firmware information

The following topic is used to send downstream data:

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

IoT Platform pushes firmware information to this topic. Devices subscribe to this topic to retrieve the firmware information.

Alink request format:

{
  "code": "1000",
  "data": {
    "size": 432945,
    "version": "2.0.0",
    "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"
  },
  "id": "1507707025",
  "message": "success"
}
Table 2. Parameters
Parameter Value 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 information.
code String The status code.
version String The version of the firmware.
size Long The size of the firmware. Unit: bytes.
url String The storage location of the firmware in OSS.
sign String The signature value of the firmware.
signMethod String The signature algorithm. The supported algorithms are MD5 and SHA256.
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 firmware belongs.
Note If the module name is default, IoT platform does not send the module parameter.

Submit update progress

The following topic is used to submit data:

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

During firmware updates, devices can use this topic to submit update progress percentages.

Alink request format:

{
  "id": "123",
  "params": {
    "step": "-1",
    "desc": "Firmware update has failed. No firmware information is available.",
    "module": "MCU"
  }
}
Table 3. Parameters
Parameter Value 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 information of the firmware update.

Valid values:
  • 1 to 100. Indicates the update progress percentage.
  • -1: indicates that the update failed.
  • -2: indicates that the download failed.
  • -3: indicates that the verification failed.
  • -4: indicates that the burning failed.
desc String The description of the current step. If an exception occurs, this parameter can display the error message.
module String The name of the module to which the firmware belongs.
Note When submitting the firmware version of the default module, you do not need to specify the module parameter.

Devices query the latest firmware information

The following topics are used to send data:

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

Response topic: /sys/{productKey}/{deviceName}/thing/property/desired/get_reply

Alink request format:

{
  "id": "123",
  "version": "1.0",
  "params": {
      "module": "MCU"
  },
  "method": "thing.ota.firmware.get"
}
Table 4. Parameters
Parameter Value 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. Valid value: 1.0.
params String The request parameters.
module String The name of the module to which the firmware belongs.
Note If you do not specify this parameter, the firmware information of the default module is queried.
method String The request method. Valid value: thing.ota.firmware.get.

IoT Platform responds after receiving requests from devices.

  • Return firmware information to devices. Response format:
    {
      "id": "123",
      "code": 200,
      "data": {
        "size": 93796291,
        "sign": "f8d85b250d4d787a9f483d89a974****",
        "version": "1.0.1.9.20171112.1432",
        "url": "https://the_firmware_url",
        "signMethod": "Md5",
        "md5": "f8d85b250d4d787a9f483d89a9747348",
        "module": "MCU"
      }
    }
    Table 5. Parameters
    Parameter Value 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 call was successful.
    version String The version of the firmware.
    size Long The size of the firmware. Unit: bytes.
    url String The storage location of the firmware in OSS.
    sign String The signature value of the firmware.
    signMethod String The signature method. Valid values:
    • SHA256
    • Md5
    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 firmware belongs.
    Note If the module name is default, IoT platform does not send the module parameter.
  • No firmware information is sent. Response format:
    {
      "id": "123",
      "code": 200,
      "data": {
      }
    }