Creates an over-the-air (OTA) update package after an update package file is uploaded to Object Storage Service (OSS).

Usage notes

Before you call this operation to create an update package, you must call the GenerateOTAUploadURL operation to generate the parameters that are required to upload an update package file and then call the OSS PostObject operation to upload the file.

Limits

  • Each Alibaba Cloud account can have a maximum of 500 update packages.
  • Each Alibaba Cloud account can run a maximum of 10 queries per second (QPS).
    Note 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 value can contain letters, digits, periods (.), hyphens (-), and underscores (_). It must be 1 to 64 characters in length.

FirmwareName String Yes Firmware2

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

IotInstanceId String No iot-cn-0pp1n8t****

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

Notice
  • If your instance has an ID, you must configure this parameter. If you do not set this parameter, the call fails.
  • If your instance has no Overview page or ID, you do not need to set this parameter.

For more information, see Overview.

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

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

Notice If the OTA update package contains a single file, this parameter is available and must be specified.
FirmwareSign String No 93230c3bde425a9d7984a594ac55****

The signature of the OTA update package file. The value is calculated by using the specified signature method to sign the update package file.

Notice If the OTA update package contains a single file, this parameter is available and must be specified. If you do not specify this parameter, the MD5 value of the update package in OSS is used.
SignMethod String No MD5

The signature method of the OTA update package. Valid value: MD5.

Default value: MD5.

FirmwareSize Integer No 900

The size of the OTA update package file. Unit: bytes.

Notice If the OTA update package contains a single file, this parameter is available. If you do not specify this parameter, the size of the update package 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 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 for a device to be updated.

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

Note
  • If the Type parameter is set to 1, you must specify this parameter, and the value cannot be the same as the update package version that is specified by the DestVersion parameter.
  • If the Type parameter is set to 0, this parameter is optional.
ModuleName String No WifiConfigModify

The name of the OTA module. OTA modules are the updatable units of the 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 update package before you create a batch update task.

  • true (default): verifies the update package
  • false: does not verify the update package
Udi String No {"ota_notice":"Upgrade the underlying camera driver to solve the problem of blurred video images. "}

The custom information that is pushed to the device. The information can be up to 4,096 characters in length. No limit is applies to the content format.

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 the update notification.

MultiFiles.N.Name String No Firmware1

The name of the OTA update package file. The name must be 1 to 32 characters in length. You can add up to 20 files. The names of multiple update package files must be unique.

Notice If the OTA update package contains multiple files, you must specify this parameter.
MultiFiles.N.Size Integer No 200

The size of the OTA update package file. Unit: bytes.

Note If the OTA update package contains multiple files, this parameter is available. If you do not specify this parameter, the size of the update package 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 update package file. This parameter specifies the storage location of the update package in OSS. You can call the GenerateOTAUploadURL operation to generate the URL of the update package.

Notice If the OTA update package contains multiple files, you must specify this parameter.
MultiFiles.N.SignValue String No 93230c3bde425a9d7984a594ac45****

The signature of the OTA update package file. The value is calculated by using the specified signature method to sign the update package file.

Note If the OTA update package contains multiple files, this parameter is available. If you do not specify this parameter, the MD5 value of the update package in OSS is used.
MultiFiles.N.FileMd5 String No 93230c3bde425a9d7984a594ac56***

The MD5 value of the OTA update package file.

Note If the OTA update package contains multiple files, this parameter is available. If you do not specify this parameter, the MD5 value of the update package 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, see Common request parameters.

Response parameters

Parameter Type Example Description
Code String iot.system.SystemException

The error code returned if the call fails. For more information, see Error codes.

Data Struct

The update package information returned if the call succeeds. For more information, see Data.

FirmwareId String s8SSHiKjpBfrM3BSN0z803****

The ID of the update package. The package ID is issued by IoT Platform.

UtcCreate String 2019-11-04T06:21:54.607Z

The time when the update package was created. The time is displayed in UTC.

ErrorMessage String A system exception occurred.

The error message returned if the call fails.

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

The ID of the request.

Success Boolean true

Indicates whether the call was successful.

  • true: The call was successful. This value indicates that the OTA update package is created.
  • false: The call failed. This value indicates that the OTA update package failed to be created.

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, visit the API Error Center.