4.4.9.2. OTA API

This system provides a low-level flashing library libupdate.so, and implements a set of cross-platform APIs for writing OTA update packages.

Source code path: hbre/otaupdate/src/ota_apis/hobot_ota_hl.c

Header file: hobot_ota_hl.h

An ota_tool has been developed based on the OTA HighLevel API. This tool helps customers more easily reference and implement related functions when designing the OTA Service.

Source code path: hbre/otaupdate/src/ota_tool

Header file: hobot_ota_hl.h

Library: libupdate.so

Error Types Returned by Dynamic Library Interfaces

The dynamic library error values are defined as follows:

enum ota_err_e {
    OTA_SUCCESS = 0,
    OTAERR_IO,
    OTAERR_PLAT_UNSUPPORT,
    OTAERR_REPEAT,
    OTAERR_MUTEX_INIT_LOCK_ERR,
    OTAERR_NOTINIT,
    OTAERR_NULLPOINTER,
    OTAERR_SHORTBUF,
    OTAERR_THREAD_CREATE,
    OTAERR_RANGE,
    OTAERR_STAGE,
    OTAERR_IMAGE_WRITE,
    OTAERR_BOOT_FAILED,
    OTAERR_VEEPROM,
    OTAERR_FILE_TYPE,
    OTAERR_UNZIP,
    OTAERR_NO_EXISTS,
    OTAERR_MALLOC,
    OTAERR_VERIFY,
    OTAERR_IMG_SIZE,
    OTAERR_UPDATE_STATUS,
}

Interface List

Interface Prototype	Description
int32_t otaInitLib(void);	Dynamic library initialization
int32_t otaDeinitLib(void);	Dynamic library deinitialization
int32_t otaGetLibVersion(char *version, int32_t len);	Get dynamic library version
int32_t otaRequestStart(const char *image_name, enum ota_update_owner owner);	Start upgrade thread
int32_t otaGetResult(void);	Get upgrade status and result
int32_t otaGetProgress(void);	Get upgrade progress
int32_t otaGetUpdatingImageName(char *image_name , int32_t len);	Get currently upgrading package
int32_t otaGetSysVersion(char *version, int32_t len);	Get current system version
int32_t otaGetPartition(uint8_t *partition);	Get current boot AB partition
int32_t otaSetPartition(uint8_t partition);	Set next boot AB partition
int32_t otaGetOwnerFlag(enum ota_update_owner *owner);	Get OTA owner (after reboot)
int32_t otaMarkOTASuccessful(void);	Mark OTA upgrade successful (after reboot)
int32_t otaCheckUpdate(void);	Check if upgrade succeeded (after reboot)
int32_t otaPartitionSync(void);	Synchronize AB and backup partitions
void otaClearFlags(void);	End upgrade, clear OTA flags

otaInitLib

【Function Declaration】

int32_t otaInitLib(void);

【Parameter Description】

[OUT] N/A
[IN] N/A

【Return Value】

OTA_SUCCESS: Success
-OTAERR_REPEAT: Repeated initialization

【Function Description】

Initialize the dynamic library for board-side flashing interface, mainly initializing the global structure g_upgrade_info.

【Example Code】

#include <stdio.h>
#include <hobot_ota_hl.h>
int main(void) {
    int32_t ret;
    ret = otaInitLib();
    if (ret != 0) {
        printf("otaInitLib return: %d\n", ret);
        return ret;
    }
    ret = otaDeinitLib();
    if (ret != 0) {
        printf("otaDeinitLib return: %d\n", ret);
        return ret;
    }
    return 0;
}

otaDeinitLib

【Function Declaration】

int32_t otaDeinitLib(void);

【Parameter Description】

[OUT] N/A
[IN] N/A

【Return Value】

OTA_SUCCESS: Success
-OTAERR_NOTINIT: Not initialized, cannot call deinitialization

【Function Description】

Deinitialization

【Example Code】

Refer to otaInitLib

otaGetLibVersion

【Function Declaration】

int32_t otaGetLibVersion(char *version, int32_t len);

【Parameter Description】

[OUT] version: Buffer to store version information. Version is returned as a three-part string (e.g., 1.0.0)
[IN] len: Length of input buffer

【Return Value】

OTA_SUCCESS: Success
-OTAERR_NULLPOINTER: Null pointer for version
-OTAERR_SHORTBUF: Input buffer too small
-OTAERR_PLAT_UNSUPPORT: Getting version number is not supported

【Function Description】

Get the version of this dynamic library

【Example Code】

#include <stdio.h>
#include <hobot_ota_hl.h>
int main(void) {
    int32_t ret;
    char version[128];
    if (ret = otaGetLibVersion(version, sizeof(version))) {
        return ret;
    }
    printf("version: %s\n", version);
}

