Data Structures
struct	golioth_ota_component
	A component/artifact within an OTA manifest. More...

struct	golioth_ota_manifest
	An OTA manifest, composed of multiple components/artifacts. More...

Macros
#define	GOLIOTH_OTA_BLOCKSIZE 1024
	Maximum size of an OTA block, in bytes.

#define	GOLIOTH_OTA_COMPONENT_HASH_LEN 64
	Size of a SHA256 of Artifact Binary in bytes.

#define	GOLIOTH_OTA_MAX_COMPONENT_BOOTLOADER_NAME_LEN 7
	Maximum size of Binary Detected Type in bytes.

#define	GOLIOTH_OTA_MAX_COMPONENT_URI_LEN (CONFIG_GOLIOTH_OTA_MAX_PACKAGE_NAME_LEN + CONFIG_GOLIOTH_OTA_MAX_VERSION_LEN + 7)
	Maximum size of Relative URI to download binary (+ 7 bytes for Path)

Enumerations
enum	golioth_ota_state { GOLIOTH_OTA_STATE_IDLE , GOLIOTH_OTA_STATE_DOWNLOADING , GOLIOTH_OTA_STATE_DOWNLOADED , GOLIOTH_OTA_STATE_UPDATING }
	State of OTA update, reported to Golioth server. More...

enum	golioth_ota_reason { GOLIOTH_OTA_REASON_READY , GOLIOTH_OTA_REASON_FIRMWARE_UPDATED_SUCCESSFULLY , GOLIOTH_OTA_REASON_NOT_ENOUGH_FLASH_MEMORY , GOLIOTH_OTA_REASON_OUT_OF_RAM , GOLIOTH_OTA_REASON_CONNECTION_LOST , GOLIOTH_OTA_REASON_INTEGRITY_CHECK_FAILURE , GOLIOTH_OTA_REASON_UNSUPPORTED_PACKAGE_TYPE , GOLIOTH_OTA_REASON_INVALID_URI , GOLIOTH_OTA_REASON_FIRMWARE_UPDATE_FAILED , GOLIOTH_OTA_REASON_UNSUPPORTED_PROTOCOL }
	A reason associated with state changes. More...

Functions
enum golioth_status	golioth_ota_payload_as_manifest (const uint8_t payload, size_t payload_size, struct golioth_ota_manifest manifest)

size_t	golioth_ota_size_to_nblocks (size_t component_size)
	Convert a size in bytes to the number of blocks required (of size up to GOLIOTH_OTA_BLOCKSIZE)

const struct golioth_ota_component *	golioth_ota_find_component (const struct golioth_ota_manifest manifest, const char package)

enum golioth_status	golioth_ota_observe_manifest_async (struct golioth_client client, golioth_get_cb_fn callback, void arg)

enum golioth_status	golioth_ota_get_block_sync (struct golioth_client client, const char package, const char version, size_t block_index, uint8_t buf, size_t block_nbytes, bool is_last, int32_t timeout_s)

enum golioth_status	golioth_ota_report_state_sync (struct golioth_client client, enum golioth_ota_state state, enum golioth_ota_reason reason, const char package, const char current_version, const char target_version, int32_t timeout_s)

enum golioth_ota_state	golioth_ota_get_state (void)

Detailed Description

Functions for interacting with Golioth OTA services

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

Macro Definition Documentation

◆ GOLIOTH_OTA_BLOCKSIZE

#define GOLIOTH_OTA_BLOCKSIZE 1024

Maximum size of an OTA block, in bytes.

Definition at line 20 of file ota.h.

◆ GOLIOTH_OTA_COMPONENT_HASH_LEN

#define GOLIOTH_OTA_COMPONENT_HASH_LEN 64

Size of a SHA256 of Artifact Binary in bytes.

Definition at line 22 of file ota.h.

◆ GOLIOTH_OTA_MAX_COMPONENT_BOOTLOADER_NAME_LEN

#define GOLIOTH_OTA_MAX_COMPONENT_BOOTLOADER_NAME_LEN 7

Maximum size of Binary Detected Type in bytes.

Definition at line 24 of file ota.h.

◆ GOLIOTH_OTA_MAX_COMPONENT_URI_LEN

#define GOLIOTH_OTA_MAX_COMPONENT_URI_LEN (CONFIG_GOLIOTH_OTA_MAX_PACKAGE_NAME_LEN + CONFIG_GOLIOTH_OTA_MAX_VERSION_LEN + 7)

Maximum size of Relative URI to download binary (+ 7 bytes for Path)

Definition at line 26 of file ota.h.

Enumeration Type Documentation

◆ golioth_ota_reason

enum golioth_ota_reason

A reason associated with state changes.

Enumerator
GOLIOTH_OTA_REASON_READY	OTA update is ready to go. Also used for "no reason".
GOLIOTH_OTA_REASON_FIRMWARE_UPDATED_SUCCESSFULLY	Firmware update was successful.
GOLIOTH_OTA_REASON_NOT_ENOUGH_FLASH_MEMORY	Insufficient flash memory on device.
GOLIOTH_OTA_REASON_OUT_OF_RAM	Insufficient RAM on device.
GOLIOTH_OTA_REASON_CONNECTION_LOST	Lost connection to server during OTA update.
GOLIOTH_OTA_REASON_INTEGRITY_CHECK_FAILURE	Data integrity check of downloaded artifact failed.
GOLIOTH_OTA_REASON_UNSUPPORTED_PACKAGE_TYPE	Package type not supported.
GOLIOTH_OTA_REASON_INVALID_URI	URI not valid.
GOLIOTH_OTA_REASON_FIRMWARE_UPDATE_FAILED	Firmware update was not successful.
GOLIOTH_OTA_REASON_UNSUPPORTED_PROTOCOL	Protocol not supported.

