CreateOTAFirmware - Developer Guide (Cloud)| Alibaba Cloud Documentation Center

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.