Cloud API

Functionality
Using Cloud API with different cloud backends
API Reference

The cloud API library exposes API to interact with cloud solutions. Using these APIs, an application can connect to a cloud, and send and receive data.

Functionality 

Cloud API defines a set of functions that a cloud driver, also called a cloud backend, must implement. Some functions of cloud API are optional and can be omitted.

To use the API, you must provide an event handler during the initialization of the cloud backend. This handler will receive events when, for example, data is received from the cloud.

After successful initialization of the cloud backend, you can establish a connection to the cloud. If the connection succeeds, the backend emits a “ready event”, and you can start interacting with the cloud.

Using Cloud API with different cloud backends 

See the following documentation to know more about using this library with different cloud backends:

Using Cloud API with nRF Cloud library

API Reference 

Header file: include/net/cloud.h

Source files: subsys/net/lib/cloud/

group cloud_api

Cloud API.

Defines

CLOUD_BACKEND_DEFINE(_name, _api)

Typedefs

typedef void (*cloud_evt_handler_t)(const struct cloud_backend *const backend, const struct cloud_event *const evt, void *user_data)

Cloud event handler function type.

Param backend: Pointer to cloud backend.
Param evt: Pointer to cloud event.
Param user_data: Pointer to user defined data that will be passed on as argument to cloud event handler.

Enums

enum cloud_event_type

Cloud events that can be notified asynchronously by the backend.

Values:

enumerator CLOUD_EVT_CONNECTING: The cloud backend is connecting to the configured cloud vendor.

enumerator CLOUD_EVT_CONNECTED: The cloud backend is connected to the cloud.

enumerator CLOUD_EVT_DISCONNECTED: The cloud backend got disconnected from the cloud.

enumerator CLOUD_EVT_READY: The cloud backend has established the appropriate resources for the connection.

enumerator CLOUD_EVT_ERROR: An error has occurred in the cloud backend.

enumerator CLOUD_EVT_DATA_SENT: Data has been sent to the cloud.

enumerator CLOUD_EVT_DATA_RECEIVED: Data has been received from the cloud.

enumerator CLOUD_EVT_PAIR_REQUEST: The device is not yet associated with the user. Pairing requested.

enumerator CLOUD_EVT_PAIR_DONE: Pairing with the user has been carried out.

enumerator CLOUD_EVT_FOTA_START: FOTA has started.

enumerator CLOUD_EVT_FOTA_DONE: FOTA has finished.

enumerator CLOUD_EVT_FOTA_ERASE_PENDING: The underlying FOTA process has a pending image erase.

enumerator CLOUD_EVT_FOTA_ERASE_DONE: The FOTA image erase has finished.

enumerator CLOUD_EVT_FOTA_DL_PROGRESS: FOTA download progress event.

enumerator CLOUD_EVT_FOTA_ERROR: FOTA error.

enumerator CLOUD_EVT_COUNT

enum cloud_disconnect_reason

Values:

enumerator CLOUD_DISCONNECT_USER_REQUEST

enumerator CLOUD_DISCONNECT_CLOSED_BY_REMOTE: The connection was closed by the cloud

enumerator CLOUD_DISCONNECT_INVALID_REQUEST: The connection is no longer valid

enumerator CLOUD_DISCONNECT_MISC: Miscellaneous error

enumerator CLOUD_DISCONNECT_COUNT

enum cloud_qos

Quality of Service for message sent by a cloud backend.

Values:

enumerator CLOUD_QOS_AT_MOST_ONCE

enumerator CLOUD_QOS_AT_LEAST_ONCE

enumerator CLOUD_QOS_EXACTLY_ONCE

enumerator CLOUD_QOS_COUNT

enum cloud_endpoint_type

Cloud endpoint type.

Values:

enumerator CLOUD_EP_MSG: Endpoint used to send messages to cloud.

enumerator CLOUD_EP_STATE: Endpoint used to update the cloud-side device state.

enumerator CLOUD_EP_STATE_DELETE: Endpoint used to delete the cloud-side device state.

enumerator CLOUD_EP_STATE_GET: Enpoint used to request the cloud-side device state.

enumerator CLOUD_EP_PAIR: Endpoint used to pair the device with a user.

enumerator CLOUD_EP_COMMON_COUNT

enumerator CLOUD_EP_PRIV_START

enumerator CLOUD_EP_PRIV_END

enum cloud_connect_result

Cloud connect results.

Values:

enumerator CLOUD_CONNECT_RES_SUCCESS

enumerator CLOUD_CONNECT_RES_ERR_NOT_INITD: Cloud backend is not initialized.

enumerator CLOUD_CONNECT_RES_ERR_INVALID_PARAM: Invalid parameters in cloud connection request.

enumerator CLOUD_CONNECT_RES_ERR_NETWORK: Host cannot be found with the available network interfaces.

enumerator CLOUD_CONNECT_RES_ERR_BACKEND: A backend-specific error.

enumerator CLOUD_CONNECT_RES_ERR_MISC: Error cause cannot be determined.

enumerator CLOUD_CONNECT_RES_ERR_NO_MEM: MQTT RX/TX buffers were not initialized.

