V2.1 Create Firmware File¶

Create a firmware file for a product.

This API is available in EnOS 2.2.0 and above.

Operation Permissions¶

Before invoking this API, ensure that the service account has been authorized the policy that includes the following service(s) and action permission(s). For how to authorize the service account, see Managing Service Accounts.

Required Service	Required Operation Permission
Firmware	Create

Prerequisite¶

The required product has been created.

Request Format¶

POST https://{apigw-address}/connect-service/v2.1/ota-firmwares?action=create

Request Parameters (URI)¶

Name	Location（Path/Query）	Mandatory/Optional	Data Type	Description
orgId	Query	Mandatory	String	The organization ID which the asset belongs to. How to get orgId>>
productKey	Query	Mandatory	String	The product key.

Request Parameters (Body)¶

The format of the request body is multipart/form-data, which consists of two form-data sections:

Firmware metadata form-data
Firmware file form-data

Header of the firmware metadata form-data¶
Name	Mandatory/Optional	Data Type	Description
Content-Disposition	Mandatory	Content-Disposition: form-data; name=”metadata”	`name` is a constant that indicates the name of the metadata message.

Body of the firmware metadata form-data¶
Name	Mandatory/Optional	Data Type	Description
name	Mandatory	StringI18n	The firmware name. Note that no repetitive firmware names are allowed under the same product. For more details on the structure and locales supported, see Internationalized name struct.
version	Mandatory	String	The firmware version.
signMethod	Mandatory	String	The signature algorithm for the firmware files, supports `md5` and `sha256`.
sign	Mandatory	String	The fimware file signature.
desc	Optional	String	The firmware description.
enableVerification	Mandatory	Boolean	Specifies whether the firmware must be verified for upgrading tasks. `true`: Needs to be verified. `false`: Does not need to be verified.
firmwareTags	Optional	Map (Key and Value are of String type)	The firmware tags. The key must be unique for each firmware. For details, see How to use tags.
maxAllowedForVerification	Optional	Integer	The maximum number of devices to be used to verify the firmware. The number must be greater than or equals to 1.
minSuccessForVerified	Optional	Integer	The minimum number of successfully verified devices to pass the firmware verfication job. The number must be greater than or equals to 1, and must not be larger than `maxAllowedForVerification`.

Header of the firmware file form-data¶
Name	Mandatory/Optional	Data Type	Description
Content-Disposition	Mandatory	Content-Disposition: form-data; name=”file”; filename=”yourFileName”	`name` is a constant that indicates the name of the metadata message. `filename` is the filename corresponding to the firmware.

Response Parameters¶

Name	Data Type	Description
data	FirmwareCreateResult Struct	The created firmware ID. For details, see FirmwareCreateResult Struct>>

FirmwareCreateResult Struct ¶

Name	Data Type	Description
firmwareId	String	The created firmware ID.

Error Codes¶

Code	Message	Description
24601	Firmware version already exists	A firmware with this version already exists.
24602	Firmware name already exists	A firmware with this name already exists.
24603	Not allowed to create firmware concurrently	Firmware cannot be created concurrently.

Samples¶

Request Sample¶

url: https://{apigw-address}/connect-service/v2.1/ota-firmwares?action=create&orgId=yourOrgId&productKey=yourProductKey
method: POST
requestBody:
  Firmware metadata form-data:
    Header:
    Content-Disposition: form-data; name="metadata"
    Body:
    {
    "name": {
        "defaultValue": "defaultValue"
    },
    "version": "yourVersion",
    "signMethod": "md5",
    "sign": "fileSig",
    "enableVerification": false,
    "desc": "ota firmware",
    "firmwareTags": {
      "tagKey": "tagValue"
    },
    "maxAllowedForVerification": 5,
    "minSuccessForVerified": 2
    }

Return Sample¶

{
    "code": 0,
    "msg": "OK",
    "requestId": "9bba8197-d6d6-4fe2-a3d2-65153ab6376c",
    "data": {
        "firmwareId": "5ee0edb729b990001b9acf9a"
    }
}

SDK Samples¶

You can access the SDK samples for Connection Service on GitHub:

Java
Python