Skip to content

Commit

Permalink
samples: cellular: nRF Cloud auto onboarding
Browse files Browse the repository at this point in the history 
Modify the nrf_provisioning library overlays
for nRF Cloud samples to use UUID-style device IDs.

Display the selected device ID from the
nrf_cloud_multi_service. The REST samples already
do this.

Update documentation.

Jira: IRIS-7518

Signed-off-by: Pete Skeggs <[email protected]>
  • Loading branch information
@plskeggs @jfischer-no
plskeggs authored and jfischer-no committed Feb 21, 2024
1 parent b13a9b4 commit c191b6f
Show file tree
Hide file tree
Showing 9 changed files with 157 additions and 84 deletions.
2 changes: 2 additions & 0 deletions doc/nrf/links.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1092,6 +1092,8 @@
.. _`nRF Cloud Device ID`: https://docs.nrfcloud.com/Devices/Properties/DeviceId.html
.. _`nRF Cloud Device Shadows`: https://docs.nrfcloud.com/Devices/Properties/Shadows.html
.. _`nRF Cloud Security`: https://docs.nrfcloud.com/Devices/Security/Security.html
.. _`nRF Cloud Auto-onboarding`: https://docs.nrfcloud.com/Devices/Associations/Provisioning.html#auto-onboarding
.. _`nRF Cloud device claiming`: https://docs.nordicsemi.com/bundle/nrf-cloud/page/SecurityServices/ProvisioningService/ClaimingDevices/ClaimingDeviceOwnershipPortal.html
.. _`nRF Cloud Preconnect Provisioning`: https://docs.nrfcloud.com/Devices/Associations/Provisioning.html#preconnect-provisioning
.. _`nRF Cloud Just-In-Time-Provisioning`: https://docs.nrfcloud.com/Devices/Associations/Provisioning.html#just-in-time-provisioning
.. _`nRF Cloud Onboarding`:
Expand Down
7 changes: 6 additions & 1 deletion doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -436,7 +436,8 @@ Cellular samples
* Configuration and overlay files to enable MCUboot to use the external flash on the nRF1961 DK.
* A :kconfig:option:`CONFIG_COAP_ALWAYS_CONFIRM` Kconfig option to select CON or NON CoAP transfers for functions that previously used NON transfers only.
* Support for the :ref:`lib_nrf_provisioning` library.
* An overlay file :file:`overlay-coap_nrf_provisioning.conf` to enable the :ref:`lib_nrf_provisioning` library with CoAP connectivity.
* Two overlay files :file:`overlay-http_nrf_provisioning.conf` and :file:`overlay-coap_nrf_provisioning.conf` to enable the :ref:`lib_nrf_provisioning` library with HTTP and CoAP connectivity respectively.
Both overlays specify UUID-style device IDs (not 'nrf-\ *IMEI*\ '-style) for compatibility with nRF Cloud auto-onboarding.

* Fixed:

Expand Down Expand Up @@ -506,6 +507,10 @@ Cellular samples
* The eDRX cycle to 5.12 s for both LTE-M and NB-IoT.
* The periodic TAU (RPTAU) to 12 hours.

* :ref:`nrf_cloud_rest_device_message` sample:

* Updated the :file:`overlay-nrf_provisioning.conf` overlay to specify UUID-style device IDs for compatibility with nRF Cloud auto-onboarding.

Cryptography samples
--------------------

Expand Down
170 changes: 96 additions & 74 deletions samples/cellular/nrf_cloud_multi_service/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ This sample implements or demonstrates the following features:
* Support for modem AT commands over UART using the :ref:`lib_at_host` library (default) or the :ref:`lib_at_shell` library (for builds that need the :ref:`Zephyr shell <shell_api>`).
See `nRF91x1 AT Commands Reference Guide`_ or `nRF9160 AT Commands Reference Guide`_ documentation on each AT command.
* Support for the `nRF Cloud Provisioning Service`_ using the :ref:`lib_nrf_provisioning` library.
For compatibility with auto-onboarding, the device ID uses the 128 bit UUID format rather than the older nrf-<IMEI> format.
* Support for remote execution of modem AT commands using application-specific device messages.
* Periodic cellular, Wi-Fi, and GNSS location tracking using the :ref:`lib_location` library.
* Periodic temperature sensor sampling on your `Nordic Thingy:91`_, or fake temperature measurements on your `Nordic nRF9161 DK`_, or `Nordic nRF9160 DK`_.
Expand Down Expand Up @@ -749,6 +750,10 @@ Building with nRF Cloud Provisioning Service Support

