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
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
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:
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
|
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
|
NeedToVerify | Boolean | No | true |
Specifies whether to verify the update package before you create a batch update task.
|
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.
|
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.