API debugging - network debugging assistant

1. Authentication parameters

2. Version report

3. Detect task

4. Download firmware

5. Report status

OTA includes 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 devices is divided into three categories at present, i.e. detect task, pull file and report status.

It mainly introduces the process testing and pulling the firmware by network debugging assistant using API in the part so as to provide reference for package testing carried out by R & D personnel.

1. Authentication parameters

Python is used to calculate Authorization here. It will only need to change product id and accesskey during actual operation. Please refer to Fig. 1 for Python code.

The code download address is as below:

◈ JAVA code, Python code download ◈ C code download

Fig. 1 Python Code Example

Authentication parameters calculated:

version=2018-10-31&res=products%2F198290&et=7555917657&method=sha1&sign=ZUXNMUqvAbuH0uHs0S1pd%2BgflNE%3D

2. Version report

POST http://ota.heclouds.com/ota/device/version?dev_id=522747162 HTTP/1.1
Content-Type: application/json
Authorization:version=2018-10-31&res=products%2F198290&et=7555917657&method=sha1&sign=ZUXNMUqvAbuH0uHs0S1pd%2BgflNE%3D
host:ota.heclouds.com
Content-Length:20

{"s_version":"V1.3"}

Fig. 2 Report Version

3. Detect Task

dev_id=522747162 needs to be changed to be the id of the device upgraded. Other parameters remain unchanged.

GET /ota/south/check?dev_id=522747162&manuf=102&model=10201&type=2&version=V11&cdn=false HTTP/1.1
Authorization:version=2018-10-31&res=products%2F198290&et=7555917657&method=sha1&sign=ZUXNMUqvAbuH0uHs0S1pd%2BgflNE%3D
host:  ota.heclouds.com
//line feed here; please delete the contents of the line during use and keep the line break.
//line feed here; please delete the contents of the line during use and keep the line break.

Fig. 3 Detect Task

4. Download firmware

GET /ota/south/download/ota_JcWgqjwXigKAfRayjjUW HTTP/1.1
Range:bytes=0-5
host:  ota.heclouds.com
//line feed here; please delete the contents of the line during use and keep the line break.
//line feed here; please delete the contents of the line during use and keep the line break.

Fig. 4 Download Firmware

When pulling part of the file, the header Range field is modified.

Range: bytes={start}－{end}, only following modes are supported at present:

1. 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.
2. 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.
3. 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.

If {end} is larger than the total length of the file (len), then end=len (get all files) by default.

Status code

Fragmented status code returned: 206;

Non-fragmented status code returned: 200

5. Report status

POST /ota/south/device/download/ota_3lI1NIMLB6E4u260cLRd/progress?dev_id=522747162 HTTP/1.1
Authorization:version=2018-10-31&res=products%2F198290&et=7555917657&method=sha1&sign=ZUXNMUqvAbuH0uHs0S1pd%2BgflNE%3D
host:ota.heclouds.com
Content-Type: application/json
Content-Length:11

{"step":54}//download report progress is 54%.

Fig. 5 Report Download Progress

POST /ota/south/device/download/ota_3lI1NIMLB6E4u260cLRd/progress?dev_id=522747162 HTTP/1.1
Authorization:version=2018-10-31&res=products%2F198290&et=7555917657&method=sha1&sign=ZUXNMUqvAbuH0uHs0S1pd%2BgflNE%3D
host:ota.heclouds.com
Content-Type: application/json
Content-Length:12

{"step":201}//meaning the upgrade is completed.

Fig. 6 Status Report – Upgrade Completed

Description

1. When the device is downloading the upgrade package (fragmented download), download progress can be reported if necessary (step=[0,100] can only be reported when the device is “downloading”);

2. If the download progress reported by the device is 100 (i.e. step: 100), the platform will change the upgrade status of the device from “downloading” to “upgrading”.

3. If only the device is in “downloading” status, the device can report the download progress via the interface. The error of “invalid state” will be returned in other status.

4. If step is above 100, it will be used as reporting states (When the device is in following three states, i.e.: to be upgraded, downloading and upgrading, the upgrade process can be completed by reporting following codes. Following states cannot be reported when it is in other states such as canceled, upgrade failed, upgrade successful, suspended):

The platform will display that the status of the task is completed after the upgrade status is reported successfully.