nRF Cloud library

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 communication protocol
• JSON as 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. nrf_cloud_connect() requires a list of supported features in the application. Use the following code in your application to initialize this list:

/* Array of supported user association methods. */
const enum nrf_cloud_ua supported_uas[] = {
             NRF_CLOUD_UA_BUTTON
};

/* Array of supported sensors. */
const enum nrf_cloud_sensor supported_sensors[] = {
             NRF_CLOUD_SENSOR_GPS,
             NRF_CLOUD_SENSOR_FLIP
};

/* List of supported user association methods. */
const struct nrf_cloud_ua_list ua_list = {
             .size = ARRAY_SIZE(supported_uas),
             .ptr = supported_uas
};

/* List of supported sensors. */
const struct nrf_cloud_sensor_list sensor_list = {
             .size = ARRAY_SIZE(supported_sensors),
             .ptr = supported_sensors
};

/* Struct containing both lists. */
const struct nrf_cloud_connect_param param = {
             .ua = &ua_list,
             .sensor = &sensor_list,
};

int err = nrf_cloud_connect(&param);

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.

Every time nRF Cloud starts a communication session with a device, it verifies if the device is uniquely associated with a user. If not, the user association procedure is triggered. The following message sequence chart shows the flow of events and expected application responses to each event:

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. This is why the NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED event occurs. The application must reconnect to the cloud using the nrf_cloud_connect() API.

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.

User association failure

User association might fail due to the following reasons:

• Mismatch in the input sequence from the device
• Time-out on the cloud

If there is a mismatch in the sequence, the library generates a new NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST event, and the user can try again. This event may be triggered several times until the cloud receives a matching sequence.

If a time-out occurs, NRF_CLOUD_EVT_ERROR is triggered and sent to the application. If this event is received, disconnect from the cloud using the nrf_cloud_disconnect() API. The application must wait for the NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED event before attempting a new connection 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:

API documentation

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

• evt: The event and any associated parameters.

Enums

enum nrf_cloud_evt_type

Asynchronous nRF Cloud events notified by the module.

Values:

NRF_CLOUD_EVT_TRANSPORT_CONNECTED = 0x1

The transport to the nRF Cloud is established.

NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST

There was a request from nRF Cloud to associate the device with a user on the nRF Cloud. On receiving this event, the user must enter the user association sequence using the nrf_cloud_user_associate API.

NRF_CLOUD_EVT_USER_ASSOCIATED

The device is successfully associated with a user.

NRF_CLOUD_EVT_READY

The device can now start sending sensor data to the cloud.

NRF_CLOUD_EVT_SENSOR_ATTACHED

A sensor was successfully attached to the cloud. Supported sensor types are defined in nrf_cloud_sensor.

NRF_CLOUD_EVT_RX_DATA

The device received data from the cloud.

NRF_CLOUD_EVT_SENSOR_DATA_ACK

The data sent to the cloud was acknowledged.

NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED

The transport was disconnected.

NRF_CLOUD_EVT_ERROR = 0xFF

There was an error communicating with the cloud.

enum nrf_cloud_ua

User association types supported by the nRF Cloud.

Values:

NRF_CLOUD_UA_BUTTON

Button input.

enum nrf_cloud_sensor

Sensor types supported by the nRF Cloud.

Values:

NRF_CLOUD_SENSOR_GPS

The GPS sensor on the device.

NRF_CLOUD_SENSOR_FLIP

The FLIP movement sensor on the device.

NRF_CLOUD_SENSOR_BUTTON

The Button press sensor on the device.

NRF_CLOUD_SENSOR_TEMP

The TEMP sensor on the device.

NRF_CLOUD_SENSOR_HUMID

The Humidity sensor on the device.

NRF_CLOUD_SENSOR_AIR_PRESS

The Air Pressure sensor on the device.

NRF_CLOUD_SENSOR_AIR_QUAL

The Air Quality sensor on the device.

NRF_CLOUD_LTE_LINK_RSRP

The RSPR data obtained from the modem.

NRF_CLOUD_DEVICE_INFO

The descriptive DEVICE data indicating its status.

enum nrf_cloud_ua_button

User input sequence values for user association type NRF_CLOUD_UA_BUTTON.

Values:

NRF_CLOUD_UA_BUTTON_INPUT_1 = 0x1

Button Input 1.

NRF_CLOUD_UA_BUTTON_INPUT_2

Button Input 2.

NRF_CLOUD_UA_BUTTON_INPUT_3

Button Input 3.

NRF_CLOUD_UA_BUTTON_INPUT_4

Button Input 4.

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

• 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

• param: Parameters to be used for the connection.

Return Value

• 0: If successful. Otherwise, a (negative) error code is returned.

int nrf_cloud_user_associate(const struct nrf_cloud_ua_param *param)

Send the user association information.

If this API succeeds, the user should expect the NRF_CLOUD_EVT_USER_ASSOCIATED event. If NRF_CLOUD_EVT_ERROR is received, retry using this API.

Parameters

• param: User association information.

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

• 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

• 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

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

Public Members

u32_t len

Length of the data.

const void *ptr

Pointer to the data.

struct nrf_cloud_ua_list

#include <nrf_cloud.h>

User association types that are supported by the device.

Public Members

u8_t size

Size of the list.

nrf_cloud_ua *ptr

Supported user association types.

struct nrf_cloud_sensor_list

#include <nrf_cloud.h>

Sensors that are supported by the device.

Public Members

u8_t size

Size of the list.

nrf_cloud_sensor *ptr

Supported sensor types.

struct nrf_cloud_ua_param

#include <nrf_cloud.h>

User association parameters.

Public Members

nrf_cloud_ua type

The type of user association that is used.

struct nrf_cloud_data sequence

The user association sequence that is used.

struct nrf_cloud_connect_param

#include <nrf_cloud.h>

Connection parameters.

Public Members

const struct nrf_cloud_ua_list *ua

Supported user association types, must not be NULL.

const struct nrf_cloud_sensor_list *sensor

Supported sensor types. May be NULL.

struct nrf_cloud_sa_param

#include <nrf_cloud.h>

Parameters of attached sensors.

Public Members

nrf_cloud_sensor sensor_type

The sensor that is being attached.

struct nrf_cloud_sensor_data

#include <nrf_cloud.h>

Sensor data transmission parameters.

Public Members

nrf_cloud_sensor type

The sensor that is the source of the data.

struct nrf_cloud_data data

Sensor data to be transmitted.

u32_t tag

Unique tag to identify the sent data. Useful for matching the acknowledgment.

struct nrf_cloud_evt

#include <nrf_cloud.h>

Asynchronous events received from the module.

Public Members

nrf_cloud_evt_type type

The event that occurred.

u32_t status

Any status associated with the event.

struct nrf_cloud_ua_param ua_req

Requested UA information. Accompanies NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST event.

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.