Cellular: nRF Device provisioning

This sample demonstrates how to use the nRF Cloud device provisioning service on your device.

Requirements 

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target
Thingy:91 X	PCA20065	thingy91x	`thingy91x/nrf9151/ns`
nRF9161 DK	PCA10153	nrf9161dk	`nrf9161dk/nrf9161/ns`
nRF9160 DK	PCA10090	nrf9160dk	`nrf9160dk/nrf9160/ns`
nRF9151 DK	PCA10171	nrf9151dk	`nrf9151dk/nrf9151/ns`

For more security, it is recommended to use the */ns variant of the board target. When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

The sample requires that the device’s private key is installed on the device and the associated device UUID is obtained from the Identity Service.

Note

This sample requires modem firmware v2.0.0 or later.

Overview 

The sample shows how the device performs the following actions:

Connects to the nRF Cloud Provisioning Service.
Retrieves the device-specific provisioning configuration.
Decodes the received commands.
Executes any AT commands, if present.
Reports the results back to the server.
If an error occurs, stops processing further commands and reports the error to the server.
Sends a FINISHED response if all commands are executed successfully and FINISHED is one of the provisioning commands.

User interface 

No user interaction with the device is required. Provisioning configuration must be defined on the server side. Refer to nRF Cloud device claiming and nRF Cloud provisioning configuration for more details.

Configuration 

See Configuring and building for information about how to permanently or temporarily change the configuration.

Configuration options 

Check and configure the following configuration options for the sample:

CONFIG_NRF_PROVISIONING_ROOT_CA_SEC_TAG: Root CA security tag for the nRF Cloud Provisioning Service. Needs to be set explicitly and if not, the compilation fails.

CONFIG_NRF_PROVISIONING_RX_BUF_SZ: Configures the response payload buffer size.

CONFIG_NRF_PROVISIONING_TX_BUF_SZ: Configures the command request buffer size.

HTTP options

CONFIG_NRF_PROVISIONING_HTTP_HOSTNAME: Configures the hostname of the nRF Cloud Provisioning Service.

CONFIG_NRF_PROVISIONING_HTTP_PORT: Configures the HTTP port of the nRF Cloud Provisioning Service.

CONFIG_NRF_PROVISIONING_HTTP_TIMEOUT_MS: Configures the HTTP timeout.

CoAP options

CONFIG_NRF_PROVISIONING_COAP_HOSTNAME: Configures the hostname of the nRF Cloud Provisioning Service.

CONFIG_NRF_PROVISIONING_COAP_PORT: Configures the CoAP port of the nRF Cloud Provisioning Service.

CONFIG_NRF_PROVISIONING_COAP_DTLS_SESSION_CACHE: Enables DTLS session cache.

Configuration files 

The sample provides predefined configuration files for typical use cases.

The following files are available:

prj.conf - Standard default configuration file.
overlay-coap.conf - Enables CoAP transfer protocol support.
overlay-at_shell.conf - Enables writing of large certificates from AT shell.

Building and running 

Note

This service is only compatible with nRF91x1 devices.

To build the sample, you can use either HTTP or CoAP transfer protocols.

west build -p -b *board_target*

west build -p -b *board_target* -- -DEXTRA_CONF_FILE="overlay-coap.conf"

Note

To use AT shell support, consider including the overlay-at_shell.conf configuration file.

This sample can be found under samples/cellular/nrf_device_provisioning in the nRF Connect SDK folder structure.

For more security, it is recommended to use the */ns variant of the board target (see the Requirements section above.) When built for this variant, the sample is configured to compile and run as a non-secure application using security by separation. Therefore, it automatically includes Trusted Firmware-M that prepares the required peripherals and secure services to be available for the application.

To build the sample, follow the instructions in Building an application for your preferred building environment. See also Programming an application for programming steps and Testing and optimization for general information about testing and debugging in the nRF Connect SDK.

Note

When building repository applications in the SDK repositories, building with sysbuild is enabled by default. If you work with out-of-tree freestanding applications, you need to manually pass the --sysbuild parameter to every build command or configure west to always use it.

Testing 

After programming the sample to your development kit, complete the following steps to test it:

Connect the kit to the computer using a USB cable. The kit is assigned a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the nrfutil device list command. Alternatively, check your operating system’s device manager or its equivalent.
Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.
Add a provisioning configuration using the nRF Cloud Provisioning Service.
Power on or reset your device.
Observe that the sample starts and connects to the LTE network.
Observe that provisioning pauses and resumes while fetching and executing provisioning commands.

Sample output 

The following is an example output of the sample when the device has not been claimed:

*** Booting nRF Connect SDK v3.0.99-ab6a14880c0a ***
*** Using Zephyr OS v4.1.99-7f1481559760 ***
<inf> nrf_provisioning_sample: nRF Device Provisioning Sample
<inf> nrf_provisioning_sample: Bringing network interface up and connecting to the network
<inf> nrf_provisioning_sample: Provisioning scheduled, next attempt in 3 seconds
<inf> nrf_provisioning_sample: Network connectivity established
<inf> nrf_provisioning_sample: IPv4 connectivity established
<inf> nrf_provisioning_sample: IPv6 connectivity established
<inf> nrf_provisioning_sample: Provisioning started
<inf> nrf_provisioning_http: Requesting commands
<inf> nrf_provisioning_http: Connected
<err> nrf_provisioning_http: Device provided wrong auth credentials
<wrn> nrf_provisioning: Unauthorized access: device is not yet claimed.
<wrn> nrf_provisioning_sample: Provisioning failed, device not claimed
<wrn> nrf_provisioning_sample: Claim the device using the device's attestation token on nrfcloud.com
<wrn> nrf_provisioning_sample: Attestation token:

<attestation_token>

<inf> nrf_provisioning_sample: Provisioning stopped
<inf> nrf_provisioning_sample: Provisioning scheduled, next attempt in 60 seconds

The following is an example output of the sample when there is no provisioning commands available from the service:

*** Booting nRF Connect SDK v3.0.99-ab6a14880c0a ***
*** Using Zephyr OS v4.1.99-7f1481559760 ***
<inf> nrf_provisioning_sample: nRF Device Provisioning Sample
<inf> nrf_provisioning_sample: Bringing network interface up and connecting to the network
<inf> nrf_provisioning_sample: Provisioning scheduled, next attempt in 1 seconds
<inf> nrf_provisioning_sample: Provisioning started
<inf> nrf_provisioning_sample: Network connectivity established
<inf> nrf_provisioning_sample: IPv4 connectivity established
<inf> nrf_provisioning_sample: IPv6 connectivity established
<inf> nrf_provisioning_http: Requesting commands
<inf> nrf_provisioning_http: Connected
<inf> nrf_provisioning_http: No commands to process on server side
<inf> nrf_provisioning_sample: Provisioning done, no commands received from the server
<inf> nrf_provisioning_sample: Provisioning stopped
<inf> nrf_provisioning_sample: Provisioning scheduled, next attempt in 60 seconds

The following is an example output when the sample is processing commands from the server:

<inf> nrf_provisioning_sample: Provisioning started
<inf> nrf_provisioning_http: Requesting commands
<inf> nrf_provisioning_http: Connected
<inf> nrf_provisioning_http: Processing commands
<inf> nrf_provisioning_sample: nRF Provisioning requires device to deactivate network
<inf> nrf_provisioning_sample: Network connectivity lost
<inf> nrf_provisioning_sample: nRF Provisioning requires device to activate network
<inf> nrf_provisioning_sample: Network connectivity established
<inf> nrf_provisioning_sample: IPv4 connectivity established
<inf> nrf_provisioning_sample: IPv6 connectivity established
<inf> nrf_provisioning_http: Sending response to server
<inf> nrf_provisioning_http: Requesting commands
<inf> nrf_provisioning_http: Connected
<inf> nrf_provisioning_http: Processing commands
<inf> nrf_provisioning_sample: nRF Provisioning requires device to deactivate network
<inf> nrf_provisioning_sample: Network connectivity lost
<inf> nrf_provisioning_sample: nRF Provisioning requires device to activate network
<inf> nrf_provisioning_sample: Network connectivity established
<inf> nrf_provisioning_sample: IPv4 connectivity established
<inf> nrf_provisioning_sample: IPv6 connectivity established
<inf> nrf_provisioning_http: Sending response to server
<inf> nrf_provisioning_http: Requesting commands
<inf> nrf_provisioning_http: Connected
<inf> nrf_provisioning_http: Processing commands
<inf> nrf_provisioning_sample: nRF Provisioning requires device to deactivate network
<inf> nrf_provisioning_sample: Network connectivity lost
<inf> nrf_provisioning_sample: nRF Provisioning requires device to activate network
<inf> nrf_provisioning_sample: Network connectivity established
<inf> nrf_provisioning_sample: IPv4 connectivity established
<inf> nrf_provisioning_sample: IPv6 connectivity established
<inf> nrf_provisioning_http: Sending response to server
<inf> nrf_provisioning_sample: Provisioning done
<inf> nrf_provisioning_sample: The device can now connect to the provisioned cloud service
<inf> nrf_provisioning_sample: Provisioning stopped
<inf> nrf_provisioning_sample: Provisioning scheduled, next attempt in 62 seconds

Provisioning with the nRF Cloud Provisioning Service using auto-onboarding 

Auto-onboarding is the easiest method to provision and onboard devices to the nRF Cloud.

Complete the following steps to provision your device:

Connect the kit to the computer using a USB cable. The kit is assigned a serial port. Serial ports are referred to as COM ports on Windows, /dev/ttyACM devices on Linux, and /dev/tty devices on macOS. To list Nordic Semiconductor devices connected to your computer together with their serial ports, open a terminal and run the nrfutil device list command. Alternatively, check your operating system’s device manager or its equivalent.
Connect to the kit with a terminal emulator (for example, the Serial Terminal app). See Testing and optimization for the required settings and steps.
Enter command nrf_provisioning token to generate an attestation token for the device
Copy the content of the response.
Log in to the nRF Cloud portal.
Select Security Services in the left sidebar. A panel opens to the right.
Select Claimed Devices.
Click Claim Device. A pop-up opens.
Copy and paste the attestation token into the Claim token text box.
Select an existing provisioning rule or create a new rule to auto-onboard the device during the claiming process.
Click Claim Device. The device is now claimed and an entry appears on the Claimed Devices page.
Open the Serial Terminal and enter command nrf_provisioning now to start the provisioning process. The device connects to the nRF Cloud Provisioning Service and retrieves the provisioning configuration.

Refer to nRF Cloud device claiming for more details on managing claimed devices.

Dependencies 

This sample uses the following nRF Connect SDK libraries:

It uses the following sdk-nrfxlib library:

Modem library