All Products
Search
Document Center

IoT Platform:CreateOTAFirmware

Last Updated:Sep 15, 2023

Creates an over-the-air (OTA) update package for devices after you generate a URL for each file that you want to add to the OTA update package.

Usage notes

Before you call this operation to create an OTA update package, you must call the GenerateOTAUploadURL operation to generate the information about the files that you want to add to the OTA update package and call the PostObject operation of Object Storage Service (OSS) to upload the files.

Limits

A maximum of 500 update packages can be created within a single instance.

QPS limits

You can call this operation up to 10 times per second per account.

Note

The Resource Access Management (RAM) users of an Alibaba Cloud account share the quota of the account.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter

Type

Required

Example

Description

Action

String

Yes

CreateOTAFirmware

The operation that you want to perform. Set the value to CreateOTAFirmware.

DestVersion

String

Yes

2.0.0

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

FirmwareName

String

Yes

Firmware2

The name of the OTA update package. The name must be unique within an Alibaba Cloud account. The name cannot be modified after the OTA 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 a digit.

IotInstanceId

String

No

iot-cn-0pp1n8t****

The instance ID. You can view the instance ID on the Overview page in the IoT Platform console.

Important
  • If your instance has an ID, you must specify this parameter. Otherwise, the request fails.

  • If the Overview page or instance ID is not displayed in the IoT Platform console, you do not need to specify this parameter.

FirmwareUrl

String

No

https://iotx-ota.oss-cn-shanghai.aliyuncs.com/ota/bcd6142594d0183a16d825ad8225****/A6B3400B70CA4D6D872160D1A91A****.bin

The URL of the file that you want to add to the OTA update package. This parameter specifies the storage location of the file in OSS. You can call the GenerateOTAUploadURL operation to generate the URL of the file.

Important

If you want to add only one file to the OTA update package, you must specify this parameter.

FirmwareSign

String

No

93230c3bde425a9d7984a594ac55****

The signature value of the file that you want to add to the OTA update package. The signature value is calculated by using a specific signature algorithm, such as the Secure Hash Algorithm 256 (SHA-256) or MD5 algorithm, to sign the file.

Important

If you want to add only one file to the OTA update package, you can specify this parameter. If you do not specify this parameter, the MD5 value of the file in OSS is used.

SignMethod

String

No

MD5

The signature algorithm of the file that you want to add to the OTA update package. Valid values:

  • MD5 (default)

  • SHA256

FirmwareSize

Integer

No

900

The size of the file that you want to add to the OTA update package. Unit: bytes.

Important

If you want to add only one file to the OTA update package, you can specify this parameter. If you do not specify this parameter, the size of the file in OSS is used.

ProductKey

String

No

a1uctKe****

The ProductKey of the product to which the OTA update package belongs.

FirmwareDesc

String

No

OTA function updated

The description of the OTA update package. The description can be up to 100 characters in length.

Type

Integer

No

0

The type of the OTA update package. Valid values:

  • 0: The uploaded file contains a full update package. IoT Platform pushes the full update package to a device for update.

  • 1: The uploaded file contains only the differences between the latest update package and the previous update package. IoT Platform pushes only the differences to a device for update.

Default value: 0.

SrcVersion

String

No

1.0.0

The version number of the OTA module of the device to be updated.

You can call the QueryDeviceDetail operation and view the value of FirmwareVersion in the response.

Note
  • If you set Type to 1, you must specify this parameter, and the value of this parameter cannot be the same as the value of DestVersion.

  • If you set Type to 0, you do not need to specify this parameter.

ModuleName

String

No

WifiConfigModify

The name of the OTA module. OTA modules are the updatable units of devices that belong to the same product.

Note
  • If you do not specify this parameter, the default OTA module is used. The default value indicates that the complete device firmware is updated.

  • You can call the CreateOTAModule operation to create a custom OTA module. You can call the ListOTAModuleByProduct operation to query the existing OTA modules of a product.

NeedToVerify

Boolean

No

true

Specifies whether to verify the OTA update package before you create a batch update task. Valid values:

  • true (default)

  • false

Udi

String

No

{"ota_notice":"Update the underlying camera driver to resolve the issue of blurry images in videos."}

The custom information that you want to send to a device. The format of the custom information has no limits. However, the information cannot exceed 4,096 characters in length.

