nRF Cloud

The nRF Cloud library enables applications to connect to Nordic Semiconductor’s nRF Cloud. It abstracts and hides the details of the transport and the encoding scheme that is used for the payload and provides a simplified API interface for sending data to the cloud. The current implementation supports the following technologies:

• GNSS, TEMP, and other application-specific sensor data

• Cellular and Wi-Fi location data

• TLS-secured MQTT, TLS-secured REST, or DTLS-secured CoAP as the communication protocol

• JSON as the data format for MQTT and REST

• CBOR and JSON as the data format for CoAP

Note

The remainder of this document describes the nRF Cloud library’s MQTT connectivity support. See the nRF Cloud REST library and the nRF Cloud CoAP library for other connectivity options.

Initializing

Before using any other APIs of the module, the application must call the nrf_cloud_init() function. If this call fails, the application must not use any functions of the module.

Note

Initialize the module before starting any timers, sensor drivers, or communication on the link.

Connecting

The application can use the nrf_cloud_connect() function to connect to the cloud. This API triggers a series of events and actions in the system. If the API fails, the application must retry to connect.

If the CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD Kconfig option is not enabled, the application should monitor the connection socket. The nrf_cloud_connect() function blocks and returns success when the MQTT connection to the cloud completes.

If the CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD Kconfig option is enabled, an nRF Cloud library thread monitors the connection socket. The nrf_cloud_connect() function does not block and returns success if the connection monitoring thread has started.

When the CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD Kconfig option is enabled, an additional event, NRF_CLOUD_EVT_TRANSPORT_CONNECTING, is sent to the application. To adjust the stack size of the connection monitoring thread, set the CONFIG_NRF_CLOUD_CONNECTION_POLL_THREAD_STACK_SIZE Kconfig option. The NRF_CLOUD_EVT_TRANSPORT_CONNECT_ERROR event is sent if an error occurs while the transport connection is being established. The status field of the nrf_cloud_evt structure contains the reason for the error that is defined by nrf_cloud_connect_result. The NRF_CLOUD_EVT_TRANSPORT_DISCONNECTED event also contains additional information in the status field that is defined by nrf_cloud_disconnect_status.

First, the library tries to establish the transport for communicating with the cloud. This procedure involves a TLS handshake that might take up to three seconds. The API blocks for the duration of the handshake.

The cloud uses the certificates of the device for authentication. See Updating the nRF Cloud certificate and the Modem key management library for more information on modem credentials. The device ID is also the MQTT client ID. There are multiple configuration options for the device or client ID. See Configuration options for device ID for more information.

As the next step, the API subscribes to an MQTT topic to start receiving requests from the cloud.

Associating

This section applies to devices onboarding using JITP.

Every time nRF Cloud starts a communication session with a device, it verifies whether the device is uniquely associated with a user. If not, the user association procedure is triggered.

The following message sequence chart shows the flow of events and the expected application responses to each event during the user association procedure:

The chart shows the sequence of successful user association of an unassociated device.

Note

Currently, nRF Cloud requires that communication is re-established to update the device’s permission to send user data. The application must disconnect using the nrf_cloud_disconnect() function and then reconnect using nrf_cloud_connect().

When the device is successfully associated with a user on the cloud, subsequent connections to the cloud (also across power cycles) occur in the following sequence:

After receiving the NRF_CLOUD_EVT_READY event, the application can start sending sensor data to the cloud.

nRF Cloud onboarding options

You can add a device to an nRF Cloud account in the following three ways:

• Using the nRF Cloud device provisioning service and nRF Cloud Auto-onboarding: once the process completes, the device will be listed in your account.

• Using JITP with factory-installed certificates for Nordic development kits and Thingys: provide the device ID and PIN to nRF Cloud as indicated on the sticker.

• Using scripted provisioning and onboarding: upload the onboard.csv file to nRF Cloud’s Bulk Onboard screen or use the REST API.

See: the nRF Cloud Provisioning documentation and the Provisioning and onboarding section of the Cellular: nRF Cloud multi-service sample documentation for more information.

Configuration options for device ID

• CONFIG_NRF_CLOUD_CLIENT_ID_SRC_IMEI - If you enable this option, the ID is automatically generated using a prefix and the modem’s IMEI (<prefix><IMEI>). This is the default. You can configure the prefix by using CONFIG_NRF_CLOUD_CLIENT_ID_PREFIX. The default format of the prefix is nrf- and it is valid only for Nordic devices such as Thingy:91, Thingy:91 X, or an nRF91 Series DK. For custom hardware, use a prefix other than nrf- by modifying CONFIG_NRF_CLOUD_CLIENT_ID_PREFIX.

• CONFIG_NRF_CLOUD_CLIENT_ID_SRC_INTERNAL_UUID - If you enable this option, the ID is automatically generated using the modem’s 128-bit internal UUID, which results in a 36 character string of hexadecimal values in the 8-4-4-4-12 UUID format.

  • This option requires modem firmware v1.3.0 or higher.

  • This option is required when using auto-onboarding.

  • This option only takes effect if the CONFIG_MODEM_JWT Kconfig option is also enabled. If the CONFIG_MODEM_JWT Kconfig option is not set to y, the default CONFIG_NRF_CLOUD_CLIENT_ID_SRC_IMEI Kconfig option will be selected instead.

• CONFIG_NRF_CLOUD_CLIENT_ID_SRC_COMPILE_TIME - If you enable this option, the ID is set at compile time using the value specified by CONFIG_NRF_CLOUD_CLIENT_ID.

• 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 Hardware ID library documentation for details.

• 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 nrf_cloud_init_param structure when calling the nrf_cloud_init() function.

Firmware over-the-air (FOTA) updates

The nRF Cloud library supports FOTA updates for your nRF91 Series device. The CONFIG_NRF_CLOUD_FOTA Kconfig option is enabled by default when CONFIG_NRF_CLOUD_MQTT is set. This enables FOTA functionality in the application. FOTA support for applications using CoAP or REST is enabled with the CONFIG_NRF_CLOUD_FOTA_POLL Kconfig option.

nRF Cloud FOTA enables the following additional features and libraries:

• CONFIG_FOTA_DOWNLOAD enables FOTA download

• CONFIG_DFU_TARGET enables DFU target

• CONFIG_DOWNLOAD_CLIENT enables Download client

• CONFIG_FOTA_DOWNLOAD_PROGRESS_EVT

• CONFIG_FOTA_PROGRESS_EVT_INCREMENT

• CONFIG_REBOOT

• CONFIG_CJSON_LIB

• CONFIG_SETTINGS

For FOTA updates to work, the device must provide the information about the supported FOTA types to nRF Cloud. The device passes this information by writing a fota_v2 field containing an array of FOTA types into the serviceInfo field in the device’s shadow. The nrf_cloud_service_info_json_encode() function can be used to generate the proper JSON data to enable FOTA. Additionally, the nrf_cloud_shadow_device_status_update() function can be used to generate the JSON data and perform the shadow update.

Following are the supported FOTA types:

• "APP" - Updates the application.

• "BOOT" - Updates the Second-stage upgradable bootloader.

• "MDM_FULL" - Full modem FOTA updates the entire modem firmware image. Full modem updates require external flash memory with minimum 4 MB of available space. For an nRF91 Series device, a full modem firmware image is approximately 2 MB. Consider the power and network costs before deploying full modem FOTA updates.

• "MODEM" - Delta modem FOTA applies incremental changes between specific versions of the modem firmware. Delta modem updates are much smaller in size and do not require external memory.

• "SMP" - Updates an auxiliary device’s firmware using the Simple Management Protocol.

For example, a device that supports all the FOTA types writes the following data into the device shadow:

