Golioth Firmware SDK
No Matches


typedef void(* golioth_fw_update_state_change_callback) (enum golioth_ota_state state, enum golioth_ota_reason reason, void *user_arg)


void golioth_fw_update_init (struct golioth_client *client, const char *current_version)
void golioth_fw_update_init_with_config (struct golioth_client *client, const struct golioth_fw_update_config *config)
void golioth_fw_update_register_state_change_callback (golioth_fw_update_state_change_callback callback, void *user_arg)
bool fw_update_is_pending_verify (void)
void fw_update_rollback (void)
 Initiate a firmware rollback.
void fw_update_reboot (void)
void fw_update_cancel_rollback (void)
enum golioth_status fw_update_handle_block (const uint8_t *block, size_t block_size, size_t offset, size_t total_size)
enum golioth_status fw_update_read_current_image_at_offset (uint8_t *buf, size_t bufsize, size_t offset)
void fw_update_post_download (void)
enum golioth_status fw_update_validate (void)
enum golioth_status fw_update_change_boot_image (void)
void fw_update_end (void)

Detailed Description

Create a background thread that will execute Over-the-Air (OTA) updates


Typedef Documentation

◆ golioth_fw_update_state_change_callback

typedef void(* golioth_fw_update_state_change_callback) (enum golioth_ota_state state, enum golioth_ota_reason reason, void *user_arg)

Function callback type, for FW update state change listeners

stateThe new state being transitioned to
reasonThe reason the state transition is happening
user_argArbitraty user argument, can be NULL.

Definition at line 65 of file fw_update.h.

Function Documentation

◆ fw_update_cancel_rollback()

void fw_update_cancel_rollback ( void )

Cancel the rollback and commit to the current firmware image.

Marks the image as "good" and prevents rollback to the old image.

◆ fw_update_change_boot_image()

enum golioth_status fw_update_change_boot_image ( void )

Switch to the new boot image. This will cause the new image to be booted next time.

GOLIOTH_OK - changed boot image
Otherwise - Error changing boot image, abort firmware update

◆ fw_update_end()

void fw_update_end ( void )

Called when firmware update aborted

Can be used by backend ports to clean up after a firmware update is aborted.

◆ fw_update_handle_block()

enum golioth_status fw_update_handle_block ( const uint8_t * block,
size_t block_size,
size_t offset,
size_t total_size )

Handle a single block of a new firmware image (e.g. write to flash in the secondary firmware slot).

blockThe block data buffer
block_sizeThe block data size, in bytes
offsetThe offset of this block in the overall firmware image
total_sizeThe total firmware image size
GOLIOTH_OK - Block handled
Otherwise - error handling block, abort firmware update

◆ fw_update_is_pending_verify()

bool fw_update_is_pending_verify ( void )

Returns true if this is the first boot of a new candidate image that is pending/not-yet-confirmed as "good".

◆ fw_update_post_download()

void fw_update_post_download ( void )

Post-download hook.

Called by golioth_fw_update.c after downloading the full image. Can be used by backend ports to do any final work, if needed.

◆ fw_update_read_current_image_at_offset()

enum golioth_status fw_update_read_current_image_at_offset ( uint8_t * buf,
size_t bufsize,
size_t offset )

Copy bufsize bytes of the currently running image at a specific offset into buf.

This is only called if CONFIG_GOLIOTH_OTA_PATCH == 1. The data of the current image is used as the base of the patch operation.

bufOutput buffer, populated with bufsize bytes of the current image
bufsizeHow many bytes to copy
offsetThe byte offset from the start of the currently running image to start reading
GOLIOTH_OK - copied bufsize bytes into buf
Otherwise - error copying bytes, abort firmware update

◆ fw_update_reboot()

void fw_update_reboot ( void )

Reboot the device.

Called by library during a rollback event or after writing a new pending/candidate image to flash.

◆ fw_update_rollback()

void fw_update_rollback ( void )

Initiate a firmware rollback.

◆ fw_update_validate()

enum golioth_status fw_update_validate ( void )

Validate new image after downloading

Called by golioth_fw_update.c after downloading the full image. Can be used by backend ports to validate the image before attempting to boot into it.

GOLIOTH_OK - image validated
Otherwise - error in validation, abort firmware update

◆ golioth_fw_update_init()

void golioth_fw_update_init ( struct golioth_client * client,
const char * current_version )

Create a thread that will perform firmware updates.

The thread will observe OTA manifests then execute the OTA update, including state reporting to Golioth and updating firmware on the device.

Will ignore any received OTA manifests where the firmware already matches current_version.

The current_version parameter is assumed to be a static string and is therefore not copied (just a shallow copy of the pointer is stored internally). Calling code should ensure that current_version is not pointing to a string which might go out of scope.

clientThe client handle from golioth_client_create
current_versionThe current firmware version (e.g. "1.2.3"), shallow copy, must be NULL-terminated

◆ golioth_fw_update_init_with_config()

void golioth_fw_update_init_with_config ( struct golioth_client * client,
const struct golioth_fw_update_config * config )

Same as golioth_fw_update_init, but with additional configuration specified via struct.

clientThe client handle from golioth_client_create
configThe configuration struct (see golioth_fw_update_config).

◆ golioth_fw_update_register_state_change_callback()

void golioth_fw_update_register_state_change_callback ( golioth_fw_update_state_change_callback callback,
void * user_arg )

Register listener for FW update state changes.

This is useful if your app needs to react or track changes in the state of the FW update process (e.g. DOWNLOADING, DOWNLOADED, etc).

callbackFunction to be called when a state change happens
user_argArbitraty user argument, can be NULL