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 |
---|---|---|---|
PCA10090 |
|
||
PCA20035 |
thingy91_nrf9160 |
|
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_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.
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:
Open a web browser and navigate to the correct device in nRF Connect for 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 Connect for 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 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: