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

Optional

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: