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.

Requirements

• 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.

Note

The command examples in this guide are valid for Windows. Your command-line interface may vary if you use another operating system.

Prerequisites

• 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 Connect 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:

1. Create a new application for the multi-service sample and nRF9160 DK target using nRF Connect for VS Code:

   1. Under Kconfig fragments, select the overlay_coap.conf overlay.

      Note

      See more on configuration options for the multi-service sample.

      The nRF Cloud library allows you to configure supported samples to use either a UUID or IMEI. The default is IMEI with an nrf- prefix. See Configuration options for device ID for more information.

2. 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.

For nRF91x1 devices, see the auto-onboarding option. For devices that are not compatible with the nRF Cloud Security Service, proceed with the steps that follow.

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.

Onboarding the device for the first timeThe device is already onboarded

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:

1. Navigate to the folder on your computer containing the extracted Utils repository.
2. Navigate to the python/modem-firmware-1.3+ subfolder.
3. Open a command prompt (or other command-line interface according to your operating system).
4. If your device is not already switched on and connected over USB, do this now.

5. Create a self-signed CA certificate using the create_ca_cert script:

   python create_ca_cert.py -c US -st OR -l Portland -o "Nordic" -ou "Test" -cn example.com -e name@example.com -p ca_9160 -f nordic_ca
   

6. Run the device_credentials_installer.py script with the --coap argument. 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.md for 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.

7. Upload the CSV file using either the nRF Cloud portal or the nrf_cloud_onboard.py script:

   Using the nRF Cloud portalUsing the nrf_cloud_onboard.py script

   To onboard the device, complete the following steps:

   1. Log in to the nRF Cloud portal.
   2. Select Device Management in the left navigation bar.
   3. Select Provision Devices.

   4. Upload the CSV you generated using the credential installer script.

      The page refreshes and provides a bulk operation ID, along with a downloadable file.

   5. Download and view the response to confirm that your device is now onboarded.

   See the nRF Cloud Utils repository README.md file for more information on the script.

   Your API key is team-specific and a required argument for the script.

   Navigate to the utils subfolder containing the script and enter the following command, replacing the API key and CSV filename with your own:

   python ./nrf_cloud_onboard.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:

1. Connect your device over USB to the computer running nRF Connect for Desktop.
2. Turn the device on.
3. Open the Serial Terminal app.
4. Choose your device to connect.

5. Confirm that your device is connected.

   If the device does not respond, press the RESET (SW5) button to reboot the device.

6. In the terminal, enter AT+CFUN=4 to disable the modem.

7. Check the output to confirm that the modem is disabled.
8. Open Cellular Monitor.
9. Choose your device.
10. Select the Certificate Manager tab.

11. 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-----
    

12. Click Update certificate.

13. Verify that the device certificate is updated in the Terminal tab.

14. 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.

15. 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.

Note

The connection may return a failure on the first try. If this happens, allow the device to attempt connecting again before you begin troubleshooting.