General remote upgrade function includes two categories, i.e. module upgrade and MCU application upgrade. The device to be upgraded performs data exchange with OneNET platform through HTTP protocol of RESTful standard format to complete the upgrade.

RESTful API necessary for southern device is divided into three categories at present, i.e. detect task, pull file and report status, in which, the contents of pull file include two APIs (TOKEN verification and file acquisition).

It introduces the use of API and the process for testing the pulling firmware through postman simulator on this page.

The document is suitable for relevant operators who perform general OTA function operations at device side.

1. Authentication parameters

Python is used to calculate product Authorization here. It will only need to change product id and accesskey during actual operation. Please refer to[API authentication]for specific process. (/book/develop/auth.md)，Python code is shown in Fig. 2.

Fig. 1 Product id and accesskey

Fig. 2 Phthon Code

As shown in Fig. 2 the authentication parameters calculated as below:

version=2018-10-31&res=products%2F245528&et=7559008892&method=sha1&sign=TPllhakDDnUV90epLnOqpj6aWqI%3D

2. Detect Task

http://ota.heclouds.com/ota/south/check?dev_id=527776559&manuf=102&model=10201&type=2&version=V1&cdn=false

The parameter Authorization of Headers: the value is the product token calculated in Fig. 2.

For manuf=102&model=10201, please refer to the table below.
dev_id=527776559 is changed to be the device id to be upgraded.
Other parameters remain unchanged.

Chip platform	Chip model	Manufacturer Number	Chip number
FANLUN	ESP32	101	10101
nordic	nrf52832	102	10201
GigaDevice	GD32	103	10301
Miscellaneous	Miscellaneous	100	10001

Fig. 3 Postman Simulator Testing Example – URL Parameter

Fig. 4 Postman Simulator Testing Example – Header

As shown in Fig. 4, the example of the code for request response is as below:

{
    "errno": 0,
    "error": "succ",
    "data": {
        "target": "V1",
        "token": "ota_iF0hnXrq2CxLrP8vZ39l",
        "size": 22,
        "md5": "ad2f4e4ea2a27eace7e4913139f8f01a",
        "signal": 10,
        "power": 50,
        "retry": 0,
        "interval": 0,
        "type": 1
    }
}

3. Verify TOKEN

For instructions of use for TOKEN verification and response information, please refer to the document of OTA-SDK instructions.

http://ota.heclouds.com/ota/south/download/ota_iF0hnXrq2CxLrP8vZ39l/check?dev_id=527776559

The parameter Authorization of Headers: the value is the product token calculated above.

dev_id=527776559 is changed to be the device id to be upgraded.
ota_iF0hnXrq2CxLrP8vZ39l is the task token obtained in authentication parameter steps.
Other parameters remain unchanged.

Fig. 5 Postman Simulator Testing Example – URL Parameter

4. Pull file

For the instruction of the use of pull file and response information, please refer to the document ofOTA-SDK instructions.

http://ota.heclouds.com/ota/south/download/ota_iF0hnXrq2CxLrP8vZ39l

ota_iF0hnXrq2CxLrP8vZ39 is the task token obtained in authentication parameter steps while other parameters remain unchanged.

The whole file may be pulled as shown in Fig. 6, or only part of the file can be pulled as shown in Fig. 7:

Fig. 6 Postman – Pull the Whole File

Fig. 7 Postman – Pull Part of the File

Explanation of Header Range field:

Range: bytes={start}-{end}

At present, it only supports following modes:

Range: bytes={start}-, get the data from the first byte ({start}+1) to the last one. For example: Range: bytes=0-, get all data. Range: bytes=2-, get data from the 3rd one to the last one. Note: if {start}>= total length of the file, then {start}=0 by default.

Range: bytes={start}-{end}, get the data from the first byte ({start}+1) to the byte of {end}+1. For example: Range: bytes=0-99, get the first 100 bytes. Note: if end}>>= total length of the file, then end=len-1 by default.If {start}>
{end}, start is set to be 0.

Range: bytes=-{end}, get the data of the bytes from end to the last one. For example: Range: bytes=-100, get the data of the last 100 bytes.

Fragment status code

Fragmented status code returned: 206;
Non-fragmented status code returned: 200

5. Report status

Please refer to the document ofOTA-SDK instructionsfor the instructions for the use of report status and response information.

http://ota.heclouds.com/ota/south/report?dev_id=527776559&token=ota_iF0hnXrq2CxLrP8vZ39l

The parameter Authorization of Headers: the value is the product token calculated above.

The contents of Body are as below:

{
    "result": 201

}

result:

101:Upgrade package downloaded successfully
102:Download failed, insufficient space
103:Download failed, memory overflow
104:Download failed, download request timed out
105:Download failed, low battery
106:Download failed, weak signal
107:Download failed, unknown exception
201:Upgrade successfully
202:Download failed, low battery
203:Download failed, memory overflow
204:Download failed, inconsistent version
205:Download failed, md5 verification failed
206:Download failed, unknown abnormal

error:

0:Status report succeeded
1:Status report failed, token authentication failed
2:Status report failed, status code error
20:Status report failed, upgrade task completed
21:Invalid operation
22:Status report failed, upgrade task canceled
24:Request content result error

Description

dev_id=527776559 is changed to be the device id to be upgraded.
ota_iF0hnXrq2CxLrP8vZ39l is the task token obtained in authentication parameter steps.
Other parameters remain unchanged.