Wi-Fi: nRF Cloud

The nRF Cloud sample demonstrates an nRF Cloud application running on nRF70 Series and nRF71 Series hardware, using Wi-Fi® as the transport. It integrates Wi-Fi-based location services, periodic sensor sampling, and more. It also demonstrates how to build connected, error-tolerant applications using Zephyr’s conn_mgr connectivity management framework.

Requirements

The sample supports the following development kits:

Hardware platforms	PCA	Board name	Board target	Shields
nRF7120 DK		nrf7120dk	nrf7120dk/nrf7120/cpuapp/ns
nRF7002 DK	PCA10143	nrf7002dk	nrf7002dk/nrf5340/cpuapp/ns
nRF54LM20 DK	PCA10184	nrf54lm20dk	nrf54lm20dk/nrf54lm20b/cpuapp/ns nrf54lm20dk/nrf54lm20a/cpuapp/ns	nrf7002eb2

Note

The nRF7120 DK has not been tested on target for this sample.

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.

Features

This sample implements or demonstrates the following features:

• Error-tolerant use of the nRF Cloud CoAP API using the nRF Cloud CoAP library.

• Error-tolerant use of the nRF Cloud MQTT API using the nRF Cloud library.

• Periodic Wi-Fi location tracking by scanning nearby access points and submitting them to nRF Cloud, using the Location library.

• Fake temperature measurements.

• Transmission of sensor samples to the nRF Cloud portal as nRF Cloud Device Messages.

• Construction of valid nRF Cloud Device Messages.

• Minimal LED status indication using the Zephyr LED API.

• Definition of a user config Trace Event (temperature_alert).

• Transmission of an Alert Trace Event whenever a specified temperature limit is exceeded.

Structure and theory of operation

This sample is separated into a number of smaller functional units. The top level functional unit and entry point for the sample is the src/main.c file. This file starts three primary threads, each with a distinct function:

• The cloud connection thread (con_thread, src/cloud_connection.c) runs the Cloud connection loop, which maintains a connection to nRF Cloud.

• The application thread (app_thread, src/application.c) runs the Application thread and main application loop, which controls demo features and submits device messages to the Device message queue.

• The message queue thread (msg_thread, src/message_queue.c) then transmits these messages whenever there is an active connection. See Device message queue.

src/main.c also optionally starts a fourth thread, the led_thread, which animates any onboard LEDs if LED status indication is enabled.

When using CoAP, one additional thread starts: The CoAP shadow delta checking thread (coap_shadow, src/shadow_support_coap.c) runs the CoAP shadow delta checking loop which periodically asks nRF Cloud for any shadow changes.

Cloud connection loop

The cloud connection loop (implemented in src/cloud_connection.c) monitors network availability. It starts a connection with nRF Cloud whenever the Internet becomes reachable, and closes that connection whenever Internet access is lost. It has error handling and timeout features to ensure that failed or lost connections are re-established after a waiting period (CONFIG_CLOUD_CONNECTION_RETRY_TIMEOUT_SECONDS).

Whenever a connection to nRF Cloud is started, the cloud connection loop follows the nRF Cloud connection process. The nRF Cloud library handles most of the connection process, with exception to the following behavior:

When an MQTT device is first being associated with an nRF Cloud account, the nRF Cloud MQTT API will send a user association request notification to the device. Upon receiving this notification, the device must wait for a user association success notification, and then manually disconnect from and reconnect to nRF Cloud. Notifications of user association success are sent for every subsequent connection after this as well, so the device must only disconnect and reconnect if it previously received a user association request notification. This behavior is handled by the NRF_CLOUD_EVT_USER_ASSOCIATION_REQUEST and NRF_CLOUD_EVT_USER_ASSOCIATED cases inside the cloud_event_handler() function.

When a CoAP device attempts to connect to nRF Cloud, the connection will fail to be authenticated until the device is onboarded to an nRF Cloud account. See Onboarding a device for details.

Upon startup, the cloud connection loop also updates the device shadow. This is performed in the update_shadow() function.

Device message queue

