Updated on 2022-02-24 GMT+08:00

Creating a Software Upgrade Task

Typical Scenario

If the device software needs to be upgraded, an NA can call this API to create a software upgrade task for multiple devices. Before the upgrade, ensure that the target version package has been uploaded to the IoT platform. Currently, only the software of NB-IoT devices can be upgraded.

API Function

This API is used by an NA to upgrade the software of multiple devices on the IoT platform. Currently, only the software of NB-IoT devices can be upgraded.

API Prototype

Method

POST

URL

https://server:port/iodm/northbound/v1.5.0/operations/softwareUpgrade

Transport Protocol

HTTPS

Request Parameters

Parameter

Mandatory or Optional

Type

Location

Description

app_key

Mandatory

String

header

Identifies an application that can be accessed on the IoT platform. The value of this parameter is allocated by the IoT platform when the application is created on the platform.

Authorization

Mandatory

String

header

Indicates the authentication information for accessing the IoT platform. The value is Bearer {accessToken}, in which {accessToken} indicates the access token returned by the Authentication API.

fileId

Mandatory

String

body

Identifies the target software version.

targets

Mandatory

OperateDevices

body

Indicates the target to be upgraded.

policy

Optional

OperatePolicy

body

Indicates the execution policy of the upgrade task.

OperateDevices structure

Parameter

Mandatory or Optional

Type

Location

Description

deviceGroups

Optional

List<String>

body

Indicates the device group name list. A maximum of 256 device groups are supported.

Either this parameter or devices must be specified.

deviceType

Optional

String(256)

body

Indicates the device type.

This parameter must be specified when a device group is specified.

model

Optional

String(256)

body

Indicates the device model.

This parameter must be specified when a device group is specified.

manufacturerName

Optional

String(256)

body

Indicates the manufacturer name.

This parameter must be specified when a device group is specified.

devices

Optional

List<String>

body

Indicates the device ID list. A maximum of 256 devices are supported.

Either this parameter or deviceGroups must be specified.

OperatePolicy structure

Parameter

Mandatory or Optional

Type

Location

Description

executeType

Mandatory

String

body

Indicates the execution type. The default value is now.

  • now: The upgrade task is executed now.
  • device_online: The upgrade task is executed when a device goes online.
  • custom: The execution type is customized.

startTime

Optional

String

body

Indicates the start time of the operation task. This parameter must be specified when executeType is set to custom. The value is in the format of yyyyMMdd'T'HHmmss'Z'. An example value is 20151212T121212Z.

endTime

Optional

String

body

Indicates the end time of the operation task. This parameter must be specified when executeType is set to custom. The value is in the format of yyyyMMdd'T'HHmmss'Z'. An example value is 20151212T121212Z.

retryType

Optional

Boolean

body

Indicates whether the platform retries the task upon an execution failure. The default value is false.

  • true: Retry is performed.
  • false: The platform does not retry the task.

retryTimes

Optional

Integer[1,5]

body

Indicates the number of retries. The value ranges from 1 to 5. This parameter must be specified when retryType is set to true.

Response Parameters

Status Code: 200 OK

Parameter

Type

Description

operationId

String

Identifies an operation task.

Request Example

Method: POST
Request:
https://server:port/iodm/northbound/v1.5.0/operations/softwareUpgrade
Header:
app_key: ******
Authorization: Bearer ******
Content-Type: application/json
Body:
{
  "fileId": "**********",
  "targets": {
    "devices": [
      "*****"
    ]
  }
}

Response Example

Response:
Status Code: 200 OK
Content-Type: application/json
Body:
{
  "operationId": "**********"
}

Error Codes

HTTP Status Code

Error Code

Error Description

Remarks

400

120015

Bad request error.

A request error occurs.

Recommended handling: Check whether the parameters in the request are correct.

400

123016

The parameter is error, targetversion not match with device.

The value of targetVersion is incorrect. Specifically, it does not match the specified device.

Recommended handling: Check whether the values of deviceType, manufacturerName, and model carried in the API request are consistent with the target version package information specified by fileId.

400

123019

manufacturerName is null.

The manufacturer name is null.

Recommended handling: Check whether manufacturerName carried in the API request is correct.

400

123020

deviceType is null

The device type is null.

Recommended handling: Check whether deviceType carried in the API request is correct.

400

123021

model is null.

The device model is null.

Recommended handling: Check whether model carried in the API request is correct.

400

123022

deviceGroups and devices cannot be null together

deviceGroups and devices cannot be both null.

Recommended handling: Specify either deviceGroups or devices.

400

123023

deviceGroups and devices cannot be exist together

deviceGroups and devices cannot coexist.

Recommended handling: Specify either deviceGroups or devices.

400

123024

The number of deviceGroups or devices reached upper limit

The number of device groups or devices reaches the upper limit.

Recommended handling: Check the number of device groups or devices. The number cannot exceed 256.

400

123025

executeType is error or can not to be null.

The value of executeType is incorrect or is not specified.

Recommended handling: Check whether executeType in the request is unspecified or incorrect.

400

123026

startTime or endTime is null or error.

The value of startTime or endTime is empty or incorrect.

Recommended handling: Check whether startTime and endTime in the request are unspecified or incorrect.

400

123028

retryTimes is null or beyond the limit.

The value of retryTimes is empty or exceeds the upper limit.

Recommended handling: Verify that the value of retryTimes in the request is left unspecified or is not less than 1 or greater than 5.

400

123032

startTime can not be later than the endTime.

The value of startTime cannot be later than the value of endTime.

Recommended handling: Check whether startTime in the request is later than endTime.

400

123033

startTime can not be earlier than the now.

The value of startTime cannot be earlier than the current time.

Recommended handling: Check whether startTime in the request is earlier than the current time.

400

123034

endtime must be greater than 5 minutes.

The value of endtime must be 5 minutes later than that of startTime.

Handling suggestions: Verify that the interval between startTime and endTime in the request is greater than 5 minutes.

403

1010009

app throttle exceed.

The NA calls the API at a frequency that exceeds the flow control threshold (100 calls per minute by default).

Recommended handling: Contact IoT platform maintenance personnel to adjust the flow control threshold or control the API call frequency.

403

1010005

App_key or access_token is invalid.

The access token is invalid.

Recommended handling: Check whether accessToken carried in the API request is correct.

404

123002

Device or package file not found.

The device or package does not exist.

Recommended handling: Check whether fileId carried in the API request is correct.