Push an update package to devices

IoT Platform provides the over-the-air (OTA) update and management feature. To update devices, make sure that your devices support the OTA service. Then, you can upload an update package to the IoT Platform console and push OTA update notifications to the devices. This article describes how to add an update package, verify the update package, and push the update package to multiple devices by using the IoT Platform console.

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. This feature allows you to manage update package versions based on products. 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 firmware files with products, see the instructions in the console.
3. Optional. If AliOS Things chips are installed on your devices, you can enable the secure update feature.

   We recommend that you enable this feature to ensure integrity and security of update packages. If you use the secure update feature, verify the update package and update package signatures of devices. For more information, see OTA Tutorial for AliOS Things.

   1. Go to the OTA Update page, and click Secure Update.
   2. In the dialog box that appears, turn on the Secure Update switch for the product to be updated.
      When the secure update feature is in the Activated state, click Copy in the Public Key column to copy the public key. You can use the public key to verify the signature of the device.
4. Optional. Add a custom OTA module.
   An OTA module indicates the module of devices to be updated in a product. These OTA modules include the firmware, software, and driver. The default module is the firmware of a device. You can also add another module as an OTA module.

   On the Modules tab, click Add Module, set the required parameters, and then click OK.

   Parameter	Description
   Product	The product to which the module belongs.
   Module Name	The module name. The module name must be unique in the product. The module name cannot be modified after the module is created. The module name must be 1 to 64 characters in length, and can contain letters, digits, periods(.), hyphens (-), and underscores (_).
   Module Alias	The module alias. The module alias must be 4 to 64 characters in length, and can contain letters, digits, periods(.), hyphens (-), and underscores (_).
   Module Description	The module description. The module description must be 1 to 100 characters in length.

5. On the OTA Update page, click the Update Packages tab, and click Add Update Package.
6. Set the required parameters, upload an update package file, and then click OK.

   Parameter	Description
   Types of Update Packages	Full: If you select Full, you must upload a complete update package. The system pushes the complete update package to devices for update. Differential: If you select Differential, you must upload a file that contains only the differences between the original update package version and the destination update package version. IoT Platform pushes the differences to devices for update. Then, the differences are merged into the original update packages. Differential updates optimize the usage of device resources and minimize the traffic that is consumed during update package pushing.
   Update Package Name	The update package name. The update package name must be unique in the Alibaba Cloud account. The update package name cannot be modified after the update package is created. The name must be 1 to 40 characters in length, and can contain letters, digits, hyphens (-), underscores (_), and parentheses (). The name must start with a letter or digit.
   Product	The product to which the update package belongs.
   Update Package Module	The OTA module to which the update package applies. You can click Add Module. In the dialog box that appears, set the required parameters and click OK to add a module.
   Update Package Version	The update package version. The name must be 1 to 64 characters in length, and can contain letters, digits, periods (.), hyphens (-), and underscores (_). You must specify this parameter if you set the Types of Update Packages parameter to Full.
   Version number to be upgraded	The version number for the OTA module of the device to be updated. The drop-down list shows the OTA module versions of all devices in the current product. You can enter a version number in the field, or select a version from the drop-down list. You must specify this parameter if you set the Types of Update Packages parameter to Differential.
   Post-upgrade version number	The version number of the update package. You must specify this parameter if you set the Types of Update Packages parameter to Differential.
   Signature Algorithm	The signature algorithm. Valid values: MD5 and SHA256. If you use the Link SDK for Android and set the Types of Update Packages parameter to Differential, select the MD5 algorithm.
   Select Update Package	Select an update package file to upload. The maximum size of an update package file is 1,000 MB. The file format can only be .bin, .tar, .gz, .tar.gz, .zip, or .gzip. Note The file extension of an update package file to be uploaded must be lowercase, for example, test.zip.
   Verify Update Package	Specifies whether you need to verify the update package on several devices before you perform a batch update. Yes: You must verify the update package. You can perform a batch update after the update package is verified. For more information about how to perform a batch update, see the next step. No: No verification is required. You can perform a batch update without the need to verify the update package.
   Update Package Description	The update package description. The description must be 1 to 100 characters in length.

