Instructions for use of OTA - SDK
To obtain SDK or technical support, pleasefill in enterprise and project informationto make an application and then send it to chenkeyu@cmiot.chinamobile.com
1. User routine
The user routine of OTA is sample folder, which corresponds to OtaSample item in VS project. The functions involved include:| Function Name | Function Description | Parameters and notes |
|---|---|---|
| ota_init | Ota context initialization function | check_time: time interval for checking upgrade task in seconds |
| ota_loop | Ota logic control function | Whether to check upgrade task immediately notes：Periodic call is required. |
| ota_deinit | Ota context destruction function | Note: After ota process is completed, the function shall be called to clear relevant memory space. |
2. Logic control
OTA logic control function and related function files are in core folder, which corresponds to CMIOT-OTA items in VS project. The files and secondary folders in core folder include:| File or folder name | Description |
|---|---|
| ota_core.c | Including ota logic control function and functional functions. |
| ota_parse.c | Including parse message control function |
| ota_api.h | ota external use header file |
| ota_internal.h | ota internal use header file |
| cjson/ | json parsing component |
| http/ | http message parsing component |
| mbedtls/ | HMAC signature encryption component |
Ota logical control functions and related analytical functions are included in ota_core.c file. The functions include:
| Function Name | Function Description | Parameters and notes |
|---|---|---|
| OTA_Pack_Check_Task | Query task API package | None |
| OTA_Pack_Check_Token | Token verification API package | None |
| OTA_Pack_Get_Package | Get file API package | None |
| OTA_Pack_Report | Report status API package | None |
| OTA_Pack_Authorization_Info | Authorization parameter calculation and package | None |
| OTA_CHECK_DEVICE | Check if the device is available for upgrade. | Note: Check if the power and signal strength comply with the conditions preset. |
3. Adaptation interface
The adaptation interface of OTA is located in adapter folder, which corresponds to OtaAdapter in VS project. The interface is divided into two parts, i.e. system interface and network interface. The functions involved in system interface include:| Function Name | Function Description | Parameters and notes |
|---|---|---|
| OTA_Event_Handle | Ota event trigger function | None |
| ota_log_printf | Log print | None |
| ota_atoi | String to integer | None |
| ota_itoa_decimal | Decimal integer to string | None |
| ota_hex2str | Hexadecimal to string | Note: md5 calculation result is converted into string for comparison. |
| ota_malloc | Memory application | None |
| ota_free | Memory release | None |
| ota_get_tick | Get system running time | Note: used for timing. |
| ota_get_deviceID | Get device ID | None |
| ota_get_manuf | Get manufacturer No. | None |
| ota_get_model | Get module No. | None |
| ota_get_type | Get upgrade type | Note: 1 refers to fota task; 2 refers to sota task. |
| ota_get_version | Get current version | None |
| ota_get_signals | Get signal strength | None |
| ota_get_powers | Get battery power | None |
| ota_get_auth_version | Get authentication version | Note: Current authentication version is fixed as “2018-10-31”. |
| ota_get_auth_res | Get res. | Note: It refers to getting of product ID in current SDK. |
| ota_get_auth_et | Get authentication expiration time | Note: UNIX time |
| ota_get_auth_method | Get signature calculation method | Note: It supports ha1/sha256/md5 (all lowercase) currently. |
| ota_get_auth_accesskey | Get accesskey | None |
| ota_read_flash | Restore ota state from flash. | None |
| ota_save_flash | Save ota state to flash | None |
| ota_calculate_range | Calculate the range for getting upgrade package next time. (range) | None |
In which, the functions involved in network interface include:
| Function Name | Function Description | Parameters and notes |
|---|---|---|
| ota_net_init | Network connection initialization | None |
| ota_net_send | Send function | None |
| ota_get_host_by_name | Domain name resolution | Note: Return to the fixed IP directly if domain name resolution is not supported. |
4. Event Description
SDK logic control and user data exchange are realized through event triggering, and they are included in the function of OTA_Event_Handle(). In which, the events involved include:| Event name | Function Description | Parameter and note |
|---|---|---|
| OTA_EVENT_TASK_ManufOrModel_ERROR | Task detection failed, manufacturer number or module number is inconsistent. | None |
| OTA_EVENT_TASK_Ver_ERROR | Task detection failed, the initial version number of differential package is inconsistent. | None |
| OTA_EVENT_TASK_STATE_ERROR | Task detection failed, task status failed | None |
| OTA_EVENT_TASK_NO_TASK | Task detection failed, no corresponding task. | None |
| OTA_EVENT_TASK_OTHER_ERROR | Task detection failed due to other reasons. | Note: The reasons include OneNET error, task stop, etc. |
| OTA_EVENT_TASK_SUCCESS | Task detection succeeded | Note: After the task is detected successfully, the context state parameter is downloaded. |
| OTA_EVENT_TOKEN_OK | token verification successful | Note: tok verification is completed for acquisition. |
| OTA_EVENT_TOKEN_INTERNAL_ERROR | token verification failed, OneNET internal error | None |
| OTA_EVENT_TOKEN_EXPIRED_ERROR | token verification failed, token expired. | Note:end this OTA process And destroy the context |
| OTA_EVENT_TOKEN_RETRIEVE_ERROR | token verification failed, token expired. | Note: A new task may be detected and new token can be updated. |
| OTA_EVENT_TOKEN_CHECK_ERROR | token verification failed, token error | Note:end this OTA process And destroy the context |
| OTA_EVENT_TOKEN_PAUSED_ERROR | token verification failed, task suspended. | Note:try again according to the time of the retrial, but do not consume the number of retries |
| OTA_EVENT_TOKEN_TASK_EXPIRED_ERROR | token verification failed, task ended. | Note:end this OTA process And destroy the context |
| OTA_EVENT_TOKEN_TERMINATE_ERROR | token verification failed, task cancelled. | Note:end this OTA process And destroy the context |
| OTA_EVENT_TOKEN_OTHER_ERROR | token verification failure due to other reasons. | None |
| OTA_EVENT_REPORT_DOWNLOAD_SUCCESS | Start to report download success status. | None |
| OTA_EVENT_REPORT_LOW_POWER | Start to report download failure status caused by low battery power. | None |
| OTA_EVENT_REPORT_BAD_SIGNAL | Start to report download failure status caused by weak signal. | None |
| OTA_EVENT_REPORT_UNKNOWN_ERROR | Start to report download failure status caused by other reasons. | Note:other reasons include the consumption of the number of retries, the server did not find resources, file size inconsistency, invalid token and so on |
| OTA_EVENT_REPORT_UPDATE_SUCCESS | Start to report successful upgrade status. | None |
| OTA_EVENT_REPORT_MD5_ERROR | Start to report upgrade failure status caused by md5 verification failure. | None |
| OTA_EVENT_REPORT_SUCCESS | Status reported successfully. | Note：reported success，if report is download success,then start upgrading Note: If it is other status, terminate OTA process and the context. |
| OTA_EVENT_REPORT_FAILED | Status report failed due to other reasons. | Note: The reasons include token failure,the status code of uploading error, the upgrade task has been cancelled, the upgrade task has been completed, and invalid operation, If the upgrade task has been cancelled or completed,recommend to end the OTA process and destroy the context |
| OTA_EVENT_custom_retry_download | Start download retry. | Note: Since the number of bytes received is not equal to the contentlength, the retry timing was started |
| OTA_EVENT_custom_save_packet | ||
| OTA_EVENT_custom_ready_update | Start to upgrade. | None |
| OTA_EVENT_custom_save_task_info | Save task information to flash. | Note: save the received file as a file |
| OTA_EVENT_custom_report_error_clear | End OTA process | Note:when the escalation status fails due to the cancellation of the upgrade task and the completion of the upgrade task, it is recommended to end the OTA process and destroy the context |
| OTA_EVENT_custom_delete_package | Clear the upgrade package data saved when destroying the context. | None |
5. Other descriptions
(1) When running the project on win platform, it only requires to modify default_device_id, default_manuf, default_model, default_type, default_version, default_res and default_access_key.(2) In the event OTA_EVENT_custom_ready_update, other methods shall be added to determine whether the upgrade is successful (for example, by comparing the versions before and after the upgrade, etc.), and then report the upgrade status;
(3) The calculated result with signature for encryption will be saved to encrypt_result variable in the context in OTA_Pack_Authorization_Info(). In OTA_EVENT_custom_save_task_info event, it can be saved into flash or re-calculated when the status is restored.
(4) If no data is received for a certain period of time, it shall be marked as a retry (ctx_net_state is reset to NET_STATE_NULL while isRetry is reset as DownLoadRetry_True);
(5) When detecting task API, if cdn is set to be “true”, the download ip of the upgrade package can be returned;
(6) If it is necessary to save some data into flash for restoring in ota_save_flash function, the token returned when task is detected successfully, the signal requirements, power requirements, time of retry, time interval of retry, upgrade package size, size of upgrade package downloaded, md5 information of upgrade package, etc. shall be saved. Furthermore, the size of the upgrade packaged downloaded shall be updated in flash every time when the fragment package is obtained successfully and the data has been stored;
(7) The fragment range of pull file shall be calculated in ota_calculate_range() function every time, and the method of calculation can be designed freely based on actual needs;
(8) isRetry to retry state in callback event can be reset to retry state in callback event in case the power is low or the signal is weak when downloading the upgrade package; (9) The file name of the upgrade package can be obtained from Content-Disposition if necessary;
(10) The minimum range of each fragment packet obtained is limited to 2 bytes;
(11) In report status, if OneNET receives status code but no response is made from sdk due to some reasons (e.g. due to the network), the context may be destroyed directly in OTA_EVENT_REPORT_FAILED event according to actual needs.