Cloud module

The cloud module establishes and maintains the connection to a supported cloud service. It uses 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.

Cloud services

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
	TLS
	TCP
	FOTA
	nRF Cloud A-GPS
	nRF Cloud P-GPS
Azure IoT Hub	MQTT
	TLS
	TCP
	FOTA
	nRF Cloud A-GPS
	nRF Cloud P-GPS
nRF Cloud	MQTT
	TLS
	TCP
	FOTA
	nRF Cloud A-GPS
	nRF Cloud P-GPS
LwM2M v1.1 compliant service (Coiote Device Management, Leshan homepage)	LwM2M
	CoAP
	DTLS
	UDP protocol
	FOTA
	nRF Cloud A-GPS

nRF Cloud A-GPS and P-GPS

When the cloud module is configured to communicate with AWS IoT Core, Azure IoT Hub, or an LwM2M server, 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 service to fetch A-GPS and P-GPS data directly from nRF Cloud using REST calls and relay this data to the nRF9160 SiP using the pre-established cloud connection. By reusing the pre-established connection, the application saves overhead related to maintaining multiple connections at the same time. When configuring the application to communicate with nRF Cloud, A-GPS and P-GPS data are received directly from the service, and not by proxy. For more information, see nRF Cloud Location Services.

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.

Full modem FOTA updates are only supported by nRF Cloud. This application implements full modem FOTA only for the nRF9160 development kit version 0.14.0 and higher. To enable full modem FOTA, add the -DOVERLAY_CONFIG=overlay-full_modem_fota.conf parameter to your build command.

Also, specify your development kit version by appending it to the board name. For example, if your development kit version is 1.0.1, use the board name nrf9160dk_nrf9160_ns@1_0_1 in your build command.

Connection awareness

The cloud module implements connection awareness by maintaining 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:

• CONFIG_AWS_IOT_BROKER_HOST_NAME

• CONFIG_AWS_IOT_SEC_TAG

Configurations for Azure IoT Hub library

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

• CONFIG_AZURE_IOT_HUB_DPS_ID_SCOPE

• CONFIG_MQTT_HELPER_SEC_TAG

• CONFIG_AZURE_FOTA_SEC_TAG

If not using the default DPS (Device Provisioning Service) host, ensure that the hostname option is correctly set using the following Kconfig option:

• CONFIG_AZURE_IOT_HUB_DPS_HOSTNAME

Configurations for LwM2M integration layer

When building for LwM2M, the cloud module’s default configuration is to communicate with AVSystem’s Coiote Device Management, with a runtime provisioned Pre-shared key (PSK) set by the CONFIG_LWM2M_INTEGRATION_PSK option. This enables the device to work with Coiote Device Management without provisioning the PSK to the modem before running the application. To allow the device to communicate with other LwM2M servers, modify the default configuration by changing the following Kconfig options:

• CONFIG_LWM2M_CLIENT_UTILS_SERVER

• CONFIG_LWM2M_RD_CLIENT_SUPPORT_BOOTSTRAP

• CONFIG_LWM2M_INTEGRATION_ENDPOINT_PREFIX

• CONFIG_LWM2M_INTEGRATION_PSK

• CONFIG_LWM2M_INTEGRATION_PROVISION_CREDENTIALS

See server setup for information on how the Coiote Device Management server can be configured to communicate with the application.

Important

In production, it is not recommended to use the default PSK that is automatically provisioned by the application. If possible, bootstrapping should be enabled to periodically change the PSK used in the connection. The PSK should also be provisioned to the modem before running the application. Disable the CONFIG_LWM2M_INTEGRATION_PROVISION_CREDENTIALS option and provision the PSK to a sec tag set by CONFIG_LWM2M_CLIENT_UTILS_SERVER_TLS_TAG or CONFIG_LWM2M_CLIENT_UTILS_BOOTSTRAP_TLS_TAG.

In addition to the steps documented in the aforementioned section, you must also enable manipulation of the application’s real-time configurations through the Coiote Device Management console. This is documented in Uploading XML definition for configuration object.

Module hierarchy

The following diagram illustrates the relationship between the cloud module, integration layers, and the 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.

Module events

The asset_tracker_v2/src/events/cloud_module_event.h header file contains a list of various events sent by the module.

Dependencies

This module uses the following nRF Connect SDK libraries and drivers:

• Cloud wrapper API

• nRF Cloud A-GPS

• nRF Cloud P-GPS

API documentation

Header file: asset_tracker_v2/src/events/cloud_module_event.h

Source files: asset_tracker_v2/src/events/cloud_module_event.c asset_tracker_v2/src/modules/cloud_module.c

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_LTE_CONNECT

Connect to LTE. This event is sent out when the modem should connect to LTE (put into normal mode) post provisioning of server credentials.

Only used when building for LwM2M.

enumerator CLOUD_EVT_LTE_DISCONNECT

Disconnect from LTE. This event is sent out when the modem should be put into offline mode prior to provisioning of server credentials.

Only used when building for LwM2M.

enumerator CLOUD_EVT_USER_ASSOCIATION_REQUEST

User association request received from cloud.

enumerator CLOUD_EVT_USER_ASSOCIATED

User association completed.

enumerator CLOUD_EVT_REBOOT_REQUEST

Reboot requested from cloud.

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_SEND_QOS

Sending data to cloud using QoS library. The payload associated with this event is of type qos_data (message).

This event is only meant for the cloud module and is used to filter QoS data through the module’s internal message queue. This event is consumed by the cloud module as soon as it has been processed.

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

#include <cloud_module_event.h>

Cloud module event.

Public Members

struct app_event_header header

Cloud module application event header.

enum cloud_module_event_type type

Cloud module event type.

struct cloud_data_cfg config

Variable that contains a new configuration received from the cloud service.

struct cloud_module_data_ack ack

Variable that contains data that was attempted to be sent. Could be used to free allocated data post transmission.

struct qos_data message

Variable that contains the message that should be sent to cloud.

uint32_t id

Module ID, used when acknowledging shutdown requests.

int err

Code signifying the cause of error.