Any thread may submit device messages to the device message queue (implemented in src/message_queue.c), where they are stored until a working connection to nRF Cloud is established. Once this happens, the message thread transmits all enqueued messages, one at a time, to nRF Cloud. If an enqueued message fails to send, it is re-queued and retried later. Transmission is paused whenever the connection to nRF Cloud is lost. If more than CONFIG_MAX_CONSECUTIVE_SEND_FAILURES messages in a row fail to send, the connection is reset and re-established after a delay (CONFIG_CLOUD_CONNECTION_RETRY_TIMEOUT_SECONDS).

The following are sent directly rather than through the queue:

• Device shadow updates.

• Ground fix requests from the Location library.

Application thread and main application loop

The application thread is implemented in the src/application.c file, and is responsible for the high-level behavior of this sample.

When it starts, it logs the reset reason code.

It performs the following major tasks:

• Establishes periodic position tracking (which the Location library performs).

• Periodically samples temperature data (using the src/temperature.c file).

• Constructs timestamped sensor sample and location device messages.

• Sends sensor sample and location device messages to the Device message queue.

• Prints temperature alerts.

Note

Periodic location tracking is handled by the Location library once it has been requested, whereas temperature samples are individually requested by the Main Application Loop.

CoAP shadow delta checking loop

The CoAP shadow delta checking thread performs the following tasks:

• Checks for a change in the device shadow with the nrf_cloud_coap_shadow_get() function.

• Parse and process the JSON shadow delta document.

• If a change is received, the thread sends the change back with the nrf_cloud_coap_shadow_state_update() function. This is necessary to prevent the device from unnecessarily receiving the same shadow delta the next time through the loop.

Temperature sensing

Temperature sensing is implemented in src/temperature.c, including generation of simulated temperature readings. For temperature readings to be visible in the nRF Cloud portal, they must be marked as enabled in the Device Shadow (handled in src/cloud_connection.c).

Location tracking

Location tracking is handled in src/location_tracking.c. This sets up a periodic location request and passes results to a callback configured by src/application.c.

For location readings to be visible in the nRF Cloud portal, they must be marked as enabled in the Device Shadow (handled in src/cloud_connection.c).

The device scans MAC addresses of nearby Wi-Fi access points and submits them to nRF Cloud to obtain a location estimate.

LED status indication

On boards that support LED status indication, this sample can indicate its current status with any on-board LEDs.

This is performed by a background thread implemented in the src/led_control.c file.

Other threads may request either a temporary or indefinite LED pattern. This wakes up the led_thread, which begins animating the requested pattern, sleeping for 100 milliseconds at a time between animation frames, until the requested pattern has completed (if it is temporary), or until a new pattern is requested in its place.

This feature is enabled by default for the board_target mentioned in the Requirements sections.

The patterns displayed, the states they describe, and the options required for them to appear are as follows:

Status	Pattern	Conditions
Trying to connect to nRF Cloud (for the first time)	Single LED lit, spinning around the square of LEDs	LED status indication is enabled
Connection to nRF Cloud lost, reconnecting	Single LED lit, spinning around the square of LEDs	The CONFIG_LED_VERBOSE_INDICATION option is enabled
Fatal error	All four LEDs blinking, 75% duty cycle	LED status indication is enabled
Device message sent successfully	Alternating checkerboard pattern (two LEDs are lit at a time, either LED1 and LED4, or LED2 and LED3)	The CONFIG_LED_VERBOSE_INDICATION option is enabled
Idle	Single LED lit, bouncing between opposite corners (LED1 and LED4)	The CONFIG_LED_CONTINUOUS_INDICATION option is enabled

Under all other circumstances, on-board LEDs are turned off.

Note

The nRF7002 DK has only two on-board LEDs, so LED status indication works only partially on that target. Patterns that require four LEDs (such as the “Device message sent successfully” and “Idle” patterns) will not display as described.

Note

The CONFIG_LED_VERBOSE_INDICATION and CONFIG_LED_CONTINUOUS_INDICATION options are enabled by default.

See Customizing LED status indication for details on customizing the LED behavior.

