Using nRF Cloud with the nRF Connect SDK

nRF Cloud is Nordic Semiconductor’s IoT cloud platform that offers services in the fields of connectivity, device management, and location services.

Overview

nRF Cloud allows you to remotely manage and update your IoT devices using Firmware Over-the-Air (FOTA). FOTA can be used to update the device application, bootloader, and modem. The modem can be incrementally updated with a modem delta image. If the device has sufficiently large external flash storage, the modem can be entirely updated with a full modem image.

nRF Cloud also helps your devices determine their locations using GNSS. It uses both assisted GNSS (A-GNSS) and predicted GPS (P-GPS). It can determine device location from cellular and Wi-Fi network information sent by the device.

Additionally, nRF Cloud allows devices to report data to the cloud for collection and analysis later. To read more about nRF Cloud, see the nRF Cloud website and the nRF Cloud documentation.

You can use the services offered by nRF Cloud in the following scenarios:

  • Device connected to nRF Cloud over CoAP.

    The services can be used through the nRF Cloud web portal.

  • Device connected to nRF Cloud over MQTT.

    The services can be used through the nRF Cloud web portal.

  • Device connected to nRF Cloud over MQTT, with a customer-developed website or application.

    The website or application interacts with the nRF Cloud REST API to display device data and manage it in a customized way.

  • Device connected to nRF Cloud over REST.

    The device uses the services by interacting with the nRF Cloud REST API.

  • Device connected to a customer cloud service in a suitable manner.

    The services can be used from the customer cloud service that communicates over REST to interact with the nRF Cloud REST API in a proxy configuration.

Choosing a device ID format: prefix-IMEI, device UUID, or other

nRF Cloud supports a variety of device ID formats:

  • A prefix plus IMEI

    The prefix nrf- is reserved for Nordic development kits or evaluation platforms.

  • The device UUID

    This is a guaranteed unique ID stored in the modem.

  • Compile-time

    A fixed device ID compiled into the firmware.

  • Run-time

    A device ID generated by the application in an application-specific way.

  • Hardware ID

    A device ID generated from one of a selection of hardware IDs.

Nordic development kits such as the nRF9160 DK have a sticker on the back indicating the device’s IMEI and PIN. They are preprovisioned with just-in-time provisioning (JITP) certificates so they can be added easily to nRF Cloud using the device ID nrf-IMEI and PIN. Device IDs that start with nrf- are checked against a database of genuine Nordic development kits, Thingy:91, and Thingy:91 X. If the device ID (and the accompanying PIN or Hardware ID) is not found in the database, the device cannot connect. This means that customers using custom hardware cannot use the nrf- prefix for their device IDs. Choose your own PIN when creating JITP credentials for a custom device.

The device_credentials_installer.py script uses the device UUID format by default. See these command line options to use other device ID formats:

  • --id_str ID_STR

    Set a device ID that is used instead of UUID. Will be set as a prefix if the --id_imei option is enabled. The default value for the option is empty.

  • --id_imei

    Enable using IMEI for device ID instead of UUID. You can add a prefix to the IMEI with the --id_str option. The default value for the option is false.

Your firmware’s device ID configuration must align with the options used when executing the device_credentials_installer.py script. See the Configuration options for device ID section of the nRF Cloud library documentation for more information.

The device_credentials_installer.py script automatically connects over USB or RTT to your device and installs the certificates in the modem. Before running the script, you must install and run firmware on the device that allows it to accept AT commands over USB or RTT, such as the AT Client sample.

If the device already contains certificates, delete the old certificates from the device by adding the --delete option.

Choosing a protocol: CoAP, MQTT or REST

When choosing a protocol, consider the following:

  • How often does the device transmit data?

  • Which cloud APIs does the device need to access?

  • What are the power consumption requirements for the device?

  • What are the network data usage requirements for the device?

  • What are the carrier’s network settings (NAT timeout, eDRX/PSM) and how will the settings affect device behavior?

MQTT has a higher (data/power) cost to set up a connection than CoAP or REST. However, the data size of an MQTT publish event is smaller than a comparable REST transaction. The data size of a CoAP transfer can be the smallest of all. MQTT may be preferred if a device is able to maintain a connection to the broker and sends/receives data frequently. REST may be preferred if a device sends data infrequently or does not need to receive unsolicited data from the cloud. CoAP may be preferred if a device sends data infrequently, does not need to receive unsolicited data from the cloud, and must use the least amount of cellular data and the least amount of power.

CoAP overview

  • The device initiates a DTLS connection to nRF Cloud.

  • nRF Cloud supports DTLS 1.2 Connection ID in order to keep the UDP connection open and usable for a long time, regardless of any NAT translation changes between the device and cloud.

  • For authentication, the device must send a JSON Web Token (JWT) with the initial connection. The JWT is approximately 450 bytes.

  • Each CoAP transaction contains a CoAP header and API-specific payload.

REST overview

  • The device initiates a TLS connection to nRF Cloud.

  • nRF Cloud supports a connection keep-alive/idle time of 60 seconds for REST API sockets.

  • For authentication, the device must send a JSON Web Token (JWT) with each REST transaction. The JWT is approximately 450 bytes, but can be larger depending on the claims.

  • Each REST transaction contains HTTP headers, including the JWT, and any API specific payload.

MQTT overview

  • The device initiates a mutual-TLS (mTLS) connection to the nRF Cloud MQTT broker.

  • The MQTT keep-alive time can be set by the device and can be longer than 60s.

  • Device authentication through mTLS lasts throughout the MQTT connection.

  • Once connected, the device subscribes to the desired MQTT topics.

  • Each MQTT publish event contains the MQTT topic and the payload.

Security

A device can successfully connect to nRF Cloud using CoAP or REST if the following requirements are met:

  • The device contains a correct x509 CA certificate, and private key.

  • The public key derived from the private key is registered with an nRF Cloud account. The device will be visible in the nRF Cloud portal, including location service data and sensor data, if the public key is also associated with the same nRF Cloud account.

  • The device calls nRF Cloud REST APIs and provides a JSON Web Token (JWT) signed by the private key.

  • The device calls the nRF Cloud CoAP connect function, which generates and sends the JWT automatically. After that, calls to the CoAP service APIs do not transmit the JWT again but rely on the DTLS Connection ID to maintain a connection for long periods of time.

A device can successfully connect to nRF Cloud using MQTT if the following requirements are met:

  • The device contains a correct x509 CA certificate, device certificate, and private key.

  • The device ID and device certificate are provisioned and onboarded with nRF Cloud.

nRF Cloud supports the following three ways for creating and installing these certificates both in the device and the cloud:

  • nRF Cloud provisioning service and library

    This option enables devices to receive provisioning commands over the air and can then optionally onboard the devices to nRF Cloud. This allows you to defer the provisioning step until a device is deployed in the field instead of during manufacturing. The only manufacturing step is to request the attestation token from the device to claim the device in nRF Cloud.

    The device’s private key is generated by the device and stored securely. It cannot be read from the device, ensuring security.

    See the following for more information:

  • Just-in-time provisioning (JITP)

    Note

    This option is not supported by CoAP connections.

    Nordic development kits and evaluation platforms are preprovisioned with JITP certificates. To use JITP for custom devices, or to replace the JITP credentials in a device, do the following:

    1. In your nRF Cloud account, enter the device ID in a web form, then download a JSON file containing the CA certificate, device certificate, and private key.

      Alternatively, use the nRF Cloud REST API to do this.

    2. Program the credentials in the JSON file into the device using the Cellular Monitor app.

    The private key is exposed during these steps, and therefore, this is the less secure option. See Updating the nRF Cloud certificate for details.

  • Preconnect provisioning

    This is supported by CoAP, MQTT, and REST connections.

    1. Run the device_credentials_installer.py Python script to create and install credentials on the device:

      • You need to specify a number of parameters including the device ID.

      • The script instructs the device to securely generate and store a private key.

      • The private key never leaves the device, which makes this a more secure option.

      • It creates a device certificate and signs it with the specified CA.

      • It writes the device certificate and AWS CA certificate to the device.

    2. Run the nrf_cloud_onboard.py script to onboard the device to your nRF Cloud account.

    For more details about the scripts, refer to the nRF Cloud Utilities documentation.

    See Securely generating credentials and nRF Cloud Provisioning for more details.

nRF Connect SDK library support

The nRF Connect SDK provides the nRF Cloud library, which if enabled, allows you to connect your devices to nRF Cloud and use the update, location, and connectivity services using MQTT or REST.

For more information on the various services, see the following documentation:

Applications and samples

The following application uses the nRF Cloud for services in nRF Connect SDK:

The following sample demonstrates nRF Cloud-specific functionality using CoAP:

The following sample demonstrates nRF Cloud-specific functionality using MQTT:

The following samples demonstrate nRF Cloud-specific functionality using REST:

Other related samples and applications that use nRF Cloud services: