doc: nrf_cloud: Device ID and provisioning info

Expand documentation regarding device IDs based on customer feedback. Add additional information concerning the provisioning service. Jira: IRIS-5868 Signed-off-by: Pete Skeggs <[email protected]> Co-authored-by: Justin Morton <[email protected]>
nrfconnect · Aug 22, 2024 · 5c78866 · 5c78866
1 parent 5405e07
commit 5c78866
Show file tree

Hide file tree

Showing 2 changed files with 89 additions and 10 deletions.
diff --git a/doc/nrf/external_comp/nrf_cloud.rst b/doc/nrf/external_comp/nrf_cloud.rst
@@ -27,12 +27,79 @@ To read more about nRF Cloud, see the `nRF Cloud`_ website and the `nRF Cloud do
 You can use the services offered by nRF Cloud in the following scenarios:
 
 * Device connected to nRF Cloud over CoAP.
-  The services can be used from nRF Cloud.
+
+  The services can be used through the nRF Cloud web portal.
+
 * Device connected to nRF Cloud over MQTT.
-  The services can be used from nRF Cloud.
-* Device connected to nRF Cloud over MQTT, with a customer-developed website or application that interacts with the `nRF Cloud REST API`_ to display device data and manage it in a customized way.
-* Device connected to nRF Cloud over REST, interacting using the `nRF Cloud REST API`_.
-* Device connected to a customer cloud service in a suitable manner. The services can be used from the customer cloud service that communicates over REST to the nRF Cloud REST API in a proxy configuration.
+
+  The services can be used through the nRF Cloud web portal.
+
+* Device connected to nRF Cloud over MQTT, with a customer-developed website or application.
+
+  The website or application interacts with the `nRF Cloud REST API`_ to display device data and manage it in a customized way.
+
+* Device connected to nRF Cloud over REST.
+
+  The device uses the services by interacting with the `nRF Cloud REST API`_.
+
+* Device connected to a customer cloud service in a suitable manner.
+
+  The services can be used from the customer cloud service that communicates over REST to interact with the `nRF Cloud REST API`_ in a proxy configuration.
+
+Choosing a device ID format: prefix-IMEI, device UUID, or other
+***************************************************************
+
+nRF Cloud supports a variety of device ID formats:
+
+* A prefix plus IMEI
+
+  The prefix ``nrf-`` is reserved for Nordic development kits or evaluation platforms.
+
+* The device UUID
+
+  This is a guaranteed unique ID stored in the modem.
+
+* Compile-time
+
+  A fixed device ID compiled into the firmware.
+
+* Run-time
+
+  A device ID generated by the application in an application-specific way.
+
+* Hardware ID
+
+  A device ID generated from one of a selection of hardware IDs.
+
+Nordic development kits such as the nRF9160 DK have a sticker on the back indicating the device's IMEI and PIN.
+They are preprovisioned with just-in-time provisioning (JITP) certificates so they can be added easily to nRF Cloud using the device ID ``nrf-IMEI`` and PIN.
+Device IDs that start with ``nrf-`` are checked against a database of genuine Nordic development kits and Thingy:91s.
+If the device ID (and the accompanying PIN or Hardware ID) is not found in the database, the device cannot connect.
+This means that customers using custom hardware cannot use the ``nrf-`` prefix for their device IDs.
+Choose your own PIN when creating creating JITP credentials for a custom device.
+
+The `device_credentials_installer.py`_ script uses the device UUID format by default.
+See these command line options to use other device ID formats:
+
+* ``--id_str ID_STR``
+
+  Set a device ID that is used instead of UUID.
+  Will be set as a prefix if the ``--id_imei`` option is enabled.
+  The default value for the option is empty.
+
+* ``--id_imei``
+
+  Enable using IMEI for device ID instead of UUID.
+  You can add a prefix to the IMEI with the ``--id_str`` option.
+  The default value for the option is false.
+
+Your firmware's device ID configuration must align with the options used when executing the :file:`device_credentials_installer.py` script.
+See the :ref:`configuration_device_id` section of the :ref:`lib_nrf_cloud` library documentation for more information.
+
+The :file:`device_credentials_installer.py` script automatically connects over USB or RTT to your device and installs the certificates in the modem.
+Before running the script, you must install and run firmware on the device that allows it to accept AT commands over USB or RTT, such as the :ref:AT Client <at_client_sample>` sample.
+
+If the device already contains certificates, delete the old certificates from the device by adding the ``--delete`` option.
 
 Choosing a protocol: CoAP, MQTT or REST
 ***************************************
@@ -94,23 +161,34 @@ A device can successfully connect to `nRF Cloud`_ using CoAP or REST if the foll
 A device can successfully connect to `nRF Cloud`_ using MQTT if the following requirements are met:
 
 * The device contains a correct x509 CA certificate, device certificate, and private key.
-* The device ID and device certificate are provisioned with nRF Cloud.
-* The device ID is associated with an nRF Cloud account.
+* The device ID and device certificate are provisioned and onboarded with nRF Cloud.
 
-`nRF Cloud`_ supports the following two ways for creating and installing these certificates both in the device and the cloud:
+`nRF Cloud`_ supports the following three ways for creating and installing these certificates both in the device and the cloud:
 
 * nRF Cloud provisioning service and library
 
+  This option enables devices to receive provisioning commands over the air and can then optionally onboard the devices to nRF Cloud.
+  This allows you to defer the provisioning step until a device is deployed in the field instead of during manufacturing.
+  The only manufacturing step is to request the ``attestation token`` from the device to claim the device in nRF Cloud.
+
+  The device's private key is generated by the device and stored securely.
+  It cannot be read from the device, ensuring security.
+
   See the following for more information:
 
   * `nRF Cloud Provisioning Service`_
   * `nRF Cloud Auto-onboarding`_
+  * `nRF Cloud device claiming`_
   * :ref:`nrf_cloud_multi_service_provisioning_service`
   * :ref:`lib_nrf_provisioning`
 
-* Just in time provisioning
+* Just-in-time provisioning (JITP)
+
+  .. note::
+     This option is not supported by CoAP connections.
 
-  This is not supported by CoAP connections.
+  Nordic development kits and evaluation platforms are preprovisioned with JITP certificates.
+  To use JITP for custom devices, or to replace the JITP credentials in a device, do the following:
 
   1. In your nRF Cloud account, enter the device ID in a web form, then download a JSON file containing the CA certificate, device certificate, and private key.
 

diff --git a/doc/nrf/libraries/networking/nrf_cloud.rst b/doc/nrf/libraries/networking/nrf_cloud.rst
@@ -141,6 +141,7 @@ Configuration options for device ID
 
 * :kconfig:option:`CONFIG_NRF_CLOUD_CLIENT_ID_SRC_HW_ID` - If you enable this option, the ID is automatically generated using a unique hardware ID (for example, a MAC address).
   You can choose the required hardware ID using the ``HW_ID_LIBRARY_SOURCE`` Kconfig choice.
+  See the :ref:`lib_hw_id` library documentation for details.
 
 * :kconfig:option:`CONFIG_NRF_CLOUD_CLIENT_ID_SRC_RUNTIME` - If you enable this option, the ID is set at runtime.
   If the nRF Cloud library is used directly, set the NULL-terminated ID string in the :c:struct:`nrf_cloud_init_param` structure when calling the :c:func:`nrf_cloud_init` function.