Data Structures
struct	golioth_coap_rsp_code
	CoAP response code returned by server. More...

struct	golioth_psk_credential

struct	golioth_pki_credential

struct	golioth_credential
	TLS Authentication Credential. More...

struct	golioth_client_config
	Golioth client configuration, passed into golioth_client_create. More...

Typedefs
typedef void(*	golioth_client_event_cb_fn) (struct golioth_client client, enum golioth_client_event event, void arg)

typedef void(*	golioth_get_cb_fn) (struct golioth_client client, enum golioth_status status, const struct golioth_coap_rsp_code coap_rsp_code, const char path, const uint8_t payload, size_t payload_size, void *arg)

typedef void(*	golioth_set_block_cb_fn) (struct golioth_client client, enum golioth_status status, const struct golioth_coap_rsp_code coap_rsp_code, const char path, size_t block_size, void arg)

typedef void(*	golioth_get_block_cb_fn) (struct golioth_client client, enum golioth_status status, const struct golioth_coap_rsp_code coap_rsp_code, const char path, const uint8_t payload, size_t payload_size, bool is_last, void *arg)

typedef void(*	golioth_set_cb_fn) (struct golioth_client client, enum golioth_status status, const struct golioth_coap_rsp_code coap_rsp_code, const char path, void arg)

typedef void(*	golioth_post_cb_fn) (struct golioth_client client, enum golioth_status status, const struct golioth_coap_rsp_code coap_rsp_code, const char path, const uint8_t payload, size_t payload_size, void *arg)

Enumerations
enum	golioth_client_event { GOLIOTH_CLIENT_EVENT_CONNECTED , GOLIOTH_CLIENT_EVENT_DISCONNECTED }
	Golioth client events. More...

enum	golioth_content_type { GOLIOTH_CONTENT_TYPE_JSON , GOLIOTH_CONTENT_TYPE_CBOR , GOLIOTH_CONTENT_TYPE_OCTET_STREAM }
	Golioth Content Type. More...

enum	golioth_auth_type { GOLIOTH_TLS_AUTH_TYPE_PSK , GOLIOTH_TLS_AUTH_TYPE_PKI , GOLIOTH_TLS_AUTH_TYPE_TAG }
	Authentication type. More...

Functions
struct golioth_client *	golioth_client_create (const struct golioth_client_config *config)

bool	golioth_client_wait_for_connect (struct golioth_client *client, int timeout_ms)

enum golioth_status	golioth_client_start (struct golioth_client *client)

enum golioth_status	golioth_client_stop (struct golioth_client *client)

void	golioth_client_destroy (struct golioth_client *client)

bool	golioth_client_is_running (struct golioth_client *client)

bool	golioth_client_is_connected (struct golioth_client *client)

void	golioth_client_register_event_callback (struct golioth_client client, golioth_client_event_cb_fn callback, void arg)

uint32_t	golioth_client_num_items_in_request_queue (struct golioth_client *client)

void	golioth_client_set_packet_loss_percent (uint8_t percent)

golioth_sys_thread_t	golioth_client_get_thread (struct golioth_client *client)

Detailed Description

Functions for creating a Golioth client and managing client lifetime.

Used to connect to Golioth cloud using the CoAP protocol over DTLS.

For authentication, you can use either pre-shared key (PSK) or X.509 certificates (aka Public Key Infrastructure, PKI).

https://docs.golioth.io/reference/device-api

Typedef Documentation

◆ golioth_client_event_cb_fn

typedef void(* golioth_client_event_cb_fn) (struct golioth_client *client, enum golioth_client_event event, void *arg)

Callback function type for client events

Parameters

client	The client handle
event	The event that occurred
arg	User argument, copied from golioth_client_register_event_callback. Can be NULL.

Definition at line 133 of file client.h.

◆ golioth_get_block_cb_fn

typedef void(* golioth_get_block_cb_fn) (struct golioth_client *client, enum golioth_status status, const struct golioth_coap_rsp_code *coap_rsp_code, const char *path, const uint8_t *payload, size_t payload_size, bool is_last, void *arg)

Callback for blockwise get requests

Will be called repeatedly, once for each block received from the server, on timeout (i.e. response never received), or when the request is cancelled (e.g. when the Golioth client is stopped). The callback function should check status to determine which case triggered the callback.

The CoAP response code is available by reading code_class (2.xx) and code_detail (x.00) from coap_rsp_code:

When status is GOLIOTH_OK, coap_rsp_code->code_class will be a 2.XX success code.
When status is GOLIOTH_COAP_RESPONSE_CODE, check coap_rsp_code->code_class for a non-success code (4.XX, etc.)
All other status values indicate an error in which a response was not received. The coap_rsp_code is undefined and will be NULL.

Parameters

client	The client handle from the original request.
status	Golioth status code.
coap_rsp_code	CoAP response code received from Golioth. Can be NULL.
path	The path from the original request
payload	The application layer payload in the response packet. Can be NULL.
payload_size	The size of payload, in bytes
is_last	True if this is the final block of the get request
arg	User argument, copied from the original request. Can be NULL.

Definition at line 204 of file client.h.

◆ golioth_get_cb_fn

typedef void(* golioth_get_cb_fn) (struct golioth_client *client, enum golioth_status status, const struct golioth_coap_rsp_code *coap_rsp_code, const char *path, const uint8_t *payload, size_t payload_size, void *arg)

Callback function type for all asynchronous get and observe requests

Will be called when a response is received, on timeout (i.e. response never received), or when the request is cancelled (e.g. when the Golioth client is stopped). The callback function should check status to determine which case triggered the callback.

The CoAP response code is available by reading code_class (2.xx) and code_detail (x.00) from coap_rsp_code:

When status is GOLIOTH_OK, coap_rsp_code->code_class will be a 2.XX success code.
When status is GOLIOTH_COAP_RESPONSE_CODE, check coap_rsp_code->code_class for a non-success code (4.XX, etc.)
All other status values indicate an error in which a response was not received. The coap_rsp_code is undefined and will be NULL.

Parameters

client	The client handle from the original request.
status	Golioth status code.
coap_rsp_code	CoAP response code received from Golioth. Can be NULL.
path	The path from the original request
payload	The application layer payload in the response packet. Can be NULL.
payload_size	The size of payload, in bytes
arg	User argument, copied from the original request. Can be NULL.

Definition at line 158 of file client.h.

◆ golioth_post_cb_fn

typedef void(* golioth_post_cb_fn) (struct golioth_client *client, enum golioth_status status, const struct golioth_coap_rsp_code *coap_rsp_code, const char *path, const uint8_t *payload, size_t payload_size, void *arg)

Callback function type for all asynchronous post requests

Will be called when a response is received, on timeout (i.e. response never received), or when the request is cancelled (e.g. when the Golioth client is stopped). The callback function should check status to determine which case triggered the callback.

The CoAP response code is available by reading code_class (2.xx) and code_detail (x.00) from coap_rsp_code:

When status is GOLIOTH_OK, coap_rsp_code->code_class will be a 2.XX success code.
When status is GOLIOTH_COAP_RESPONSE_CODE, check coap_rsp_code->code_class for a non-success code (4.XX, etc.)
All other status values indicate an error in which a response was not received. The coap_rsp_code is undefined and will be NULL.

Parameters

client	The client handle from the original request.
status	Golioth status code.
coap_rsp_code	CoAP response code received from Golioth
path	The path from the original request
payload	The application layer payload in the response packet. Can be NULL.
payload_size	The size of payload, in bytes
arg	User argument, copied from the original request. Can be NULL.

Definition at line 260 of file client.h.

◆ golioth_set_block_cb_fn

typedef void(* golioth_set_block_cb_fn) (struct golioth_client *client, enum golioth_status status, const struct golioth_coap_rsp_code *coap_rsp_code, const char *path, size_t block_size, void *arg)

Callback function type for blockwise uploads that also returns the blocksize in szx format

Parameters

client	The client handle from the original request.
status	Golioth status code.
coap_rsp_code	CoAP response code received from Golioth. Can be NULL.
path	The path from the original request
block_size	The block size from the server in bytes
arg	User argument, copied from the original request. Can be NULL.

Definition at line 174 of file client.h.

◆ golioth_set_cb_fn

typedef void(* golioth_set_cb_fn) (struct golioth_client *client, enum golioth_status status, const struct golioth_coap_rsp_code *coap_rsp_code, const char *path, void *arg)

Callback function type for all asynchronous set and delete requests as well as blockwise uploads

Will be called when a response is received, on timeout (i.e. response never received), or when the request is cancelled (e.g. when the Golioth client is stopped). The callback function should check status to determine which case triggered the callback.

The CoAP response code is available by reading code_class (2.xx) and code_detail (x.00) from coap_rsp_code:

When status is GOLIOTH_OK, coap_rsp_code->code_class will be a 2.XX success code.
When status is GOLIOTH_COAP_RESPONSE_CODE, check coap_rsp_code->code_class for a non-success code (4.XX, etc.)
All other status values indicate an error in which a response was not received. The coap_rsp_code is undefined and will be NULL.

Parameters

client	The client handle from the original request.
status	Golioth status code.
coap_rsp_code	CoAP response code received from Golioth
path	The path from the original request
arg	User argument, copied from the original request. Can be NULL.

Definition at line 233 of file client.h.

Enumeration Type Documentation

◆ golioth_auth_type

enum golioth_auth_type

Authentication type.

Enumerator
GOLIOTH_TLS_AUTH_TYPE_PSK	Authenticate with pre-shared key (psk-id and psk)
GOLIOTH_TLS_AUTH_TYPE_PKI	Authenticate with PKI certificates (CA cert, public client cert, private client key)
GOLIOTH_TLS_AUTH_TYPE_TAG	Authenticate with TLS credential tag (Zephyr specific)

Definition at line 62 of file client.h.

◆ golioth_client_event

enum golioth_client_event

Golioth client events.

Enumerator
GOLIOTH_CLIENT_EVENT_CONNECTED	Client was previously not connected, and is now connected.
GOLIOTH_CLIENT_EVENT_DISCONNECTED	Client was previously connected, and is now disconnected.

Definition at line 35 of file client.h.

◆ golioth_content_type

enum golioth_content_type

Golioth Content Type.

Enumerator
GOLIOTH_CONTENT_TYPE_JSON
GOLIOTH_CONTENT_TYPE_CBOR
GOLIOTH_CONTENT_TYPE_OCTET_STREAM

Definition at line 44 of file client.h.

Function Documentation

◆ golioth_client_create()

struct golioth_client * golioth_client_create ( const struct golioth_client_config * config )

Create a Golioth client

Dynamically creates a client and returns an opaque handle to the client. The handle is a required parameter for most other Golioth SDK functions.

An RTOS thread and request queue is created and the client is automatically started (no need to call golioth_client_start).

Parameters

config Client configuration

Returns: Non-NULL The client handle (success); NULL There was an error creating the client

◆ golioth_client_destroy()

void golioth_client_destroy ( struct golioth_client * client )

Destroy a Golioth client

Frees dynamically created resources from golioth_client_create.

Parameters

client The handle of the client to destroy

◆ golioth_client_get_thread()

golioth_sys_thread_t golioth_client_get_thread ( struct golioth_client * client )

Return the thread handle of the client thread.

Parameters

client The client handle

Returns: The thread handle of the client thread

◆ golioth_client_is_connected()

bool golioth_client_is_connected ( struct golioth_client * client )

Returns whether the client is currently connected to Golioth servers.

If client requests receive responses, this is the indication of being connected. If requests time out (no response from server), then the client is considered disconnected.

Parameters

client The client handle

Return values

true	The client is connected to Golioth
false	The client is not connected, or the client handle is not valid

◆ golioth_client_is_running()

bool golioth_client_is_running ( struct golioth_client * client )

Returns whether the client is currently running

Parameters

client The client handle

Return values

true	The client is running
false	The client is not running, or the client handle is not valid

◆ golioth_client_num_items_in_request_queue()

uint32_t golioth_client_num_items_in_request_queue ( struct golioth_client * client )

The number of items currently in the client thread request queue.

Will be a number between 0 and GOLIOTH_COAP_REQUEST_QUEUE_MAX_ITEMS.

Parameters

client The client handle

Returns: The number of items currently in the client thread request queue.

◆ golioth_client_register_event_callback()

void golioth_client_register_event_callback	(	struct golioth_client *	client,
		golioth_client_event_cb_fn	callback,
		void *	arg )

Register a callback that will be called on client events (e.g. connected, disconnected)

Parameters

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

◆ golioth_client_set_packet_loss_percent()

void golioth_client_set_packet_loss_percent ( uint8_t percent )

Simulate packet loss at a particular percentage (0 to 100).

Intended for testing and troubleshooting in packet loss scenarios. Does nothing if percent is outside of the range [0, 100].

Parameters

percent Percent packet loss (0 is no packets lost, 100 is all packets lost)

◆ golioth_client_start()

enum golioth_status golioth_client_start ( struct golioth_client * client )

Start the Golioth client

Does nothing if the client is already started. The client is started after calling golioth_client_create.

Parameters

client The client handle

Return values

GOLIOTH_OK	Client started
GOLIOTH_ERR_NULL	Client handle invalid

◆ golioth_client_stop()

enum golioth_status golioth_client_stop ( struct golioth_client * client )

Stop the Golioth client

Client will finish the current request (if there is one), then enter a dormant state where no packets will be sent or received with Golioth, and the client thread will be in a blocked state.

This function will block until the client thread is actually stopped.

Does nothing if the client is already stopped.

Parameters

client The client handle

Return values

GOLIOTH_OK	Client stopped
GOLIOTH_ERR_NULL	Client handle invalid

◆ golioth_client_wait_for_connect()

bool golioth_client_wait_for_connect	(	struct golioth_client *	client,
		int	timeout_ms )

Wait (block) until connected to Golioth, or timeout occurs.

If timeout_ms set to -1, it will wait forever until connected.

Parameters

client	The client handle
timeout_ms	How long to wait, in milliseconds, or -1 to wait forever

Returns: True, if connected, false otherwise.

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ golioth_client_event_cb_fn

◆ golioth_get_block_cb_fn

◆ golioth_get_cb_fn

◆ golioth_post_cb_fn

◆ golioth_set_block_cb_fn

◆ golioth_set_cb_fn

Enumeration Type Documentation

◆ golioth_auth_type

◆ golioth_client_event

◆ golioth_content_type

Function Documentation

◆ golioth_client_create()

◆ golioth_client_destroy()

◆ golioth_client_get_thread()

◆ golioth_client_is_connected()

◆ golioth_client_is_running()

◆ golioth_client_num_items_in_request_queue()

◆ golioth_client_register_event_callback()

◆ golioth_client_set_packet_loss_percent()

◆ golioth_client_start()

◆ golioth_client_stop()

◆ golioth_client_wait_for_connect()