V2.1 Create OTA Job


Create an OTA job for batch verification or upgrading.


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 OTA

Prerequisite

  • The required device and firmware have been created.

  • You have learnt the Limitations about firmware upgrades.

Request Format

POST https://{apigw-address}/connect-service/v2.1/ota-jobs?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>>

firmwareId

Query

Mandatory

String

The firmware ID.

Request Parameters (Body)

The structure of the request parameter will vary according to whether you are creating a firmware verification task or a firmware upgrade task.

Upgrade Task

Name

Mandatory/Optional

Data Type

Description

name

Optional

StringI18n

The job name. For more details on the structure and locales supported, see Internationalized name struct.

type

Mandatory

String

The job type. Use upgrade for upgrade task.

upgradeScope

Mandatory

UpgradeScope Struct

The scope of the upgrade. For more details, see UpgradeScope Struct.

upgradePolicy

Mandatory

String

The upgrade policy. Available options are as per the below.

  • snapshot

  • incremental

enableUpgradeRequest

Mandatory

Boolean

  • true: Device can request for upgrade.

  • false: Device cannot request for upgrade.

upgradeTimeout

Optional

Long

The timeout for the upgrade, which starts when the OTA task enters the “upgrading” state. The available range is between 300 to 172,800 seconds, with the default as 7,200. You can use the Search OTA Task API to search for the status of the OTA task.

retryPolicy

Optional

RetryPolicy Struct

The policy for retrying failed OTA tasks. Default is no retry. For more details, see RetryPolicy Struct.

schedulePolicy

Optional

SchedulePolicy Struct

The schedule policy for the OTA task. By default, the task starts immediately and repeats daily from 00:00:00 to 23:59:59. For more details, see SchedulePolicy Struct.

maximumConcurrency

Optional

Integer

The maximum number of concurrent upgrade tasks. The default value is 300.

Firmware Verification Task

Name

Mandatory/Optional

Data Type

Description

type

Mandatory

String

The job type. Use verify for verification task.

upgradeScope

Mandatory

UpgradeScope Struct

The scope of the upgrade. For more details, see UpgradeScope Struct. For firmware verification tasks, the value of the type parameter in this struct must be partial.

upgradeTimeout

Optional

Long

The timeout for the verification, which starts when the OTA task enters the “upgrading” state. The available range is between 300 to 172,800 seconds, with the default as 7,200. You can use the Search OTA Task API to search for the status of the OTA task.

Response Parameters

Name

Data Type

Description

data

JobCreateResult Struct

The details of the created OTA job. For more details, see JobCreateResult Struct.

Error Codes

Code

Message

Description

24404

Firmware not found

The firmware cannot be found.

24610

Not allowed to create job as firmware is not verified while enable verification is switched on

OTA job cannot be created as firmware has switched on enable verification but the firmware has not been verified.

24611

upgradeScope type total is not allowed for verification task

The option total for parameter type in UpgradeScope Struct is not allowed for verification jobs.

24612

Exceeded max verification deviceKeys, max[%d]

Exceeded the maximum number (%d) of devices for verification.

Samples

Request Sample

url: https://{apigw-address}/connect-service/v2.1/ota-jobs?action=create&orgId=yourOrgId&firmwareId=yourFirmwareId
method: POST
requestBody:
{
    "name":{
        "defaultValue":"ota-job-test",
        "i18nValue":{

        }
    },
    "type":"upgrade",
    "upgradePolicy":"snapshot",
    "upgradeScope":{
        "type":"partial",
        "versionNumbers":[
            "1.0"
        ],
        "deviceKeys":[
            "deviceKey1",
            "deviceKey2"
        ]
    },
    "startSchedule":0,
    "endSchedule":86399,
    "enableUpgradeRequest":true
}

Return Sample

{
    "code":0,
    "msg":"OK",
    "requestId":"0bdefc0f-369f-4664-a570-695f4e31877c",
    "data":{
        "jobId":"5ee1a91029b990001b9c188e"
    }
}

SDK Samples


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