1. Overview

This application note overviews integration of the customized Asset Tracker v2 application with nRF Cloud, and explains how to complete certificate provisioning and onboard the device to nRF Cloud.

2. Device Preparations

1. Set up the hardware platform with an LTE antenna as described in Setting Up Emcraft SOM-NRF9151 Hardware Platform.

2. Install the modem and application firmware onto the hardware platform as described in Installing SOM-NRF9151 Images.

3. Understanding nRF Cloud Integration

The Asset Tracker v2 application implements a cloud module, which establishes and maintains the connection to a supported cloud service using the 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.

The Integration layers table lists the nRF Connect SDK client libraries that are supported by the cloud wrapper API and the associated integration layers. By default, the Cloud wrapper API is configured to use the nRF Cloud library and MQTT protocol for integration with nRF Cloud.

3.1. nRF Cloud Library

The nRF Cloud library enables applications to connect to Nordic Semiconductor’s nRF Cloud. It abstracts and hides the details of the transport and the encoding scheme that is used for the payload and provides a simplified API interface for sending data to the cloud. The current implementation supports the following technologies:

• GNSS, TEMP, and other application-specific sensor data

• Cellular and Wi-Fi^® location data.

• TLS-secured MQTT, TLS-secured REST, or DTLS-secured CoAP as the communication protocol

• JSON as the data format for MQTT and REST.

• CBOR and JSON as the data format for CoAP.

3.2. Cloud Module States and Cloud Connection Sequence

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. At this step, the application calls nrf_cloud_init() to initialize the nRF Cloud library.

• 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. In this sub-state, the application calls nrf_cloud_connect() to initialize connection to the nRF Cloud endpoint.

  • SUB_STATE_CLOUD_CONNECTED - The cloud service is connected, data can now be sent. In this state, the application monitors the connection state and publishes data to MQTT topics.

• STATE_SHUTDOWN - The module has been shut down after receiving a request to do so from the util module.

3.3. nRF Cloud 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:

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.

4. Provisioning Device Certificates and Onboarding the Device to nRF Cloud

The cloud uses the certificates of the device for authentication. See Updating the nRF Cloud certificate and the Modem key management library for more information on modem credentials. The device ID is also the MQTT client ID. There are multiple configuration options for the device or client ID. See Configuration options for device ID for more information.

By default, the application uses the nRF Cloud device provisioning service and nRF Cloud Auto-onboarding, which can be performed by completing the following steps:

1. From the nRF9151 serial console, reset the board: kernel reboot cold.

2. Verify that the system has been reset, by checking that the boot-up messages appear on the nRF9151 serial console:

   ... *** Booting nRF Connect SDK v2.8.0-a1e9573f536a *** *** Using Zephyr OS v3.7.99-ef2877d1b5a7 *** ...

3. Verify that the device credentials used for nRF Cloud connection are not present in the modem non-volatile memory (default sec tag used by nRF Cloud is 16842753):

   uart:~$ at at%cmng=1,16842753 OK

4. If the device credentials are present in the in the modem non-volatile memory:

   1. Switch the modem to minimum functionality mode using at at+cfun=0 command.

   2. Remove the device credentials from the default slot:

      uart:~$ at at%cmng=3,16842753,2 OK uart:~$ at at%cmng=3,16842753,1 OK uart:~$ at at%cmng=3,16842753,0 OK

   3. Verify that the device credentials had been successfully removed:

      uart:~$ at at%cmng=1,16842753 OK

   4. Issue the nrf_provisioning uuid command to read the device UUID:

      uart:~$ nrf_provisioning uuid 50343959-3733-4c71-806b-202470cee0bf

   5. Log in to the nRF Cloud portal, select Security Services in the left sidebar and go to Claimed Devices page.

   6. Verify that the device with appropriate UUID is not present on this page. Remove the device if necessary.

   7. Go to Device Management → Devices page.

   8. Verify that the device with appropriate UUID is not present on this page. Remove the device if necessary.

5. Claim the device on the nRF Clould portal as per Technical Documentation:

   1. Issue the nrf_provisioning token command to read the device identity attestation token.

   2. Log in to the nRF Cloud portal and select Security Services in the left sidebar.

   3. Select Claimed Devices.

   4. Click the Claim Device button.

   5. In the pop-up window, copy and paste the identity attestation token into the Claim token text box.

   6. Create a new default onbording rule or select the existing “nRF Cloud Onboarding“ provisioning rule.

   7. Click Claim Device.

6. Reset the board and verify that the application connects to LTE network:

   ... *** Booting nRF Connect SDK v2.8.0-a1e9573f536a *** *** Using Zephyr OS v3.7.99-ef2877d1b5a7 *** ... [00:00:00.286,102] <inf> main: Start asset_tracker_v2 v98.98-4-release on nrf9151som (release build) ... [00:00:08.771,759] <inf> app_event_manager: MODEM_EVT_LTE_CONNECTED [00:00:08.774,383] <inf> app_event_manager: MODEM_EVT_LTE_PSM_UPDATE [00:00:08.815,704] <inf> app_event_manager: DATA_EVT_DATE_TIME_OBTAINED

7. Issue the nrf_provisioning init command to initiate device provisioning:

   uart:~$ nrf_provisioning init [00:04:02.086,029] <inf> nrf_provisioning: Checking for provisioning commands in 1s seconds [00:04:03.185,852] <inf> nrf_provisioning_http: Requesting commands [00:04:10.463,836] <inf> nrf_provisioning_http: Connected [00:04:10.464,782] <inf> nrf_provisioning_http: Processing commands ...

8. Wait until the provisioning is completed. The device should print the following messages to the serial console and reboot:

   [00:01:01.040,557] <inf> cloud_module: Provisioning done, rebooting [00:01:01.040,740] <inf> app_event_manager: CLOUD_EVT_REBOOT_REQUEST [00:01:01.041,381] <inf> app_event_manager: UTIL_EVT_SHUTDOWN_REQUEST [00:01:01.041,961] <inf> app_event_manager: UI_EVT_SHUTDOWN_READY [00:01:01.042,083] <wrn> modules_common: Module "ui" shutdown registered [00:01:01.042,144] <inf> app_event_manager: LOCATION_MODULE_EVT_SHUTDOWN_READY [00:01:01.042,388] <wrn> modules_common: Module "location" shutdown registered [00:01:01.043,060] <inf> app_event_manager: APP_EVT_SHUTDOWN_READY [00:01:01.043,212] <wrn> modules_common: Module "app" shutdown registered [00:01:01.044,036] <inf> app_event_manager: CLOUD_EVT_SHUTDOWN_READY [00:01:01.044,403] <wrn> modules_common: Module "cloud" shutdown registered [00:01:01.044,921] <inf> app_event_manager: DATA_EVT_SHUTDOWN_READY [00:01:01.045,043] <wrn> modules_common: Module "data" shutdown registered [00:01:01.045,898] <inf> app_event_manager: SENSOR_EVT_SHUTDOWN_READY [00:01:01.046,051] <wrn> modules_common: Module "sensor" shutdown registered [00:01:01.081,726] <inf> app_event_manager: MODEM_EVT_SHUTDOWN_READY [00:01:01.082,061] <wrn> modules_common: Module "modem" shutdown registered [00:01:06.082,183] <err> util_module: Rebooting!

9. Verify that the system has been reset, and the device successfully connects to nRF Cloud by checking that the following messages appear on the nRF9151 serial console:

   ... *** Booting nRF Connect SDK v2.8.0-a1e9573f536a *** *** Using Zephyr OS v3.7.99-ef2877d1b5a7 *** ... [00:00:00.286,102] <inf> main: Start asset_tracker_v2 v98.98-4-release on nrf9151som (release build) ... [00:00:12.544,982] <inf> app_event_manager: MODEM_EVT_LTE_CONNECTED [00:00:12.685,607] <inf> app_event_manager: CLOUD_EVT_CONNECTING [00:00:12.686,157] <inf> app_event_manager: MODEM_EVT_LTE_PSM_UPDATE [00:00:12.686,676] <inf> app_event_manager: DATA_EVT_DATE_TIME_OBTAINED [00:00:16.213,531] <inf> net_mqtt: Connect completed [00:00:17.874,542] <inf> app_event_manager: CLOUD_EVT_CONFIG_RECEIVED [00:00:17.882,507] <inf> app_event_manager: DATA_EVT_CONFIG_SEND [00:00:17.883,544] <inf> app_event_manager: CLOUD_EVT_DATA_SEND_QOS [00:00:19.394,226] <inf> app_event_manager: CLOUD_EVT_CONNECTED

10. Issue the nrf_provisioning uuid command to read the device UUID:

    uart:~$ nrf_provisioning uuid 50343959-3733-4c71-806b-202470cee0bf

11. Go to nRF Cloud page and verify that the device with this UUID successfully connects to nRF Cloud.