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

Procedure

The following figure shows the procedure of an OTA update over MQTT.

Procedure

Notes

  • To perform a differential update, the device must submit the version number of an OTA module. To perform a full update, the device does not need to submit the version number of an OTA module. If the version number is not submitted, you cannot specify a source version when you configure a batch update. For more information, see Initiate a batch update task.

    A device needs to submit the version number only once during the startup before the first update. After the update succeeds, the device must immediately submit the current version number.

  • In the IoT Platform console, after you start updating multiple devices, each device is in the Pending Update state.

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

    Note After a device receives an update notification from IoT Platform, the device can download the update package and performs an update immediately or during off-peak business hours.
  • IoT Platform checks whether an OTA update succeeds based on the version number that is submitted by the device.
  • An offline device cannot receive an update notification from IoT Platform.

    After the status of the device changes to online, IoT Platform identifies whether the device needs to be updated. If an update is required, IoT Platform sends an update notification to the device. Otherwise, no notification is sent.

Message formats

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

The following steps describe the procedure of an OTA update.

  1. Optional. Connect a device to the OTA service of IoT Platform and submit the version number.

    The version number is pushed to the following topic over MQTT: /ota/device/inform/${YourProductKey}/${YourDeviceName}. Sample message:

    {
      "id": "123",
      "params": {
        "version": "1.0.1",
        "module": "MCU"
      }
    }
    Table 1. The following table describes the 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.
  2. In the IoT Platform console, add an update package, check the update package, and then start a batch update.

    For more information, see Overview.

  3. After you start an update in the console, the device receives the URL of the update package 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}. After IoT Platform sends an OTA update request to the device, the device receives the URL of the update package from this topic.

    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",
        "extData":{
            "key1":"value1",
            "key2":"value2"
         }
      },
      "id": "1507707025",
      "message": "success"
    }
    Table 2. The following table describes the 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 HTTP 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 This parameter is available only if an update package is a differential package.

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

    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".

  4. Optional. Download the update package within 24 hours after the device SDK receives the URL of the update package. Otherwise, the URL expires.

    To request an update task from IoT Platform, the device can send a message to the following topic: /sys/{productKey}/{deviceName}/thing/ota/firmware/get. Sample message:

    {
      "id": "123",
      "version": "1.0",
      "params": {
          "module": "MCU"
      },
      "method": "thing.ota.firmware.get"
    }
    Table 3. The following table describes the 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 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. Set the value to thing.ota.firmware.get.

    After IoT Platform receives the request, IoT Platform sends the update package information to the following topic: /sys/{productKey}/{deviceName}/thing/ota/firmware/get_reply.

    • IoT Platform sends the information about the latest update package to the device. 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 4. The following table describes the 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 This parameter is available only if an update package is a differential package.

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

      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": {
        }
      }
  5. Call the operation to download the update package over HTTPS after the device SDK receives the URL of the update package. For more information, see OTA.
    Note The device cannot automatically download the update package. You must call the required operation in the SDK to download the update package. If the device fails to download the update package from the URL within 24 hours, the URL expires.
  6. During an update, the device must send the update progress to the following topic: /ota/device/progress/${YourProductKey}/${YourDeviceName}. Sample message:
    {
      "id": "123",
      "params": {
        "step": "-1",
        "desc": "The OTA update failed. No update package is found. ",
        "module": "MCU"
      }
    }
    Table 5. The following table describes the 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: indicate that the burning failed.
    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 update package applies.
    Note If the device submits the update progress of the default module, the module parameter is optional.
  7. After the OTA update of a device is completed, the device must send the current firmware version to the following topic: /ota/device/inform/${YourProductKey}/${YourDeviceName}. If the submitted version is the same as the version that the OTA service sends to the topic, the OTA update is successful. Otherwise, the OTA update fails.
    Note A successful OTA update is indicated by the submitted firmware version. For example, a device submits an update progress of 100%. However, if the current firmware version is not submitted within a specified timeout period, IoT Platform considers that the update fails.

    We recommend that you restart the device immediately after the OTA update is completed. After the device goes online, submit the current version number. The interval between a request to connect the device with IoT Platform and a request to submit the current version number cannot exceed 2 seconds.

Common errors

  • The signature is invalid. If the URL of an update package is invalid or changed, this error occurs, as shown in the following figure. Data masking
  • The access is denied. This error occurs due to the expiration of a URL. Each URL is valid for 24 hours. Data masking