IoT Platform:Initiate a batch update

Procedure

1. Log on to the IoT Platform console.

2. On the Overview page, click All environment. On the All environment tab, find the instance that you want to manage and click the instance ID or instance name.

3. 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.
4. On the Update Packages tab, find the update package that you want to manage and click Batch Update in the Actions column. In the Update Scope Configuration step, configure the parameters and click Next. The following table describes the parameters.
   

   Parameter	Description
   Update Method	The type of the update. This parameter is optional. Valid values: Static Update: updates only the existing devices that meet the specified conditions. Dynamic Update: continuously updates the devices that meet the specified conditions. Dynamic updates can be performed in the following scenarios: The devices that are activated after a dynamic update is performed meet the specified conditions. The current OTA module versions that the devices report do not meet the specified conditions. However, the devices continue to report the OTA module versions that meet the specified 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 version-based 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	The scope of the update. This parameter is optional. Valid values: All Devices: updates all devices that meet the specified update conditions in the specified product. Selected Devices: updates only the specified devices. If you select Selected Devices, you can use one of the following methods to select the required devices: Select: Select the devices that you want to update from the Device Range drop-down list. If you use an Enterprise Edition instance in the Japan (Tokyo) region, you can use the Advanced search feature to search for devices. You can also download a CSV file that contains the names of the matched devices. Upload File: Download a template file in the .csv format, enter the names of the required devices in the template file, and then upload the template file. Each template file can contain a maximum of 1,000,000 records. If a template file contains one or more invalid device names, an error occurs. Click Download Invalid Device Name List to download the file that contains invalid device names. Then, 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. If you select Phased Update, the Update Adoption Rate (%) field appears. You must specify a percentage for the specified devices in the field. IoT Platform calculates the number of devices that can be updated based on the specified percentage. The calculation result is rounded down. Group Update: updates the specified device group. This option is displayed only if you set the Update Method parameter to Static Update. The Group list drop-down list displays all parent groups and their subgroups in the current instance. For more information about how to create a device group, see Device groups.
   Version number to be upgraded	Before you configure this parameter, take note of the following items: 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, this parameter is not displayed. The Version number to be upgraded 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 configure this parameter, no limit is specified for the version number of 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. If you set the Update Method parameter to Dynamic Update when you create an update batch and the update batch is in the updating state, you can change the value of this parameter.

