Cloud wrapper API

Integration layers
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 integration layer + client library combination 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`

Data addressing 

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

AWS IoT topics 

Device-to-Cloud

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

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 metavalues 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

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

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

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`
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

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`

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

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_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_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(void)

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

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

int cloud_wrap_state_send(char *buf, size_t len)

Send device state data to cloud.

Parameters

buf – [in] Pointer to buffer containing data to be sent.
len – [in] Length of buffer.

Returns