The `nRF Cloud Provisioning Service`_ allows you to securely provision and onboard your Nordic Semiconductor devices entirely over-the-air (after you have obtained an `attestation token <nRF Cloud Generating attestation tokens_>`_ for the device).

.. note::

This service is not compatible with devices that use the nRF9160, but only newer nRF91x1 devices such as the nRF9161.

You can enable support for this service by building the sample as follows:

.. tabs::
Expand Down Expand Up @@ -776,6 +781,7 @@ You can enable support for this service by building the sample as follows:
The :file:`overlay_coap.conf` overlay causes the sample to use CoAP instead of MQTT for normal communication.

Once the sample is built and flashed, proceed to :ref:`nrf_cloud_multi_service_provisioning_service` for instructions on how to provision your device with the Provisioning Service.
The device is identified using its UUID rather than its IMEI, since both overlays set the :kconfig:option:`CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID` Kconfig option.

.. _nrf_cloud_multi_service_building_wifi_scan:

Expand Down Expand Up @@ -966,22 +972,110 @@ For your device to successfully connect to nRF Cloud, you must `onboard it <nRF
The following sections outline the various onboarding methods that this sample supports.

* If you are building with :ref:`provisioning service support <nrf_cloud_multi_service_building_provisioning_service>`, proceed to :ref:`nrf_cloud_multi_service_provisioning_service`.
Use this method for nRF91x1-based devices.
* If you are not building with Provisioning Service support, proceed to :ref:`nrf_cloud_multi_service_standard_onboarding`.
Use this method for nRF9160-based devices.
* If you are building with :ref:`hard-coded credentials <nrf_cloud_multi_service_build_hardcoded>`, proceed to :ref:`nrf_cloud_multi_service_onboard_hardcoded`.
* Otherwise, proceed to :ref:`nrf_cloud_multi_service_standard_onboarding`.

.. note::
You only need to perform one of the above methods.
Select the one that best matches your build configuration.
Select the one that best matches your needs, then build and run the sample with the required build configuration.

.. _nrf_cloud_multi_service_install_nrf_utils:

Download and install nRF Cloud Utilities
========================================

To perform many of the actions in the other sections, you will need to install the `nRF Cloud Utilities <nRF Cloud Utilities documentation_>`_ repository.
This is not necessary if you are using the `auto-onboarding <nRF Cloud Auto-onboarding_>`_ feature of the nRF Cloud Provisioning Service.

To install the repository, clone or download it and `install the required packages <nRF Cloud Utilities Prerequisites>`_.

.. _nrf_cloud_multi_service_provisioning_service:

Provisioning with the nRF Cloud Provisioning Service
====================================================

The nRF Cloud Provisioning Service is only compatible with nRF91x1 devices.
For devices using the nRF9160, proceed to :ref:`nrf_cloud_multi_service_standard_onboarding`.

If you have :ref:`enabled support <nrf_cloud_multi_service_building_provisioning_service>` for the `provisioning service <nRF Cloud Provisioning Service_>`_, you can provision and onboard your device in one of two ways:

* Using auto-onboarding, the easiest method.

The nRF Cloud Provisioning Service auto-onboarding is currently compatible with CoAP and REST but not MQTT connectivity to nRF Cloud; for that, use scripted onboarding.

With this method, use the nRF Connect Serial Terminal program and the nRF Cloud portal.
The device ID used in nRF Cloud portal requires the UUID format and not the 'nrf-\ *IMEI*\ ' format.
See `device claiming <nRF Cloud device claiming_>`_ for more information.

* Using scripted onboarding, as follows:

First, :ref:`create a self-signed CA certificate <nrf_cloud_multi_service_create_self_signed_ca>`.

Then, complete the following steps for each device you wish to onboard:

1. Make sure that your device is plugged in and this sample has been flashed to it.
#. Use the :file:`claim_and_provision_device.py` Python script :ref:`you installed <nrf_cloud_multi_service_install_nrf_utils>` to provision and onboard your device

.. tabs::

.. group-tab:: MQTT

.. parsed-literal::
:class: highlight
python3 claim_and_provision_device.py --api_key "\ *your_api_key*\ " --ca="self\_\ *self_cert_serial*\ \_ca.pem" --ca_key="self\_\ *self_cert_serial*\ \_prv.pem" --install_ca --unclaim --id_imei --id_str "nrf-"
Where the :file:`.pem` files are the self-signed CA certificate and private key files :ref:`you created <nrf_cloud_multi_service_create_device_cred_locally>` and *your_api_key* is your `nRF Cloud REST API key`_.

.. group-tab:: CoAP

.. parsed-literal::
:class: highlight
python3 claim_and_provision_device.py --api_key "\ *your_api_key*\ " --ca="self\_\ *self_cert_serial*\ \_ca.pem" --ca_key="self\_\ *self_cert_serial*\ \_prv.pem" --install_ca --unclaim --id_imei --id_str "nrf-" --coap
Where the :file:`.pem` files are the self-signed CA certificate and private key files :ref:`you created <nrf_cloud_multi_service_create_device_cred_locally>` and *your_api_key* is your `nRF Cloud REST API key`_.
The ``--coap`` option indicates that the device needs the CoAP root CA installed.
See below for more details.

.. note::
This command assumes you have left the :kconfig:option:`CONFIG_NRF_CLOUD_CLIENT_ID_SRC_IMEI` option enabled and the :kconfig:option:`CONFIG_NRF_CLOUD_CLIENT_ID_PREFIX` option set to ``nrf-``.
See :ref:`configuration_device_id` to use other device ID formats.

This script automatically performs the following steps:

1. Obtains an `attestation token <nRF Cloud Generating attestation tokens_>`_ from your device over UART using the :ref:`lib_nrf_provisioning` library shell, and then *claims* your device on nRF Cloud.
2. Generates, signs, and installs a device credential for your device.

* This happens entirely over-the-air.
* The private key for this credential is generated by the device itself.
It is stored securely and never leaves the device.

3. Installs any necessary root CA certificates.

* CoAP connections use one root CA certificate, whereas HTTPS and MQTT use another.
* Devices using CoAP need both installed, since HTTPS is used for FOTA and P-GPS on CoAP devices.

This script may take a few minutes.
When it succeeds, you should see several provisioning commands be issued and succeed, and some additional final output:

.. parsed-literal::
:class: highlight
Adding device 'nrf-\ *IMEI*\ ' to cloud account...
ProvisionDevices API call response: 202 - Accepted
Done.
Where *IMEI* is the IMEI of your device.

The device should also appear in the devices list in the nRF Cloud portal.

Once the script is complete, you can connect to your device with a UART terminal to monitor its activity.

Within a few minutes of script completion, it should successfully connect to nRF Cloud and begin demonstrating the :ref:`supported nRF Cloud features <nrf_cloud_multi_service_features>`.

.. _nrf_cloud_multi_service_standard_onboarding:

Onboarding a device without the nRF Cloud Provisioning Service
Expand Down Expand Up @@ -1082,78 +1176,6 @@ Then, complete the following steps for each device you wish to onboard:

You should see a message stating that the file was uploaded successfully, and your device should appear in the `Devices <nRF Cloud Portal Devices_>`_ page.

.. _nrf_cloud_multi_service_provisioning_service:

Provisioning with the nRF Cloud Provisioning Service
====================================================

If you have :ref:`enabled support <nrf_cloud_multi_service_building_provisioning_service>` for the `nRF Cloud Provisioning Service`_, you can provision and onboard your device as follows:

First, :ref:`create a self-signed CA certificate <nrf_cloud_multi_service_create_self_signed_ca>`.

Then, complete the following steps for each device you wish to onboard:

1. Make sure your device is plugged in, and that this sample has been flashed to it.
#. Use the :file:`claim_and_provision_device.py` Python script :ref:`you installed <nrf_cloud_multi_service_install_nrf_utils>` to provision and onboard your device

.. tabs::

.. group-tab:: MQTT

.. parsed-literal::
:class: highlight
python3 claim_and_provision_device.py --api_key "\ *your_api_key*\ " --ca="self\_\ *self_cert_serial*\ \_ca.pem" --ca_key="self\_\ *self_cert_serial*\ \_prv.pem" --install_ca --unclaim --id_imei --id_str "nrf-"
Where the :file:`.pem` files are the self-signed CA certificate and private key files :ref:`you created <nrf_cloud_multi_service_create_device_cred_locally>` and *your_api_key* is your `nRF Cloud REST API key`_.

.. group-tab:: CoAP

.. parsed-literal::
:class: highlight
python3 claim_and_provision_device.py --api_key "\ *your_api_key*\ " --ca="self\_\ *self_cert_serial*\ \_ca.pem" --ca_key="self\_\ *self_cert_serial*\ \_prv.pem" --install_ca --unclaim --id_imei --id_str "nrf-" --coap
Where the :file:`.pem` files are the self-signed CA certificate and private key files :ref:`you created <nrf_cloud_multi_service_create_device_cred_locally>` and *your_api_key* is your `nRF Cloud REST API key`_.
The ``--coap`` option indicates that the device needs the CoAP root CA installed.
See below for more details.

.. note::
This command assumes you have left the :kconfig:option:`CONFIG_NRF_CLOUD_CLIENT_ID_SRC_IMEI` option enabled and the :kconfig:option:`CONFIG_NRF_CLOUD_CLIENT_ID_PREFIX` option set to ``nrf-``.
See :ref:`configuration_device_id` to use other device ID formats.

This script automatically performs the following steps:

1. Obtains an `attestation token <nRF Cloud Generating attestation tokens_>`_ from your device over UART using the :ref:`lib_nrf_provisioning` library shell, and then `claims` your device on nRF Cloud.
2. Generates, signs, and installs a device credential for your device.

* This happens entirely over-the-air.
* The private key for this credential is generated by the device itself.
It is stored securely and never leaves the device.

3. Installs any necessary root CA certificates.

* CoAP connections use one root CA certificate, whereas HTTPS and MQTT use another.
* Devices using CoAP need both installed, since HTTPS is used for FOTA and PGPS on CoAP devices.

This script may take a few minutes.
When it succeeds, you should see several provisioning commands be issued and succeed, and some additional final output:

.. parsed-literal::
:class: highlight
Adding device 'nrf-\ *IMEI*\ ' to cloud account...
ProvisionDevices API call response: 202 - Accepted
Done.
Where *IMEI* is the IMEI of your device.

The device should also appear in the devices list in the nRF Cloud portal.

Once the script is complete, you can connect to your device with a UART terminal to monitor its activity.

Within a few minutes of script completion, it should successfully connect to nRF Cloud and begin demonstrating the :ref:`supported nRF Cloud features <nrf_cloud_multi_service_features>`.

.. _nrf_cloud_multi_service_onboard_hardcoded:

Onboarding with hard-coded device credentials
Expand Down
1 change: 1 addition & 0 deletions samples/cellular/nrf_cloud_multi_service/overlay-coap_nrf_provisioning.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,6 +40,7 @@ CONFIG_ZCBOR_CANONICAL=y
# Used only if none has been provisioned
CONFIG_NRF_PROVISIONING_WITH_CERT=y
CONFIG_NRF_PROVISIONING_ROOT_CA_SEC_TAG=42
CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID=y

# Max provisioning commands per response
CONFIG_NRF_PROVISIONING_CBOR_RECORDS=20
Expand Down
1 change: 1 addition & 0 deletions samples/cellular/nrf_cloud_multi_service/overlay-http_nrf_provisioning.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ CONFIG_ZCBOR_CANONICAL=y
# Used only if none has been provisioned
CONFIG_NRF_PROVISIONING_WITH_CERT=y
CONFIG_NRF_PROVISIONING_ROOT_CA_SEC_TAG=50
CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID=y

# Max provisioning commands per response
CONFIG_NRF_PROVISIONING_CBOR_RECORDS=20
Expand Down
12 changes: 10 additions & 2 deletions samples/cellular/nrf_cloud_multi_service/src/cloud_connection.c
View file
Original file line number Diff line number Diff line change
Expand Up @@ -198,13 +198,21 @@ void disconnect_cloud(void)
*/
static bool connect_cloud(void)
{
char device_id[NRF_CLOUD_CLIENT_ID_MAX_LEN + 1];
int err;

LOG_INF("Connecting to nRF Cloud");

err = nrf_cloud_client_id_get(device_id, sizeof(device_id));
if (!err) {
LOG_INF("Device ID: %s", device_id);
} else {
LOG_ERR("Error requesting the device id: %d", err);
}

/* Clear the disconnected flag, no longer accurate. */
k_event_clear(&cloud_events, CLOUD_DISCONNECTED);

int err;

#if defined(CONFIG_NRF_CLOUD_MQTT)
/* Connect to nRF Cloud -- Non-blocking. State updates are handled in callbacks. */
err = nrf_cloud_connect();
Expand Down
43 changes: 38 additions & 5 deletions samples/cellular/nrf_cloud_rest_device_message/README.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -54,18 +54,40 @@ The configured Send LED (**LED 2** by default) (:ref:`CONFIG_REST_DEVICE_MESSAGE

.. _nrf_cloud_rest_device_message_provisioning:

Just-in-time provisioning (JITP) with nRF Cloud
***********************************************
Provisioning and onboarding your device to nRF Cloud
****************************************************

You must on-board your device to nRF Cloud for this sample to function.
You only need to do this once for each device.

This sample supports two methods to on-board your device:

Your device must be provisioned with nRF Cloud for this sample to function.
* Using `nRF Cloud Provisioning Service`_ and the auto-onboarding option.
This is the preferred option for nRF91x1-based devices.
The nRF Cloud Provisioning Service auto-onboarding is currently compatible with REST and CoAP but not MQTT connectivity to nRF Cloud; for that, use the next method.
* Using Just-in-time provisioning.
This is the legacy option.
Use this method for nRF9160-based devices.

Complete the following steps to provision your device:
Remote provisioning and auto-onboarding with nRF Cloud
======================================================

Build and run the sample with the remote provisioning overlay as explained below: :ref:`nrf_cloud_rest_device_message_remote_provisioning_overlay`.
Follow the steps outlined in `device claiming <nRF Cloud device claiming_>`_.
See `nRF Cloud Auto-onboarding`_ for more information.
The device ID is in the UUID format, not the legacy 'nrf-\ *IMEI*\ ' format.

Just-in-time provisioning (JITP) with nRF Cloud
===============================================

Complete the following steps to on-board your device:

1. Enable the :ref:`CONFIG_REST_DEVICE_MESSAGE_DO_JITP <CONFIG_REST_DEVICE_MESSAGE_DO_JITP>` option.
#. Press button 1 when prompted at startup.
#. Follow the instructions for just-in-time provisioning (JITP) printed to UART.

You only need to do this once for each device.
See `nRF Cloud Just-In-Time-Provisioning`_ for more information.
The device ID is in the legacy 'nrf-\ *IMEI*\ ' format.

Configuration
*************
Expand Down Expand Up @@ -104,6 +126,10 @@ Building and running

The configuration file for this sample is located in :file:`samples/cellular/nrf_cloud_rest_device_message`.
See :ref:`configure_application` for information on how to configure the parameters.

nRF Cloud logging overlay
=========================

To enable `Zephyr Logging`_ to nRF Cloud using the :ref:`lib_nrf_cloud_log` library, add the following parameter to your build command:

``-DOVERLAY_CONFIG=overlay_nrfcloud_logging.conf``
Expand All @@ -112,11 +138,18 @@ This overlay allows the sample and various subsystems that have logging enabled
Set the :kconfig:option:`CONFIG_NRF_CLOUD_LOG_OUTPUT_LEVEL` option to the log level of messages to send to nRF Cloud, such as ``4`` for debug log messages.
Set the :kconfig:option:`CONFIG_NRF_CLOUD_REST_DEVICE_MESSAGE_SAMPLE_LOG_LEVEL_DBG` option so that log messages are generated on each button press.

.. _nrf_cloud_rest_device_message_remote_provisioning_overlay:

Remote provisioning overlay
===========================

This overlay is for use with nRF91x1-based devices only.
To enable remote provisioning with the `nRF Cloud Provisioning Service`_ add the following parameter to your build command:

``-DOVERLAY_CONFIG=overlay-nrf_provisioning.conf``

This overlay enables the :ref:`lib_nrf_provisioning` library and its provisioning shell.
It configures the device ID to use the UUID format, not the legacy 'nrf-\ *IMEI*\ ' format.
The sample will periodically check for provisioning commands.
Press **Button 2** to manually initiate a check for provisioning commands.

Expand Down
1 change: 1 addition & 0 deletions samples/cellular/nrf_cloud_rest_device_message/overlay-nrf_provisioning.conf
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ CONFIG_NRF_PROVISIONING_LOG_LEVEL_INF=y
# Include a certificate as part of the binary. Used only if none has been provisioned
CONFIG_NRF_PROVISIONING_WITH_CERT=y
CONFIG_NRF_PROVISIONING_ROOT_CA_SEC_TAG=50
CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID=y

# Read modem attestation token and uuid from shell
CONFIG_MODEM_ATTEST_TOKEN=y
Expand Down
Loading

0 comments on commit c191b6f

Please sign in to comment.