nRF Cloud¶
The nRF Cloud library enables applications to connect to Nordic Semiconductor’s nRF Cloud. It abstracts and hides the details of the transport and the encoding scheme that is used for the payload and provides a simplified API interface for sending data from supported sensor types to the cloud. The current implementation supports the following technology:
GPS and FLIP sensor data
TLS secured MQTT as the communication protocol
JSON as the data format
Initializing¶
Before using any other APIs of the module, the application must call nrf_cloud_init()
.
If this API fails, the application must not use any APIs of the module.
Note
Initialize the module before starting any timers, sensor drivers, or communication on the link.
Connecting¶
The application can use nrf_cloud_connect()
to connect to the cloud.
This API triggers a series of events and actions in the system.
If the API fails, the application must retry to connect.
First, the library tries to establish the transport for communicating with the cloud. This procedure involves a TLS handshake that might take up to three seconds. The API blocks for the duration of the handshake.
Next, the API subscribes to an MQTT topic to start receiving user association requests from the cloud. The cloud uses the device’s certificates for authentication. See Updating the nRF Connect for Cloud certificate and the Modem key management library for more information on modem credentials. The certificates are generated using the device’s ID and PIN/HWID.
Every time nRF Cloud starts a communication session with a device, it verifies whether the device is uniquely associated with a user. If not, the user association procedure is triggered. When adding the device to an nRF cloud account, the user must provide the correct device ID and PIN (for Thingy:91) or HWID (for nRF9160 DK) to nRF Cloud.
The following message sequence chart shows the flow of events and expected application responses to each event during the user association procedure:
Note
This chart shows the sequence of successful user association of an unassociated device.
Currently, nRF Cloud requires that communication is re-established to update the device’s permission to send user data.
The application must disconnect using nrf_cloud_disconnect()
and then reconnect using nrf_cloud_connect()
.
When the device is successfully associated with a user on the cloud, subsequent connections to the cloud (also across power cycles) follow this sequence:
After receiving NRF_CLOUD_EVT_READY
, the application can start sending sensor data to the cloud.
Sending sensor data¶
The library offers two APIs, nrf_cloud_sensor_data_send()
and nrf_cloud_sensor_data_stream()
, for sending sensor data to the cloud.
Currently, the supported sensor types are GPS and FLIP (see nrf_cloud_sensor
).
Use nrf_cloud_sensor_data_stream()
to send sensor data with best quality.
Before sending any sensor data, call the function nrf_cloud_sensor_attach()
with the type of the sensor.
Note that this function must be called after receiving the event NRF_CLOUD_EVT_READY
.
It triggers the event NRF_CLOUD_EVT_SENSOR_ATTACHED
if the execution was successful.
Removing the link between device and user¶
If you want to remove the link between a device and an nRF Cloud user, you must do this from the nRF Cloud. It is not possible for a device to unlink itself.
When a user disassociates a device, the library disallows any further sensor data to be sent to the cloud and generates an NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST
event.
The application can then decide to associate again by responding with nrf_cloud_user_associate()
with the new input sequence.
See the following message sequence chart:
Using Cloud API with nRF Cloud library¶
You can use this library in conjunction with Cloud API. The following sections describe the various stages in the process of connection to the nRF Cloud.
Initialization¶
To use a defined Cloud API backend, a binding must be obtained using the Cloud API function cloud_get_binding()
to which you can pass the name of the desired backend.
The nRF Cloud library defines the Cloud API backend as NRF_CLOUD
via the CLOUD_BACKEND_DEFINE
macro.
The backend must be initialized using the cloud_init()
function, with the binding, and a function pointer to user defined Cloud API event handler as parameters.
If cloud_init()
returns success, the backend is ready for use.
The return values for a failure scenario of the cloud_init()
function are described below for the nRF Cloud backend:
-EACCES: invalid state; already initialized
-EINVAL: invalid event handler provided
-ENOMEM: error building MQTT topics; the given client ID of the device could be too long
Note
If CONFIG_NRF_CLOUD_PROVISION_CERTIFICATES
is enabled, error values could be different or have different error descriptions.
Connecting to the Cloud¶
The nRF Cloud library offers two ways to handle backend connections when the cloud_connect()
function is called.
If the CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD
Kconfig option is enabled, a cloud backend thread monitors the connection socket.
If the option is not enabled, the user application is responsible for monitoring the socket.
The dual functionalities of the cloud_connect()
function in the two scenarios are described below:
CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD
enabledFunction does not block and returns success if the connection monitoring thread has started. Below are some of the error codes that can be returned:
CLOUD_CONNECT_RES_ERR_NOT_INITD
: Cloud backend is not initializedCLOUD_CONNECT_RES_ERR_ALREADY_CONNECTED
: Connection process has already been started
Upon success, the monitoring thread sends an event of type
CLOUD_EVT_CONNECTING
to the user’s cloud event handler, with theerr
field set to success. If an error occurs, another event of the same type is sent, with theerr
field set to indicate the cause. These additional errors are described in the following section.CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD
disabledFunction blocks and returns success when the MQTT connection to the cloud has completed. The connection socket is set in the backend binding and it becomes available for the application to use. Below are some of the error codes that can be returned:
CLOUD_CONNECT_RES_ERR_NETWORK
: Host cannot be found with the available network interfacesCLOUD_CONNECT_RES_ERR_BACKEND
: A backend-specific error; In the case of nRF Cloud, this can indicate a FOTA initialization errorCLOUD_CONNECT_RES_ERR_MISC
: Error cause cannot be determinedCLOUD_CONNECT_RES_ERR_NO_MEM
: MQTT RX/TX buffers were not initializedCLOUD_CONNECT_RES_ERR_PRV_KEY
: Invalid private keyCLOUD_CONNECT_RES_ERR_CERT
: Invalid CA or client certificateCLOUD_CONNECT_RES_ERR_CERT_MISC
: Miscellaneous certificate errorCLOUD_CONNECT_RES_ERR_TIMEOUT_NO_DATA
: Timeout; typically occurs when the inserted SIM card has no data
For both connection methods, when a device with JITP certificates attempts to connect to nRF Cloud for the first time, the cloud rejects the connection attempt so that it can provision the device. When this occurs, the Cloud API generates a
CLOUD_EVT_DISCONNECTED
event with theerr
field set toCLOUD_DISCONNECT_INVALID_REQUEST
. The device should restart the connection process upon receipt of theCLOUD_EVT_DISCONNECTED
event.
Connected to the Cloud¶
When the connection between the device and the cloud has been successfully established, the Cloud API dispatches a CLOUD_EVT_CONNECTED
event.
If the device is not associated with an nRF Cloud account, a CLOUD_EVT_PAIR_REQUEST
event is generated.
The device must wait until it is added to an account, which is indicated by the CLOUD_EVT_PAIR_DONE
event.
If a device pair request is received, the device must disconnect and reconnect after receiving the CLOUD_EVT_PAIR_DONE
event.
This is necessary because the updated policy of the cloud becomes effective only on a new connection.
Following the CLOUD_EVT_PAIR_DONE
event, the Cloud API sends a CLOUD_EVT_READY
event to indicate that the cloud is ready to receive data from the device.
Disconnection from the Cloud¶
The user application can generate a disconnect request with the cloud_disconnect()
function.
A successful disconnection is indicated by the CLOUD_EVT_DISCONNECTED
event.
The err
field in the event message is set to CLOUD_DISCONNECT_USER_REQUEST
.
If an unexpected disconnect event is received, the err
field contains the cause.
If CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD
is not enabled, the only cause of disconnection is CLOUD_DISCONNECT_MISC
.
The user application should use the connection socket to determine a reason.
If the socket is being monitored by the backend thread, the following causes of disconnection can occur:
CLOUD_DISCONNECT_CLOSED_BY_REMOTE
: The connection was closed by the cloud; POLLHUPCLOUD_DISCONNECT_INVALID_REQUEST
: The connection is no longer valid; POLLNVALCLOUD_DISCONNECT_MISC
: Miscellaneous error; POLLERR
API documentation¶
include/net/nrf_cloud.h
subsys/net/lib/nrf_cloud/src/
-
group
nrf_cloud
Typedefs
-
typedef void (*
nrf_cloud_event_handler_t
)(const struct nrf_cloud_evt *evt)¶ Event handler registered with the module to handle asynchronous events from the module.
- Parameters
[in] evt
: The event and any associated parameters.
Enums
-
enum
nrf_cloud_evt_type
¶ Asynchronous nRF Cloud events notified by the module.
Values:
-
enumerator
NRF_CLOUD_EVT_TRANSPORT_CONNECTED
¶ The transport to the nRF Cloud is established.
-
enumerator
NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST
¶ There was a request from nRF Cloud to associate the device with a user on the nRF Cloud.
-
enumerator
NRF_CLOUD_EVT_USER_ASSOCIATED
¶ The device is successfully associated with a user.
-
enumerator
NRF_CLOUD_EVT_READY
¶ The device can now start sending sensor data to the cloud.
-
enumerator
NRF_CLOUD_EVT_SENSOR_ATTACHED
¶ A sensor was successfully attached to the cloud. Supported sensor types are defined in nrf_cloud_sensor.
-
enumerator
NRF_CLOUD_EVT_RX_DATA
¶ The device received data from the cloud.
-
enumerator
NRF_CLOUD_EVT_SENSOR_DATA_ACK
¶ The data sent to the cloud was acknowledged.
-
enumerator
NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED
¶ The transport was disconnected.
-
enumerator
NRF_CLOUD_EVT_FOTA_DONE
¶ The device should be restarted to apply a firmware upgrade
-
enumerator
NRF_CLOUD_EVT_ERROR
¶ There was an error communicating with the cloud.
-
enumerator
-
enum
nrf_cloud_sensor
¶ Sensor types supported by the nRF Cloud.
Values:
-
enumerator
NRF_CLOUD_SENSOR_GPS
¶ The GPS sensor on the device.
-
enumerator
NRF_CLOUD_SENSOR_FLIP
¶ The FLIP movement sensor on the device.
-
enumerator
NRF_CLOUD_SENSOR_BUTTON
¶ The Button press sensor on the device.
-
enumerator
NRF_CLOUD_SENSOR_TEMP
¶ The TEMP sensor on the device.
-
enumerator
NRF_CLOUD_SENSOR_HUMID
¶ The Humidity sensor on the device.
-
enumerator
NRF_CLOUD_SENSOR_AIR_PRESS
¶ The Air Pressure sensor on the device.
-
enumerator
NRF_CLOUD_SENSOR_AIR_QUAL
¶ The Air Quality sensor on the device.
-
enumerator
NRF_CLOUD_LTE_LINK_RSRP
¶ The RSPR data obtained from the modem.
-
enumerator
NRF_CLOUD_DEVICE_INFO
¶ The descriptive DEVICE data indicating its status.
-
enumerator
Functions
-
int
nrf_cloud_init
(const struct nrf_cloud_init_param *param)¶ Initialize the module.
- Warning
This API must be called exactly once, and it must return successfully.
- Parameters
[in] param
: Initialization parameters.
- Return Value
0
: If successful. Otherwise, a (negative) error code is returned.
-
int
nrf_cloud_connect
(const struct nrf_cloud_connect_param *param)¶ Connect to the cloud.
In any stage of connecting to the cloud, an NRF_CLOUD_EVT_ERROR might be received. If it is received before NRF_CLOUD_EVT_TRANSPORT_CONNECTED, the application may repeat the call to nrf_cloud_connect to try again.
- Parameters
[in] param
: Parameters to be used for the connection.
- Return Value
0
: If successful. Otherwise, a (negative) error code is returned.
-
int
nrf_cloud_sensor_attach
(const struct nrf_cloud_sa_param *param)¶ Attach a sensor to the cloud.
This API should only be called after receiving an NRF_CLOUD_EVT_READY event. If the API succeeds, wait for the NRF_CLOUD_EVT_SENSOR_ATTACHED event before sending the sensor data.
- Parameters
[in] param
: Sensor information.
- Return Value
0
: If successful. Otherwise, a (negative) error code is returned.
-
int
nrf_cloud_sensor_data_send
(const struct nrf_cloud_sensor_data *param)¶ Send sensor data reliably.
This API should only be called after receiving an NRF_CLOUD_EVT_SENSOR_ATTACHED event. If the API succeeds, you can expect the NRF_CLOUD_EVT_SENSOR_DATA_ACK event.
- Parameters
[in] param
: Sensor data.
- Return Value
0
: If successful. Otherwise, a (negative) error code is returned.
-
int
nrf_cloud_shadow_update
(const struct nrf_cloud_sensor_data *param)¶ Update the device shadow with sensor data.
- Parameters
[in] param
: Sensor data.
- Return Value
0
: If successful. Otherwise, a (negative) error code is returned.
-
int
nrf_cloud_sensor_data_stream
(const struct nrf_cloud_sensor_data *param)¶ Stream sensor data.
This API should only be called after receiving an NRF_CLOUD_EVT_SENSOR_ATTACHED event.
- Parameters
[in] param
: Sensor data.
- Return Value
0
: If successful. Otherwise, a (negative) error code is returned.
-
int
nrf_cloud_disconnect
(void)¶ Disconnect from the cloud.
This API may be called any time after receiving the NRF_CLOUD_EVT_TRANSPORT_CONNECTED event. If the API succeeds, you can expect the NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED event.
- Return Value
0
: If successful. Otherwise, a (negative) error code is returned.
-
void
nrf_cloud_process
(void)¶ Function that must be called periodically to keep the module functional.
-
struct
nrf_cloud_data
¶ - #include <nrf_cloud.h>
Generic encapsulation for any data that is sent to the cloud.
-
struct
nrf_cloud_topic
¶ - #include <nrf_cloud.h>
MQTT topic.
-
struct
nrf_cloud_sensor_list
¶ - #include <nrf_cloud.h>
Sensors that are supported by the device.
-
struct
nrf_cloud_connect_param
¶ - #include <nrf_cloud.h>
Connection parameters.
Public Members
-
const struct nrf_cloud_sensor_list *
sensor
¶ Supported sensor types. May be NULL.
-
const struct nrf_cloud_sensor_list *
-
struct
nrf_cloud_sa_param
¶ - #include <nrf_cloud.h>
Parameters of attached sensors.
Public Members
-
enum nrf_cloud_sensor
sensor_type
¶ The sensor that is being attached.
-
enum nrf_cloud_sensor
-
struct
nrf_cloud_sensor_data
¶ - #include <nrf_cloud.h>
Sensor data transmission parameters.
Public Members
-
enum nrf_cloud_sensor
type
¶ The sensor that is the source of the data.
-
struct nrf_cloud_data
data
¶ Sensor data to be transmitted.
-
uint32_t
tag
¶ Unique tag to identify the sent data. Useful for matching the acknowledgment.
-
enum nrf_cloud_sensor
-
struct
nrf_cloud_evt
¶ - #include <nrf_cloud.h>
Asynchronous events received from the module.
Public Members
-
enum nrf_cloud_evt_type
type
¶ The event that occurred.
-
uint32_t
status
¶ Any status associated with the event.
-
struct nrf_cloud_data
data
¶ Received data.
-
struct nrf_cloud_topic
topic
¶ Topic on which data was received.
-
enum nrf_cloud_evt_type
-
struct
nrf_cloud_init_param
¶ - #include <nrf_cloud.h>
Initialization parameters for the module.
Public Members
-
nrf_cloud_event_handler_t
event_handler
¶ Event handler that is registered with the module.
-
nrf_cloud_event_handler_t
-
typedef void (*