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.
The sample supports the following development kits:
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.
This sample requires modem firmware v1.3.x or later.
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.
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.
Your device must be provisioned for this sample to function.
Complete the following steps to provision your device:
Enable the CONFIG_REST_DEVICE_MESSAGE_DO_JITP option.
Press the button (configured with CONFIG_REST_DEVICE_MESSAGE_DO_JITP) 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.
See Configuring your application for information about how to permanently or temporarily change the configuration.
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.
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
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.
This sample uses the following nRF Connect SDK libraries:
In addition, it uses the following secure firmware component: