Skip to main content

Getting started with nRF Cloud

Use this page as a starting point to learn about nRF Cloud.

Features and first steps​

nRF Cloud provides you with the following features:

  • Device messaging
  • FOTA
  • Location services
  • Provisioning services

For more details see the Overview page.

The first steps to take are the following:

  1. Get an account on the nRF Cloud portal. See the detailed instructions.
  2. Create your certificates and security tags for connecting to nRF Cloud.
  3. Get the nrfcloud-utils scripts.

Adding a device to your account​

To add a device to your account, take the following actions depending on your device:

Deploying your app to many devices​

You need to consider the following when deploying your app to several devices:

Certificates and security tags​

You need the following four security assets to connect your device to nRF Cloud:

  • The Server certificate - Used in a root-of-trust configuration to verify that you are connecting to a trusted server. When resolving api.nrfcloud.com, you might be directed to different servers.
  • The Device ID - This is similar to a username when logging in. It needs to be unique for each device. Common choices are UUIDs and prefixed IMEIs.
  • The Device key pair - This pair contains a public key and a private key specific to each device. The private key should be known only by the device. It is like a password attached to the Device ID.
  • The Device certificate - This is checked directly with the server when logging in. It does not use the root-of-trust model. Instead, the server maintains a database of Device IDs and Device certificates and matches each certificate directly. It is also used to onboard your device to your account.

Some of these components are secret and need to be stored securely. The nRF91 Series devices offer storage inside the modem. Multiple types of credentials can be stored under a numeric ID. These IDs are called Security Tags or sectags. By default, nRF Cloud credentials are stored on the sectag 16842753. The Device ID is not stored inside the modem and you need to set it separately. Often, an automatically generated UUID is used for that purpose. UUIDs provided by the modem are constant and unique for each device. They can be obtained using the AT%DEVICEUUID command. The modem can hold multiple sets of credentials and these can be used for multiple services, not just nRF Cloud. The Device certificates and Private keys are considered secret and cannot be read out after they have been written. Instead, the app can request the modem to use these secrets to establish connections, following the opaque key pattern.

nRF Cloud Utils​

The most common actions to interface with nRF Cloud and nRF91 Series devices are encapsulated with this collection of scripts. You can perform management actions in nRF Cloud using REST API calls. Devices usually use AT commands or shell commands over a serial interface.

To interface with nRF Cloud, use the nRF Cloud Utils. For instructions on the initial setup, refer to the README documentation. Make sure to have your nRF Cloud API Key ready before you start using nRF Cloud Utils.

Local onboarding​

This section explains how you can create the credentials locally and then register with nRF Cloud using the nRF Cloud Utils.

  1. Program the firmware into your device.

  2. Create a local certificate authority (CA). Its contents is not checked, but you need one to make certificates for your devices. Optionally, pass options to the script to specify your owner information.

    create_ca_cert

    Now, you should have three .pem files containing the key pair and the CA certificate of your CA. The files have a unique prefix.

  3. Get your device registered using the device_credentials_installer script:

    device_credentials_installer -d --ca *_ca.pem --ca-key *_prv.pem --coap --verify

Upon success, you can find an onboard.csv file with information about your device. This file is needed to register the certificate with your account. If you encounter a No device found error, you might need to specify the serial port using the --port option.

Onboard the device to your account using the nrf_cloud_onboard script as follows:

nrf_cloud_onboard --api-key $API_KEY --csv onboard.csv

You can install credentials on many devices in a row using the --append option and adding the bulk onboard.csv to your account with the same command.

You have now successfully registered your device to nRF Cloud and it is available in the Devices panel of the portal. The device's UUID is used as Device ID.

Using the Provisioning Service​

note

nRF Cloud's Secure Services use Attestation tokens that are generated by devices to prove that you own a specific Nordic Semiconductor device. They are unique for each device and do not expire. Only devices with modem firmware version 2.0.0 and higher are supported. nRF9160 devices are not supported.

You can create the device credentials locally, also on a manufacturing computer. Here are some reasons for using the Provisioning Service:

  • Simplify manufacturing: Gathering Attestation tokens is much simpler than doing full provisioning, making it easier to set up the manufacturing workflow.
  • Flexibility: Certificates expire. With the Provisioning Service, you can deploy certificate updates to your devices remotely. If you need to add credentials for another service, there is a secure and reliable way to do that, too.
  • Genuine device check: nRF Cloud checks whether Attestation tokens are from a genuine Nordic Semiconductor device.

The following might be potential downsides of using the Provisioning Service:

  • Memory usage on device: Extra memory is needed to handle large certificates, which can conflict with a memory-intensive application.
  • Cost: Provisioning requests are not free. However, the cost should be compared to savings gained in manufacturing.

Provision one device using provisioning service​

  1. Flash an app using the Provisioning Service library, see Preparing your device.
  2. Claim your device and apply a provisioning tag. For faster handling, you can try pushing Button 1 on your device to make it look for provisioning jobs immediately.
claim_and_provision_device --api-key $API_KEY --provisioning-tags "nrf-cloud-onboarding"

After this, your device will be auto-onboarded. The device's UUID is used as the Device ID. You can look up your devices that use this tag in the portal. Use this only for testing and development purposes and refer to the Deploying your app to many devices section to scale up for production.

Scaling up local onboarding​

Add information to the local CA certificate for later identification. The local CA certificates are not supposed to be copied between devices and should be identifiable for each manufacturing machine. Collect batches of devices in the onboard.csv file. You do not need to give your API Key to the factory. Instead, the factory can send the CSV files to the maintainer of the nRF Cloud account. You can also use the nrf_cloud_onboard script to onboard batches of devices. For more details, refer to the steps in the Local onboarding section.