5. In the Update Policy Configuration step, configure the parameters and click Complete. Then, IoT Platform pushes update notifications to devices. The following table describes the parameters.
   

   Parameter	Description
   Upgrade time	The time when you want to perform the OTA update. Valid values: Update: immediately performs the OTA update. Scheduled Update: performs the OTA update within a specified time range. You can specify a start time and an end time for the OTA update. 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.
   Whether IoT Platform Actively Pushes Update Task	Specifies whether IoT Platform automatically pushes update tasks to devices. Yes: After an update batch is created, IoT Platform automatically pushes update tasks to the specified online devices. This is the default value. In this case, a device can still initiate a request to obtain the information about the OTA update task from IoT Platform. No: The device initiates 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: Constant Rate and Variable Rate. Important This parameter is not displayed if you set the Whether IoT Platform Actively Pushes Update Task parameter to No. The Variable Rate option is available only for Enterprise Edition instances. The following list describes the parameters: If you specify Constant Rate, you must configure the Update at Constant Rate parameter. Valid values: 10 to 10000. The value must be an integer. Unit: devices per minute. After you specify a value for the Update at Constant Rate parameter, the push rate remains unchanged. For example, if you want to fix a high-risk vulnerability, you must push an update package to all devices to perform an update. In this case, we recommend that you set the Update Package Push Rate parameter to Constant Rate. You can set the maximum constant push rate to 10,000 devices per minute. This way, you can push the update package to the devices that you want to update at the earliest opportunity. Variable Rate: In some cases, you may need to push an update package at a low rate first (such as one device per minute), and then continuously increase the push rate based on specific conditions. You can set the Update Package Push Rate parameter to Variable Rate. For example, you want to push an update package to all devices at a low rate when a new feature is added. This way, you can perform an update first on a small portion of devices at the beginning of the update process. Then, you can check whether the updated devices run as expected and determine whether to increase the push rate based on the check result. This process is similar to the process of performing a phased update before a full update to ensure a successful update of all devices. If you specify Variable Rate, you must configure the following parameters: Basic Push Rate: specifies the number of devices to which you want to push an update package per minute if the number of devices to which the update package is pushed or the number of updated devices does not reach the value of the Pushed Devices or Updated Devices parameter in the Increase Push Rate section. Valid values: 1 to 10000. The value must be an integer that is less than or equal to the value of the Maximum Push Rate parameter. Incremental Factor: specifies an incremental factor based on which the system increases a push rate. This parameter applies if the number of devices to which the update package is pushed or the number of updated devices reaches the value of the Pushed Devices or Updated Devices parameter in the Increase Push Rate section. Valid values: 1.20 to 5.00. The value is rounded to two decimal places. Maximum Push Rate: specifies the maximum number of devices to which you want to push the update package per minute. Valid values: 10 to 10000. The value must be an integer. If the rate at which the system pushes the update package reaches the maximum push rate, the system pushes the update package at the maximum push rate and no longer changes the push rate. Increase Push Rate: specifies a threshold value for the Pushed Devices or Updated Devices parameter. Valid values: 1 to 100000. The value must be an integer. If the number of devices to which the update package is pushed or the number of updated devices reaches the threshold value, the system increases the push rate based on the value of the Incremental Factor parameter. Example: You perform an OTA update by configuring the following settings: Set the Update Package Push Rage parameter to Variable Rate, set the Basic Push Rate parameter to 50, set the Incremental Factor parameter to 2, set the Maximum Push Rate to 10000, and then set the Pushed Devices parameter to 1000 in the Increase Push Rate section. The following process describes how the OTA update is performed: An OTA update task is created to push an update package to 1,000 devices at a rate of 50 devices per minute at the beginning of the process. Then, the push rate increases based on the incremental factor. The following process describes how the system increases the push rate: The OTA update task pushes the update package to 1,000 devices at a rate of 50 devices per minute. Then, the system increases the push rate to 100 devices per minute based on the value of the Incremental Factor parameter. The OTA update task pushes the update package to another 1,000 devices at a rate of 100 devices per minute. A total of 2,000 devices have received the update package. Then, the system increases the push rate to 200 devices per minute. The OTA update task pushes the update package to another 1,000 devices at a rate of 200 devices per minute. A total of 3,000 devices have received the update package. Then, the system increases the push rate to 400 devices per minute. The OTA update task pushes the update package to another 1,000 devices at a rate of 400 devices per minute. A total of 4,000 devices have received the update package. Then, the system increases the push rate to 800 devices per minute. This way, the OTA update task pushes the update package at a rate of 800 devices per minute, 1,600 devices per minute, 3,200 devices per minute, and then 6,400 devices per minute until a total of 8,000 devices receive the update package and the push rate is increased to 12,800 devices per minute based on the value of the Incremental Factor parameter. The value 12800 exceeds the threshold value 10000 that you specified for the Maximum Push Rate parameter. Therefore, the OTA update task pushes the update package at the maximum push rate of 10,000 devices per minute and no longer changes the push rate. If an update batch that you created is in the updating state, you can change the push rate that you specified to push an update package. However, you cannot change the push type from Constant Rate to Variable Rate or the other way around. For more information, see Manage update batches.
   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 Important The value of the Upgrade failed retry interval parameter must be less than the value of the Device upgrade time-out (minutes) parameter. Examples: 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 want to set the Upgrade failed retry interval parameter to Retry in 24 Hours, we recommend that you do not configure 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 if an update fails. Valid values: 1 2 5
   Device upgrade time-out (minutes)	The timeout period of the update for a single device. If a specified device has not been updated within this period, the update times out. Valid values: 1 to 1440. Unit: minutes. Note The update period starts from the first time the specified device reports 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. The start time of the update period remains unchanged. If you set the Update Method parameter to Dynamic Update when you create an update batch and the update batch is in the updating state, you can change the value of this parameter. For more information, see Manage update batches.
   The device supports simultaneous updates of multiple modules	Specifies whether a device supports simultaneous updates on multiple modules. This parameter is displayed only for an Enterprise Edition instance or a public instance of the new version. Valid values: Yes: A device supports simultaneous updates on multiple modules. In this case, IoT Platform uses the current update task to overwrite the previous update tasks for the same module and does not overwrite the update tasks that are in progress. Important Only a device that uses Link SDK V4.x for C supports simultaneous updates on multiple modules. For more information, see Overview. You can set the The device supports simultaneous updates of multiple modules or Override Previous Device Update Tasks parameter to Yes. The settings of the The device supports simultaneous updates of multiple modules and Override Previous Device Update Tasks parameters of a new dynamic update batch for a device group must be the same as those of the existing dynamic update batch for the device group. For more information, see the Simultaneous updates of multiple modules table in the Overview topic. No: A device does not support simultaneous updates on multiple modules. Default value: No.
   Override Previous Device Update Tasks	Specifies whether to overwrite the previous update task of a device. If a device has multiple update tasks, you must specify whether to use the current update task to overwrite the previous update tasks. An update task on a device can be in the Pending Confirmation, To Be Pushed, or Pushed state. Valid values: Yes: Only the latest update task is performed. The previous update tasks are canceled. No: Only the existing update task is performed. Default value: No. Note The update tasks that are in progress are not overwritten.
   Take Effect for only Devices that Newly Report Versions	Specifies whether to update only the devices that subsequently report new OTA module versions. This parameter is displayed only if you set the Update Method parameter to Dynamic Update. Valid values: Yes: updates only the devices that report new OTA module versions. No: updates the existing devices that meet the update conditions and continuously checks whether the devices that report new OTA module versions meet the update conditions. Default value: No.
   APP Confirm Upgrade	Specifies whether you can use a mobile app to perform the update. If you select Yes, you must develop the mobile app. Valid values: 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 multiple update tasks that are in the pending confirmation state at a time. Then, the device can obtain the information about the OTA update task based on the value of the Whether IoT Platform Actively Pushes Update Task parameter. No: A device obtains the information about the OTA update task based on the setting of the Whether IoT Platform Actively Pushes Update Task parameter. Default value: No.
   Update Package Download Protocol	The protocol that you want to use to download the update package. Valid values: HTTPS and MQTT. After a device receives the update package URL from IoT Platform, you can use this protocol to download the update package. Important If you want to download the update package by using the Message Queuing Telemetry Transport (MQTT) protocol, take note of the following items: Your service must be deployed in the China (Shanghai), China (Beijing), or China (Shenzhen) region. The OTA update package can contain only one file, and the size of the file cannot exceed 16 MB. You must use the latest version of Link SDK for C to develop the device features to perform OTA updates and download files over MQTT. For more information, see Sample code.
   Batch label	Click Add Tag. In the fields that appears, specify the tag key and tag value. If an update batch that you created is in the updating state, you can modify the tag or add more tags. For more information, see Manage update batches. The tags of an update batch are sent to devices when IoT Platform pushes update notifications to these devices. You can move the pointer over the icon to view the rules based on which you can configure tags.

6. 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, you can change the values of the Version number to be upgraded and Device upgrade time-out parameters. You can cancel the timeout settings.
   Important

   • Before you modify dynamic update settings, take note of the following items:
     • Version number to be upgraded: If you add a version number, the existing devices that use the version and new devices that match the dynamic policy are updated. If you remove 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.
   • You cannot change the value of the Version number to be upgraded parameter for a group-based dynamic update batch.

Result

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 status of each device and the update package information in the IoT Platform console. For more information, see View update status.

Related API operations

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