Definition at line 43 of file ota.h.

◆ golioth_ota_state

enum golioth_ota_state

State of OTA update, reported to Golioth server.

Enumerator
GOLIOTH_OTA_STATE_IDLE	No OTA update in progress.
GOLIOTH_OTA_STATE_DOWNLOADING	OTA is being downloaded and written to flash.
GOLIOTH_OTA_STATE_DOWNLOADED	OTA has been downloaded and written to flash.
GOLIOTH_OTA_STATE_UPDATING	OTA is being applied to the system, but is not yet complete.

Definition at line 30 of file ota.h.

Function Documentation

◆ golioth_ota_find_component()

const struct golioth_ota_component * golioth_ota_find_component	(	const struct golioth_ota_manifest *	manifest,
		const char *	package )

Find a component by package name in a manifest, or NULL if not found.

Parameters

manifest	manifest to find component in
package	package name to find in manifest

Returns: if found - pointer to component; if not found - NULL

◆ golioth_ota_get_block_sync()

enum golioth_status golioth_ota_get_block_sync	(	struct golioth_client *	client,
		const char *	package,
		const char *	version,
		size_t	block_index,
		uint8_t *	buf,
		size_t *	block_nbytes,
		bool *	is_last,
		int32_t	timeout_s )

Get a single artfifact block synchronously

Since some artifacts (e.g. "main" firmware) are larger than the amount of RAM the device has, it is assumed the user will call this function multiple times to handle blocks one at a time.

This function will block until one of three things happen (whichever comes first):

A response is received from the server
The user-provided timeout_s period expires without receiving a response
The default GOLIOTH_COAP_RESPONSE_TIMEOUT_S period expires without receiving a response

Parameters

client	The client handle from golioth_client_create
package	Package name, to identify the artifact
version	Version of package, to identify the artifact
block_index	0-based index of block to get
buf	Output param, memory allocated by caller, block data will be copied here. Must be at least GOLIOTH_OTA_BLOCKSIZE bytes.
block_nbytes	Output param, memory allocated by caller, populated with number of bytes in the block, 0 to GOLIOTH_OTA_BLOCKSIZE.
is_last	Set to true, if this is the last block
timeout_s	The timeout, in seconds, for receiving a server response

Return values

GOLIOTH_OK	response received from server, get was successful
GOLIOTH_ERR_NULL	invalid client handle
GOLIOTH_ERR_INVALID_STATE	client is not running, currently stopped
GOLIOTH_ERR_QUEUE_FULL	request queue is full, this request is dropped
GOLIOTH_ERR_TIMEOUT	response not received from server, timeout occurred

◆ golioth_ota_get_state()

enum golioth_ota_state golioth_ota_get_state ( void )

Get the current state of OTA update

Returns: The current OTA update state

◆ golioth_ota_observe_manifest_async()

enum golioth_status golioth_ota_observe_manifest_async	(	struct golioth_client *	client,
		golioth_get_cb_fn	callback,
		void *	arg )

Observe for the OTA manifest asynchronously

This function will enqueue a request and return immediately without waiting for a response from the server. The callback will be invoked whenever the manifest is changed on the Golioth server.

◆ golioth_ota_payload_as_manifest()

enum golioth_status golioth_ota_payload_as_manifest	(	const uint8_t *	payload,
		size_t	payload_size,
		struct golioth_ota_manifest *	manifest )

Convert raw byte payload into a golioth_ota_manifest

Parameters

payload	Pointer to payload data
payload_size	Size of payload, in bytes
manifest	Output param, memory allocated by caller, populated with manifest

Return values

GOLIOTH_OK	payload converted to struct golioth_ota_manifest
GOLIOTH_ERR_INVALID_FORMAT	failed to parse manifest

◆ golioth_ota_report_state_sync()

enum golioth_status golioth_ota_report_state_sync	(	struct golioth_client *	client,
		enum golioth_ota_state	state,
		enum golioth_ota_reason	reason,
		const char *	package,
		const char *	current_version,
		const char *	target_version,
		int32_t	timeout_s )

Report the state of OTA update to Golioth server synchronously

Parameters

client	The client handle from golioth_client_create
state	The OTA update state
reason	The reason for this state change
package	The artifact package name
current_version	The artifact current_version. Can be NULL.
target_version	The artifact new/target version from manifest. Can be NULL.
timeout_s	The timeout, in seconds, for receiving a server response

Return values

GOLIOTH_OK	response received from server, get was successful
GOLIOTH_ERR_NULL	invalid client handle
GOLIOTH_ERR_INVALID_STATE	client is not running, currently stopped
GOLIOTH_ERR_QUEUE_FULL	request queue is full, this request is dropped
GOLIOTH_ERR_TIMEOUT	response not received from server, timeout occurred

◆ golioth_ota_size_to_nblocks()

size_t golioth_ota_size_to_nblocks ( size_t component_size )

Convert a size in bytes to the number of blocks required (of size up to GOLIOTH_OTA_BLOCKSIZE)

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ GOLIOTH_OTA_BLOCKSIZE

◆ GOLIOTH_OTA_COMPONENT_HASH_LEN

◆ GOLIOTH_OTA_MAX_COMPONENT_BOOTLOADER_NAME_LEN

◆ GOLIOTH_OTA_MAX_COMPONENT_URI_LEN

Enumeration Type Documentation

◆ golioth_ota_reason

◆ golioth_ota_state

Function Documentation

◆ golioth_ota_find_component()

◆ golioth_ota_get_block_sync()

◆ golioth_ota_get_state()

◆ golioth_ota_observe_manifest_async()

◆ golioth_ota_payload_as_manifest()

◆ golioth_ota_report_state_sync()

◆ golioth_ota_size_to_nblocks()