File lt_ota.h

#include <libretiny.h>
#include <uf2ota/uf2types.h>

Classes

Type	Name
struct	lt_ota_ctx_t OTA update process context.

Public Types

Type	Name
enum	lt_ota_type_t Chip's OTA type enumeration.

Public Functions

Type	Name
void	lt_ota_begin (lt_ota_ctx_t * ctx, size_t size) Initialize the update context to begin OTA process.
bool	lt_ota_can_rollback () Check if OTA rollback is possible (switching the stored index to another partition).
uint8_t	lt_ota_dual_get_current () Get the currently running firmware's OTA index.
uint8_t	lt_ota_dual_get_stored () Read the currently active OTA index, i.e. the one that will boot upon restart.
bool	lt_ota_end (lt_ota_ctx_t * ctx) Finish the update process. If the update has been written completely, try to activate the target image. Free allocated internal structures, regardless of the activation result.
lt_ota_type_t	lt_ota_get_type () Get OTA type of the device's chip.
uf2_ota_scheme_t	lt_ota_get_uf2_scheme () Check which UF2 OTA scheme should be used for applying firmware updates.
bool	lt_ota_is_valid (uint8_t index) Check if the specified OTA image is valid.
void	lt_ota_set_write_protect (uf2_ota_t * uf2) Set family-specific, write-protected flash areas in the OTA update context. This shouldn't be called manually, as it's done by lt_ota_begin().
bool	lt_ota_switch (bool revert) Try to switch OTA index to the other image. For single-OTA chips, only check if the upgrade image is valid.
size_t	lt_ota_write (lt_ota_ctx_t * ctx, const uint8_t * data, size_t len) Process a chunk of data.
bool	lt_ota_write_block (lt_ota_ctx_t * ctx, uf2_block_t * block) Try to write the block. In case of UF2 errors, error code is set in the context. Note: use lt_ota_write() instead. This is for internal usage only.

Public Types Documentation

enum lt_ota_type_t

enum lt_ota_type_t {
    OTA_TYPE_SINGLE = 0,
    OTA_TYPE_DUAL = 1,
    OTA_TYPE_FILE = 2
};

Public Functions Documentation

function lt_ota_begin

Initialize the update context to begin OTA process.

void lt_ota_begin (
    lt_ota_ctx_t * ctx,
    size_t size
)

Parameters:

ctx OTA context
size length of the update file; 0 if unknown

function lt_ota_can_rollback

Check if OTA rollback is possible (switching the stored index to another partition).

bool lt_ota_can_rollback ()

Note that this is not the same as "switching" OTA with revert=true.

Returns:

true if 2nd image is valid and the chip is dual-OTA; false otherwise

function lt_ota_dual_get_current

Get the currently running firmware's OTA index.

uint8_t lt_ota_dual_get_current ()

Returns:

OTA index if dual-OTA is supported, 0 otherwise

function lt_ota_dual_get_stored

Read the currently active OTA index, i.e. the one that will boot upon restart.

uint8_t lt_ota_dual_get_stored ()

Returns:

OTA index if dual-OTA is supported, 0 otherwise

function lt_ota_end

Finish the update process. If the update has been written completely, try to activate the target image. Free allocated internal structures, regardless of the activation result.

bool lt_ota_end (
    lt_ota_ctx_t * ctx
)

Parameters:

ctx OTA context

Returns:

false if activation was attempted and not successful; true otherwise

function lt_ota_get_type

lt_ota_type_t lt_ota_get_type ()

function lt_ota_get_uf2_scheme

Check which UF2 OTA scheme should be used for applying firmware updates.

uf2_ota_scheme_t lt_ota_get_uf2_scheme ()

Returns:

OTA scheme of the target partition

function lt_ota_is_valid

Check if the specified OTA image is valid.

bool lt_ota_is_valid (
    uint8_t index
)

Parameters:

index OTA index to check; 0 for single-OTA chips, 1 or 2 for dual-OTA chips

Returns:

true if index is valid for the chip's OTA type, and there is a valid image; false otherwise

function lt_ota_set_write_protect

Set family-specific, write-protected flash areas in the OTA update context. This shouldn't be called manually, as it's done by lt_ota_begin().

void lt_ota_set_write_protect (
    uf2_ota_t * uf2
)

Parameters:

uf2 uf2ota context

function lt_ota_switch

Try to switch OTA index to the other image. For single-OTA chips, only check if the upgrade image is valid.

bool lt_ota_switch (
    bool revert
)

This can be used to "activate" the upgrade after flashing.

Parameters:

revert switch if (and only if) the other image is already marked as active (i.e. switch back to the running image)

Returns:

false if the second image (or upgrade image) is not valid; false if writing failed; true otherwise

function lt_ota_write

Process a chunk of data.

size_t lt_ota_write (
    lt_ota_ctx_t * ctx,
    const uint8_t * data,
    size_t len
)

Data is written to the buffer, unless a full UF2 block is already available, in which case it's also processed by UF2OTA and written to flash.

It's advised to write in 512-byte chunks (or its multiples).

Parameters:

ctx OTA context
data chunk of bytes to process
len size of the chunk

Returns:

number of bytes correctly processed; should equal 'len' in case of no errors

function lt_ota_write_block

Try to write the block. In case of UF2 errors, error code is set in the context. Note: use lt_ota_write() instead. This is for internal usage only.

bool lt_ota_write_block (
    lt_ota_ctx_t * ctx,
    uf2_block_t * block
)

Parameters:

block UF2 block to check and write; cannot be NULL

Returns:

whether no error has occurred

The documentation for this class was generated from the following file cores/common/base/api/lt_ota.h