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: