Golioth Firmware SDK
|
Data Structures | |
struct | golioth_response_t |
Response status and CoAP class/code. More... | |
struct | golioth_psk_credentials_t |
struct | golioth_pki_credentials_t |
struct | golioth_tls_credentials_t |
TLS Authentication Credentials. More... | |
struct | golioth_client_config_t |
Golioth client configuration, passed into golioth_client_create. More... | |
Typedefs | |
typedef void * | golioth_client_t |
Opaque handle to the Golioth client. More... | |
typedef void(* | golioth_client_event_cb_fn) (golioth_client_t client, golioth_client_event_t event, void *arg) |
typedef void(* | golioth_get_cb_fn) (golioth_client_t client, const golioth_response_t *response, const char *path, const uint8_t *payload, size_t payload_size, void *arg) |
typedef void(* | golioth_get_block_cb_fn) (golioth_client_t client, const golioth_response_t *response, const char *path, const uint8_t *payload, size_t payload_size, bool is_last, void *arg) |
typedef void(* | golioth_set_cb_fn) (golioth_client_t client, const golioth_response_t *response, const char *path, void *arg) |
Enumerations | |
enum | golioth_client_event_t { GOLIOTH_CLIENT_EVENT_CONNECTED , GOLIOTH_CLIENT_EVENT_DISCONNECTED } |
Golioth client events. More... | |
enum | golioth_tls_auth_type_t { GOLIOTH_TLS_AUTH_TYPE_PSK , GOLIOTH_TLS_AUTH_TYPE_PKI } |
TLS authentication type. More... | |
Functions | |
golioth_client_t | golioth_client_create (const golioth_client_config_t *config) |
bool | golioth_client_wait_for_connect (golioth_client_t client, int timeout_ms) |
golioth_status_t | golioth_client_start (golioth_client_t client) |
golioth_status_t | golioth_client_stop (golioth_client_t client) |
void | golioth_client_destroy (golioth_client_t client) |
bool | golioth_client_is_running (golioth_client_t client) |
bool | golioth_client_is_connected (golioth_client_t client) |
void | golioth_client_register_event_callback (golioth_client_t client, golioth_client_event_cb_fn callback, void *arg) |
uint32_t | golioth_client_num_items_in_request_queue (golioth_client_t client) |
void | golioth_client_set_packet_loss_percent (uint8_t percent) |
bool | golioth_client_has_allocation_leaks (void) |
golioth_sys_thread_t | golioth_client_get_thread (golioth_client_t client) |
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/protocols/coap
https://docs.golioth.io/reference/protocols/coap/auth
https://docs.golioth.io/reference/protocols/device-auth
typedef void(* golioth_client_event_cb_fn) (golioth_client_t client, golioth_client_event_t event, void *arg) |
Callback function type for client events
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 114 of file golioth_client.h.
typedef void* golioth_client_t |
Opaque handle to the Golioth client.
Definition at line 30 of file golioth_client.h.
typedef void(* golioth_get_block_cb_fn) (golioth_client_t client, const golioth_response_t *response, const char *path, const uint8_t *payload, size_t payload_size, bool is_last, void *arg) |
Definition at line 138 of file golioth_client.h.
typedef void(* golioth_get_cb_fn) (golioth_client_t client, const golioth_response_t *response, 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 or on timeout (i.e. response never received). The callback function should check response->status to determine which case it is (response received or timeout).
client | The client handle from the original request. |
response | Response status and class/code |
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 131 of file golioth_client.h.
typedef void(* golioth_set_cb_fn) (golioth_client_t client, const golioth_response_t *response, const char *path, void *arg) |
Callback function type for all asynchronous set and delete requests
Will be called when a response is received or on timeout (i.e. response never received). The callback function should check response->status to determine which case it is (response received or timeout). If response->status is GOLIOTH_OK, then the set or delete request was successful.
client | The client handle from the original request. |
response | Response status and class/code |
path | The path from the original request |
arg | User argument, copied from the original request. Can be NULL. |
Definition at line 158 of file golioth_client.h.
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 33 of file golioth_client.h.
TLS 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) |
Definition at line 56 of file golioth_client.h.
golioth_client_t golioth_client_create | ( | const golioth_client_config_t * | 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).
config | Client configuration |
void golioth_client_destroy | ( | golioth_client_t | client | ) |
Destroy a Golioth client
Frees dynamically created resources from golioth_client_create.
client | The handle of the client to destroy |
golioth_sys_thread_t golioth_client_get_thread | ( | golioth_client_t | client | ) |
Return the thread handle of the client thread.
client | The client handle |
bool golioth_client_has_allocation_leaks | ( | void | ) |
Return whether there exists an allocated resource that has not been freed by the client.
Intended only for Golioth SDK developers, for test and debug purposes.
bool golioth_client_is_connected | ( | golioth_client_t | 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.
client | The client handle |
bool golioth_client_is_running | ( | golioth_client_t | client | ) |
Returns whether the client is currently running
client | The client handle |
uint32_t golioth_client_num_items_in_request_queue | ( | golioth_client_t | 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.
client | The client handle |
void golioth_client_register_event_callback | ( | golioth_client_t | client, |
golioth_client_event_cb_fn | callback, | ||
void * | arg | ||
) |
Register a callback that will be called on client events (e.g. connected, disconnected)
client | The client handle |
callback | Callback function to register |
arg | Optional argument, forwarded directly to the callback when invoked. Can be NULL. |
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].
percent | Percent packet loss (0 is no packets lost, 100 is all packets lost) |
golioth_status_t golioth_client_start | ( | golioth_client_t | client | ) |
Start the Golioth client
Does nothing if the client is already started. The client is started after calling golioth_client_create.
client | The client handle |
golioth_status_t golioth_client_stop | ( | golioth_client_t | 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.
client | The client handle |
bool golioth_client_wait_for_connect | ( | golioth_client_t | 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.
client | The client handle |
timeout_ms | How long to wait, in milliseconds, or -1 to wait forever |