See Configuring LED status indication for third-party boards for details on configuring LED status indication on third-party boards.

Test counter

Every time a sensor sample is sent, this counter is incremented and its current value is sent to nRF Cloud. A plot of the counter value over time appears automatically in the nRF Cloud portal, useful for visualizing connection loss, resets, and re-establishment.

You can enable or disable the counter using the device shadow’s desired config section ("counterEnable": true/false), or force it always active with CONFIG_TEST_COUNTER.

Device message formatting

This sample, when using MQTT to communicate with nRF Cloud, constructs JSON-based device messages.

While any valid JSON string can be sent as a device message, and accepted and stored by nRF Cloud, there are some pre-designed message structures, known as schemas. The nRF Cloud portal knows how to interpret these schemas. These schemas are described in nRF Cloud application protocols for long-range devices. The device messages constructed in the src/application.c file all adhere to the general message schema.

Temperature data device messages conform to the temp deviceToCloud schemas.

This sample, when using CoAP to communicate with nRF Cloud, uses the nRF Cloud CoAP library to construct and transmit CBOR-based device messages. Some CoAP traffic, specifically AWS shadow traffic, remains in JSON format.

Configuration

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

Disabling key features

You can independently disable the following key features of this sample by setting their respective Kconfig option disabled:

Feature	Kconfig option
Location tracking	CONFIG_LOCATION_TRACKING
Temperature tracking	CONFIG_TEMP_TRACKING
Shadow handling when using CoAP	CONFIG_COAP_SHADOW

For examples, see the Configuration options section, or disable individual features using their respective Kconfig options.

Customizing LED status indication

To disable LED status indication (other than the selected idle behavior) after a connection to nRF Cloud has been established at least once, disable CONFIG_LED_VERBOSE_INDICATION.

To turn the LED off while the sample is idle (rather than show an idle pattern), disable CONFIG_LED_CONTINUOUS_INDICATION.

If you disable both of these options together, the status indicator LED remains off after a connection to nRF Cloud has been established at least once.

Configuring LED status indication for third-party boards

This sample supports four discrete GPIO LEDs (CONFIG_LED_INDICATION_GPIO and CONFIG_LED_INDICATOR_4LED). The board must have a compatible devicetree entry (gpio-leds).

To disable LED indication, enable CONFIG_LED_INDICATION_DISABLED.

Useful debugging options

To see all debug output for this sample, enable the CONFIG_WIFI_NRF_CLOUD_LOG_LEVEL_DBG option.

See also the Test counter.

Configuration options

Check and configure the following Kconfig options for the sample:

CONFIG_APP_VERSION

(string) Wi-Fi nRF Cloud sample version

CONFIG_CLOUD_CONNECTION_RETRY_TIMEOUT_SECONDS

(int) Cloud connection retry timeout (seconds)

If connecting to nRF Cloud takes longer than this timeout, it will be reattempted.

CONFIG_CLOUD_READY_TIMEOUT_SECONDS

(int) Cloud readiness timeout (seconds)

If the connection to nRF Cloud does not become ready within this timeout, the sample will reset its connection and try again.

CONFIG_DATE_TIME_ESTABLISHMENT_TIMEOUT_SECONDS

(int) Date and time establishment timeout (seconds)

The sample will wait this many seconds for the device to determine the current date and time before giving up and moving on.

CONFIG_APPLICATION_THREAD_STACK_SIZE

(int) Application Thread Stack Size (bytes)

Sets the stack size (in bytes) for the application thread of the sample.

CONFIG_CONNECTION_THREAD_STACK_SIZE

(int) Connection Thread Stack Size (bytes)

Sets the stack size (in bytes) for the connection thread of the sample.

CONFIG_MESSAGE_THREAD_STACK_SIZE

(int) Message Queue Thread Stack Size (bytes)

Sets the stack size (in bytes) for the message queue processing thread of the sample.

CONFIG_LED_THREAD_STACK_SIZE

(int) LED Thread Stack Size (bytes)

Sets the stack size (in bytes) for the LED thread.

CONFIG_MAX_OUTGOING_MESSAGES

(int) Outgoing message maximum

Sets the maximum number of device messages which may be enqueued before further messages are dropped. Increasing this value may require an increase to CONFIG_HEAP_MEM_POOL_SIZE.

CONFIG_MAX_CONSECUTIVE_SEND_FAILURES

(int) Max outgoing consecutive send failures

Sets the maximum number of device messages which may fail to send before a connection reset and cooldown is triggered.

CONFIG_CONSECUTIVE_SEND_FAILURE_COOLDOWN_SECONDS

(int) Cooldown after max consecutive send failures exceeded

If a connection reset is triggered by too many failed device messages, the sample will wait this long (in seconds) before trying again.

CONFIG_SENSOR_SAMPLE_INTERVAL_SECONDS

(int) Sensor sampling interval (seconds)

Sets the time to wait between each sensor sample.

CONFIG_LOCATION_TRACKING

(bool) Location tracking service

Uses Wi-Fi information to determine and report device location.

CONFIG_LOCATION_TRACKING_SAMPLE_INTERVAL_SECONDS

(int) Location sampling interval (seconds)

Sets the location sampling interval in seconds.

CONFIG_TEMP_TRACKING

(bool) Track temperature

Sets whether to take temperature measurements.

CONFIG_TEMP_ALERT_LIMIT

(int) Temperature limit to print alert

Sets the temperature in degrees C over which a temperature alert will be printed through serial terminal.

CONFIG_LED_INDICATION_GPIO

(bool) Enable LED indication using the gpio-leds driver

CONFIG_LED_INDICATION_DISABLED

(bool) Disable LED indication

CONFIG_LED_INDICATOR_4LED

(bool) Four binary LEDs

CONFIG_LED_INDICATOR_NONE

(bool) No indicator LEDs

CONFIG_LED_VERBOSE_INDICATION

(bool) Enables extra LED status indications

CONFIG_LED_CONTINUOUS_INDICATION

(bool) Show an idle pattern instead of turning LEDs off

CONFIG_TEST_COUNTER

(bool) Sets whether the test counter is enabled

When enabled, the test counter configuration setting in the shadow is ignored.

CONFIG_TEST_COUNTER_MULTIPLIER

(int) The number of test counter messages sent on each update

This is a way to increase the number of device messages sent by the sample. It is useful for load testing.

CONFIG_COAP_SHADOW

(bool) Updating shadow service

Updates the shadow with device information. Checks for a shadow delta periodically and processes it if received.

CONFIG_COAP_SHADOW_CHECK_RATE_SECONDS

(int) Shadow job check interval (seconds)

Sets the time to wait between each request to get any change to the device shadow.

CONFIG_COAP_SHADOW_THREAD_STACK_SIZE

(int) CoAP Shadow Thread Stack Size (bytes)

Sets the stack size (in bytes) for the CoAP shadow thread of the sample.

CONFIG_COAP_SEND_CONFIRMABLE

(bool) Send device messages as confirmable

Ensures all CoAP transfers, even for often less important messages such as sensor data, are sent as confirmable messages.

Building and running

This sample can be found under samples/wifi/nrf_cloud 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.

Building with hard-coded CA and device credentials

The CONFIG_NRF_CLOUD_PROVISION_CERTIFICATES Kconfig option allows you to use hard-coded CA and device credentials stored in unprotected program memory for connecting to nRF Cloud.

Important

The CONFIG_NRF_CLOUD_PROVISION_CERTIFICATES Kconfig option is not secure, and should be used only for demonstration purposes. Because this setting stores your device’s private key in unprotected program memory, using it makes your device vulnerable to impersonation.

Note

This is only one of several mutually exclusive ways to install credentials to your device. See Onboarding for other methods.

If you are certain you understand the inherent security risks, you can use this option as follows:

1. Follow the instructions under Onboarding with hard-coded device credentials.

2. Create a certs folder directly in the wifi_nrf_cloud folder, and copy client-cert.pem, private-key.pem, and ca-cert.pem files into it.

   Make sure not to place the new folder in the wifi_nrf_cloud/src folder by accident.

   Now, these certificates are automatically used if the CONFIG_NRF_CLOUD_PROVISION_CERTIFICATES Kconfig option is enabled.

3. Build the sample with the CONFIG_NRF_CLOUD_PROVISION_CERTIFICATES Kconfig option enabled and the device ID you created configured.

   This is required for onboarding to succeed.

   Enable the CONFIG_NRF_CLOUD_CLIENT_ID_SRC_COMPILE_TIME Kconfig option and set CONFIG_NRF_CLOUD_CLIENT_ID to the device ID.

   For example, if the device ID is 698d4c11-0ccc-4f04-89cd-6882724e3f6f:

   BashPowerShell

   west build --board *board_target* -p always -- -DCONFIG_NRF_CLOUD_PROVISION_CERTIFICATES=y -DCONFIG_NRF_CLOUD_CLIENT_ID_SRC_COMPILE_TIME=y -DCONFIG_NRF_CLOUD_CLIENT_ID=\"698d4c11-0ccc-4f04-89cd-6882724e3f6f\"
   

Setting up Wi-Fi access point credentials

This sample uses the Wi-Fi credentials library to manage Wi-Fi credentials. Before the sample can connect to a Wi-Fi network, you must add at least one credential set.

Once your device has been flashed with this sample, you can add a credential by connecting to your device’s UART interface and then entering the following command:

wifi cred add NetworkSSID WPA2-PSK NetworkPassword

Where NetworkSSID is replaced with the SSID of the Wi-Fi access point you want your device to connect to, and NetworkPassword is its password. Then, either reboot the device or use the wifi cred auto_connect command to manually trigger a connection attempt.

Important

Do not use any special characters in the SSID or password, such as spaces or quotes.

From now on, these credentials will automatically be used when the configured network is reachable.

See the Wi-Fi shell sample documentation for more details on the wifi commands.

Building with CoAP

By default, the sample uses MQTT to connect to nRF Cloud. To use CoAP instead, add the following parameter to your build command:

-DEXTRA_CONF_FILE=coap.conf

Onboarding

For your device to successfully connect to nRF Cloud, you must onboard it. The following sections outline the onboarding methods that this sample supports.

• Proceed to Onboarding a device (recommended).

• If you are building with hard-coded credentials, proceed to Onboarding with hard-coded device credentials.

Note

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

Installing nRF Cloud Utils

To perform many of the actions described in the other sections, you need to install the nRF Cloud Utils.

To install the nRF Cloud Utils, run the following command to use this package as a dependency:

pip3 install nrfcloud-utils

Onboarding a device

You can onboard your devices as follows:

First, 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.

2. Install the device and server credentials using the device_credentials_installer script from nRF Cloud Utils:

   Select the protocol (MQTT or CoAP) you built the sample for:

   MQTTCoAP

   device_credentials_installer --ca self_*_ca.pem --ca-key self_*_prv.pem --id-str device_id -s -d --verify --local-cert --cmd-type tls_cred_shell

   Where:

   • device_id is the (globally unique) ID for your device. You must use the same device ID that you configured for the sample at build time. See Building with hard-coded CA and device credentials for details on setting a compile-time device ID.

   • The .pem files are the self-signed CA certificate and private key files you created.

   The --cmd-type tls_cred_shell option indicates that the device is using the TLS Credentials Shell for run-time credentials management.

   The --local-cert option indicates that the device private key and certificate should be generated on the host machine, not on-device. This is necessary because the TLS Credentials Shell does not support CSR generation currently. Delete the device private key from your machine after it is installed to the device by this script.

   This script generates, signs, and installs a device credential for your device. The private key for this credential is generated by the device itself, and stored in secure storage.

   This script also installs any nRF Cloud root CA certificates required in a single chain to the CONFIG_NRF_CLOUD_SEC_TAG security tag (sec_tag). CoAP connections use one root CA certificate, whereas HTTPS and MQTT use another.

   If the script succeeds, you should see the following output:

   Saving nRF Cloud device onboarding CSV file onboard.csv...
   Onboarding CSV file saved, row count: 1
   

   And a new file, onboard.csv should be created. This file will be used in the next step.

3. Onboard the device to your account using the nrf_cloud_onboard script as follows:

   nrf_cloud_onboard --api-key your_api_key --csv onboard.csv

   Where your_api_key is your nRF Cloud API key from your User Account.

   Alternatively, you can Manually onboard the device to nRF Cloud.

Onboarding with hard-coded device credentials

It is possible to onboard your devices using hard-coded device credentials. If you are certain you understand the inherent security risks, you can do so as follows:

First, create a self-signed CA certificate.

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

1. Locally generate a device credential

   In addition to the arguments prescribed in that section, also include the -embed_save argument when running the create_device_credentials.py Python script:

   create_device_credentials --ca self_*_ca.pem --ca-key self_*_prv.pem -c US --cn device_id -p dev_credentials --embed-save

   Where device_id is the device ID you created, and the .pem files are the self-signed CA certificate and private key files.

   This automatically generates the following three files inside the dev_credentials folder:

   • client-cert.pem

   • private-key.pem

   • ca-cert.pem

   The client-cert.pem and private-key.pem files are specially formatted versions of the cred_<device_id>_crt.pem and cred_<device_id>_prv.pem files respectively. The ca-cert.pem is a copy of the nRF Cloud root CA in the same format. Do not confuse this CA certificate with your self-signed CA certificate. See CA certificates for server authentication in AWS IoT Core for more details.

   Your device needs these three credentials to connect successfully with nRF Cloud.

2. Onboard the device to your account with the nrf_cloud_onboard script:

   nrf_cloud_onboard --api-key your_api_key --csv onboard.csv

   Where your_api_key is your nRF Cloud API key from your User Account.

   Alternatively, you can Manually onboard the device to nRF Cloud.

3. Follow the instructions under Building with hard-coded CA and device credentials.

Creating a self-signed CA certificate for device certificate signing

Before a device can connect to nRF Cloud, it must have device credentials. You need to sign these credentials yourself using a CA certificate you create. This is referred to as your self-signed CA certificate.

To create your self-signed CA certificate:

1. Install the nRF Cloud Utils.

2. Use the nRF Cloud Utils create_ca_cert script to generate the certificate:

   create_ca_cert -c US -f self_
   

   Remember to set -c to your two-letter country code. See the Create CA Cert section in the nRF Cloud Utils documentation for more details.

   You should now have the following three files:

   • self_<self_cert_serial>_ca.pem

   • self_<self_cert_serial>_prv.pem

   • self_<self_cert_serial>_pub.pem

   Where <self_cert_serial> is your self-signed CA certificate’s serial number in hex. These three files are your self-signed CA certificate and private/public keypair. You will use them to sign device credentials.

   If you were directed here as part of other instructions, proceed to the next step of those instructions.

   Note

   You only need to generate these three files once. You can use them to sign as many device credentials as you need.

Generating device credentials locally

To generate and sign a device credential locally using your self-signed CA certificate, perform the following steps:

1. Create a globally unique device ID for the device.

   The ID can be anything you want, as long as it is not prefixed with nrf- and is globally unique. See nRF Cloud Device ID for details.

   Each device should have its own device ID, and you must use it exactly for all other actions involving that device, otherwise onboarding will fail. This ID is referred to in other steps using the term device_id.

2. Navigate to the folder where you created your self-signed CA certificate, and use the create_device_credentials.py Python script you installed to generate a self-signed certificate for the device:

   create_device_credentials -ca self_*_ca.pem -ca_key self_*_prv.pem -c US -cn device_id -f cred_

   Where device_id is the device ID you created, and the .pem files are the self-signed CA certificate and private key files you created.

   Remember to set -c to your two-letter country code. See the Create Device Credentials section in the nRF Cloud Utils documentation for more details.

   You should now have the following three files:

   • cred_<device_id>_crt.pem

   • cred_<device_id>_pub.pem

   • cred_<device_id>_prv.pem

   These three files are your device credentials, and can only be used by a single device.

   If you were directed here as part of other instructions, proceed to the next step of those instructions.

   Important

   If an attacker obtains the private key contained in cred_<device_id>_prv.pem, they will be able to impersonate your device.

Onboarding a device manually

Once you have obtained device credentials for your device, it can be onboarded.

To onboard devices manually, you can use the Bulk Onboard Devices page of the nRF Cloud portal as follows:

1. Create an onboarding CSV file named <device_id>_onboard.csv and give it the following contents:

   device_id,,,,"device_cert"

   Where device_id is replaced by the device ID you created, and device_cert is replaced by the exact contents of <device_id>_crt.pem.

   For example, if the device ID you created is 698d4c11-0ccc-4f04-89cd-6882724e3f6f:

   698d4c11-0ccc-4f04-89cd-6882724e3f6f,,,,"-----BEGIN CERTIFICATE-----
   sCC8AtbNQhzbp4y01FEzXaf5Fko3Qdq0o5LbuNpVA7S6AKAkjt17QzKJAiGWHakh
   RnwzoA2dF4wR0rMP5vR6dqBblaGAA5hN7GE2vPBHTDNZGJ6tZ9dnO6446dg9gGds
   eeadE1HdVnUj8nb+7CGm39vJ4fuNk9vogH0nMdxjCnXAinoOMRx8EklQsR747+Gz
   sxcdVYuNEb/E2vWBHTDNZGJ6tZC1JC9d6/RC3Vb1JC4tWnK9mk/Jw984ZuYugpMc
   1t9umoGFYCz0nMdxjCnXAbnoOMC5A0RxcWPzxfC5A0RH+j+mwoMxwhgfFY4EhVxp
   oCC8labNQhzRC3Vc1JC4tWnK9mpVA7k/o5LbuNpVA7S6AKAkjt17QzKJAiGWHakh
   RXwcoAndF4wPzxfC5A0RHponmwBHTDoM7GE2vPBHTDNZGJ6tZ9dnO6446dg9gGds
   eefdE1HcVnULbuNpVA7S6AKAkjxjCnt1gH0nMdxjCnXAinoOMRx8EklQsR747+Fz
   srm/VYaNEb/E2vPBHTDNZGJ6tZc1JC9d6/RC3Vc1JC4tWnK9mk/Jr984ZuYugpMc
   nt9uZTGFYCzZD0FFAA5NAC4i1PARStFycWPzxfC5A0RqodhswoMxwhgfFY4EhVx=
   -----END CERTIFICATE-----
   "
   

   Do not attempt to use this example directly, it has been filled with dummy data. See nRF Cloud REST API ProvisionDevices for more details.

   If you are onboarding more than a single device at once, you can repeat this format (separated by a newline) for each device you are onboarding. Alternatively, you can create a separate CSV file for each device you wish to onboard, and upload them individually.

2. Navigate to the Bulk Onboard Devices page of the nRF Cloud portal and upload the <device_id>_onboard.csv file you created.

   To get there from the Dashboard, click Devices under Device Management in the navigation pane on the left, then click Add Devices and select Bulk Onboard.

   Once the Bulk Onboard Devices page is open, drag in the <device_id>_onboard.csv file and click Onboard.

   You should see a message stating that the file was uploaded successfully, and a device with the device IDs you created should appear in the Devices page.

If you were directed here as part of other instructions, proceed to the next step of those instructions.

References

• RFC 7252 - The Constrained Application Protocol

• RFC 7959 - Block-Wise Transfer in CoAP

• RFC 7049 - Concise Binary Object Representation

• RFC 8610 - Concise Data Definition Language (CDDL)

• RFC 8132 - PATCH and FETCH Methods for CoAP

• RFC 9146 - Connection Identifier for DTLS 1.2

Dependencies

This sample uses the following nRF Connect SDK libraries and drivers:

• nRF Cloud

• Location

It uses the following Zephyr libraries:

• CoAP

• CoAP Client

In addition, it uses the following secure firmware component:

• Trusted Firmware-M