otaRequestStart

【Function Declaration】

int32_t otaRequestStart(const char *image_name, enum ota_update_owner owner);

【Parameter Description】

[OUT] N/A
[IN] image_name: Absolute path of the update package. Supports multiple package types passed simultaneously, separated by semicolons.
[IN] owner: Process initiating this update, defined by enum ota_update_owner

【Return Value】

OTA_SUCCESS: Success
-OTAERR_NULLPOINTER: Null pointer for image_name
-OTAERR_RANGE: Invalid owner setting, out of defined range
-OTAERR_NOTINIT: Dynamic library not initialized
-OTAERR_REPEAT: Another process is currently upgrading
-OTAERR_IO: IO failure
-OTAERR_THREAD_CREATE: Thread creation failed

【Function Description】

Start the upgrade thread to perform update on the provided image_name, and set the current upgrade owner.

【Example Code】

#include <stdio.h>
#include <hobot_ota_hl.h>
int main(void) {
    int32_t ret;
    int32_t result;
    int32_t progress;
    char imgname[256];
    ret = otaInitLib();
    if (ret != 0) {
        printf("otaInitLib return: %d\n", ret);
        return ret;
    }
    if (ret = otaRequestStart("/userdata/all_in_one.zip", OTA_TOOL)) {
        printf("otaRequestStart return: %d\n", ret);
        return ret;
    }
    do {
        result = otaGetResult();
        if (ret = otaGetUpdatingImageName(imgname, sizeof(imgname))) {
            printf("otaGetUpdatingImageName return: %d\n", imgname);
        }
        progress = otaGetProgress();
        printf("current image: %s, progress: %d\n", imgname, progress);
        sleep(1);
    } while(result != 0 && result != 3);

    ret = otaGetPartition(&cur_part);
    if (ret != 0) {
        printf("otaGetPartition returned with %d\n", ret);
    }
    ret = otaSetPartition(1 - cur_part);
    if (ret != 0) {
        printf("otaSetPartition returned with %d\n", ret);
    }
    /* Then reboot system */
    return 0;
}

otaGetResult

【Function Declaration】

int32_t otaGetResult(void);

【Parameter Description】

[OUT] N/A
[IN] N/A

【Return Value】

OTA_UPGRADE_NOT_START: Upgrade not started
OTA_UPGRADE_IN_PROGRESS: Upgrading
OTA_UPGRADE_SUCCESS: Upgrade completed successfully
OTA_UPGRADE_FAILED: Upgrade completed with failure
-OTAERR_NOTINIT: Dynamic library not initialized

【Function Description】

Get upgrade result

【Example Code】

Refer to otaRequestStart

otaGetProgress

【Function Declaration】

int32_t otaGetProgress(void);

【Parameter Description】

[OUT] N/A
[IN] N/A

【Return Value】

0 ~ 100: Current upgrade progress (%)
-OTAERR_NOTINIT: Dynamic library not initialized

【Function Description】

Get current upgrade progress

【Example Code】

Refer to otaRequestStart

otaGetUpdatingImageName

【Function Declaration】

int32_t otaGetUpdatingImageName(char *image_name , int32_t len);

【Parameter Description】

[OUT] image_name: Buffer to store result. Possible values for image_name: “idle_state” – Upgrade not started “all_img_finish” – Upgrade completed “” – Failed before writing image Other package names ending with “.img”
[IN] len: Buffer length

【Return Value】

OTA_SUCCESS: Success
-OTAERR_NULLPOINTER: Null pointer for image_name
-OTAERR_NOTINIT: Dynamic library not initialized
-OTAERR_SHORTBUF: Buffer length too short

【Function Description】

Get the currently upgrading image

【Example Code】

Refer to otaRequestStart

otaGetSysVersion

【Function Declaration】

int32_t otaGetSysVersion(char *version, int32_t len);

【Parameter Description】

[OUT] version: Buffer to store version information. Version stores system software version, starting with date (yyyymmdd)
[IN] len: Length of input buffer

【Return Value】

OTA_SUCCESS: Success
-OTAERR_NULLPOINTER: Null pointer for version
-OTAERR_SHORTBUF: Input buffer too small
-OTAERR_IO: IO error, please retry

【Function Description】

Get current system software version

【Example Code】

#include <stdio.h>
#include <hobot_ota_hl.h>
int main(void) {
    int32_t ret;
    char version[128];
    if (ret = otaGetSysVersion(version, sizeof(version))) {
        printf("otaGetSysVersion return: %d\n", ret);
        return -1;
    }
    printf("current system version: %s\n", version);
    return 0;
}

