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 or DTLS-secured CoAP as the communication protocol

  • JSON as the data format for MQTT

  • 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 CoAP library for extended information on CoAP connectivity.

Initializing

Before using any other APIs of the module, set the CONFIG_NRF_CLOUD Kconfig option and call the nrf_cloud_init() function in the application. 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 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.

nRF Cloud onboarding options

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

Refer to the Adding a device to your account section of the nRF Cloud documentation for more information.

Configuration options for device ID

The recommended source is the device UUID, which matches the device ID that nRF Cloud provisioning tools default to. The library selects one of two UUID retrieval paths depending on the target SoC, so most applications can leave the default unchanged.

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 is enabled with the CONFIG_NRF_CLOUD_FOTA_POLL Kconfig option.

nRF Cloud FOTA enables the following additional features and libraries:

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.

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:

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 CoAP

Header file: include/net/nrf_cloud_fota_poll.h
nRF Cloud FOTA poll