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 |
|---|---|---|---|
PCA10090 |
|
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 <nRF Cloud 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:
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.
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.
The sample is built as a non-secure firmware image for the nrf9160dk_nrf9160_ns build target. Because of this, it automatically includes the Secure Partition Manager. You can also configure it to use TF-M instead of SPM.
See Building and programming an application for information about how to build and program the application.
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: