Cloud module

Features
Configuration options
- Mandatory configurations
Module hierarchy
Module states
Module events
Dependencies
API documentation

The cloud module establishes and maintains the connection to a supported cloud service. Use the Cloud wrapper API to integrate and handle the client libraries present in the nRF Connect SDK.

Features 

This section documents the various features implemented by the module.

The cloud module supports communication with multiple cloud services, one service at the time. The Supported cloud services table lists the cloud services supported by the module together with protocols and technologies used with them. See Cloud wrapper API for more information on how each client library is integrated in the module.

Cloud service	Protocols and technologies
AWS IoT Core	MQTT
	TCP
	TLS
	FOTA
	nRF Cloud A-GPS
	nRF Cloud P-GPS
Azure IoT Hub	MQTT
	TCP
	TLS
	FOTA
	nRF Cloud A-GPS
	nRF Cloud P-GPS
nRF Cloud	MQTT
	TCP
	TLS
	FOTA
	nRF Cloud A-GPS
	nRF Cloud P-GPS

nRF Cloud A-GPS and P-GPS 

When the cloud module is configured to communicate with AWS IoT Core or Azure IoT Hub, it supports processing of received A-GPS and P-GPS data using the nRF Cloud A-GPS and nRF Cloud P-GPS libraries. This enables the cloud to fetch A-GPS and P-GPS data from nRF Cloud using REST calls and relay the data to the nRF9160 SiP using the pre-established connection to AWS IoT Core or Azure IoT Hub. Maintaining multiple cloud connections at the same time is not feasible because of high data traffic and energy consumption. Establishing a secure connection typically consists of multiple kB of exchanged data with the cloud service. When configuring the application to communicate with nRF Cloud, A-GPS and P-GPS data are received directly from the service, in contrast to the AWS IoT and Azure IoT Hub implementations.

FOTA 

The client libraries supported by the cloud wrapper API all implement their own version of FOTA. This enables the cloud to issue FOTA updates and update the application and modem firmware while the device is in field. For additional documentation on the various FOTA implementations, refer to the respective client library documentation linked to in Integration layers.

Connection awareness 

The cloud module implements connection awareness by maintaing an internal state that is based on events from the modem module and callbacks from the Cloud wrapper API.

If the module is disconnected, it will try to reconnect while the LTE connection is still valid. To adjust the number of reconnection attempts, set the CONFIG_CLOUD_CONNECT_RETRIES option. Reconnection is implemented with a binary backoff based on the following lookup table:

static struct cloud_backoff_delay_lookup backoff_delay[] = {
   { 32 }, { 64 }, { 128 }, { 256 }, { 512 },
   { 2048 }, { 4096 }, { 8192 }, { 16384 }, { 32768 },
   { 65536 }, { 131072 }, { 262144 }, { 524288 }, { 1048576 }
};

If the module reaches the maximum number of reconnection attempts, the application receives an error event notification of type CLOUD_EVT_ERROR, causing the application to perform a reboot.

Configuration options 

CONFIG_CLOUD_THREAD_STACK_SIZE - Cloud module thread stack size: This option increases the cloud module’s internal thread stack size.

CONFIG_CLOUD_CLIENT_ID_USE_CUSTOM - Configuration for enabling the use of a custom cloud client ID: This option is used to enable the use of a custom client ID for connection to the respective cloud service. By default, the cloud module uses the IMEI of the nRF9160-based device as the client ID.

CONFIG_CLOUD_CLIENT_ID - Configuration for providing a custom cloud client ID: This option sets the custom client ID for the respective cloud service. For setting a custom client ID, you need to set CONFIG_CLOUD_CLIENT_ID_USE_CUSTOM to y.

CONFIG_CLOUD_CONNECT_RETRIES - Configuration that sets the number of cloud reconnection attempts: This option sets the number of times that a connection will be re-attempted upon a disconnect from the cloud service.

Mandatory configurations 

To be able to use a supported cloud client library, you need to set a few mandatory Kconfig options. These typically include the cloud service hostname and the security tag associated with the certificates used to establish a connection. Before running the application, you need to provision the certificates to the modem using the same security tag. For more information on how to set up a connection and provision certificates to the modem, see the documentation for the respective client library in Integration layers.

Note

There are no mandatory configuration settings for the nRF Cloud library. The nRF9160 DK and Thingy91 come preprovisioned with certificates required to establish a connection to nRF Cloud. The default configuration of the nRF Cloud library uses the security tag that the nRF Cloud certificates are stored to.

Configurations for AWS IoT library

To enable communication with AWS IoT, set the following options in the overlay-aws.conf file:

Configurations for Azure IoT Hub library

To enable communication with Azure IoT Hub, set the following options in the overlay-azure.conf file:

Module hierarchy 

The following diagram illustrates the relationship between the cloud module, integration layers, and client libraries.

Cloud module hierarchy

Module states 

The cloud module has an internal state machine with the following states:

STATE_LTE_INIT - The initial state of the module in which it awaits the modem to be initialized.
STATE_LTE_DISCONNECTED - The module has performed all required initialization and waits for the modem to connect to LTE.
STATE_LTE_CONNECTED - The modem is connected to LTE and the internal cloud connection routine starts. This state has two sub-states:
- SUB_STATE_CLOUD_DISCONNECTED - The cloud service is disconnected.
- SUB_STATE_CLOUD_CONNECTED - The cloud service is connected, data can now be sent.
STATE_SHUTDOWN - The module has been shut down after receiving a request to do so from the util module.

State transitions take place based on events from other modules, such as the app module, data module, and util module.

group cloud_module_event

Cloud module event.

Enums

enum cloud_module_event_type

Event types submitted by the cloud module.

Values:

enumerator CLOUD_EVT_CONNECTED: Cloud service is connected.

enumerator CLOUD_EVT_DISCONNECTED: Cloud service is disconnected.

enumerator CLOUD_EVT_CONNECTING: Connecting to a cloud service.

enumerator CLOUD_EVT_CONNECTION_TIMEOUT: Connection has timed out.

enumerator CLOUD_EVT_USER_ASSOCIATION_REQUEST: User association request received from cloud.

enumerator CLOUD_EVT_USER_ASSOCIATED: User association completed.

enumerator CLOUD_EVT_CONFIG_RECEIVED: A new device configuration has been received from cloud. The payload associated with this event is of type cloud_data_cfg (config).

enumerator CLOUD_EVT_CONFIG_EMPTY: An empty device configuration has been received from cloud.

enumerator CLOUD_EVT_FOTA_START: A FOTA update has started.

enumerator CLOUD_EVT_FOTA_DONE: FOTA has been performed, a reboot of the application is needed.

enumerator CLOUD_EVT_FOTA_ERROR: An error occurred during a FOTA update.

enumerator CLOUD_EVT_DATA_ACK: Sending of data to cloud has been attempted. The payload associated with this event is of type cloud_module_data_ack (ack).

enumerator CLOUD_EVT_SHUTDOWN_READY: The cloud module has performed all procedures to prepare for a shutdown of the system. The event carries the ID (id) of the module.

enumerator CLOUD_EVT_ERROR: An irrecoverable error has occurred in the cloud module. Error details are attached in the event structure.

struct cloud_module_data_ack

#include <cloud_module_event.h>

Structure used to acknowledge messages sent to the cloud module.

Public Members

void *ptr: Pointer to data that was attempted to be sent.

size_t len: Length of data that was attempted to be sent.

struct cloud_module_event