golioth_fw_update

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

Functions
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)
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

https://docs.golioth.io/reference/protocols/coap/ota

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

Parameters

state	The new state being transitioned to
reason	The reason the state transition is happening
user_arg	Arbitraty 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.

Returns

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).

This function must return GOLIOTH_ERR_IO when there is an issue storing the block.

Parameters

block	The block data buffer
block_size	The block data size, in bytes
offset	The offset of this block in the overall firmware image
total_size	The total firmware image size

Returns

GOLIOTH_OK - Block handled

GOLIOTH_ERR_IO - 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_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.

Returns

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.

Parameters

client	The client handle from golioth_client_create
current_version	The 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.

Parameters

client	The client handle from golioth_client_create
config	The 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).

Parameters

callback	Function to be called when a state change happens
user_arg	Arbitraty user argument, can be NULL