enumerator CLOUD_CONNECT_RES_ERR_PRV_KEY: Invalid private key

enumerator CLOUD_CONNECT_RES_ERR_CERT: Invalid CA or client certificate

enumerator CLOUD_CONNECT_RES_ERR_CERT_MISC: Miscellaneous certificate error

enumerator CLOUD_CONNECT_RES_ERR_TIMEOUT_NO_DATA: Timeout; typically occurs when the inserted SIM card has no data

enumerator CLOUD_CONNECT_RES_ERR_ALREADY_CONNECTED: Connection process has already been started.

Functions

static inline int cloud_init(struct cloud_backend *const backend, cloud_evt_handler_t handler)

Initialize a cloud backend. Performs all necessary configuration of the backend required to connect its online counterpart.

Parameters

backend – Pointer to cloud backend structure.
handler – Handler to receive events from the backend.

static inline int cloud_uninit(const struct cloud_backend *const backend)

Uninitialize a cloud backend. Gracefully disconnects remote endpoint and releases memory.

Parameters

backend – Pointer to cloud backend structure.

static inline int cloud_connect(const struct cloud_backend *const backend)

Request connection to a cloud backend.

The backend is required to expose the socket in use when this function returns. The socket should then be available through backend->config->socket and the application may start listening for events on it.

Parameters

backend – Pointer to a cloud backend structure.

Returns

connect result defined by enum cloud_connect_result.

static inline int cloud_disconnect(const struct cloud_backend *const backend)

Disconnect from a cloud backend.

Parameters

backend – Pointer to a cloud backend structure.

Returns

0 or a negative error code indicating reason of failure.

static inline int cloud_send(const struct cloud_backend *const backend, struct cloud_msg *msg)

Send data to a cloud.

Parameters

backend – Pointer to a cloud backend structure.
msg – Pointer to cloud message structure.

Returns

0 or a negative error code indicating reason of failure.

static inline int cloud_ping(const struct cloud_backend *const backend)

Optional API to ping the cloud’s remote endpoint periodically.

Parameters

backend – Pointer to cloud backend.

Returns

0 or a negative error code indicating reason of failure.

static inline int cloud_keepalive_time_left(const struct cloud_backend *const backend)

Helper function to determine when next keep alive message should be sent. Can be used for instance as a source for poll timeout.

Parameters

backend – Pointer to cloud backend.

Returns

Time in milliseconds until next keep alive message is expected to be sent.

Returns

-1 if keep alive messages are not enabled.

static inline int cloud_input(const struct cloud_backend *const backend)

Process incoming data to backend.

Note

This is a non-blocking call.

Parameters

backend – Pointer to cloud backend.

Returns

0 or a negative error code indicating reason of failure.

static inline int cloud_ep_subscriptions_add(const struct cloud_backend *const backend, const struct cloud_endpoint *list, size_t list_count)

Add Cloud endpoint subscriptions.

Parameters

backend – Pointer to cloud backend structure.
list – Pointer to a list of endpoint subscriptions.
list_count – Number of entries in the endpoint subscription list.

static inline int cloud_ep_subscriptions_remove(const struct cloud_backend *const backend, const struct cloud_endpoint *list, size_t list_count)

Remove Cloud endpoint subscriptions.

Parameters

backend – Pointer to cloud backend structure.
list – Pointer to a list of endpoint subscriptions.
list_count – Number of entries in the endpoint subscriptions list.

static inline int cloud_user_data_set(struct cloud_backend *const backend, void *user_data)

Set the user-defined data that is passed as an argument to cloud event handler.

Parameters

backend – Pointer to cloud backend structure.
user_data – Pointer to user defined data that will be passed on as argument to cloud event handler.

static inline int cloud_get_id(const struct cloud_backend *const backend, char *id, size_t id_len)

Get the id string for the current device.

Parameters

backend – Pointer to cloud backend structure.
id – Pointer to buffer to receive ID.
id_len – Size of buffer.

Returns

0 on success otherwise error number.

static inline void cloud_notify_event(struct cloud_backend *backend, struct cloud_event *evt, void *user_data)

Calls the user-provided event handler with event data.

Parameters

backend – Pointer to cloud backend.
evt – Pointer to event data.
user_data – Pointer to user-defined data.

struct cloud_backend *cloud_get_binding(const char *name)

Get binding (pointer) to cloud backend if a registered backend matches the provided name.

Parameters

name – String with the name of the cloud backend.

Returns

Pointer to the cloud backend structure.

struct cloud_endpoint: #include <cloud.h>

Cloud endpoint data.

struct cloud_msg: #include <cloud.h>

Cloud message type.

struct cloud_event

#include <cloud.h>

Cloud event type.

Public Members

int fota_progress: FOTA progress in percentage.

struct cloud_api

#include <cloud.h>

Cloud backend API.

ping() and user_data_set() can be omitted, the other functions are mandatory.

struct cloud_backend_config: #include <cloud.h>

Structure for cloud backend configuration.

struct cloud_backend: #include <cloud.h>

Structure for cloud backend.

Cloud API

Functionality

Using Cloud API with different cloud backends

API Reference

Functionality 

Using Cloud API with different cloud backends 

API Reference 