IoT Platform supports the Over-the-Air (OTA) feature. You can use the OTA feature to update device firmware. This article describes how to use the OTA feature to update device firmware when Message Queuing Telemetry Transport (MQTT) is used to connect devices to IoT Platform. It also describes topics and data formats that are used during data forwarding.

OTA update process of device firmware

The following figure shows the process of a firmware update.process
The following topics are used during the firmware update:
  • Devices use the following topic to report firmware versions to IoT Platform.
    /ota/device/inform/${YourProductKey}/${YourDeviceName}
  • Devices receive firmware update notifications by subscribing to the following topic.
    /ota/device/upgrade/${YourProductKey}/${YourDeviceName}
  • Devices use the following topic to report the progress of the firmware update.
    /ota/device/progress/${YourProductKey}/${YourDeviceName}
Note
  • A device needs to report the firmware version only once during the startup.
  • In the IoT Platform console, after you start updating multiple devices, each device is in the Pending Update state.

    When the OTA service of IoT Platform receives the update progress that is reported by a device, the status of the device changes to Updating.

  • You can check if an OTA update is successful based on the device version.
  • An offline device cannot receive an update notification from IoT Platform.

    After the status of the device changes to online, IoT Platform identifies the change and the OTA system verifies whether the device requires an update. If an update is required, the OTA system sends an update notification to the device. Otherwise, no notification is sent.

Message format

For more information about how to use language-specific SDKs to implement OTA updates on devices, see the Link SDK documentation.

  1. To connect to the OTA system, a device must report the firmware version to a topic.

    The format of the topic is /ota/device/inform/${YourProductKey}/${YourDeviceName}. Sample message:

    {
      "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 firmware.
    module String The name of the module to which the firmware belongs.
    Note
    • If the device reports the firmware version of the default module, the module parameter is optional.
    • The firmware version of the default module indicates the firmware version of the device.
  2. In the IoT Platform console, you can add firmware, verify firmware, and update firmware.

    For more information, see Push firmware to devices.

  3. After you start a firmware update in the console, the device receives the URL of the firmware update from a topic. The message that includes the URL is sent from the OTA service of IoT Platform to the topic.

    The format of the topic is /ota/device/upgrade/${YourProductKey}/${YourDeviceName}.

    Sample message:

    {
      "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"
      },
      "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 firmware.
    size Long The size of the firmware. Unit: bytes.
    url String The endpoint of the Object Storage Service (OSS) bucket that stores the firmware.
    isDiff Long If the firmware type is differential, the message includes the isDiff parameter that is set to 1. The value 1 indicates that the firmware file is a differential package. The differential package includes only the differences between the original firmware and the new firmware. The device must integrate the differential package with the original firmware to form the new firmware. If the firmware type is full, this parameter is not included.
    sign String The firmware 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 firmware belongs.
    Note If the name of the default module is specified, IoT Platform does not send the module parameter.
  4. After the device receives the URL, the device connects to the URL by using HTTPS and download the firmware update from the URL.
    Note If the device fails to download the firmware update from the URL within 24 hours, the URL becomes invalid.

    During a firmware update, a device must send the update progress to a topic in the following format: /ota/device/progress/${YourProductKey}/${YourDeviceName}. Sample message:

    {
      "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 message ID. 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 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 firmware belongs.
    Note If the device reports the firmware version of the default module, the module parameter is optional.
  5. After the firmware update of a device is completed, the device must send the current firmware version to a topic in the following format: /ota/device/inform/${YourProductKey}/${YourDeviceName}. If the reported version is the same as the version that the OTA service sends to the topic, the firmware update is successful. Otherwise, the firmware update fails.
    Note A successful firmware update is indicated based only on the reported version. For example, a device reports an update progress of 100%. However, no firmware version is reported. This case is also considered as a failed update.

Common errors during firmware downloads

  • Sign failed. If the URL of a firmware update is invalid or changed, this issue occurs, as shown in the following figure. Error
  • Access denied. This error occurs due to an expired URL. The URL is valid for 24 hours.URL expired