nrfcloud-utils 0.0.1__tar.gz

nrfcloud_utils-0.0.1/LICENSE.txt

@@ -0,0 +1,28 @@
+Copyright (c) 2025, Nordic Semiconductor ASA
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+3. Neither the name of Nordic Semiconductor ASA nor the names of its
+   contributors may be used to endorse or promote products derived from this
+   software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY NORDIC SEMICONDUCTOR ASA AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL NORDIC SEMICONDUCTOR ASA OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

nrfcloud_utils-0.0.1/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.3
+Name: nrfcloud-utils
+Version: 0.0.1
+Summary: Scripts and utilities for working with the nRF Cloud
+License: BSD-3-Clause
+Author: Nordic Semiconductor ASA
+Requires-Python: >=3.10,<4.0
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: cbor2 (>=5.4.2.post1,<6.0.0)
+Requires-Dist: colorama (>=0.4.4,<0.5.0)
+Requires-Dist: cryptography (>=44.0.1,<45.0.0)
+Requires-Dist: pyjwt (>=2.3.0,<3.0.0)
+Requires-Dist: pynrfjprog (>=10.23.0,<11.0.0)
+Requires-Dist: pyserial (>=3.5,<4.0)
+Requires-Dist: requests (>=2.32.0,<3.0.0)
+Requires-Dist: semver (>=3.0.0,<4.0.0)
+Requires-Dist: urllib3 (>=2.2.2,<3.0.0)
+Project-URL: Repository, https://github.com/nRFCloud/utils
+Description-Content-Type: text/markdown
+
+# nRF Cloud Utilities
+
+nRF Cloud Utils is a script collection to make it easier to interface with nRF Cloud.
+A common use-case is to register devices with your account or to run a fota job.
+
+The scripts in this repository mainly use endpoints in [the REST API](https://api.nrfcloud.com/v1).
+
+The scripts are gathered from various teams and organized according to their programmatic language: [Python](https://github.com/nRFCloud/utils/tree/master/python/modem-firmware-1.3%2B).
+
+See also the official [nRF Cloud documentation](https://docs.nordicsemi.com/bundle/nrf-cloud/page/index.html).
+
+## Install
+
+Run the following command to use this package as a dependency:
+
+    pip3 install nrfcloud-utils
+
+## Requirements
+
+Do you already have an nRF Cloud account? If not, please visit [nrfcloud.com](https://nrfcloud.com) and register. Then, click on the burger on the top-right to get to your user account. Take note of your API key, you will need it soon. Note that if you are part of multiple teams on nRF Cloud, the API key will be different for each one.
+
+To register a device, you need compatible firmware flashed to it. Most scripts work with an [AT Host library](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/modem/at_host.html) enabled app or the [AT Client sample](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/samples/cellular/at_client/README.html) flashed.
+However, if you intend to use the [Provisioning Service](https://docs.nordicsemi.com/bundle/nrf-cloud/page/SecurityServices/ProvisioningService/ProvisioningOverview.html), you will need to enable its [library](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/networking/nrf_provisioning.html) in your firmware or flash the nRF Cloud Multi Service sample.
+
+## 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.
+
+The fastest way to get your device registered is using the Device Credentials Installer:
+
+    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. We need this file 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.
+
+Finally, add the device to your account with the Onboarding script:
+
+    nrf_cloud_onboard --api-key $API_KEY --csv onboard.csv
+
+You can also 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. When compiling with the nRF Cloud Libraries, make sure to use the correct KConfig options:
+
+    CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID=y
+    CONFIG_NRF_CLOUD_SEC_TAG=16842753
+
+For a more detailed overview of the scripts, see [Advanced Usage](ADVANCED.md). There, you can also find details on how to use the Provisioning Service instead of provisioning your devices locally.
+
+## 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
+

nrfcloud_utils-0.0.1/README.md

@@ -0,0 +1,83 @@
+# nRF Cloud Utilities
+
+nRF Cloud Utils is a script collection to make it easier to interface with nRF Cloud.
+A common use-case is to register devices with your account or to run a fota job.
+
+The scripts in this repository mainly use endpoints in [the REST API](https://api.nrfcloud.com/v1).
+
+The scripts are gathered from various teams and organized according to their programmatic language: [Python](https://github.com/nRFCloud/utils/tree/master/python/modem-firmware-1.3%2B).
+
+See also the official [nRF Cloud documentation](https://docs.nordicsemi.com/bundle/nrf-cloud/page/index.html).
+
+## Install
+
+Run the following command to use this package as a dependency:
+
+    pip3 install nrfcloud-utils
+
+## Requirements
+
+Do you already have an nRF Cloud account? If not, please visit [nrfcloud.com](https://nrfcloud.com) and register. Then, click on the burger on the top-right to get to your user account. Take note of your API key, you will need it soon. Note that if you are part of multiple teams on nRF Cloud, the API key will be different for each one.
+
+To register a device, you need compatible firmware flashed to it. Most scripts work with an [AT Host library](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/modem/at_host.html) enabled app or the [AT Client sample](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/samples/cellular/at_client/README.html) flashed.
+However, if you intend to use the [Provisioning Service](https://docs.nordicsemi.com/bundle/nrf-cloud/page/SecurityServices/ProvisioningService/ProvisioningOverview.html), you will need to enable its [library](https://docs.nordicsemi.com/bundle/ncs-latest/page/nrf/libraries/networking/nrf_provisioning.html) in your firmware or flash the nRF Cloud Multi Service sample.
+
+## 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.
+
+The fastest way to get your device registered is using the Device Credentials Installer:
+
+    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. We need this file 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.
+
+Finally, add the device to your account with the Onboarding script:
+
+    nrf_cloud_onboard --api-key $API_KEY --csv onboard.csv
+
+You can also 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. When compiling with the nRF Cloud Libraries, make sure to use the correct KConfig options:
+
+    CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID=y
+    CONFIG_NRF_CLOUD_SEC_TAG=16842753
+
+For a more detailed overview of the scripts, see [Advanced Usage](ADVANCED.md). There, you can also find details on how to use the Provisioning Service instead of provisioning your devices locally.
+
+## 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

nrfcloud_utils-0.0.1/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.poetry]
+name = "nrfcloud-utils"
+version = "v0.0.1"
+description = "Scripts and utilities for working with the nRF Cloud"
+authors = ["Nordic Semiconductor ASA"]
+license = "BSD-3-Clause"
+readme = "README.md"
+repository = "https://github.com/nRFCloud/utils"
+packages = [
+    { include = "nrfcloud_utils", from = "src" }
+]
+
+[tool.poetry.dependencies]
+python = "^3.10"
+pyserial = "^3.5"
+cbor2 = "^5.4.2.post1"
+colorama = "^0.4.4"
+cryptography = "^44.0.1"
+pynrfjprog = "^10.23.0"
+requests = "^2.32.0"
+urllib3 = "^2.2.2"
+semver = "^3.0.0"
+pyjwt = "^2.3.0"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^7.3.1"
+pytest-cov = "^4.0.0"
+pytest-watch = "^4.2.0"
+
+[tool.poetry.scripts]
+claim_and_provision_device = "nrfcloud_utils.claim_and_provision_device:run"
+claim_devices = "nrfcloud_utils.claim_devices:run"
+create_ca_cert = "nrfcloud_utils.create_ca_cert:run"
+create_device_credentials = "nrfcloud_utils.create_device_credentials:run"
+create_proxy_jwt = "nrfcloud_utils.create_proxy_jwt:run"
+device_credentials_installer = "nrfcloud_utils.device_credentials_installer:run"
+gather_attestation_tokens = "nrfcloud_utils.gather_attestation_tokens:run"
+modem_credentials_parser = "nrfcloud_utils.modem_credentials_parser:run"
+nrf_cloud_device_mgmt = "nrfcloud_utils.nrf_cloud_device_mgmt:run"
+nrf_cloud_onboard = "nrfcloud_utils.nrf_cloud_onboard:run"
+
+[tool.pytest.ini_options]
+addopts = ["--import-mode=importlib"]

nrfcloud_utils-0.0.1/src/nrfcloud_utils/ca_certs.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+#
+# Copyright (c) 2025 Nordic Semiconductor ASA
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+# Amazon Root CA 1 for connection to nRF Cloud: MQTT, REST, file downloads
+aws_ca  = """-----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-----
+"""
+
+# nRF Cloud CoAP CA (coap.nrfcloud.com)
+nrf_cloud_coap_ca = """-----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-----
+"""
+
+# nRF Cloud CoAP CA (dev)
+nrf_cloud_coap_ca_dev = """-----BEGIN CERTIFICATE-----
+MIIBmzCCAUKgAwIBAgIUOdcovsGv94HR18N97qIgq6mfyXowCgYIKoZIzj0EAwIw
+GjEYMBYGA1UEAwwPblJGIENsb3VkIC0gRGV2MB4XDTIzMDMzMTEyMTM1NVoXDTQ4
+MTIzMTEyMTM1NVowGjEYMBYGA1UEAwwPblJGIENsb3VkIC0gRGV2MFkwEwYHKoZI
+zj0CAQYIKoZIzj0DAQcDQgAEsWwBJY6XL1tD+3qs62oHPzIR+gxAd2suL38kvJWP
+rxeEJjDqUBP2+UvAMpDuChG/aQ3x5bw9enFlN1EUJaJrt6NmMGQwHQYDVR0OBBYE
+FHJV6uiRFXRDMrIejIAbDRUkF2CAMB8GA1UdIwQYMBaAFHJV6uiRFXRDMrIejIAb
+DRUkF2CAMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYDVR0PAQH/BAQDAgGGMAoGCCqG
+SM49BAMCA0cAMEQCIDJdB0q6IVTSMBJCjgrdqsazeUbkxWG019X/yJTQyd2QAiA8
+AmLG/0x09X2Qm+30MgNxOE4BiybZuwH9NF8KQVqQlg==
+-----END CERTIFICATE-----
+"""
+
+# nRF Cloud CoAP CA (beta)
+nrf_cloud_coap_ca_beta = """-----BEGIN CERTIFICATE-----
+MIIBnzCCAUSgAwIBAgIUWfE1+Lh4L1RP15WBkwINIgLZgtIwCgYIKoZIzj0EAwIw
+GzEZMBcGA1UEAwwQblJGIENsb3VkIC0gQmV0YTAeFw0yMzA1MDgwODI4MDdaFw00
+ODEyMzEwODI4MDdaMBsxGTAXBgNVBAMMEG5SRiBDbG91ZCAtIEJldGEwWTATBgcq
+hkjOPQIBBggqhkjOPQMBBwNCAARvM7cUr6xL9C992usqvq6aH+LLNbG6IWoiOYBo
+QJEHnFo0Zb6sIwBWPJUj/DhQxu73/oCF6IAcv5yDdXJBl0fBo2YwZDAdBgNVHQ4E
+FgQUt7i3/I+0fTq7gaFSKfxkV2wpiv0wHwYDVR0jBBgwFoAUt7i3/I+0fTq7gaFS
+KfxkV2wpiv0wEgYDVR0TAQH/BAgwBgEB/wIBADAOBgNVHQ8BAf8EBAMCAYYwCgYI
+KoZIzj0EAwIDSQAwRgIhAMDbNg4llzbBpmCKHu7Vv0WtyQnEwWbEr5eRhtX33O4a
+AiEA7sD3ABtaQa4df/uhnytbO5W2Qf8YfHtZLsrWmPKKR5w=
+-----END CERTIFICATE-----
+"""
+
+def get_ca_certs(coap=False, stage="prod"):
+    if not coap:
+        return aws_ca
+
+    if stage == "dev":
+        return nrf_cloud_coap_ca_dev + aws_ca
+    if stage == "beta":
+        return nrf_cloud_coap_ca_beta + aws_ca
+
+    return nrf_cloud_coap_ca + aws_ca