Using the nRF Cloud CoAP API¶
This end-to-end guide demonstrates how to perform the following operations:
- Build a sample with CoAP support.
- Prepare the device to connect to nRF Cloud over CoAP.
- Onboard the device.
- Confirm that the device is connected and sending data to nRF Cloud over CoAP. This guide uses a sample that also supports Location Services.
- nRF9160 DK v1.0.0 or later.
- nRF Connect SDK v2.5.0 or later.
nRF Connect for Desktop, and the latest versions of the following tools:
- nRF Serial Terminal for AT commands.
- Cellular Monitor to update the certificates on the device.
- nRF Programmer to update the modem firmware.
Modem firmware v1.3.5 or later.
- VS Code with the nRF Connect for VS Code extension.
- nRF Cloud multi-service sample. This sample includes CoAP support, as well as AT commands, which you need for certificate and credential management. See Building the nRF Cloud multi-service sample.
The command examples in this guide are valid for Windows. Your command-line interface may vary if you use another operating system.
- Create an nRF Cloud account.
- Download a zipped archive of the nRF Cloud Utils repository and extract it to a location of your choice. This guide uses the Python scripts.
- Update the modem firmware using nRF Programmer if your device does not meet the modem firmware requirement.
Building the nRF Cloud multi-service sample¶
Build the multi-service sample using nRF Connect for VS Code. This sample allows you to use AT commands when you inject credentials to the device in a later step, as well as demonstrate connectivity to nRF Cloud over CoAP.
For the steps in this section, refer to How to build an application and include the following changes:
Create a new application for the multi-service sample and nRF9160 DK target using nRF Connect for VS Code:
Under Kconfig fragments, select the
Build and flash the sample.
Installing device credentials and onboarding¶
This step depends on whether you are using the device for the first time or have already onboarded it.
Before you can onboard the device and connect to nRF Cloud, you need to inject credentials to the device, including the CoAP CA certificate. If you have onboarded the device already and added it to your account, you still need to inject the CoAP CA certificate.
If you have never connected your device to nRF Cloud before, you must create a self-signed CA certificate, as well as inject the AWS and CoAP CA certificates. Complete the following steps:
- Navigate to the folder on your computer containing the extracted Utils repository.
- Navigate to the
- Open a command prompt (or other command-line interface according to your operating system).
- If your device is not already switched on and connected over USB, do this now.
Create a self-signed CA certificate using the
python create_ca_cert.py -c US -st OR -l Portland -o "Nordic" -ou "Test" -cn example.com -e email@example.com -p ca_9160 -f nordic_ca
device_credentials_installer.pyscript with the
--coapargument. Including this argument passes the necessary AWS CA and CoAP CA certificates to the device so you do not need to update them manually. Check the Utils
README.mdfor more information on the required and optional arguments. Your actual values will vary from the following example:
python device_credentials_installer.py --coap --id_str nrf- --id_imei -d --ca ca_9160\nordic_ca333cff6f4a5bdbd0a9434bc7de170e653d7fc87ced_ca.pem --ca_key ca_9160\nordic_ca5f8b96884c3a511f874935ec4b03782eb2dea32cda_prv.pem --csv 9160_prod_provision.csv
This generates a CSV file for onboarding.
Upload the CSV file using either the nRF Cloud portal or the
To onboard the device, complete the following steps:
- Log in to the nRF Cloud portal.
- Select Device Management in the left navigation bar.
- Select Provision Devices.
Upload the CSV you generated using the credential installer script.
The page refreshes and provides a bulk operation ID, along with a downloadable file.
Download and view the response to confirm that your device is now onboarded.
See the nRF Cloud Utils repository
README.mdfile for more information on the script.
Your API key is team-specific and a required argument for the script.
Navigate to the
utilssubfolder containing the script and enter the following command, replacing the API key and CSV filename with your own:
python ./nrf_cloud_provision.py --apikey $API_KEY --csv 9160_prod_provision.csv
The service returns a bulk operation ID, which the script uses to fetch the operation results.
You can now confirm that the device is connected and sending information to nRF Cloud using either nRF Serial Terminal, or by checking the device's page in the nRF Cloud portal. If the device is not sending messages to nRF Cloud, press the RESET (SW5) button to reboot the device.
If your device is already onboarded and registered to your account, you do not need to generate and install new device credentials. However, to use CoAP, you must update the root CA certificate on the device to include both the AWS and CoAP root CA certificates. You can update this using the Cellular Monitor app, part of nRF Connect for Desktop. Complete the following steps:
- Connect your device over USB to the computer running nRF Connect for Desktop.
- Turn the device on.
- Open the Serial Terminal app.
- Choose your device to connect.
Confirm that your device is connected.
If the device does not respond, press the RESET (SW5) button to reboot the device.
In the terminal, enter
AT+CFUN=4to disable the modem.
- Check the output to confirm that the modem is disabled.
- Open Cellular Monitor.
- Choose your device.
- Select the Certificate Manager tab.
Copy and paste the following AWS CA and CoAP CA certificates into the CA Certificate field with the default security tag
16842753. Note that the certificates are in the same field, one after the other, with the AWS CA certificate first:
-----BEGIN CERTIFICATE----- MIIDQTCCAimgAwIBAgITBmyfz5m/jAo54vB4ikPmljZbyjANBgkqhkiG9w0BAQsF ADA5MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6 b24gUm9vdCBDQSAxMB4XDTE1MDUyNjAwMDAwMFoXDTM4MDExNzAwMDAwMFowOTEL MAkGA1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEZMBcGA1UEAxMQQW1hem9uIFJv b3QgQ0EgMTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALJ4gHHKeNXj ca9HgFB0fW7Y14h29Jlo91ghYPl0hAEvrAIthtOgQ3pOsqTQNroBvo3bSMgHFzZM 9O6II8c+6zf1tRn4SWiw3te5djgdYZ6k/oI2peVKVuRF4fn9tBb6dNqcmzU5L/qw IFAGbHrQgLKm+a/sRxmPUDgH3KKHOVj4utWp+UhnMJbulHheb4mjUcAwhmahRWa6 VOujw5H5SNz/0egwLX0tdHA114gk957EWW67c4cX8jJGKLhD+rcdqsq08p8kDi1L 93FcXmn/6pUCyziKrlA4b9v7LWIbxcceVOF34GfID5yHI9Y/QCB/IIDEgEw+OyQm jgSubJrIqg0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMC AYYwHQYDVR0OBBYEFIQYzIU07LwMlJQuCFmcx7IQTgoIMA0GCSqGSIb3DQEBCwUA A4IBAQCY8jdaQZChGsV2USggNiMOruYou6r4lK5IpDB/G/wkjUu0yKGX9rbxenDI U5PMCCjjmCXPI6T53iHTfIUJrU6adTrCC2qJeHZERxhlbI1Bjjt/msv0tadQ1wUs N+gDS63pYaACbvXy8MWy7Vu33PqUXHeeE6V/Uq2V8viTO96LXFvKWlJbYK8U90vv o/ufQJVtMVT8QtPHRh8jrdkPSHCa2XV4cdFyQzR1bldZwgJcJmApzyMZFo6IQ6XU 5MsI+yMRQ+hDKXJioaldXgjUkK642M4UwtBV8ob2xJNDd2ZhwLnoQdeXeGADbkpy rqXRfboQnoZsG4q5WTP468SQvvG5 -----END CERTIFICATE----- -----BEGIN CERTIFICATE----- MIIBjzCCATagAwIBAgIUOEakGUS/7BfSlprkly7UK43ZAwowCgYIKoZIzj0EAwIw FDESMBAGA1UEAwwJblJGIENsb3VkMB4XDTIzMDUyNDEyMzUzMloXDTQ4MTIzMDEy MzUzMlowFDESMBAGA1UEAwwJblJGIENsb3VkMFkwEwYHKoZIzj0CAQYIKoZIzj0D AQcDQgAEPVmJXT4TA1ljMcbPH0hxlzMDiPX73FHsdGM/6mqAwq9m2Nunr5/gTQQF MBUZJaQ/rUycLmrT8i+NZ0f/OzoFsKNmMGQwHQYDVR0OBBYEFGusC7QaV825v0Ci qEv2m1HhiScSMB8GA1UdIwQYMBaAFGusC7QaV825v0CiqEv2m1HhiScSMBIGA1Ud EwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgGGMAoGCCqGSM49BAMCA0cAMEQC IH/C3yf5aNFSFlm44CoP5P8L9aW/5woNrzN/kU5I+H38AiAwiHYlPclp25LgY8e2 n7e2W/H1LXJ7S3ENDBwKUF4qyw== -----END CERTIFICATE-----
Click Update certificate.
- Verify that the device certificate is updated in the Terminal tab.
Press the RESET (SW5) button to reboot the device. This also re-enables the modem.
The device attempts to connect over CoAP, using its updated certificates.
Confirm in Serial Terminal that the device connects successfully to nRF Cloud.
You can now confirm that the device is connected and sending information to nRF Cloud from the device's page in the nRF Cloud portal. If the device is not sending messages to nRF Cloud, press the RESET (SW5) button to reboot the device.
The connection may return a failure on the first try. If this happens, allow the device to attempt connecting again before you begin troubleshooting.