Golioth Firmware SDK
Loading...
Searching...
No Matches
golioth_ota

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)
 

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_size, bool is_last, 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
}
 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_componentgolioth_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, 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_BLOCKSIZE

#define GOLIOTH_OTA_BLOCKSIZE   1024

Maximum size of an OTA block, in bytes.

Definition at line 26 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 28 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_size, bool is_last, void *arg)

Definition at line 134 of file ota.h.

Enumeration Type Documentation

◆ 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 49 of file ota.h.

◆ 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,
ota_component_block_write_cb cb,
void * arg )

◆ 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
manifestmanifest to find component in
packagepackage 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):

  1. A response is received from the server
  2. The user-provided timeout_s period expires without receiving a response
  3. The default GOLIOTH_COAP_RESPONSE_TIMEOUT_S period expires without receiving a response
Parameters
clientThe client handle from golioth_client_create
packagePackage name, to identify the artifact
versionVersion of package, to identify the artifact
block_index0-based index of block to get
bufOutput param, memory allocated by caller, block data will be copied here. Must be at least GOLIOTH_OTA_BLOCKSIZE bytes.
block_nbytesOutput param, memory allocated by caller, populated with number of bytes in the block, 0 to GOLIOTH_OTA_BLOCKSIZE.
is_lastSet to true, if this is the last block
timeout_sThe timeout, in seconds, for receiving a server response
Return values
GOLIOTH_OKresponse received from server, get was successful
GOLIOTH_ERR_NULLinvalid client handle
GOLIOTH_ERR_INVALID_STATEclient is not running, currently stopped
GOLIOTH_ERR_QUEUE_FULLrequest queue is full, this request is dropped
GOLIOTH_ERR_TIMEOUTresponse 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
payloadPointer to payload data
payload_sizeSize of payload, in bytes
manifestOutput param, memory allocated by caller, populated with manifest
Return values
GOLIOTH_OKpayload converted to struct golioth_ota_manifest
GOLIOTH_ERR_INVALID_FORMATfailed 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
clientThe client handle from golioth_client_create
stateThe OTA update state
reasonThe reason for this state change
packageThe artifact package name
current_versionThe artifact current_version. Can be NULL.
target_versionThe artifact new/target version from manifest. Can be NULL.
timeout_sThe timeout, in seconds, for receiving a server response
Return values
GOLIOTH_OKresponse received from server, get was successful
GOLIOTH_ERR_NULLinvalid client handle
GOLIOTH_ERR_INVALID_STATEclient is not running, currently stopped
GOLIOTH_ERR_QUEUE_FULLrequest queue is full, this request is dropped
GOLIOTH_ERR_TIMEOUTresponse 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)