nRF9160: Cloud client¶

Overview
Requirements
Setup
Configurations
Functionality and Supported Technologies
- Functions
- Cloud events used in the sample
Building and running
- Testing
Dependencies

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 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 Cloud. No extra steps are required to use the Cloud client sample with nRF 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 Cloud web interface, the data format must be in JSON format.

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_get_binding() : Binds to a desired cloud backend using an identifiable string.
cloud_init() : Sets up the cloud connection.
cloud_connect() : Connects to the cloud service.
cloud_ping() : Pings the cloud service.
cloud_input() : Retrieves data from the cloud service.
cloud_send() : Sends data to the cloud service.

Cloud events used in the sample ¶

The sample uses the following cloud events:

CLOUD_EVT_CONNECTED : Connected to the cloud service.
CLOUD_EVT_READY : Ready for cloud communication.
CLOUD_EVT_DISCONNECTED : Disconnected from the cloud service.
CLOUD_EVT_DATA_RECEIVED : Data received from the cloud service.

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.

Testing ¶

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

Open a web browser and navigate to the correct device in nRF Cloud.
Connect the USB cable and power on or reset your device.

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

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

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

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

Dependencies ¶

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

nRF Cloud
AWS IoT
DK Button and LEDs
Cloud API
lib/bsd_lib
lib/lte_link_control

In addition, it uses the Secure Partition Manager sample:

Secure Partition Manager