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 Cloud device provisioning library.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
nRF9161 DK	PCA10153	nrf9161dk	nrf9161dk/nrf9161/ns
nRF9160 DK	PCA10090	nrf9160dk	nrf9160dk/nrf9160/ns
nRF9151 DK	PCA10171	nrf9151dk	nrf9151dk/nrf9151/ns

When built for a board target with the */ns variant, 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.

Provisioning and onboarding your device to nRF Cloud

You must onboard your device to nRF Cloud for this sample to function. You only need to do this once for each device.

This sample supports two methods to onboard your device:

• Using nRF Cloud Provisioning Service and the auto-onboarding option.

  This is the preferred option for nRF91x1-based devices. The nRF Cloud Provisioning Service auto-onboarding is currently compatible with REST and CoAP but not MQTT connectivity to nRF Cloud; for that, use the next method.

• Using Just-in-time provisioning.

  This is the legacy option. Use this method for nRF9160-based devices.

Remote provisioning and auto-onboarding with nRF Cloud

Build and run the sample with the remote provisioning overlay as explained below: Remote provisioning overlay. Follow the steps outlined in device claiming. See nRF Cloud Auto-onboarding for more information. The device ID is in the UUID format, not the legacy ‘nrf-IMEI‘ format.

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

Complete the following steps to onboard your device:

1. Enable the CONFIG_REST_DEVICE_MESSAGE_DO_JITP option.

2. Press button 1 when prompted at startup.

3. Follow the instructions for just-in-time provisioning (JITP) printed to UART.

See nRF Cloud Just-In-Time-Provisioning for more information. The device ID is in the legacy ‘nrf-IMEI‘ format.

Configuration

See Configuring and building an 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.

TF-M logging must use the same UART as the application. For more details, see shared TF-M logging.

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 a board target with the */ns variant, 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, follow the instructions in Configuring and building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

The configuration file for this sample is located in samples/cellular/nrf_cloud_rest_device_message. See Configuring and building an application for information on how to configure the parameters.

nRF Cloud logging overlay

To enable Zephyr Logging to nRF Cloud using the nRF Cloud Log library, add the following parameter to your build command:

-DEXTRA_CONF_FILE=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.

Remote provisioning overlay

This overlay is for use with nRF91x1-based devices only. To enable remote provisioning with the nRF Cloud Provisioning Service add the following parameter to your build command:

-DEXTRA_CONF_FILE=overlay-nrf_provisioning.conf

This overlay enables the nRF Cloud device provisioning library and its provisioning shell. It configures the device ID to use the UUID format, not the legacy ‘nrf-IMEI‘ format. 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:

• nRF Cloud

• nRF Cloud REST

• nRF Cloud Alert

• nRF Cloud Log

• Modem JWT

• LTE link control

• DK Buttons and LEDs

• Modem information

• AT Host

In addition, it uses the following secure firmware component:

• Trusted Firmware-M