Cloud wrapper API

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:

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

  1. Open Coiote Device Management server.

  2. Click the device inventory icon (second icon from the top) in the left pane in the UI.

    Coiote Device Management Server UI

    Coiote Device Management Server UI

  3. Locate your Device ID and click on Management.

  4. Click Objects in the left vertical tabs section.

  5. Click Add new LwM2M object definition.

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

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

A-GNSS 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_CLOUD_LOCATION_RESULT_RECEIVED

Data received from 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_cloud_location_send(char *buf, size_t len, bool ack, uint32_t id)

Send cloud location 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.

bool cloud_wrap_cloud_location_response_wait(void)

Indicates whether cloud implementation can and is configured to return the resolved location back to the device.

Returns:

Indicates whether resolved location is sent back to the device.

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

Send A-GNSS 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.