7. If you select Yes in the Verify Update Package field, find the required update package, and click Verify next to the update package. In the Verify Update Package dialog box, set the required parameters, and click OK to verify the update package on one or more devices.
   Note After the preceding devices are updated and the status of the update package is displayed as Verified, you can perform a batch update.

   Parameter	Description
   Version number to be upgraded	If you perform a full update, this parameter is optional. The drop-down list shows the versions of all devices in the current product, except for the version for the destination device. You can select one or more versions. After you select the required versions, the related devices are added to the Device to be verified list as candidate devices. If you do not set this parameter, no limit is set on the version number for the OTA module of the devices to be verified. If you perform a differential update, the value of this parameter is the version number that you specify when you add the update package.
   Device to be verified	Select one or more devices to be verified.
   Device upgrade time-out (minutes)	The timeout period of the update. If the 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.

8. On the Update Packages tab, find the required update package, and click Batch Update next to the update package. In the dialog box that appears, configure the required update scope and update policy, and click OK to push update notifications to devices in batches.

   Configuration	Parameter	Description
   Update scope	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 Apply Update to parameter to Selected Devices, do not set this parameter. The drop-down list shows the versions of all devices in the current product, except for the version for the destination device. 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 verified. If you perform a differential update, the value of this parameter is the version number that you specify when you add the update package.
   	Update Method	Static Update: updates only the current devices that meet the conditions. Dynamic Update: constantly updates the devices that meet the conditions. Dynamic updates can be applied to the following scenarios: The devices that are subsequently activated meet the conditions. The current OTA module versions that devices submit do not meet the conditions. However, the devices subsequently submit the OTA module versions that meet the 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.
   	Apply Update to	All Devices: updates all eligible devices in the specified product. Selected Devices: updates only the specified devices. If you set 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. Upload: 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 includes one or more invalid device names, an error occurs. You can click Download Invalid Device Name List to download a TXT file. The file includes invalid device names. Phased Update: updates the specified devices. This option appears if you select Static Update from the Update Policy drop-down list. After you select Phased Update, specify a range for devices in the Range (%) field that appears. IoT Platform calculates the number of devices to be updated based on the specified range. The calculation result is rounded down. You must specify at least one device for phased update.
   Update scope	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 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 available only if you set the Update Policy parameter to Static Update.
   	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 1000.
   	Retry Interval	The interval after which a retry is performed if the update fails. Valid values: Do Not Retry Retry Immediately Retry in 10 Minutes Retry in 30 Minutes Retry in 1 Hour Retry in 24 Hours
   	Maximum Retries	The maximum number of retries after the update fails. Valid values: 1 2 5
   	Timeout (Minutes)	The timeout period of the update. If the 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.
   	Override Previous Device Update Tasks	Specifies whether to overwrite the previous update task. Each device can be in only one ongoing update task at a time. The To Be Pushed, Pushed, or In Upgrade state is displayed if a device is in an ongoing update task. If you select Yes, only the new update task is performed. The previous task is canceled. If you select No and an update task exists for the device, only the 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 Policy parameter to Dynamic Update. This parameter specifies whether to update only the devices that submit firmware versions later. Make sure that the submitted firmware versions are used as the firmware versions to be updated If you select Yes, only the devices that subsequently submit firmware versions are updated. If you select No, the current devices that meet the conditions are updated. In addition, IoT Platform constantly checks the devices. If the devices that subsequently submit firmware versions meet the conditions, these devices are updated.
   	Tag	Click Add Tag. In the dialog box that appears, enter the key and value of the tag, and click OK. After an update batch is created, you cannot modify the tag that is added to the update batch. The tag of an update batch is sent to devices when IoT Platform pushes update notifications to these devices.