Golioth Zephyr SDK
Golioth Networking

Functions for communicating with the Golioth servers. More...

Modules

 Golioth Remote Procedure Call
 
 Golioth Settings
 
 Golioth System Client
 

Classes

struct  golioth_tls
 (D)TLS credentials of Golioth client. More...
 
struct  golioth_message_callback_reg
 Data associated with a message callback registration. More...
 
struct  golioth_client
 Represents a Golioth client instance. More...
 
struct  golioth_blockwise_observe_ctx
 Represents a Golioth blockwise observe context. More...
 
struct  golioth_blockwise_download_ctx
 Represents blockwise download transfer from Golioth. More...
 

Macros

#define GOLIOTH_COAP_MAX_NON_PAYLOAD_LEN   128
 
#define GOLIOTH_MAX_IDENTITY_LEN   32
 
#define GOLIOTH_EMPTY_PACKET_LEN   (16 + GOLIOTH_MAX_IDENTITY_LEN)
 
#define GOLIOTH_MAX_NUM_MESSAGE_CALLBACKS   4
 
#define GOLIOTH_LIGHTDB_PATH(x)   ".d/" x
 
#define GOLIOTH_LIGHTDB_STREAM_PATH(x)   ".s/" x
 

Typedefs

typedef void(* golioth_message_callback) (struct golioth_client *client, struct coap_packet *rx, void *user_arg)
 
typedef int(* golioth_blockwise_observe_received_t) (struct golioth_blockwise_observe_ctx *ctx, const uint8_t *data, size_t offset, size_t len, bool last)
 Type of the callback being called when a single block of data is received as part of CoAP observe notification. More...
 
typedef int(* golioth_blockwise_download_received_t) (struct golioth_blockwise_download_ctx *ctx, const uint8_t *data, size_t offset, size_t len, bool last)
 Type of the callback being called when a single block of data is received as part of CoAP response. More...
 

Functions

void golioth_blockwise_download_init (struct golioth_client *client, struct golioth_blockwise_download_ctx *ctx)
 Initialize blockwise download. More...
 
void golioth_init (struct golioth_client *client)
 Initialize golioth client instance. More...
 
bool golioth_is_connected (struct golioth_client *client)
 Check if client is connected to Golioth. More...
 
int golioth_connect (struct golioth_client *client, const char *host, uint16_t port)
 Connect to Golioth. More...
 
int golioth_disconnect (struct golioth_client *client)
 Disconnect from Golioth. More...
 
int golioth_set_proto_coap_dtls (struct golioth_client *client, sec_tag_t *sec_tag_list, size_t sec_tag_count)
 Set DTLS as transport protocol. More...
 
int golioth_send_coap (struct golioth_client *client, struct coap_packet *packet)
 Send CoAP packet to Golioth. More...
 
int golioth_send_coap_payload (struct golioth_client *client, struct coap_packet *packet, uint8_t *data, uint16_t data_len)
 Send CoAP packet with separate payload to Golioth. More...
 
int golioth_ping (struct golioth_client *client)
 Send PING message to Golioth. More...
 
int golioth_send_hello (struct golioth_client *client)
 Send Hello message to Golioth. More...
 
int golioth_lightdb_get (struct golioth_client *client, const uint8_t *path, enum coap_content_format format, struct coap_reply *reply, coap_reply_t reply_cb)
 Get value from Golioth's Light DB. More...
 
int golioth_lightdb_set (struct golioth_client *client, const uint8_t *path, enum coap_content_format format, uint8_t *data, uint16_t data_len)
 Set value to Golioth's Light DB. More...
 
int golioth_lightdb_delete (struct golioth_client *client, const uint8_t *path)
 Delete value in Golioth's Light DB. More...
 
int golioth_lightdb_observe (struct golioth_client *client, const uint8_t *path, enum coap_content_format format, struct coap_reply *reply, coap_reply_t reply_cb)
 Observe value in Golioth's Light DB. More...
 
int golioth_observe_blockwise (struct golioth_client *client, struct golioth_blockwise_observe_ctx *ctx, const char *path, struct coap_reply *reply, golioth_blockwise_observe_received_t received_cb)
 Observe resource with blockwise updates. More...
 
