# nRF Cloud Utils
[](https://pypi.org/project/nrfcloud-utils/)
nRF Cloud Utils is a script collection to make it easier to interface with nRF Cloud. They also include [nrfcredstore](https://github.com/NordicSemiconductor/nrfcredstore) to interface with nRF91 Series devices.
The scripts in this repository mainly use endpoints in the [nRF Cloud API](https://api.nrfcloud.com/v1) and the [nRF Cloud Provisioning API](https://api.provisioning.nrfcloud.com/v1/).
See also the official [nRF Cloud documentation](https://docs.nordicsemi.com/bundle/nrf-cloud/page/index.html).
## Table of Contents
* [Install](#install)
* [Requirements](#requirements)
* [How-To: Registering devices quickly](#how-to-registering-devices-quickly)
* [Advanced Usage](#advanced-usage)
* [Development installation](#development-installation)
* [Test](#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](https://nrfcloud.com).
2. Retrieve your API key. You can find it in your [nRF Cloud User Account page](https://nrfcloud.com/#/account). 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](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/modem/at_host.html). Refer to the [AT Client sample](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/samples/cellular/at_client/README.html) in the nRF Connect SDK for an implementation example.
* **For using the Provisioning Service:** Enable the [Provisioning Service library](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/networking/nrf_provisioning.html). You can find more documentation about the [Provisioning Service here](https://docs.nordicsemi.com/bundle/nrf-cloud/page/SecurityServices/ProvisioningService/ProvisioningOverview.html). 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](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](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:
```Kconfig
# 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
# Or IMEI as the device ID
CONFIG_NRF_CLOUD_CLIENT_ID_SRC_IMEI=y
# But not both at the same time
```
: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 ./ca_prv_key.pem --verify
```
#### nrf-\<IMEI\>
```
device_credentials_installer -d --ca ./ca.pem --ca-key ./ca_prv_key.pem --verify --id-imei --id-str nrf-
```
: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](https://nrfcloud.com/#/devices).
## Advanced Usage
For a more detailed overview of the scripts and their capabilities, refer to the [Advanced Usage Guide](https://github.com/nRFCloud/utils/blob/main/ADVANCED.md). 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](https://python-poetry.org/):
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](#development-installation).
poetry run pytest
Check coverage
poetry run pytest --cov=. tests
Raw data
{
"_id": null,
"home_page": "https://github.com/nRFCloud/utils",
"name": "nrfcloud-utils",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Nordic Semiconductor ASA",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/b0/d9/727a645daee90afa7152e980f7d8bc915b9a2809cec75436b1058c871390/nrfcloud_utils-3.0.3.tar.gz",
"platform": null,
"description": "# nRF Cloud Utils\n\n[](https://pypi.org/project/nrfcloud-utils/)\n\n\n\nnRF Cloud Utils is a script collection to make it easier to interface with nRF Cloud. They also include [nrfcredstore](https://github.com/NordicSemiconductor/nrfcredstore) to interface with nRF91 Series devices.\n\nThe scripts in this repository mainly use endpoints in the [nRF Cloud API](https://api.nrfcloud.com/v1) and the [nRF Cloud Provisioning API](https://api.provisioning.nrfcloud.com/v1/).\n\nSee also the official [nRF Cloud documentation](https://docs.nordicsemi.com/bundle/nrf-cloud/page/index.html).\n\n## Table of Contents\n\n* [Install](#install)\n* [Requirements](#requirements)\n* [How-To: Registering devices quickly](#how-to-registering-devices-quickly)\n* [Advanced Usage](#advanced-usage)\n* [Development installation](#development-installation)\n* [Test](#test)\n\n## Install\n\nRun the following command to use this package as a dependency:\n\n pip3 install nrfcloud-utils\n\n## Requirements\n\n1. Create an account in [nrfcloud.com](https://nrfcloud.com).\n2. Retrieve your API key. You can find it in your [nRF Cloud User Account page](https://nrfcloud.com/#/account). Note that if you are part of multiple teams on nRF Cloud, the API key will be different for each one.\n3. Depending on your goal, you'll need to configure your nRF Connect SDK project with the following libraries:\n\n* **For basic device registration:** Enable the [AT Host library](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/modem/at_host.html). Refer to the [AT Client sample](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/samples/cellular/at_client/README.html) in the nRF Connect SDK for an implementation example.\n\n* **For using the Provisioning Service:** Enable the [Provisioning Service library](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/networking/nrf_provisioning.html). You can find more documentation about the [Provisioning Service here](https://docs.nordicsemi.com/bundle/nrf-cloud/page/SecurityServices/ProvisioningService/ProvisioningOverview.html). The nRF Connect SDK provides these illustrative samples:\n\n * **nRF Cloud Multi Service Sample:** Demonstrates onboarding alongside other cloud interactions.\n * [https://github.com/nrfconnect/sdk-nrf/tree/main/samples/cellular/nrf_cloud_multi_service](https://github.com/nrfconnect/sdk-nrf/tree/main/samples/cellular/nrf_cloud_multi_service)\n * **nRF Provisioning Sample:** Provides a focused look at the provisioning steps.\n * [https://github.com/nrfconnect/sdk-nrf/tree/main/samples/cellular/nrf_provisioning](https://github.com/nrfconnect/sdk-nrf/tree/main/samples/cellular/nrf_provisioning)\n\n4. When compiling with the nRF Cloud Libraries, make sure your project has the next Kconfig options:\n\n ```Kconfig\n # Enable modem-based JSON Web Token (JWT) generation required for nRF Cloud authentication\n CONFIG_MODEM_JWT=y\n\n # Configure the nRF Cloud library to use the device's internal UUID \n CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID=y\n # Or IMEI as the device ID\n CONFIG_NRF_CLOUD_CLIENT_ID_SRC_IMEI=y\n # But not both at the same time\n ```\n:warning:**Failure to include these settings will prevent the device from connecting to nRF Cloud.**\n\n## How-To: Registering devices quickly\n\nStart 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.\n\n create_ca_cert\n\nNow, you should have three `.pem` files containing the key pair and the CA certificate of your CA. The files have a unique prefix.\n\nTo 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:\n\n#### UUID\n```\ndevice_credentials_installer -d --ca ./ca.pem --ca-key ./ca_prv_key.pem --verify\n```\n\n#### nrf-\\<IMEI\\>\n```\ndevice_credentials_installer -d --ca ./ca.pem --ca-key ./ca_prv_key.pem --verify --id-imei --id-str nrf-\n```\n:warning:**Failure to select the correct device ID will result in a connection refused from nRF Cloud.**\n\nUpon success, you can find an `onboard.csv` file with information about your device. This file is needed to register the certificate with your account.\nIf you encounter a `No device found` error, you might need to specify the serial port using the `--port` option.\n\nOnboard the device to your account using the `nrf_cloud_onboard` script as follows:\n\n nrf_cloud_onboard --api-key $API_KEY --csv onboard.csv\n\nIt 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.\n\nCongratulations! You have successfully registered your device to nRF Cloud, you should be able to visualize it on the [Devices panel](https://nrfcloud.com/#/devices).\n\n## Advanced Usage\n\nFor a more detailed overview of the scripts and their capabilities, refer to the [Advanced Usage Guide](https://github.com/nRFCloud/utils/blob/main/ADVANCED.md). 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.\n\n## Development installation\n\nClone the repository:\n\n git clone https://github.com/nRFCloud/utils.git nrfcloud-utils\n cd nrfcloud-utils\n\nFor development mode, you need [poetry](https://python-poetry.org/):\n\n curl -sSL https://install.python-poetry.org | python3 -\n\nMake sure `poetry` is in your PATH. If you're using `bash`:\n\n echo 'export PATH=/home/$USER/.local/bin:$PATH' | tee -a ~/.bashrc\n source ~/.bashrc\n\nInstall package dependencies, development dependencies, and the nrfcloud-utils into poetry's internal virtual environment:\n\n poetry install\n\n## Test\n\nUnit tests are included in the `tests` folder. Each test script corresponds to a script in the sources.\nStatic files used in the tests are put in the `tests/fixtures` folder.\nRunning the tests depends on a [development installation](#development-installation).\n\n poetry run pytest\n\nCheck coverage\n\n poetry run pytest --cov=. tests\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Scripts and utilities for working with the nRF Cloud",
"version": "3.0.3",
"project_urls": {
"Homepage": "https://github.com/nRFCloud/utils",
"Repository": "https://github.com/nRFCloud/utils"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "635f0c77d6b5e97700ce7b7e7859acf5b06c269ac43d1e4bf038d36c34af02aa",
"md5": "46cf08a9f231d393b055af792fd5c370",
"sha256": "b374c717d881366df4ef01bbee7ae9a9455ce57cb0b12299e8ac4c28fa12505f"
},
"downloads": -1,
"filename": "nrfcloud_utils-3.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "46cf08a9f231d393b055af792fd5c370",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 47791,
"upload_time": "2025-07-11T08:19:47",
"upload_time_iso_8601": "2025-07-11T08:19:47.335305Z",
"url": "https://files.pythonhosted.org/packages/63/5f/0c77d6b5e97700ce7b7e7859acf5b06c269ac43d1e4bf038d36c34af02aa/nrfcloud_utils-3.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "b0d9727a645daee90afa7152e980f7d8bc915b9a2809cec75436b1058c871390",
"md5": "199f64c7a02587928e8d52cfa66db698",
"sha256": "fe057350980e104c403e6044c2f1bacc59fe3020f795020f0e7b7605ab514ec9"
},
"downloads": -1,
"filename": "nrfcloud_utils-3.0.3.tar.gz",
"has_sig": false,
"md5_digest": "199f64c7a02587928e8d52cfa66db698",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 38904,
"upload_time": "2025-07-11T08:19:49",
"upload_time_iso_8601": "2025-07-11T08:19:49.274430Z",
"url": "https://files.pythonhosted.org/packages/b0/d9/727a645daee90afa7152e980f7d8bc915b9a2809cec75436b1058c871390/nrfcloud_utils-3.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-11 08:19:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nRFCloud",
"github_project": "utils",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "nrfcloud-utils"
}
JSON
