Creating a Firmware Upgrade Task

Typical Scenario

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

API Function

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

API Prototype

Method	POST
URL	https://server:port/iodm/northbound/v1.5.0/operations/firmwareUpgrade
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 firmware 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/firmwareUpgrade
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.