After you create the OTA update package and create an update task, IoT Platform sends the custom information to the specified device when IoT Platform pushes an update notification.

MultiFiles.N.Name

String

No

Firmware1

The name of the file that you want to add to the OTA update package. The name must be 1 to 32 characters in length. You can specify up to 20 file names. Each name must be unique in the OTA update package.

Important

If you want to add multiple files to the OTA update package, you must specify this parameter.

MultiFiles.N.Size

Integer

No

200

The size of the file that you want to add to the OTA update package. Unit: bytes.

Note

If you want to add multiple files to the OTA update package, you can specify this parameter. If you do not specify this parameter, the size of the file in OSS is used.

MultiFiles.N.Url

String

No

https://iotx-ota.oss-cn-shanghai.aliyuncs.com/ota/bcd6142594d0183a16d825ad8225****/A6B3400B70CA4D6D872160D1A91A****.bin

The URL of the file that you want to add to the OTA update package. This parameter specifies the storage location of the file in OSS. You can call the GenerateOTAUploadURL operation to generate a URL for each file that you want to add to the OTA update package.

Important

If you want to add multiple files to the OTA update package, you must specify this parameter.

MultiFiles.N.SignValue

String

No

93230c3bde425a9d7984a594ac45****

The signature value of the file that you want to add to the OTA update package. The signature value is calculated by using a specific signature algorithm to sign the file.

Note

If you want to add multiple files to the OTA update package, you can specify this parameter. If you do not specify this parameter, the MD5 value of the file in OSS is used.

MultiFiles.N.FileMd5

String

No

93230c3bde425a9d7984a594ac56***

The MD5 value of the file that you want to add to the OTA update package.

Note

If you want to add multiple files to the OTA update package, you can specify this parameter. If you do not specify this parameter, the MD5 value of the file in OSS is used.

In addition to the preceding operation-specific request parameters, you must specify common request parameters when you call this operation. For more information about common request parameters, see Common parameters.

Response parameters

Parameter

Type

Example

Description

Code

String

iot.system.SystemException

The error code returned if the request failed. For more information, see Error codes.

Data

Struct

The OTA update package information returned if the request was successful. For more information, see the following parameters.

FirmwareId

String

s8SSHiKjpBfrM3BSN0z803****

The ID of the OTA update package. The ID is a unique identifier issued by IoT Platform to the OTA update package.

UtcCreate

String

2019-11-04T06:21:54.607Z

The time when the OTA update package was created. The time is displayed in Coordinated Universal Time (UTC).

ErrorMessage

String

A system exception occurred.

The error message returned if the request failed.

RequestId

String

291438BA-6E10-4C4C-B761-243B9A0D324F

The request ID.

Success

Boolean

true

Indicates whether the request was successful. Valid values:

  • true

  • false

Examples

Sample requests

https://iot.cn-shanghai.aliyuncs.com/?Action=CreateOTAFirmware
&ProductKey=a1uctKe****
&FirmwareName=Firmware2
&DestVersion=2.0.0
&FirmwareUrl=https%3A%2F%2iotx-ota.oss-cn-shanghai.aliyuncs.com%2Fota%2F****%2F****.bin
&SignMethod=MD5
&FirmwareSign=93230c3bde425a9d7984a594ac55****
&FirmwareSize=900
&FirmwareDesc=OTA function updated
&Type=0
&ModuleName=WifiConfigModify
&<Common request parameters>

Sample success responses

XML format

<CreateOTAFirmwareResponse>
    <Data>
        <FirmwareId>s8SSHiKjpBfrM3BSN0z803****</FirmwareId>
        <UtcCreate>2019-11-04T06:21:54.607Z</UtcCreate>
    </Data>
    <RequestId>E4BD5A12-7C1D-4712-A7D5-B2432331165E</RequestId>
    <Success>true</Success>
</CreateOTAFirmwareResponse>

JSON format

{  
  "Data": {
    "FirmwareId": "s8SSHiKjpBfrM3BSN0z803****",
    "UtcCreate": "2019-11-04T06:21:54.607Z"
  },
  "RequestId": "291438BA-6E10-4C4C-B761-243B9A0D324F",
  "Success": true
}

Error codes

For a list of error codes, see Service error codes.