Create OTA Job¶
Create an OTA job for batch verification or upgrading.
Operation Permissions¶
Required Authorization |
Required Operation Permission |
---|---|
Device Management |
Full Access |
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. Available options are as per the below.
|
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.
|
enableUpgradeRequest |
Mandatory |
Boolean |
|
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 |
---|---|---|---|
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. Available options are as per the below.
|
upgradeScope |
Mandatory |
UpgradeScope Struct |
The scope of the upgrade. For more details, see UpgradeScope Struct>>. For firmware verification tasks, the value of the |
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. |
UpgradeScope Struct ¶
Name |
Mandatory/Optional |
Data Type |
Description |
---|---|---|---|
type |
Mandatory |
String |
The scope of the devices to be upgraded. Available options are as per the below.
|
versionNumbers |
Mandatory |
String Array |
The list of firmware version numbers. |
deviceKeys |
Optional |
String Array |
Specify the devices for firmware upgrade or verification via device keys. Only one of the parameters |
attributes |
Optional |
Map (Key is of String type, and Value is of Object Array) |
Specify the devices for firmware upgrade or verification via the attributes and their corresponding values. Only one of the parameters |
tags |
Optional |
Map (Key is of String type, and Value is of String Array) |
Specify the devices for firmware upgrade or verification via the device tags and their corresponding values. Only one of the parameters |
assetTrees |
Optional |
AssetTreeScope Struct |
Specify the devices for firmware upgrade or verification via asset tree. Only one of the parameters |
AssetTreeScope Struct ¶
Name |
Mandatory/Optional |
Data Type |
Description |
---|---|---|---|
treeId |
Mandatory |
String |
The asset tree ID. |
includedNotes |
Optional |
String Array |
The nodes in the asset tree. Specifying one node means all sub-nodes are included as well. Leave this blank to select the entire tree. |
RetryPolicy Struct ¶
Name |
Mandatory/Optional |
Data Type |
Description |
---|---|---|---|
enableRetry |
Optional |
Boolean |
|
retryInterval |
Mandatory if |
Integer |
The retry interval after failure. |
retryCount |
Mandatory if |
Integer |
The maximum number of retries. |
SchedulePolicy Struct ¶
Name |
Mandatory/Optional |
Data Type |
Description |
---|---|---|---|
isRepeatDaily |
Optional |
Boolean |
|
startTimestamp |
Mandatory |
Long |
The timestamp of the schedule start time. |
endTimestamp |
Mandatory |
Long |
The timestamp of the schedule end time. If |
Response Parameters¶
Name |
Data Type |
Description |
---|---|---|
data |
JobCreateResult Struct |
The details of the created OTA job. For more details, see JobCreateResult Struct>> |
JobCreateResult Struct ¶
Name |
Data Type |
Description |
---|---|---|
jobId |
String |
The job ID. |
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 |
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"
}
}
Java SDK Sample¶
package com.envisioniot.enos.connect_service.ota.job;
import com.envision.apim.poseidon.config.PConfig;
import com.envision.apim.poseidon.core.Poseidon;
import com.envisioniot.enos.api.common.constant.common.StringI18n;
import com.envisioniot.enos.connect_service.v2_1.ota.job.CreateJobRequest;
import com.envisioniot.enos.connect_service.v2_1.ota.job.CreateJobResponse;
import com.envisioniot.enos.connect_service.vo.ota.UpgradeScope;
import com.google.common.collect.ImmutableSet;
public class CreateJob {
public static void main(String[] args) {
final String appKey = "yourAppKey";
final String appSecret = "yourAppSecret";
String serverUrl = "yourServerUrl";
String orgId = "yourOrgId";
String firmwareId = "yourFirmwareId";
CreateJobRequest request = new CreateJobRequest();
request.setOrgId(orgId);
request.setFirmwareId(firmwareId);
request.setName(new StringI18n("testJob"));
request.setType("upgrade");
request.setUpgradePolicy("snapshot");
// Instantiate upgradeScope
UpgradeScope upgradeScope = new UpgradeScope();
upgradeScope.setType("partial");
// versionNumbers is required, whatever the type.
upgradeScope.setVersionNumbers(ImmutableSet.of("1.0"));
// Define your filter if type is "partial"
upgradeScope.setDeviceKeys(ImmutableSet.of("deviceKey1","deviceKey2"));
request.setUpgradeScope(upgradeScope);
request.setEnableUpgradeRequest(true);
request.setStartSchedule(0L);
request.setEndSchedule(2000L);
CreateJobResponse response = Poseidon
.config(PConfig.init().appKey(appKey).appSecret(appSecret).debug())
.url(serverUrl)
.getResponse(request, CreateJobResponse.class);
}
}