This article describes how to push an update package to multiple devices at a time in the IoT Platform console for an over-the-air (OTA) update.

Prerequisites

The following operations are performed:
  1. Add an update package.
  2. (Optional) Verify an update package.

Procedure

  1. Log on to the IoT Platform console.
  2. In the left-side navigation pane, choose Maintenance > OTA Update.
    Note To provide better services, IoT Platform improves the OTA update feature and adds statistics on update package versions. When you use the new OTA update feature in the console for the first time, you must associate the uploaded update packages with products. You can associate an update package with only one product. For more information about how to associate update packages with products, see the instructions in the console.
  3. On the Update Packages tab, find the update package that you want to use and click Batch Update in the Actions column. Set the parameters and click Next.
    Parameter Description
    Upgrade Method
    • Static Update: updates only the existing devices that meet the required conditions.
    • Dynamic Update: constantly updates the devices that meet the required conditions.

      Dynamic updates can be applied to the following scenarios:

      • The devices that are subsequently activated meet the required conditions.
      • The current OTA module versions that devices submit do not meet the required conditions. However, the devices subsequently submit the OTA module versions that meet the required conditions.
      Note
      • You can use an update package to create only one dynamic update batch. If you have created a dynamic update batch by using an update package, you must cancel this dynamic update batch before you create another one.
      • A device can be updated at most 10 times in a dynamic update batch. If the device has been updated 10 times, no update can be initiated on the device even if the required conditions are subsequently met for a dynamic update.
    Upgrade range
    • All Devices: updates all eligible devices in the specified product.
    • Selected Devices: updates only the specified devices. If you select Selected Devices, use one of the following methods to select the required devices:
      • Select: Select the required devices from the Device Range drop-down list.
      • Choose File: Download a template file in the .csv format. Perform the steps that are provided in the template to enter the names of the required devices. Then, upload the template file. Each template file can contain a maximum of 10,000 records.

        If a template file contains one or more invalid device names, an error occurs. You can click Download Invalid Device Name List to download a TXT file. The file contains invalid device names. Then, you must modify and re-upload the template file.

    • Phased Update: updates the specified devices. This option is displayed only if you set the Update Method parameter to Static Update. You must specify at least one device for a phased update.

      After you select Phased Update, specify a percentage for devices in the Grayscale range field. IoT Platform calculates the number of devices to be updated based on the specified percentage. The calculation result is rounded down.

    Version number to be upgraded
    • If you perform a full static update, this parameter is optional. If you perform a full dynamic update, this parameter is required. If you set the Upgrade range parameter to Selected Devices, do not set this parameter.

      The drop-down list displays the OTA module versions of all devices in the current product, except for the version to be updated to. You can select one or more versions.

      If you do not set this parameter, no limit is set on the version number for the OTA module of the devices to be updated.

    • If you perform a differential update, the value of this parameter is the version number that you specify when you add the update package.
  4. Configure the update policy and click Complete. Then, IoT Platform pushes update notifications to devices.
    Parameter Description
    Update Time The time when the OTA update is performed.
    • Update: immediately performs the OTA update.
    • Scheduled Update: performs the OTA update during a specified time range. You can specify a start time and an end time. The start time must be 5 minutes to 7 days later than the current time. The end time must be 1 hour to 30 days later than the start time. The end time is optional. If you do not specify an end time, the update is not forcibly stopped.
      Note Scheduled updates are supported only if you set the Update Method parameter to Static Update.
    APP Confirm Upgrade Specify whether to control the update by using a mobile app. You must develop the mobile app as needed.
    • Yes: To perform an OTA update on a device, you must confirm the update by using your mobile app. You can call the ConfirmOTATask operation to confirm the update tasks that are pending confirmation. Then, the device can obtain the information about the OTA update task based on the Whether IoT Platform Actively Pushes Update Task parameter.
    • No (default): A device obtains the information about the OTA update task based on the Whether IoT Platform Actively Pushes Update Task parameter.
    Whether IoT Platform Actively Pushes Update Task Specify whether to automatically push update tasks from IoT Platform to devices.
    • Yes (default): After an update batch is created, IoT Platform automatically pushes update tasks to the specified online devices.

      In this case, a device can still initiate a request to obtain the information about the OTA update task from IoT Platform.

    • No: A device must initiate a request to obtain the information about the OTA update task from IoT Platform.
    Update Package Push Rate The number of devices to which you want to push the download URL of the update package per minute. Valid values: 10 to 2000.
    Notice If you set Whether IoT Platform Actively Pushes Update Task to No, you do not need to set this parameter.
    Upgrade failed retry interval The interval between an update failure and a retry after the failure. Valid values:
    • Do Not Retry
    • Retry Immediately
    • Retry in 10 Minutes
    • Retry in 30 Minutes
    • Retry in 1 Hour
    • Retry in 24 Hours
    Notice The retry interval that is specified by the Upgrade failed retry interval parameter must be shorter than the timeout period that is specified by the Device upgrade time-out (minutes) parameter. Example:
    • If you set the timeout period to 60 minutes, the maximum retry interval that you can specify is 30 minutes.
    • If you set the timeout period to 1,440 minutes, the maximum retry interval that you can specify is 1 hour.

    If you need to set the Upgrade failed retry interval parameter to Retry in 24 Hours, we recommend that you do not set the Device upgrade time-out (minutes) parameter. If an update times out, no retry is performed.

    Max. Retry Times The maximum number of retries that can be performed after the update fails. Valid values:
    • 1
    • 2
    • 5
    Device upgrade time-out (minutes) The timeout period of the update. If a specified device has not been updated within this period, the update times out. Valid values: 1 to 1440. Unit: minutes.
    Note The period starts from the first time the specified device submits the update progress.

    During the update, the update package may be repeatedly pushed to the specified device because the device goes online and offline multiple times. However, the start time of the update period does not change.

    Override Previous Device Update Tasks Each device can be in only one ongoing update task at a time. The Pending Confirmation, To Be Pushed, or Pushed state is displayed if a device is in an ongoing update task. If multiple update tasks exist, you must specify whether to overwrite the previous update task.
    • If you select Yes, only the new update task is performed. The previous update task is canceled.
    • If you select No and an update task exists for the device, only this previous update task is performed.
    Note The update task that is in progress is not overwritten.
    Take Effect for only Devices that Newly Report Versions This parameter is available only if you set the Update Method parameter to Dynamic Update. Valid values:
    • If you select Yes, only the devices that subsequently submit OTA module versions are updated.
    • If you select No, the existing devices that meet the required conditions are updated. In addition, IoT Platform constantly checks the devices. If the devices that subsequently submit OTA module versions meet the required conditions, these devices are also updated.
    Batch label Click Add Tag. In the field that appears, specify the Tag Key and Tag Value parameters. After an update batch is created, you cannot modify the tags that are added to the update batch.

    The tags of an update batch are sent to devices when IoT Platform pushes update notifications to these devices.

    You can click the Help icon to view the rules on how to configure tags.

  5. Optional:On the Batch Management tab of the Update Package Details page, find the dynamic update batch and click Edit in the Actions column. In the Update Scope Configuration and Update Policy Configuration steps, modify the Version number to be upgraded and Device upgrade time-out parameters. You can cancel the timeout settings.
    Notice Take note of the following items when you modify dynamic update settings:
    • Version number to be upgraded: If you add a version number, the existing devices with the version number are updated. The new devices that match the dynamic policy are also updated. If you delete a version number, the existing devices are not affected.
    • Device upgrade time-out: This parameter takes effect only for dynamic OTA updates on new devices. The existing devices are not affected.

Results

After you initiate a batch update, IoT Platform pushes an update notification to the specified devices based on your settings. You can view the update statuses of the devices and the update package information in the console. For more information, see View update status.

Related operations

Operation Description
CreateOTAStaticUpgradeJob Creates a static update batch.
CreateOTADynamicUpgradeJob Creates a dynamic update batch.
CancelOTAStrategyByJob Cancels an update policy that is associated with a dynamic update batch.
CancelOTATaskByDevice Cancels the pending device update tasks of an update package.
CancelOTATaskByJob Cancels the device update tasks of an update batch.

For more information about API operations related to the OTA update feature, see OTA updates.