Creates an update package after an update package file is uploaded to Object Storage Service (OSS).

Limits

  • Each Alibaba Cloud account can have a maximum of 500 update packages.
  • 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.
  • 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 current version of the firmware. 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 update package. The name must be unique within an Alibaba Cloud account and 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.

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

The URL of the update package. This parameter specifies the storage location of the update package in OSS. This parameter is returned when you call the GenerateOTAUploadURL operation to generate the parameters that are required to upload an update package.

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

The ID of the instance. This parameter is not required for public instances. However, the parameter is required for the instances that you have purchased.

FirmwareSign String No 93230c3bde425a9d7984a594ac55****

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

If you do not specify this parameter, the MD5 value of the update package in OSS is used as the package signature.

SignMethod String No MD5

The signature method of the update package. The only valid value is MD5.

Default value: MD5.

FirmwareSize Integer No 900

The size of the update package. Unit: bytes.

If you do not specify this parameter, the size of the update package file in OSS is used as the package size.

ProductKey String No a1uctKe****

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

FirmwareDesc String No OTA function updated

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

Type Integer No 0

The type of the 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 to0, 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: verifies the update package
  • false: does not verify the update package

Default value: true

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 is successful. 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.
  • false: The call failed.

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.