otaGetPartition

【Function Declaration】

int32_t otaGetPartition(uint8_t *partition);

【Parameter Description】

[OUT] partition: Pointer to variable receiving current partition. *partition=0: currently on A partition, *partition=1: currently on B partition
[IN] N/A

【Return Value】

OTA_SUCCESS: Success
-OTAERR_NULLPOINTER: Null pointer for partition
-OTAERR_IO: IO error, please retry

【Function Description】

Get current boot AB partition

【Example Code】

Refer to otaRequestStart

otaSetPartition

【Function Declaration】

int32_t otaSetPartition(uint8_t partition);

【Parameter Description】

[OUT] N/A
[IN] partition: Next boot partition. 0: A partition, 1: B partition

【Return Value】

OTA_SUCCESS: Success
-OTAERR_NOTINIT: Dynamic library not initialized
-OTAERR_RANGE: Invalid partition range, must be 0 or 1
-OTAERR_IO: IO error, please retry
-OTAERR_STAGE: Not supported in current upgrade stage. Not supported during or after failed upgrade

【Function Description】

Set next boot AB partition

【Example Code】

Refer to otaRequestStart

otaGetOwnerFlag

【Function Declaration】

int32_t otaGetOwnerFlag(enum ota_update_owner *owner);

【Parameter Description】

[OUT] owner: Variable to receive current upgrade owner. See enum ota_update_owner
[IN] N/A

【Return Value】

OTA_SUCCESS: Success
-OTAERR_NOTINIT: Not initialized
-OTAERR_NULLPOINTER: Null pointer for partition
-OTAERR_IO: IO error, please retry

【Function Description】

Get current upgrade owner

【Example Code】

static int check_and_mark(void) {
    enum ota_update_owner owner;
    int32_t ret;
    ret = otaGetOwnerFlag(&owner);
    if (ret != 0) {
            printf("otaGetOwnerFlag returned with %d\n", ret);
            return -1;
    }
    if (owner != OTA_TOOL) {
            printf("The OTA update is not launched by ota_tool, owner: %d\n", owner);
            return -1;
    }
    ret = otaCheckUpdate();
    if (ret == -OTAERR_IMAGE_WRITE) {
            printf("ota_tool: OTA image write failed, is there a reboot during update?\n");
            goto clearFlags;
    }
    if (ret == -OTAERR_BOOT_FAILED) {
            printf("ota_tool: The new package boot failed. Please check the packages\n");
            goto clearFlags;
    }
    if (ret != 0) {
            printf("otaCheckUpdate returned with %d\n", ret);
            goto clearFlags;
    }
    ret = otaMarkOTASuccessful();
    if (ret != 0) {
            printf("otaMarkOTASuccessful returned with %d\n", ret);
            goto clearFlags;
    }
    ret = otaPartitionSync();
    if (ret != 0) {
            printf("otaPartitionSync returned with %d\n", ret);
            goto clearFlags;
    }
clearFlags:
    otaClearFlags();
    return ret;
}

otaMarkOTASuccessful

【Function Declaration】

int32_t otaMarkOTASuccessful(void);

【Parameter Description】

[OUT] N/A
[IN] N/A

【Return Value】

OTA_SUCCESS: Success
-OTAERR_NOTINIT: Not initialized
-OTAERR_IO: IO error, please retry

【Function Description】

Mark this upgrade as successful

【Example Code】

Refer to otaGetOwnerFlag

otaCheckUpdate

【Function Declaration】

int32_t otaCheckUpdate(void);

【Parameter Description】- [OUT] N/A

[IN] N/A

【Return Value】

OTA_SUCCESS: Success
-OTAERR_IO: IO error, please retry
-OTAERR_STAGE: Upgrade not performed
-OTAERR_IMAGE_WRITE: Image write failed
-OTAERR_BOOT_FAILED: New image failed to boot or partition not switched

【Description】

Check whether the current upgrade was successful.

【Example Code】

Refer to otaGetOwnerFlag

otaClearFlags

【Function Declaration】

void otaClearFlags(void);

【Parameter Description】

[OUT] N/A
[IN] N/A

【Return Value】

N/A

【Description】

Clear OTA flags.

【Example Code】

Refer to otaGetOwnerFlag

otaPartitionSync

【Function Declaration】

int32_t otaPartitionSync(void);

【Parameter Description】

[OUT] N/A
[IN] N/A

【Return Value】

-OTAERR_NOTINIT: Not initialized
-OTAERR_IO: IO error
-OTAERR_REPEAT: Conflict with another upgrade process
OTA_SUCCESS: Success

【Description】

Synchronize AB partitions and backup partition.

【Example Code】

Refer to otaGetOwnerFlag