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:
API Reference¶
include/net/cloud.h
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
¶
-
enumerator
-
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
¶
-
enumerator
-
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
¶
-
enumerator
-
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
¶
-
enumerator
-
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.
-
enumerator
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 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.
-
int
-
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.
-