int golioth_process_rx (struct golioth_client *client)
 Process incoming data from Golioth. More...
 
int golioth_register_message_callback (struct golioth_client *client, golioth_message_callback callback, void *user_arg)
 Register a callback to be called when a CoAP message is received. More...
 

Detailed Description

Functions for communicating with the Golioth servers.

Macro Definition Documentation

◆ GOLIOTH_COAP_MAX_NON_PAYLOAD_LEN

#define GOLIOTH_COAP_MAX_NON_PAYLOAD_LEN   128

◆ GOLIOTH_EMPTY_PACKET_LEN

#define GOLIOTH_EMPTY_PACKET_LEN   (16 + GOLIOTH_MAX_IDENTITY_LEN)

◆ GOLIOTH_LIGHTDB_PATH

#define GOLIOTH_LIGHTDB_PATH (   x)    ".d/" x

◆ GOLIOTH_LIGHTDB_STREAM_PATH

#define GOLIOTH_LIGHTDB_STREAM_PATH (   x)    ".s/" x

◆ GOLIOTH_MAX_IDENTITY_LEN

#define GOLIOTH_MAX_IDENTITY_LEN   32

◆ GOLIOTH_MAX_NUM_MESSAGE_CALLBACKS

#define GOLIOTH_MAX_NUM_MESSAGE_CALLBACKS   4

Typedef Documentation

◆ golioth_blockwise_download_received_t

golioth_blockwise_download_received_t

Type of the callback being called when a single block of data is received as part of CoAP response.

◆ golioth_blockwise_observe_received_t

golioth_blockwise_observe_received_t

Type of the callback being called when a single block of data is received as part of CoAP observe notification.

◆ golioth_message_callback

typedef void(* golioth_message_callback) (struct golioth_client *client, struct coap_packet *rx, void *user_arg)

Function Documentation

◆ golioth_blockwise_download_init()

void golioth_blockwise_download_init ( struct golioth_client client,
struct golioth_blockwise_download_ctx ctx 
)

Initialize blockwise download.

Parameters
clientClient instance
ctxBlockwise download context

◆ golioth_connect()

int golioth_connect ( struct golioth_client client,
const char *  host,
uint16_t  port 
)

Connect to Golioth.

Attempt to connect to Golioth.

Parameters
clientClient instance
hostServer hostname or IP address
portServer port number
Return values
0On success
<0On failure

◆ golioth_disconnect()

int golioth_disconnect ( struct golioth_client client)

Disconnect from Golioth.

Attempt to disconnect from Golioth.

Parameters
clientClient instance
Return values
0On success
<0On failure

◆ golioth_init()

void golioth_init ( struct golioth_client client)

Initialize golioth client instance.

Initializes internal data of client instance. Must be called before using any other APIs on client instance.

Parameters
clientClient instance

◆ golioth_is_connected()

bool golioth_is_connected ( struct golioth_client client)

Check if client is connected to Golioth.

Check if client instance is connected to Golioth.

Parameters
clientClient instance.
Return values
trueWhen client is connected to Golioth.
falseWhen client is not connected to Golioth.

◆ golioth_lightdb_delete()

int golioth_lightdb_delete ( struct golioth_client client,
const uint8_t *  path 
)

Delete value in Golioth's Light DB.

Delete value in Light DB.

Parameters
clientClient instance
pathLight DB resource path
Return values
0On success
<0On failure

◆ golioth_lightdb_get()

int golioth_lightdb_get ( struct golioth_client client,
const uint8_t *  path,
enum coap_content_format  format,
struct coap_reply *  reply,
coap_reply_t  reply_cb 
)

Get value from Golioth's Light DB.

Get value from Light DB and initialize passed CoAP reply handler.

Parameters
clientClient instance
pathLight DB resource path
formatRequested format of payload
replyCoAP reply handler object used for notifying about received value
reply_cbReply handler callback
Return values
0On success
<0On failure

◆ golioth_lightdb_observe()

int golioth_lightdb_observe ( struct golioth_client client,
const uint8_t *  path,
enum coap_content_format  format,
struct coap_reply *  reply,
coap_reply_t  reply_cb 
)

Observe value in Golioth's Light DB.

Observe value in Light DB and initialize passed CoAP reply handler.

Parameters
clientClient instance
pathLight DB resource path to be monitored
formatRequested format of payload
replyCoAP reply handler object used for notifying about updated value
reply_cbReply handler callback
Return values
0On success
<0On failure

◆ golioth_lightdb_set()

int golioth_lightdb_set ( struct golioth_client client,
const uint8_t *  path,
enum coap_content_format  format,
uint8_t *  data,
uint16_t  data_len 
)

Set value to Golioth's Light DB.

Set new value to Light DB.

Parameters
clientClient instance
pathLight DB resource path
formatFormat of payload
dataPayload data
data_lenPayload length
Return values
0On success
<0On failure

◆ golioth_observe_blockwise()

int golioth_observe_blockwise ( struct golioth_client client,
struct golioth_blockwise_observe_ctx ctx,
const char *  path,
struct coap_reply *  reply,
golioth_blockwise_observe_received_t  received_cb 
)

Observe resource with blockwise updates.

Parameters
clientClient instance
ctxBlockwise observe context that will be used for handling resouce updates
pathResource path to be monitored
replyCoAP reply handler object used for notifying about updated value
received_cbReceived block handler callback
Return values
0On success
<0On failure

◆ golioth_ping()

int golioth_ping ( struct golioth_client client)

Send PING message to Golioth.

Parameters
clientClient instance
Return values
0On success
<0On failure

◆ golioth_process_rx()

int golioth_process_rx ( struct golioth_client client)

Process incoming data from Golioth.

Process incoming data on network socket. It does not block when there is no more data, so it is best to use it with zsock_poll.

Parameters
clientClient instance
Return values
0On success
<0On failure

◆ golioth_register_message_callback()

int golioth_register_message_callback ( struct golioth_client client,
golioth_message_callback  callback,
void *  user_arg 
)

Register a callback to be called when a CoAP message is received.

This is similar to client->on_message, but allows for more than one "on_message" callback to be registered, and has an additional user_arg parameter which can be used to pass user data to the callback when it's invoked.

Parameters
clientClient instance
callbackMessage callback to register
user_argUser data forwarded directly to callback when invoked. Optional, can be NULL.
Return values
0registration successful
<0registration failed

◆ golioth_send_coap()

int golioth_send_coap ( struct golioth_client client,
struct coap_packet *  packet 
)

Send CoAP packet to Golioth.

This is low-level API for sending arbitrary CoAP packet to Golioth.

Parameters
clientClient instance
packetCoAP packet
Return values
0On success
<0On failure

◆ golioth_send_coap_payload()

int golioth_send_coap_payload ( struct golioth_client client,
struct coap_packet *  packet,
uint8_t *  data,
uint16_t  data_len 
)

Send CoAP packet with separate payload to Golioth.

Similar to golioth_send_coap, but appends payload (internally) before sending.

Parameters
clientClient instance
packetCoAP packet (without payload)
dataPayload data
dataPayload length
Return values
0On success
<0On failure

◆ golioth_send_hello()

int golioth_send_hello ( struct golioth_client client)

Send Hello message to Golioth.

Sends Hello message to Golioth, which is mostly useful verifying Golioth connection.

Parameters
clientClient instance
Return values
0On success
<0On failure

◆ golioth_set_proto_coap_dtls()

int golioth_set_proto_coap_dtls ( struct golioth_client client,
sec_tag_t *  sec_tag_list,
size_t  sec_tag_count 
)

Set DTLS as transport protocol.

Set DTLS as transport protocol for CoAP packets to Golioth and assignes credentials to be used.

Parameters
clientClient instance
sec_tag_listSecure tag array (see sec_tag_t and TLS_SEC_TAG_LIST)
sec_tag_countSecure tag count (see sec_tag_t and TLS_SEC_TAG_LIST)
Return values
0On success
<0On failure