Skip to main content

LightDB Set Request

Use the Golioth Firmware SDK for all Zephyr projects

The Golioth Zephyr SDK is deprecated. Please use the Golioth Firmware SDK. (Migration Guide)

The LightDB Set sample application demonstrates how to send resources to LightDB State using the Golioth SDK. Data can be set synchronously, or asynchronously. Synchronous requests block program flow until a response is received from the Golioth server. Asynchronous requests register a callback function that runs when a response is received at some point in the future.

Includes

#include <net/golioth/system_client.h>

Including the Golioth System Client header file makes the LightDB Set API functions available to your program.

Payload preparation

char sbuf[11]; // Large enough for data plus NULL terminator
snprintk(sbuf, sizeof(sbuf), "%d", some_counter_value);

We recommend converting the payload data to text using snprintk() which prevents buffer overflows. This command uses printf substitution to easily format JSON objects like "{\"value\":%d}".

Escape Quotes for Strings

Be sure to include escaped quotes around strings that are sent to LightDB state.

For instance, integers are simply formatted in quotes "42", but strings must also include escaped quotes to indicate to the server that the data is a string value: "\"Golioth\"".

Synchronous Set

int err = golioth_lightdb_set(client, "counter",
GOLIOTH_CONTENT_FORMAT_APP_JSON,
sbuf, strlen(sbuf));

The simplest way to send LightDB State data to Golioth is using the synchronous golioth_lightdb_set() function. This blocking function will send data to the given endpoint ("counter" in this example) and wait for a response (or error) from the server.

Asynchronous Set

Registering a callback

err = golioth_lightdb_set_cb(client, "counter",
GOLIOTH_CONTENT_FORMAT_APP_JSON,
sbuf, strlen(sbuf),
counter_set_handler, NULL);

The asynchronous golioth_lightdb_set_cb() function is a non-blocking approach to sending LightDB State data to Golioth. The API call registers a callback function (e.g.: counter_set_handler) to handle the server response. The final parameter of the asynchronous set can be used to pass additional user-defined arguments to the callback.

Registering a callback is required for asynchronous function calls. When the response is received from Golioth, the registered callback will run, confirming that the data was received, or passing back error codes when the set operation was not successful.

Callback function

static int counter_set_handler(struct golioth_req_rsp *rsp)
{
if (rsp->err) {
LOG_WRN("Failed to set counter: %d", rsp->err);
return rsp->err;
}

LOG_DBG("Counter successfully set");

return 0;
}

The response is passed to the callback function as a golioth_req_rsp struct that includes err. It is recommended that callbacks test for an error code to ensure the expected data was received.

User-defined arguments are passed to the callback as rsp.user_data.

Resources

The best example of a set request is found in the LightDB Set sample code.

Further documentation of the device SDK is available in the Golioth Zephyr SDK Reference (Doxygen).