Cloud API

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.

Parameters

• backend – Pointer to cloud backend.

• evt – Pointer to cloud event.

• 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.