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 |
|
When built for an _ns build target, the sample is configured to compile and run as a non-secure application.
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:
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.
When built as a non-secure firmware image for the _ns build target, the sample automatically includes the Trusted Firmware-M (TF-M).
To build the sample with Visual Studio Code, follow the steps listed on the Building nRF Connect SDK application quick guide 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: