nRF9160: Cloud client

This sample connects to, and communicates with a compatible cloud service using the respective cloud backend firmware library. The sample connects via cellular network (LTE) and publishes a custom string in intervals or upon a button trigger, to the cloud service.

Overview

The Cloud client sample demonstrates how the generic Cloud API can be used to interface with multiple cloud backends. The current version of the sample supports the following libraries as cloud backends:

To swap between the supported libraries, change the option CONFIG_CLOUD_BACKEND to match the configuration string of a compatible cloud backend. The identification strings for the different cloud backends are listed in the following table:

Cloud Backend

Configuration String

nRF Connect for Cloud

“NRF_CLOUD”

AWS IoT

“AWS_IOT”

Azure IoT Hub

“AZURE_IOT_HUB”

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

nRF9160 DK

PCA10090

nrf9160dk_nrf9160

nrf9160dk_nrf9160ns

Thingy:91

PCA20035

thingy91_nrf9160

thingy91_nrf9160ns

Setup

For configuring the different cloud backends, refer to the documentation on nRF Cloud, AWS IoT, and Azure IoT Hub. Each cloud backend has specific setup steps that must be executed before it can be used.

Note

The nRF9160 DK and Thingy:91 come preprogrammed with the certificates required for a connection to nRF Connect for Cloud. No extra steps are required to use the Cloud client sample with nRF Connect for Cloud.

Configurations

The configurations used in the sample are listed below. They can be added to cloud_client/prj.conf.

CONFIG_CLOUD_BACKEND

(string) This option selects the cloud backend to be used.

Possible values are “NRF_CLOUD”, “AWS_IOT”, “AZURE_IOT_HUB”.

CONFIG_CLOUD_MESSAGE

(string) This option sets the custom message published periodically to cloud.

None

CONFIG_CLOUD_MESSAGE_PUBLICATION_INTERVAL

(int) This option sets how often the custom message should be published to cloud, in seconds.

None

CONFIG_CLOUD_CONNECTION_RETRY_TIMEOUT_SECONDS

(int) This option sets the number of seconds between each cloud connection retry.

None

CONFIG_CLOUD_PUBLICATION_BUTTON_PRESS

(bool) This option triggers publication to cloud upon a button press.

None

CONFIG_CLOUD_PUBLICATION_SEQUENTIAL

(bool) This option sets sequential publication to cloud set by the CONFIG_MESSAGE_PUBLICATION_INTERVAL option.

None

CONFIG_POWER_SAVING_MODE_ENABLE

(bool) This option requests PSM from cellular network.

None

Note

To output data in the terminal window located in the nRF Connect for Cloud web interface, the data format must be in JSON format.

Note

The sample sets the option CONFIG_MQTT_KEEPALIVE to the maximum allowed value that is specified by the configured cloud backend. This is to limit the IP traffic between the device and the message broker of the cloud provider for supporting a low power sample. However, note that in certain LTE networks, the NAT timeout can be considerably lower than the maximum allowed MQTT keepalive. So as a recommendation, and to prevent the likelihood of getting disconnected unexpectedly, the option CONFIG_MQTT_KEEPALIVE must be set to the lowest of the aforementioned timeout limits (Maximum allowed MQTT keepalive and NAT timeout).

Functionality and Supported Technologies

The communication protocol supported by the sample is dependent on the cloud backend that is used.

Functions

The sample uses the following functions:

Cloud events used in the sample

The sample uses the following cloud events:

Note

Not all functionalities present in the generic cloud API are used by the different cloud backends.

Building and running

This sample can be found under samples/nrf9160/cloud_client in the nRF Connect SDK folder structure.

See Building and programming a sample application for information about how to build and program the application.

The sample is configured to compile and run as a non-secure application on nRF91’s Cortex-M33. Therefore, it automatically includes the Secure Partition Manager that prepares the required peripherals to be available for the application.

You can also configure it to use TF-M instead of Secure Partition Manager.

Testing

Before testing, ensure that your device is already set up with your nRF Connect for Cloud account. After programming the sample to your device, test it by performing the following steps:

  1. Open a web browser and navigate to the correct device in nRF Connect for Cloud.

  2. Connect the USB cable and power on or reset your device.

  3. Open a terminal emulator and observe that the sample has started. Wait until the “I: CLOUD_EVT_READY” status appears in the terminal.

      I: Cloud client has started
  I: Connecting to LTE network, this may take several minutes...
  +CEREG: 2,"7725","0138E000",7,0,0,"11100000","11100000"
  +CSCON: 1
  +CEREG: 1,"7725","0138E000",7,,,"00000010","00000110"
  I: Network registration status: Connected - home network
  I: Connected to LTE network
  I: Connecting to cloud
  I: CLOUD_EVT_CONNECTED
  I: CLOUD_EVT_DATA_RECEIVED
  I: Data received from cloud: {"desired":{"pairing":{"state":"paired","topics":{"d2c":..
  I: CLOUD_EVT_PAIR_DONE
  I: CLOUD_EVT_READY

The device is now connected to nRF Connect for Cloud.

  4. Press button 1 on the device and observe that the following output is displayed in the terminal:

    I: Publishing message: {"state":{"reported":{"message":"Hello Internet of Things!"}}}
+CSCON: 1

  5. Observe that the following status appears in the terminal pane for the connected device in nRF Connect for Cloud:

    "Received": {
   "state": {
      "reported": {
         "message": "Hello Internet of Things!"
      }
   }
}

Dependencies

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

It uses the following sdk-nrfxlib library:

In addition, it uses the following sample: