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 Description

1	public function createFirmwareUpgradeTask($cutInDTO, $accessToken)

Parameter Description

Parameter	Mandatory or Optional	Location	Description
$cutInDTO	Mandatory	body	For details, see CreateUpgradeTaskInDTO structure.
$accessToken	Mandatory	header	This parameter is set to the value of the access token obtained by calling the Authentication API.

CreateUpgradeTaskInDTO

Parameter	Mandatory or Optional	Location	Description
$fileId	Mandatory	body	Identifies the target firmware version.
$targets	Mandatory	body	Indicates the devices to be upgraded. For details, see OperateDevices structure.
$policy	Optional	body	Indicates the execution policy of an upgrade task. For details, see OperatePolicy structure.

OperateDevices structure

Parameter	Mandatory or Optional	Location	Description
$deviceGroups	Optional	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	body	Indicates the device type. This parameter must be specified when a device group is specified.
$model	Optional	body	Indicates the device model. This parameter must be specified when a device group is specified.
$manufacturerName	Optional	body	Indicates the manufacturer name. This parameter must be specified when a device group is specified.
$devices	Optional	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	Location	Description
$executeType	Mandatory	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	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	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	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	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

CreateUpgradeTaskOutDTO

Parameter	Description
$operationId	Identifies an operation task.

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.