nrfcloud-utils 3.1.0

Scripts and utilities for working with the nRF Cloud

nRF Cloud Utils

nRF Cloud Utils is a script collection to make it easier to interface with nRF Cloud. They also include nrfcredstore to interface with nRF91 Series devices.

The scripts in this repository mainly use endpoints in the nRF Cloud API and the nRF Cloud Provisioning API.

See also the official nRF Cloud documentation.

Table of Contents

• Install
• Requirements
• How-To: Registering devices quickly
• Advanced Usage
• Development installation
• Test

Install

Run the following command to use this package as a dependency:

pip3 install nrfcloud-utils

Requirements

1. Create an account in nrfcloud.com.
2. Retrieve your API key. You can find it in your nRF Cloud User Account page. Note that if you are part of multiple teams on nRF Cloud, the API key will be different for each one.
3. Depending on your goal, you'll need to configure your nRF Connect SDK project with the following libraries:

• 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. You can find more documentation about the Provisioning Service here. The nRF Connect SDK provides these illustrative samples:

  • nRF Cloud Multi Service Sample: Demonstrates onboarding alongside other cloud interactions.
    • https://github.com/nrfconnect/sdk-nrf/tree/main/samples/cellular/nrf_cloud_multi_service
  • nRF Provisioning Sample: Provides a focused look at the provisioning steps.
    • https://github.com/nrfconnect/sdk-nrf/tree/main/samples/cellular/nrf_provisioning

4. When compiling with the nRF Cloud Libraries, make sure your project has the next Kconfig options:

   # Enable modem-based JSON Web Token (JWT) generation required for nRF Cloud authentication
   CONFIG_MODEM_JWT=y
   
   # Configure the nRF Cloud library to use the device's internal UUID
   CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID=y
   

:warning:Failure to include these settings will prevent the device from connecting to nRF Cloud.

How-To: Registering devices quickly

Start by creating a local certificate authority (CA). Its contents won't be checked, but you need one to make certificates for your devices. Optionally, pass options to the script to specify 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.

To get your device registered, use the device_credentials_installer script. Be aware of which device ID is your project using, as it can be either a UUID or an IMEI. Depending on your device ID type, use one of the following commands:

UUID

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

nrf-<IMEI>

device_credentials_installer -d --ca *_ca.pem --ca-key *_prv.pem --verify --id-imei --id-str nrf- --coap

:warning:Failure to select the correct device ID will result in a connection refused from nRF Cloud.

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

It is possible to install credentials on many devices in a row using the --append option and add the bulk onboard.csv to your account with the same command.

Congratulations! You have successfully registered your device to nRF Cloud, you should be able to visualize it on the Devices panel.

Advanced Usage

For a more detailed overview of the scripts and their capabilities, refer to the Advanced Usage Guide. This guide provides in-depth instructions on leveraging advanced features, including the use of the Provisioning Service for remote provisioning of devices, as an alternative to local provisioning.

Development installation

Clone the repository:

git clone https://github.com/nRFCloud/utils.git nrfcloud-utils
cd nrfcloud-utils

For development mode, you need poetry:

curl -sSL https://install.python-poetry.org | python3 -

Make sure poetry is in your PATH. If you're using bash:

echo 'export PATH=/home/$USER/.local/bin:$PATH' | tee -a ~/.bashrc
source ~/.bashrc

Install package dependencies, development dependencies, and the nrfcloud-utils into poetry's internal virtual environment:

poetry install

Test

Unit tests are included in the tests folder. Each test script corresponds to a script in the sources. Static files used in the tests are put in the tests/fixtures folder. Running the tests depends on a development installation.

poetry run pytest

Check coverage

poetry run pytest --cov=src tests