From c191b6f6c7aeaa48ce842b4ede8238d4d81e7932 Mon Sep 17 00:00:00 2001 From: Pete Skeggs Date: Mon, 19 Feb 2024 16:22:07 -0800 Subject: [PATCH] samples: cellular: nRF Cloud auto onboarding 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 --- doc/nrf/links.txt | 2 + .../releases/release-notes-changelog.rst | 7 +- .../nrf_cloud_multi_service/README.rst | 170 ++++++++++-------- .../overlay-coap_nrf_provisioning.conf | 1 + .../overlay-http_nrf_provisioning.conf | 1 + .../src/cloud_connection.c | 12 +- .../nrf_cloud_rest_device_message/README.rst | 43 ++++- .../overlay-nrf_provisioning.conf | 1 + subsys/net/lib/nrf_cloud/coap/src/nrfc_dtls.c | 4 +- 9 files changed, 157 insertions(+), 84 deletions(-) diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt index d64b928d2e5b..1dadc1fd56bd 100644 --- a/doc/nrf/links.txt +++ b/doc/nrf/links.txt @@ -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`: diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index 59a006bee6d7..93b7b91bd0fd 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst @@ -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: @@ -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 -------------------- diff --git a/samples/cellular/nrf_cloud_multi_service/README.rst b/samples/cellular/nrf_cloud_multi_service/README.rst index ee7b05021d8a..98006bf6fc98 100644 --- a/samples/cellular/nrf_cloud_multi_service/README.rst +++ b/samples/cellular/nrf_cloud_multi_service/README.rst @@ -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 `). 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- 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`_. @@ -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 `_ 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:: @@ -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: @@ -966,12 +972,14 @@ For your device to successfully connect to nRF Cloud, you must `onboard it `, 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 `, 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: @@ -979,9 +987,95 @@ 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 `_ repository. +This is not necessary if you are using the `auto-onboarding `_ feature of the nRF Cloud Provisioning Service. To install the repository, clone or download it and `install the required packages `_. +.. _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 ` for the `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 `_ for more information. + +* Using scripted onboarding, as follows: + + First, :ref:`create a self-signed CA certificate `. + + 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 ` 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 ` 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 ` 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 `_ 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_standard_onboarding: Onboarding a device without the nRF Cloud Provisioning Service @@ -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 `_ page. -.. _nrf_cloud_multi_service_provisioning_service: - -Provisioning with the nRF Cloud Provisioning Service -==================================================== - -If you have :ref:`enabled support ` for the `nRF Cloud Provisioning Service`_, you can provision and onboard your device as follows: - -First, :ref:`create a self-signed CA certificate `. - -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 ` 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 ` 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 ` 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 `_ 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_onboard_hardcoded: Onboarding with hard-coded device credentials diff --git a/samples/cellular/nrf_cloud_multi_service/overlay-coap_nrf_provisioning.conf b/samples/cellular/nrf_cloud_multi_service/overlay-coap_nrf_provisioning.conf index 95d1dc8b9a03..c53fbde4d5ae 100644 --- a/samples/cellular/nrf_cloud_multi_service/overlay-coap_nrf_provisioning.conf +++ b/samples/cellular/nrf_cloud_multi_service/overlay-coap_nrf_provisioning.conf @@ -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 diff --git a/samples/cellular/nrf_cloud_multi_service/overlay-http_nrf_provisioning.conf b/samples/cellular/nrf_cloud_multi_service/overlay-http_nrf_provisioning.conf index c45683dc8e1c..ec9bc2fabb59 100644 --- a/samples/cellular/nrf_cloud_multi_service/overlay-http_nrf_provisioning.conf +++ b/samples/cellular/nrf_cloud_multi_service/overlay-http_nrf_provisioning.conf @@ -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 diff --git a/samples/cellular/nrf_cloud_multi_service/src/cloud_connection.c b/samples/cellular/nrf_cloud_multi_service/src/cloud_connection.c index f9d541e49225..c7a55d66359a 100644 --- a/samples/cellular/nrf_cloud_multi_service/src/cloud_connection.c +++ b/samples/cellular/nrf_cloud_multi_service/src/cloud_connection.c @@ -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(); diff --git a/samples/cellular/nrf_cloud_rest_device_message/README.rst b/samples/cellular/nrf_cloud_rest_device_message/README.rst index 23e6f4599e0e..3860170f3390 100644 --- a/samples/cellular/nrf_cloud_rest_device_message/README.rst +++ b/samples/cellular/nrf_cloud_rest_device_message/README.rst @@ -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 `_. +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 ` 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 ************* @@ -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`` @@ -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. diff --git a/samples/cellular/nrf_cloud_rest_device_message/overlay-nrf_provisioning.conf b/samples/cellular/nrf_cloud_rest_device_message/overlay-nrf_provisioning.conf index 26354a29ef5f..351da2ac93c9 100644 --- a/samples/cellular/nrf_cloud_rest_device_message/overlay-nrf_provisioning.conf +++ b/samples/cellular/nrf_cloud_rest_device_message/overlay-nrf_provisioning.conf @@ -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 diff --git a/subsys/net/lib/nrf_cloud/coap/src/nrfc_dtls.c b/subsys/net/lib/nrf_cloud/coap/src/nrfc_dtls.c index fec7b8b17e87..b336a3721e64 100644 --- a/subsys/net/lib/nrf_cloud/coap/src/nrfc_dtls.c +++ b/subsys/net/lib/nrf_cloud/coap/src/nrfc_dtls.c @@ -55,8 +55,8 @@ static int get_modem_info(void) return err; } - LOG_INF("IMEI: %s", mdm_param.device.imei.value_string); - LOG_INF("Modem FW version: %s", mdm_param.device.modem_fw.value_string); + LOG_INF("IMEI: %s", mdm_param.device.imei.value_string); + LOG_INF("Modem FW version: %s", mdm_param.device.modem_fw.value_string); return 0; }