Cloud wrapper API

Integration layers
- LwM2M
Data addressing
Dependencies
API documentation

The cloud wrapper API is a generic API used for controlling the connection to a supported nRF Connect SDK client library through Integration layers. It exposes generic functions such as send, connect, and disconnect, hiding the functionality that is specific to a single client library implementation.

Integration layers 

The Integration layers table lists the nRF Connect SDK client libraries that are supported by the cloud wrapper API and the associated integration layers. Each integration layer interacts with a specific client library and contains the code required to properly set up and maintain a connection to the designated cloud service. Based on the Kconfig options listed in the table, the corresponding combination of integration layer and the client library is linked in. For example, if CONFIG_AWS_IOT is enabled, CMake links in the asset_tracker_v2/src/cloud/aws_iot_integration.c file that integrates the AWS IoT library. This takes place in the asset_tracker_v2/src/cloud/CMakeLists.txt file.

Note

The various integration layers all share a common header file asset_tracker_v2/src/cloud/cloud_wrapper.h that exposes generic functions to send and receive data from the integration layer.

Client library	Integration layer	Kconfig option
AWS IoT	`asset_tracker_v2/src/cloud/aws_iot_integration.c`	`CONFIG_AWS_IOT`
Azure IoT Hub	`asset_tracker_v2/src/cloud/azure_iot_hub_integration.c`	`CONFIG_AZURE_IOT_HUB`
nRF Cloud	`asset_tracker_v2/src/cloud/nrf_cloud_integration.c`	`CONFIG_NRF_CLOUD_MQTT`
Lightweight M2M (LWM2M)	`asset_tracker_v2/src/cloud/lwm2m_integration.c`	`CONFIG_LWM2M_INTEGRATION`

LwM2M 

The application integrates LwM2M through the following APIs:

LwM2M API from Zephyr
LwM2M client utils API, and LwM2M location assistance API from nRF Connect SDK

Note

The LwM2M integration does not have support for sending of batched data.

Bootstrapping and credential handling

When the option CONFIG_LWM2M_INTEGRATION_PSK is enabled, the modem is provisioned at run time after boot with a Pre-Shared Key (PSK) set by CONFIG_LWM2M_INTEGRATION_PSK.

If CONFIG_LWM2M_RD_CLIENT_SUPPORT_BOOTSTRAP is enabled, the PSK is provisioned to a security tag dedicated to the bootstrap server connection. During bootstrapping, the application receives a separate newly generated key from the bootstrap server that is provisioned to a security tag dedicated to the management server connection. This PSK is used in the management server that the application connects to, after bootstrapping is completed.

If CONFIG_LWM2M_RD_CLIENT_SUPPORT_BOOTSTRAP is disabled, the PSK that is provisioned after boot is provisioned to the security tag dedicated to the management server and the application connects to the management server directly.

In a production scenario, it is recommended to generate and preprovision the bootstrap server PSK prior to running the application. You can do this by disabling the CONFIG_LWM2M_INTEGRATION_PROVISION_CREDENTIALS option and following the steps described in Preparing for production.

The security tags that are used for the management and bootstrap server connections are set by the CONFIG_LWM2M_CLIENT_UTILS_BOOTSTRAP_TLS_TAG and CONFIG_LWM2M_CLIENT_UTILS_SERVER_TLS_TAG options, respectively. When preprovisioning credentials, make sure the correct TLS security tag is used.

Note

Bootstrapping enables the application to rotate security credentials after deployment, which is recommended from a security standpoint.

Queue mode

Due to short NAT timeouts (approximately 60 seconds) and firewalls in UDP delivery networks, the application enables LwM2M Queue mode. In LwM2M Queue mode, the Zephyr LwM2M engine closes and opens a new socket for every transmission to cloud. This means that a new DLTS handshake is performed for every update to cloud. The overhead associated with DTLS handshakes is mitigated by enabling TLS session resumption. This enables the modem to restore the previously negotiated TLS session with the server and it does not require a full TLS handshake.

The time that the LwM2M engine polls for data after the last correspondence with cloud is set by the CONFIG_LWM2M_QUEUE_MODE_UPTIME Kconfig option. Increasing this value beyond 60 seconds does not cause any change due to the NAT and firewall issue mentioned previously. But it can be increased if the LTE network allows it. If increasing the CONFIG_LWM2M_QUEUE_MODE_UPTIME option, make sure that the LTE PSM active timeout set by CONFIG_LTE_PSM_REQ_RAT is also increased to a value greater than the Queue mode uptime. This ensures that the modem goes into LTE PSM only after the LwM2M engine has finished polling for incoming data.

Note

The CONFIG_LTE_PSM_REQ_RAT option only increases the value that is requested by the modem from the network, not what is actually given by the network.

Send operation

The application exclusively uses the LwM2M v1.1 send operation to send data to the server. This operation enables the application to explicitly send data to the server, whenever it wants. The user can set up the server to enable periodic notifications for objects and resources, but there is no guarantee that the resources will change value between notifications using that approach. The application adheres to its Real-time configurations when it samples and sends data to cloud, which is the recommended approach to reconfiguring the application. The Real-time configurations can be manipulated using an application specific configuration object accessible from cloud. In order to use this object, some additional steps are required that are documented in Uploading XML definition for configuration object.

Data addressing 

Each integration layer routes data to specific endpoints based on the content of the data and the cloud wrapper API call. The Data routing tables list the endpoints that are used in each cloud service implementation.

AWS IoT topics 

The following tables list the various topics used in the AWS IoT implementation.

Device-to-cloud (D2C)

Data	Topic
A-GPS requests	`<imei>/agps/get`
P-GPS requests	`<imei>/pgps/get`
Neighbor cell measurements	`<imei>/ncellmeas`
Button presses	`<imei>/messages`
Sensor/device data	`$aws/things/<imei>/shadow/update`
Device configuration	`$aws/things/<imei>/shadow/update`
Buffered sensor/device data	`<imei>/batch`

Cloud-to-device (C2D)

Data	Topic
A-GPS response	`<imei>/agps`
P-GPS response	`<imei>/pgps`
Device configuration updates	`$aws/things/<imei>/shadow/delta`
	`$aws/things/<imei>/shadow/get/accepted`
	`$aws/things/<imei>/shadow/get/accepted/desired/cfg`

Azure IoT Hub topics 

For simplicity, the following table omits certain meta values present in topics and property bags used in Azure IoT Hub. For more information on MQTT topics and property bags in Azure IoT Hub, refer to the Azure IoT Hub MQTT protocol support documentation.

Device-to-cloud (D2C)

Data	Topic	Property bag
A-GPS requests	`devices/<imei>/messages/events/`	`agps=get`
P-GPS requests	`devices/<imei>/messages/events/`	`pgps=get`
Neighbor cell measurements	`devices/<imei>/messages/events/`	`ncellmeas`
Button presses	`devices/<imei>/messages/events/`	NA
Sensor/device data	`$iothub/twin/PATCH/properties/reported/`	NA
Device configuration	`$iothub/twin/PATCH/properties/reported/`	NA
Buffered sensor/device data	`devices/<imei>/messages/events/`	`batch`

Cloud-to-device (C2D)

Data	Topic	Property bag
A-GPS response	`devices/<imei>/messages/devicebound/`	`agps=result`
P-GPS response	`devices/<imei>/messages/devicebound/`	`pgps=result`
Device configuration updates	`$iothub/twin/res/<code>/`	NA

nRF Cloud topics 

For more information on topics used in the nRF Cloud connection, refer to the nRF Cloud MQTT API documentation.

Device-to-cloud (D2C)

Data	AWS IoT topic
A-GPS requests	`<topic_prefix>/<imei>/d2c`
P-GPS requests	`<topic_prefix>/<imei>/d2c`
Neighbor cell measurements	`<topic_prefix>/<imei>/d2c`
Wi-Fi access points	`<topic_prefix>/<imei>/d2c`
Button presses	`<topic_prefix>/<imei>/d2c`
Sensor/device data	`<topic_prefix>/<imei>/d2c`
Device configuration	`$aws/things/<imei>/shadow/update`
Buffered sensor/device data	`<topic_prefix>/<imei>/d2c/batch`

Cloud-to-device (C2D)

Data	AWS IoT topic
A-GPS response	`<topic_prefix>/<imei>/c2d`
P-GPS response	`<topic_prefix>/<imei>/c2d`
Device configuration updates	`$aws/things/<imei>/shadow/delta`
	`$aws/things/<imei>/shadow/get/accepted`
	`$<imei>/shadow/get/accepted/desired/cfg`

LwM2M objects 

For more information on objects used in LwM2M, refer to the OMA LwM2M Object and Resource Registry.

Objects	Object ID
LwM2M Server	1
Device	3
Connectivity Monitoring	4
Firmware Update	5
Location	6
Temperature	3303
Humidity	3304
Pressure	3323
Push Button	3347
ECID-Signal Measurement Information (Neighbor cell measurements)	10256
Ground Fix (Cellular and Wi-Fi location)	33626
GNSS Assistance (A-GPS / P-GPS)	33625
Configuration (see Uploading XML definition for configuration object)	50009