{
"state": {
   "reported": {
      "device": {
         "serviceInfo": {
            "fota_v2": [
            "APP",
            "MODEM",
            "MDM_FULL",
            "BOOT"
            ]
}}}}}

You can initiate FOTA updates through nRF Cloud or by using the nRF Cloud REST API (v1). If the CONFIG_NRF_CLOUD_FOTA Kconfig option is enabled, FOTA update job information is requested by the device after the MQTT connection to nRF Cloud is completed. The CONFIG_NRF_CLOUD_FOTA_AUTO_START_JOB Kconfig option controls how FOTA jobs are started on the device.

• If enabled, the nRF Cloud library starts the FOTA update job immediately upon receipt of the FOTA update job information from nRF Cloud. If the job is successfully started, the library sends the NRF_CLOUD_EVT_FOTA_START event to the application.

• If disabled, the NRF_CLOUD_EVT_FOTA_JOB_AVAILABLE event is sent to the application. When the application is ready to start the FOTA update job it must call the nrf_cloud_fota_job_start() function.

The FOTA update is in progress until the application receives either the NRF_CLOUD_EVT_FOTA_DONE or NRF_CLOUD_EVT_FOTA_ERROR event. When receiving the NRF_CLOUD_EVT_FOTA_DONE event, the application must perform any necessary cleanup and reboot the device to complete the update. The message payload of the NRF_CLOUD_EVT_FOTA_DONE event contains the nrf_cloud_fota_type value. If the value equals NRF_CLOUD_FOTA_MODEM_DELTA, the application can optionally avoid a reboot by reinitializing the modem library and then calling the nrf_cloud_modem_fota_completed() function.

See nRF Cloud FOTA for details on the FOTA service in nRF Cloud. See nRF Cloud MQTT FOTA for MQTT-specific FOTA details such as topics and payload formats.

Building FOTA images

The build system will create the files dfu_application.zip or dfu_mcuboot.zip (or both) for a properly configured application. See Output build files (image files) for more information about FOTA zip files.

When you use the files dfu_application.zip or dfu_mcuboot.zip to create an update bundle, the nRF Cloud UI populates the Name and Version fields from the manifest.json file contained within. However, you are free to change them as needed. The UI populates the Version field from only the nRF Connect SDK version field in the manifest.json file.

Alternatively, you can use the app_update.bin file to create an update bundle, but you need to enter the Name and Version fields manually. See nRF Cloud Getting Started FOTA documentation to learn how to create an update bundle.

Modem firmware is controlled by Nordic Semiconductor. A user cannot build or upload modem firmware images. Modem FOTA update bundles (full and delta) are automatically uploaded to nRF Cloud and are available to all users.

Sending sensor data

The library offers two functions, nrf_cloud_sensor_data_send() and nrf_cloud_sensor_data_stream() (lowest QoS), for sending sensor data to the cloud.

Removing the link between device and user

If you want to remove the link between a device and an nRF Cloud account, you must do this from nRF Cloud. A device cannot remove itself from an nRF Cloud account.

Location services

nRF Cloud offers location services that allow you to obtain the location of your device. The following enhancements to this library can be used to interact with nRF Cloud Location Services:

• Assisted GNSS - nRF Cloud A-GNSS

• Predicted GPS - nRF Cloud P-GPS

• Cellular Positioning - nRF Cloud location

• nRF Cloud REST - nRF Cloud REST

API documentation

Header file: include/net/nrf_cloud.h

Source files: subsys/net/lib/nrf_cloud/src/

nRF Cloud

nRF Cloud codec documentation

Header file: include/net/nrf_cloud_codec.h

nRF Cloud Codec

nRF Cloud common definitions

Header file: include/net/nrf_cloud_defs.h

nRF Cloud common defines

nRF Cloud FOTA poll for REST and CoAP

Header file: include/net/nrf_cloud_fota_poll.h

nRF Cloud FOTA poll