nRF9160: 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.

Requirements

The sample supports the following development kits:

Hardware platforms

PCA

Board name

Build target

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 the configured button (Button 1 by default) (CONFIG_REST_DEVICE_MESSAGE_BUTTON_EVT_NUM) 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.

Provisioning

Your device must be provisioned for this sample to function.

Complete the following steps to provision your device:

  1. Enable the CONFIG_REST_DEVICE_MESSAGE_DO_JITP option.

  2. Press the button (configured with CONFIG_REST_DEVICE_MESSAGE_DO_JITP) when prompted at startup.

  3. 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_BUTTON_EVT_NUM - Button number

This configuration option defines the button to use for device interactions.

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.

Building and running

This sample can be found under samples/nrf9160/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/nrf9160/nrf_cloud_rest_device_message. See Configuring your application for information on how to configure the parameters.

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: