Cellular: nRF Cloud REST Device Message

The REST Device Message sample demonstrates how to use the nRF Cloud REST API to send Device Messages using the SendDeviceMessage REST endpoint. Every button press sends a message to nRF Cloud.

It also demonstrates use of the nRF Cloud Alert and the nRF Cloud Log libraries. The sample sends an alert when the device first comes online. It also sends a log message indicating the sample version, as well as when the button is pressed.

You can also configure the sample to use the nRF Cloud Provisioning Service with the nRF Device provisioning library.

Requirements 

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Build target
nRF9161 DK		`nrf9161dk_nrf9161`	`nrf9161dk_nrf9161_ns`
nRF9160 DK	PCA10090	nrf9160dk_nrf9160	`nrf9160dk_nrf9160_ns`

When built for an _ns build target, the sample is configured to compile and run as a non-secure application with Cortex-M Security Extensions enabled. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

The sample requires an nRF Cloud account.

Your device must be provisioned with nRF Cloud. If it is not, follow the instructions in Provisioning.

Note

This sample requires modem firmware v1.3.x or later.

Limitations 

The nRF Cloud REST API requires all requests to be authenticated with a JSON Web Token (JWT). See nRF Cloud Security for more details. Generating valid JWTs requires the network carrier to provide date and time to the modem, so the sample must first connect to an LTE carrier and determine the current date and time before REST requests can be sent.

Note also that the nRF Cloud REST API is stateless. This differs from the nRF Cloud MQTT API, which requires you to establish and maintain an MQTT connection while sending Device Messages.

User interface 

Once the device is provisioned and connected, each press of Button 1 generates a device-to-cloud button press Device Message over REST. These messages are sent to the non-bulk D2C (device-to-cloud) topic, detailed in topics used by devices running the nRF Cloud library.

The configured LTE LED (LED 1 by default) (CONFIG_REST_DEVICE_MESSAGE_LTE_LED_NUM) is lit once an LTE connection is established and JWT tokens are ready to be generated.

The configured Send LED (LED 2 by default) (CONFIG_REST_DEVICE_MESSAGE_SEND_LED_NUM) is lit when a REST request is being sent.

Just-in-time provisioning (JITP) with nRF Cloud 

Your device must be provisioned with nRF Cloud for this sample to function.

Complete the following steps to provision your device:

Enable the CONFIG_REST_DEVICE_MESSAGE_DO_JITP option.
Press button 1 when prompted at startup.
Follow the instructions for just-in-time provisioning (JITP) printed to UART.

You only need to do this once for each device.

Configuration 

See Configuring your application for information about how to permanently or temporarily change the configuration.

Configuration options 

Set the following configuration options for the sample:

CONFIG_REST_DEVICE_MESSAGE_LTE_LED_NUM - LTE LED number: This configuration option defines which LED is used to indicate LTE connection success.

CONFIG_REST_DEVICE_MESSAGE_SEND_LED_NUM - Send LED number: This configuration option defines which LED is used to indicate a REST request is being sent.

CONFIG_REST_DEVICE_MESSAGE_DO_JITP - Enable prompt to perform JITP over REST: This configuration option defines whether the application prompts the user for just-in-time provisioning on startup.

Sending traces over UART on an nRF91 Series DK 

To send modem traces over UART on an nRF91 Series DK, configuration must be added for the UART device in the devicetree and Kconfig. This is done by adding the modem trace UART snippet when building and programming.

Use the Cellular Monitor app for capturing and analyzing modem traces.

Building and running 

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

When built as firmware image for the _ns build target, the sample has Cortex-M Security Extensions (CMSE) enabled and separates the firmware between Non-Secure Processing Environment (NSPE) and Secure Processing Environment (SPE). Because of this, it automatically includes the Trusted Firmware-M (TF-M). To read more about CMSE, see Processing environments.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

The configuration file for this sample is located in samples/cellular/nrf_cloud_rest_device_message. See Configuring your application for information on how to configure the parameters. To enable Zephyr Logging to nRF Cloud using the nRF Cloud Log library, add the following parameter to your build command:

-DOVERLAY_CONFIG=overlay_nrfcloud_logging.conf

This overlay allows the sample and various subsystems that have logging enabled to send their logs to nRF Cloud. Set the CONFIG_NRF_CLOUD_LOG_OUTPUT_LEVEL option to the log level of messages to send to nRF Cloud, such as 4 for debug log messages. Set the CONFIG_NRF_CLOUD_REST_DEVICE_MESSAGE_SAMPLE_LOG_LEVEL_DBG option so that log messages are generated on each button press.

To enable remote provisioning with the nRF Cloud Provisioning Service add the following parameter to your build command:

-DOVERLAY_CONFIG=overlay-nrf_provisioning.conf

This overlay enables the nRF Device provisioning library and its provisioning shell. The sample will periodically check for provisioning commands. Press Button 2 to manually initiate a check for provisioning commands.

Press Button 1 to have a message sent to nRF Cloud:

{
  "appId": "BUTTON",
  "messageType": "DATA",
  "data": "1",
  "timestamp": "4/19/2023 12:34:21 PM"
}

Querying Device Messages over REST API 

To query the Device Messages received by the nRF Cloud backend, send a GET request to the ListMessages endpoint.

Dependencies 

This sample uses the following nRF Connect SDK libraries:

In addition, it uses the following secure firmware component:

Trusted Firmware-M