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.


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





nRF Cloud A-GNSS

nRF Cloud P-GPS

Azure IoT Hub





nRF Cloud A-GNSS

nRF Cloud P-GPS

nRF Cloud





nRF Cloud A-GNSS

nRF Cloud P-GPS

LwM2M v1.1 compliant service (Coiote Device Management, Leshan homepage)




UDP protocol


nRF Cloud A-GNSS

nRF Cloud A-GNSS 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-GNSS and P-GPS data using the nRF Cloud A-GNSS and nRF Cloud P-GPS libraries. This enables the cloud service to fetch A-GNSS and P-GPS data directly from nRF Cloud and relay this data to an nRF91 Series 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-GNSS and P-GPS data are received directly from the service, and not by proxy. For more information, see nRF Cloud Location Services.


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 for the nRF91x1 DKs and for the nRF9160 DK version 0.14.0 and higher. To enable full modem FOTA, add the -DEXTRA_CONF_FILE=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@1.0.1/nrf9160/ns 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 }, { 1024 },
   { 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 nRF91 Series 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.


There are no mandatory configuration settings for the nRF Cloud library. The nRF91 Series DKs and the Thingy:91 come with factory-provisioned 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:

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

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 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:

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


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

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.


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

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.


enum cloud_module_event_type

Event types submitted by the cloud module.



Cloud service is connected.


Cloud service is disconnected.


Connecting to a cloud service.


Connection has timed out.


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.


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.


User association request received from cloud.


User association completed.


Reboot requested from cloud.


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


Cloud location data has been received from cloud. The payload associated with this event is of type location_data.


Cloud location response has been received but location could not be resolved.


Cloud location resolution is unknown.


An empty device configuration has been received from cloud.


A FOTA update has started.


FOTA has been performed, a reboot of the application is needed.


An error occurred during a FOTA update.


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.


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

New configuration received from the cloud service.

struct cloud_module_data_ack ack

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

struct qos_data message

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.