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_COMPONENT_HEX_HASH_LEN 64
	Size of a SHA256 of Artifact hex string in bytes.

#define	GOLIOTH_OTA_COMPONENT_BIN_HASH_LEN 32
	Size of a SHA256 of Artifact bin array 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)

Typedefs
typedef enum golioth_status(*	ota_component_block_write_cb) (const struct golioth_ota_component component, uint32_t block_idx, uint8_t block_buffer, size_t block_buffer_len, bool is_last, size_t negotiated_block_size, void *arg)

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 , GOLIOTH_OTA_REASON_IO , GOLIOTH_OTA_REASON_AWAIT_RETRY }
	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)

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_download_component (struct golioth_client client, const struct golioth_ota_component component, uint32_t block_idx, ota_component_block_write_cb cb, 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_COMPONENT_BIN_HASH_LEN

#define GOLIOTH_OTA_COMPONENT_BIN_HASH_LEN 32

Size of a SHA256 of Artifact bin array in bytes.

Definition at line 28 of file ota.h.

◆ GOLIOTH_OTA_COMPONENT_HEX_HASH_LEN

#define GOLIOTH_OTA_COMPONENT_HEX_HASH_LEN 64

Size of a SHA256 of Artifact hex string in bytes.

Definition at line 26 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 30 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 32 of file ota.h.

Typedef Documentation

◆ ota_component_block_write_cb

typedef enum golioth_status(* ota_component_block_write_cb) (const struct golioth_ota_component *component, uint32_t block_idx, uint8_t *block_buffer, size_t block_buffer_len, bool is_last, size_t negotiated_block_size, void *arg)

Callback for OTA download component request

Will be called repeatedly, once for each block received from the server.

Parameters

component	The golioth_ota_component pointer from the original request
block_idx	The block number in sequence (starting with 0)
block_buffer	The component payload in the response packet.
block_buffer_len	The length of the component payload, in bytes.
is_last	true if this is the final block of the request
negotiated_block_size	The maximum block size negotated with the server, in bytes
arg	User argument, copied from the original request. Can be NULL.

Definition at line 141 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.
GOLIOTH_OTA_REASON_IO	IO error while trying to store component.
GOLIOTH_OTA_REASON_AWAIT_RETRY	Awaiting retry.

Definition at line 49 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 36 of file ota.h.

Function Documentation

◆ golioth_ota_download_component()

enum golioth_status golioth_ota_download_component	(	struct golioth_client *	client,
		const struct golioth_ota_component *	component,
		uint32_t *	block_idx,
		ota_component_block_write_cb	cb,
		void *	arg )

Begin or resume downloading an OTA component synchronously.

This function will block until the final block of the component download is received from the server or an error is received on any block. The next_block_idx is used to pass in the first block index to be downloaded (components begin with the 0th index). After returning, the same parameter has been updated to indicate the next expected block in the download process.

Use this function to resume OTA component downloads. Pass the next_block_idx from a failed run to resume the download. The ota_component_block_write_cb function must be designed to handle storage when resuming a download. Upon successful completion, it is up to the application to verify the integrity of the component (eg: compare to the SHA256 in struct golioth_ota_component).

Parameters

	client	The client handle from golioth_client_create
	component	One golioth_ota_component instance present in the golioth_ota_manifest
[in,out]	block_idx	Pointer to the next expected block index. The function will request the block index supplied as an input, when returning, this variable indicates the next block index expected. When an error status is returned, use this value as the input for the next resume operation. May be NULL to begin download with block_idx 0.
	cb	Callback function to register
	arg	Optional argument, forwarded directly to the callback when invoked. Can be NULL.

Return values

GOLIOTH_OK	the final block of package was received
GOLIOTH_ERR_FAIL	invalid client handle, path, or callback
GOLIOTH_ERR_MEM_ALLOC	unable to allocate necessary memory

◆ 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_BLOCKWISE_DOWNLOAD_MAX_BLOCK_SIZE bytes.
block_nbytes	Output param, memory allocated by caller, populated with number of bytes in the block, 0 to GOLIOTH_BLOCKWISE_DOWNLOAD_MAX_BLOCK_SIZE.
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.

Parameters

client	The client handle from golioth_client_create
callback	Callback function to register
arg	Optional argument, forwarded directly to the callback when invoked. Can be NULL.

◆ 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_BLOCKWISE_DOWNLOAD_MAX_BLOCK_SIZE)

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ GOLIOTH_OTA_COMPONENT_BIN_HASH_LEN

◆ GOLIOTH_OTA_COMPONENT_HEX_HASH_LEN

◆ GOLIOTH_OTA_MAX_COMPONENT_BOOTLOADER_NAME_LEN

◆ GOLIOTH_OTA_MAX_COMPONENT_URI_LEN

Typedef Documentation

◆ ota_component_block_write_cb

Enumeration Type Documentation

◆ golioth_ota_reason

◆ golioth_ota_state

Function Documentation

◆ golioth_ota_download_component()

◆ 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()