All Products
Search
Document Center

IoT Platform:Add an update package

Last Updated:Apr 19, 2023

To perform over-the-air (OTA) updates on IoT devices, you must add an update package to a product in the IoT Platform console. This topic describes how to add an update package.

Prerequisites

The OTA update feature is enabled for your devices. For more information about how to configure Link SDK to perform an OTA update, see Overview.

If you add an update package that contains multiple files, the devices must support update tasks that are initiated by using multiple update package files. For more information, see Sample code.

Important

Only Link SDK for C allows you to develop the OTA update feature by using an update package that contains multiple files.

Background information

For more information about how to use the OTA update feature, see Overview. For more information about how to perform OTA updates, see Perform OTA updates.

Procedure

  1. Log on to the IoT Platform console.
  2. On the Overview page, select an environment, find the instance that you want to manage, and click the instance ID or instance name.
    Important This step is required only if Enterprise Edition instances are available. If the Enterprise Edition instances are unavailable in the region that you selected, skip this step. For information about supported regions and instances, see Overview.
    Overview
  3. In the left-side navigation pane, choose Maintenance > OTA Update.

    Note

    To provide better user experience, IoT Platform improves the OTA update feature and provides statistics on update package versions. The first time you use the new OTA update feature in the IoT Platform console, 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. Optional. If AliOS Things chips are installed on your devices, you can enable the secure update feature.

    To ensure the integrity and security of update packages, we recommend that you enable the secure update feature. 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. On the OTA Update page, click Secure Update.

    2. In the Secure Update panel, find the product that you want to update, and then turn on the switch in the Secure Update column.

      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 a device.

  5. Optional. Create a custom OTA module.

    An OTA module is the module of the devices to be updated in a product. OTA modules include the firmware, software, and driver. The default module is the firmware of a device. You can also create custom OTA modules.

    On the Modules tab, click Add Module. In the Add Module dialog box, configure the parameters and click OK. The following table describes the parameters.

    Parameter

    Description

    Product

    The product to which the module belongs.

    Module Name

    The name of the module. The module name must be unique in a product. After the module is created, the name cannot be modified. The module name must be 1 to 64 characters in length, and can contain letters, digits, periods (.), hyphens (-), and underscores (_).

    Module Alias

    The alias of the module. The alias must be 4 to 64 characters in length, and can contain letters, digits, periods (.), hyphens (-), and underscores (_).

    Module Description

    The description of the module. The description must be 1 to 100 characters in length.

  6. On the OTA Update page, click the Update Packages tab and click Add Update Package.

  7. In the Add Update Package dialog box, configure the parameters, upload an update package file, and then click OK. The following table describes the parameters.

    Parameter

    Description

    Types of Update Packages

    • The type of the update package. Valid values: Full and Differential. If you select Full, you must upload a complete update package. IoT Platform pushes the complete update package to devices.

    • If you select Differential, you must upload a file that contains only the differences between the update package of the previous version and the update package of the new version. IoT Platform pushes the differences to devices. Then, the differences are merged into the original update packages. Differential updates save device resources and reduce the traffic that is consumed when IoT Platform pushes update packages.

    Update Package Name

    The name of the update package. The name must be unique in an Alibaba Cloud account. After the update package is added, the name cannot be modified. 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.

    After you add the update package, you can click Edit on the Update Package Information tab of the Update Package Details page to modify the name of the update package.

    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 Add Module dialog box, configure the parameters and click OK. The following table describes the parameters.

    Update Package Version

    The version number of the update package. The version number must be 1 to 64 characters in length, and can contain letters, digits, periods (.), hyphens (-), and underscores (_).

    This parameter is required only 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 devices to be updated. The drop-down list displays the OTA module versions of all devices in the current product. You can select a version from the drop-down list.

    This parameter is required if you set the Types of Update Packages parameter to Differential.

    Post-upgrade version number

    The version number of the update package.

    This parameter is required if you set the Types of Update Packages parameter to Differential.

    Signature Algorithm

    The signature algorithm. Valid values: MD5 and SHA256.

    If you use Link SDK for Android and set the Types of Update Packages parameter to Differential, select the MD5 algorithm.

    Select Update Package

    The update package files to upload. You can upload a maximum of 20 files. The total file size cannot exceed 1,000 MB. The file format can be .bin, .dav, .tar, .gz, .zip, .gzip, .apk, .tar.gz, .tar.xz, or .pack.

    When you upload multiple update package files, take note of the following items:

    • Each file name must be unique and cannot exceed 32 characters in length.

    • IoT Platform checks whether the signatures of multiple update package files are the same. If the signatures are the same, IoT Platform determines that the files are duplicate.

    Verify Update Package?

    Specifies whether to verify the update package on several devices before you perform a batch update. Valid values:

    • Yes: You can perform a batch update only after the update package is verified.

    • No: You can perform a batch update without the need to verify the update package.

    Update Package Description

    The description of the update package. The description can be up to 1,024 characters in length.

    After you add the update package, you can click Edit on the Update Package Information tab of the Update Package Details page to modify the update package description.

    Custom Information Pushed to Device

    The custom information that you want to send to a device. After you add the update package and create an update task, IoT Platform sends the custom information to the specified device when IoT Platform pushes an update notification.

    The custom information can be up to 4,096 characters in length. No limits are applied to the content or format.

    After you add the update package, you can click Edit on the Update Package Information tab of the Update Package Details page to modify the custom information.

Results

After you add an update package, you can view the update package on the Update Packages tab, as shown in the following figure.

Update Packages tab

Additional information

If you set the Verify Update Package? parameter to Yes when you add an update package, you must verify the update package before you perform a batch update. For more information, see Verify an update package (Optional).

If you set the Verify Update Package? parameter to No when you add an update package, you can perform a batch update without the need to verify the update package. For more information, see Initiate a batch update.

Optional: Delete the update package

Warning

If you delete an update package, the related package file immediately becomes invalid and can no longer be downloaded. As a result, the related business may be interrupted. Proceed with caution.

  1. On the Update Packages tab, find the update package and click Delete in the Actions column.

  2. In the message that appears, click OK.

Related operations

API

Overview

GenerateOTAUploadURL

Generates the URL and details of an update package to be uploaded to Object Storage Service (OSS).

CreateOTAFirmware

Adds an update package.

CreateOTAModule

Creates an OTA module for a product.

UpdateOTAModule

Modifies the alias and description of an OTA module.

DeleteOTAModule

Removes a custom OTA module.

ListOTAModuleByProduct

Queries the OTA modules of a product.

DeleteOTAFirmware

Removes an update package.

ListOTAFirmware

Queries update packages.

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