Scaling up with Provisioning Service​

To scale up using the Provisioning Service for manufacturing, split the process into the following two separate steps:

  1. Gather the device's attestation token.

    For example, the production test firmware can use the AT Host library to provide access to the AT%ATTESTTOKEN command. You can also use the gather_attestation_tokens script. This will create a CSV that you can later use with the claim_devices --provisioning-tags nrf-cloud-onboarding script to claim and provision batches of devices.

  2. After collecting the attestation tokens for a batch of devices, you need to claim them. Claim the devices in batches rather than each device separately using the script:

    claim_devices --api-key $API_KEY --provisioning-tags "nrf-cloud-onboarding" --csv attestation_tokens.csv

Simulated devices​

In some cases, it can be useful to test firmware in simulation. This enables a more feature-rich debugging suite and you can begin development before the devices are ready. The nRF Cloud multi-service sample supports the native_sim platform. You can use the CoAP and MQTT backends for simulation. FOTA is not supported in this configuration.

To use simulation, perform the following steps:

  1. Create the certificates using the following command:

    create_device_credentials --ca <CA.pem> --ca-key <PRV.pem> --embed-save

  2. Place the certs folder inside nrf_cloud_multi_service.

  3. Adjust the Client ID Kconfig option.

  4. Feed the generated onboard.csv into the nrf_cloud_onboard command to link the virtual device to your account.

    From the cloud perspective, the virtual device is treated like a real one.

Preparing your device​

This section describes how to program matching firmware onto your device to enable provisioning.

The following samples are recommended:

  • For basic device registration: Enable the AT Host library. Refer to the AT Client sample in the nRF Connect SDK for an implementation example.

  • For using the Provisioning Service: Enable the Provisioning Service library. For more details, refer to the Provisioning Service page. The nRF Connect SDK provides the following samples:

    • Asset Tracker template application, it provides an event-driven architecture for battery-powered IoT use cases with cloud connectivity, location tracking, and sensor data collection.
    • nRF Cloud multi-service sample, demonstrating onboarding alongside other cloud interactions.
    • nRF Device provisioning sample, providing a focused look at the provisioning steps.

Quick Start​

The Quick Start app allows you to install a precompiled sample and update the device's modem firmware:

  1. Open the Quick Start app from nRF Connect for Desktop.

  2. Connect your device over USB and turn it on.

  3. Follow the Quick Start app instructions:

    1. At the Program step, choose the Asset Tracker application.
    2. At the Evaluate step, the app gets the device's identity attestation token. Copy the attestation token somewhere secure.

    If you close Quick Start without copying the token, you can open the Serial Terminal app and reboot your device, the token will be printed as part of the execution.

  4. Continue with claiming and onboarding the device.

Custom compiled firmware​

To program custom firmware, you can use the nrfutil-device CLI tool or nRF Programmer app.

Creating an nRF Cloud account​

To connect your device and use nRF Cloud services, create first an nRF Cloud account as follows:

  1. Open the nRF Cloud portal and click Register.

  2. Enter your email address and choose a password.

  3. Click Create Account.

  4. Check for a verification email from nRF Cloud.

    If you do not see the verification email, check your junk mail folder for an email from no-reply@verificationemail.com.

  5. Copy the six-digit verification code and paste it into the registration dialog box.

    If you accidentally closed the registration dialog box, repeat Step 1 and click Already have a code?. Enter your email address and verification code.

You can now log in to the nRF Cloud portal with your email and password. After logging in, you can see the Dashboard view that displays your device count and service usage.

For using the REST APIs and support scripts, you need an API key. Select the correct team on the upper right corner of the portal. Then, using the burger menu in the upper right corner, select User Account and get your API Key.

Device security​

note

This guide serves as a starting point for security considerations. A professional security audit is recommended for all IoT devices. The focus in this guide is on the nRF91 Series devices and their specific security features. While developing, it is very useful to have full debug access. However, this access should be revoked for devices in customer's hands.

When creating a product using nRF Cloud, you link devices to your account. This gives the devices access to use services in your name and access some data that might be private. The following sections discuss the assets you might want to protect.

Application firmware​

Your firmware might include embedded trade secrets and service details. These can be used to attack your infrastructure and to make knock-off products based on your design. For end-user devices, Nordic Semiconductor recommends that you enable access port protection (AP-Protect), which essentially prevents reading out the application firmware.

Device credentials​

The device credentials are stored in the modem, and you have to make sure they cannot be misused. Secrets stored in the modem cannot be read out directly, but can still be used to sign JWTs to grant access. Even with the access port protection enabled, the firmware can still be erased and replaced. Since the modem and application cores are independent, the modem storage is not erased and can be used by any custom firmware.

Nordic Semiconductor recommends that you enable erase all protection in addition. With this protection enabled, the firmware cannot be erased by a connected debug probe. This mechanism is only effective if AP-Protect is enabled as well. The two mechanisms control two different ways to access the core. AP-Protect controls the debug access, while erase all protection controls the recovery access.

Because it is very easy to brick a device this way, double-check that your bootloader is working reliably before enabling these protections. You can implement a firmware mechanism to allow unlocking these protections if necessary. It makes sense to prepare a frozen version of the bootloader with a tested recovery mechanism, such as serial recovery, as well as a special recovery image to unlock the chip. Products built using the nRF Connect SDK typically use the secure bootloader chain. Following the typical structure explained in Trusted Firmware-M architecture, unlocking the device protection features needs to take place in the Secure Processing Environment (SPE).

Last updated on
This page is human-authored. If you see any errors, outdated information, or any other suggestions for improving the contents, please contact us!