Uploading XML definition for configuration object

The application defines a proprietary Configuration object that the LwM2M server needs to be made aware of to enable the manipulation of its resources using the web console. If you are using Coiote Device Management, complete the following steps to add the LwM2M object definition:

Open Coiote Device Management server.
Click the device inventory icon (second icon from the top) in the left pane in the UI.

Coiote Device Management Server UI
Locate your Device ID and click on Management.
Click Objects in the left vertical tabs section.
Click Add new LwM2M object definition.
Upload the file nrf/applications/asset_tracker_v2/src/cloud/lwm2m_integration/config_object_descript.xml or copy and paste the contents of the file to the textbox.
Click Import, Refresh data model and Yes, execute task now.

After completing the previous steps, the configuration object is detected in the console and you can set the different resources in the object. These resources configure the real-time behavior of the application and maps directly to the configurations listed in Real-time configurations.

Dependencies 

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

API documentation 

Header file: asset_tracker_v2/src/cloud/cloud_wrapper.h

Source files: asset_tracker_v2/src/cloud/nrf_cloud_integration.c asset_tracker_v2/src/cloud/aws_iot_integration.c asset_tracker_v2/src/cloud/azure_iot_hub_integration.c asset_tracker_v2/src/cloud/lwm2m_integration.c

group cloud_wrapper

A Library that exposes generic functionality of cloud integration layers.

Typedefs

typedef void (*cloud_wrap_evt_handler_t)(const struct cloud_wrap_event *evt)

Cloud wrapper library asynchronous event handler.

Param evt: [in] Pointer to the event structure.

Enums

enum cloud_wrap_event_type

Event types notified by the cloud wrapper API.

Values:

enumerator CLOUD_WRAP_EVT_CONNECTING: Cloud integration layer is connecting.

enumerator CLOUD_WRAP_EVT_CONNECTED: Cloud integration layer is connected.

enumerator CLOUD_WRAP_EVT_DISCONNECTED: Cloud integration layer is disconnected.

enumerator CLOUD_WRAP_EVT_DATA_RECEIVED: Data received from cloud integration layer. Payload is of type cloud_wrap_event_data.

enumerator CLOUD_WRAP_EVT_USER_ASSOCIATION_REQUEST: User association request received from cloud.

enumerator CLOUD_WRAP_EVT_USER_ASSOCIATED: User association completed.

enumerator CLOUD_WRAP_EVT_DATA_ACK: Event received when data has been acknowledged by cloud.

enumerator CLOUD_WRAP_EVT_PING_ACK: Event received when a ping response has been received.

enumerator CLOUD_WRAP_EVT_AGPS_DATA_RECEIVED: A-GPS data received from the cloud integration layer. Payload is of type cloud_wrap_event_data.

enumerator CLOUD_WRAP_EVT_PGPS_DATA_RECEIVED: P-GPS data received from the cloud integration layer. Payload is of type cloud_wrap_event_data.

enumerator CLOUD_WRAP_EVT_REBOOT_REQUEST: Reboot request received from cloud.

enumerator CLOUD_WRAP_EVT_LTE_CONNECT_REQUEST: Request to connect to LTE.

enumerator CLOUD_WRAP_EVT_LTE_DISCONNECT_REQUEST: Request to disconnect from LTE.

enumerator CLOUD_WRAP_EVT_FOTA_DONE: Cloud integration layer has successfully performed a FOTA update. Device should now be rebooted.

enumerator CLOUD_WRAP_EVT_FOTA_START: The cloud integration layer has started a FOTA update.

enumerator CLOUD_WRAP_EVT_FOTA_ERASE_PENDING: An image erase is pending.

enumerator CLOUD_WRAP_EVT_FOTA_ERASE_DONE: Image erase done.

enumerator CLOUD_WRAP_EVT_FOTA_ERROR: An error occurred during FOTA.

enumerator CLOUD_WRAP_EVT_ERROR: An irrecoverable error has occurred in the integration layer. Error details are attached in the event structure.

Functions

int cloud_wrap_init(cloud_wrap_evt_handler_t event_handler)

Setup and initialize the configured cloud integration layer.

Returns: 0 on success, or a negative error code on failure.

int cloud_wrap_connect(void)

Connect to cloud.

Returns: 0 on success, or a negative error code on failure.

int cloud_wrap_disconnect(void)

Disconnect from cloud.

Returns: 0 on success, or a negative error code on failure.

int cloud_wrap_state_get(bool ack, uint32_t id)

Request device state from cloud. The device state contains the device configuration.

Parameters

ack – [in] Flag signifying if the message should be acknowledged or not.
id – [in] Message ID.

Returns

0 on success, or a negative error code on failure.

int cloud_wrap_state_send(char *buf, size_t len, bool ack, uint32_t id)

Send device state data to cloud.

Parameters

buf – [in] Pointer to buffer containing data to be sent.
len – [in] Length of buffer.
ack – [in] Flag signifying if the message should be acknowledged or not.
id – [in] Message ID.

Returns

0 on success, or a negative error code on failure.

int cloud_wrap_data_send(char *buf, size_t len, bool ack, uint32_t id, const struct lwm2m_obj_path path_list[])

Send data to cloud.

Parameters

buf – [in] Pointer to buffer containing data to be sent.
len – [in] Length of buffer.
ack – [in] Flag signifying if the message should be acknowledged or not.
id – [in] Message ID.
path_list – [in] List of LwM2M objects to be sent.

Returns

0 on success, or a negative error code on failure.

int cloud_wrap_batch_send(char *buf, size_t len, bool ack, uint32_t id)

Send batched data to cloud.

Parameters

buf – [in] Pointer to buffer containing data to be sent.
len – [in] Length of buffer.
ack – [in] Flag signifying if the message should be acknowledged or not.
id – [in] Message ID.

Returns

0 on success, or a negative error code on failure.

int cloud_wrap_ui_send(char *buf, size_t len, bool ack, uint32_t id, const struct lwm2m_obj_path path_list[])

Send UI data to cloud.

Parameters

buf – [in] Pointer to buffer containing data to be sent.
len – [in] Length of buffer.
ack – [in] Flag signifying if the message should be acknowledged or not.
id – [in] Message ID.
path_list – [in] Pointer to list of LwM2M objects to be sent.

Returns

0 on success, or a negative error code on failure.

int cloud_wrap_neighbor_cells_send(char *buf, size_t len, bool ack, uint32_t id)

Send neighbor cell data to cloud.

Note

LwM2M builds: This function does not require passing in a list of objects, unlike other functions in this API. The underlying LwM2M API called when calling this function, keeps its own reference of the objects that needs to be updated.

Parameters

buf – [in] Pointer to buffer containing data to be sent.
len – [in] Length of buffer.
ack – [in] Flag signifying if the message should be acknowledged or not.
id – [in] Message ID.

Returns

0 on success, or a negative error code on failure.

int cloud_wrap_agps_request_send(char *buf, size_t len, bool ack, uint32_t id)

Send A-GPS request to cloud.

Note

LwM2M builds: This function does not require passing in a list of objects, unlike other functions in this API. The underlying LwM2M API called when calling this function, keeps its own reference of the objects that needs to be updated.

Parameters

buf – [in] Pointer to buffer containing data to be sent.
len – [in] Length of buffer.
ack – [in] Flag signifying if the message should be acknowledged or not.
id – [in] Message ID.

Returns

0 on success, or a negative error code on failure.

int cloud_wrap_pgps_request_send(char *buf, size_t len, bool ack, uint32_t id)

Send P-GPS request to cloud.

Note

LwM2M builds: This function does not require passing in a list of objects, unlike other functions in this API. The underlying LwM2M API called when calling this function, keeps its own reference of the objects that needs to be updated.

Parameters

buf – [in] Pointer to buffer containing data to be sent.
len – [in] Length of buffer.
ack – [in] Flag signifying if the message should be acknowledged or not.
id – [in] Message ID.

Returns

0 on success, or a negative error code on failure.

int cloud_wrap_memfault_data_send(char *buf, size_t len, bool ack, uint32_t id)

Send Memfault data to cloud.

Parameters

buf – [in] Pointer to buffer containing data to be sent.
len – [in] Length of buffer.
ack – [in] Flag signifying if the message should be acknowledged or not.
id – [in] Message ID.

Returns

0 on success, or a negative error code on failure.

struct cloud_wrap_event_data

#include <cloud_wrapper.h>

Structure used to reference application data that is sent and received from the cloud wrapper library.

Public Members

char *buf: Pointer to data.

size_t len: Length of data.

struct cloud_wrap_event

#include <cloud_wrapper.h>

Cloud wrapper API event.

Public Members

struct cloud_wrap_event_data data: Structured that contains data received from the cloud integration layer.

int err: Error code signifying the cause of error.