nrfconnect · rlubos · Jun 4, 2024 · Apr 12, 2024
@@ -17,7 +17,8 @@ FOTA can be used to update the device application, bootloader, and modem.
 The modem can be incrementally updated with a modem delta image.
 If the device has sufficiently large external flash storage, the modem can be entirely updated with a full modem image.
 
-nRF Cloud also helps your devices determine their location using assisted GNSS (A-GNSS) and predicted GPS (P-GPS).
+nRF Cloud also helps your devices determine their locations using GNSS.
+It uses both assisted GNSS (A-GNSS) and predicted GPS (P-GPS).
 It can determine device location from cellular and Wi-Fi network information sent by the device.
 
 Additionally, nRF Cloud allows devices to report data to the cloud for collection and analysis later.
@@ -26,8 +27,9 @@ 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 the nRF Cloud portal.
-* Device connected to nRF Cloud over MQTT. The services can be used from nRF Cloud.
+  The services can be used from nRF Cloud.
+* 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.
@@ -43,9 +45,12 @@ When choosing a protocol, consider the following:
 * What are the network data usage requirements for the device?
 * What are the carrier's network settings (NAT timeout, eDRX/PSM) and how will the settings affect device behavior?
 
-MQTT has a higher (data/power) cost to set up a connection.  However, the data size of an MQTT publish event is smaller than a comparable REST transaction.
+MQTT has a higher (data/power) cost to set up a connection than CoAP or REST.
+However, the data size of an MQTT publish event is smaller than a comparable REST transaction.
+The data size of a CoAP transfer can be the smallest of all.
 MQTT may be preferred if a device is able to maintain a connection to the broker and sends/receives data frequently.
 REST may be preferred if a device sends data infrequently or does not need to receive unsolicited data from the cloud.
+CoAP may be preferred if a device sends data infrequently, does not need to receive unsolicited data from the cloud, and must use the least amount of cellular data and the least amount of power.
 
 CoAP overview
 =============
@@ -84,7 +89,7 @@ A device can successfully connect to `nRF Cloud`_ using CoAP or REST if the foll
   The device will be visible in the nRF Cloud portal, including location service data and sensor data, if the public key is also associated with the same nRF Cloud account.
 * The device calls nRF Cloud REST APIs and provides a JSON Web Token (JWT) signed by the private key.
 * The device calls the nRF Cloud CoAP connect function, which generates and sends the JWT automatically.
-  After that, calls to the CoAP service APIs do not transmit the JWT again.
+  After that, calls to the CoAP service APIs do not transmit the JWT again but rely on the DTLS Connection ID to maintain a connection for long periods of time.
 
 A device can successfully connect to `nRF Cloud`_ using MQTT if the following requirements are met:
 
@@ -94,6 +99,15 @@ A device can successfully connect to `nRF Cloud`_ using MQTT if the following re
 
 `nRF Cloud`_ supports the following two ways for creating and installing these certificates both in the device and the cloud:
 
+* nRF Cloud provisioning service and library
+
+  See the following for more information:
+
+  * `nRF Cloud Provisioning Service`_
+  * `nRF Cloud Auto-onboarding`_
+  * :ref:`nrf_cloud_multi_service_provisioning_service`
+  * :ref:`lib_nrf_provisioning`
+
 * Just in time provisioning
 
   This is not supported by CoAP connections.
@@ -109,7 +123,7 @@ A device can successfully connect to `nRF Cloud`_ using MQTT if the following re
 
 * Preconnect provisioning
 
-  This is required for CoAP connections, and supported by MQTT or REST connections.
+  This is supported by CoAP, MQTT, and REST connections.
 
   1. Run the `device_credentials_installer.py`_ Python script to create and install credentials on the device:
 

@@ -8,13 +8,18 @@ nRF Cloud
    :depth: 2
 
 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 from supported sensor types to the 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 and FLIP sensor data
-* TLS secured MQTT as the communication protocol
-* JSON as the data format
+* 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 :ref:`lib_nrf_cloud_rest` library and the :ref:`lib_nrf_cloud_coap` library for other connectivity options.
 
 .. _lib_nrf_cloud_init:
 
@@ -52,16 +57,18 @@ The API blocks for the duration of the handshake.
 
 The cloud uses the certificates of the device for authentication.
 See :ref:`nrf9160_ug_updating_cloud_certificate` and the :ref:`modem_key_mgmt` library for more information on modem credentials.
-The certificates are generated using the device ID and PIN or HWID.
 The device ID is also the MQTT client ID.
 There are multiple configuration options for the device or client ID.
 See :ref:`configuration_device_id` for more information.
 
-As the next step, the API subscribes to an MQTT topic to start receiving user association requests from the cloud.
+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.
-When adding the device to an nRF Cloud account, the user must provide the correct device ID and PIN to nRF Cloud.
 
 The following message sequence chart shows the flow of events and the expected application responses to each event during the user association procedure:
 
@@ -99,6 +106,19 @@ When the device is successfully associated with a user on the cloud, subsequent
 
 After receiving the :c:enumerator:`NRF_CLOUD_EVT_READY` event, the application can start sending sensor data to the cloud.
 
+.. _nrf_cloud_onboarding:
+
+nRF Cloud onboarding options
+============================
+
+You can add a device to an nRF Cloud account in the following three ways:
+
+* Using the :ref:`lib_nrf_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 :file:`onboard.csv` file to nRF Cloud's **Bulk Onboard** screen or use the REST API.
+
+See: the `nRF Cloud Provisioning`_ documentation and the :ref:`nrf_cloud_multi_service_provisioning_onboarding` section of the :ref:`nrf_cloud_multi_service` sample documentation for more information.
+
 .. _configuration_device_id:
 
 Configuration options for device ID
@@ -110,7 +130,9 @@ Configuration options for device ID
   For custom hardware, use a prefix other than ``nrf-`` by modifying :kconfig:option:`CONFIG_NRF_CLOUD_CLIENT_ID_PREFIX`.
 
 * :kconfig:option:`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 requires modem firmware v1.3.0 or higher.
+  * This option is required when using `auto-onboarding <nRF Cloud Auto-onboarding_>`_.
 
 * :kconfig:option:`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 :kconfig:option:`CONFIG_NRF_CLOUD_CLIENT_ID`.
 
@@ -135,8 +157,10 @@ nRF Cloud FOTA enables the following additional features and libraries:
 * :kconfig:option:`CONFIG_DFU_TARGET` enables :ref:`lib_dfu_target`
 * :kconfig:option:`CONFIG_DOWNLOAD_CLIENT` enables :ref:`lib_download_client`
 * :kconfig:option:`CONFIG_FOTA_DOWNLOAD_PROGRESS_EVT`
+* :kconfig:option:`CONFIG_FOTA_PROGRESS_EVT_INCREMENT`
 * :kconfig:option:`CONFIG_REBOOT`
 * :kconfig:option:`CONFIG_CJSON_LIB`
+* :kconfig:option:`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.

@@ -28,10 +28,10 @@ While ionospheric corrections can also be downloaded from the satellite broadcas
 Configuration
 *************
 
-Configure the following options to enable or disable the use of this library:
+Configure the following Kconfig options to enable or disable the use of this library:
 
 * :kconfig:option:`CONFIG_NRF_CLOUD_AGNSS`
-* :kconfig:option:`CONFIG_NRF_CLOUD_MQTT` or :kconfig:option:`CONFIG_NRF_CLOUD_REST`
+* :kconfig:option:`CONFIG_NRF_CLOUD_MQTT`, :kconfig:option:`CONFIG_NRF_CLOUD_REST`, or :kconfig:option:`CONFIG_NRF_CLOUD_COAP`
 
 See :ref:`configure_application` for information on how to change configuration options.
 
@@ -44,8 +44,11 @@ A-GNSS data can be requested using one of the following methods:
 * By requesting all the available assistance data.
 
 If :kconfig:option:`CONFIG_NRF_CLOUD_MQTT` is enabled, the :c:func:`nrf_cloud_agnss_request` function is used to request by type, and the :c:func:`nrf_cloud_agnss_request_all` function is used to return all available assistance data.
+
 If :kconfig:option:`CONFIG_NRF_CLOUD_REST` is enabled, the :c:func:`nrf_cloud_rest_agnss_data_get` function is used to request A-GNSS data.
 
+If :kconfig:option:`CONFIG_NRF_CLOUD_COAP` is enabled, the :c:func:`nrf_cloud_coap_agnss_data_get` function is used to request A-GNSS data.
+
 When nRF Cloud responds with the requested A-GNSS data, the :c:func:`nrf_cloud_agnss_process` function processes the received data.
 The function parses the data and passes it on to the modem.
 
@@ -70,7 +73,7 @@ Ephemerides for 32 GPS satellites are two kB, while everything else (almanacs, U
 Ephemerides are only valid for two to four hours.
 To have valid ephemerides at all times, new ephemerides need to be downloaded on average every two hours.
 The cumulative amount of data for ephemerides for a day would then be 24 kB (24 / 2 * 2 kB).
-Of rest of the data types, almanacs are by far the largest.
+Of the rest of the data types, almanacs are by far the largest.
 Almanacs are valid for weeks, so the data usage depends mostly on the need of ephemerides.
 
 .. _agnss_filtered_ephemerides:

@@ -14,8 +14,8 @@ Alert messages are compact JSON documents that indicate a critical event, such a
 Overview
 ********
 
-This library provides an API for either REST-based or MQTT-based applications to send alerts to nRF Cloud.
-For MQTT-based applications, you can enable or disable alerts remotely using the nRF Cloud portal or REST API.
+This library provides an API for MQTT-, REST-, or CoAP-based applications to send alerts to nRF Cloud.
+For MQTT-based applications, you can enable or disable alerts remotely using the nRF Cloud portal or nRF Cloud REST API.
 
 Each alert contains the following elements, as defined in the :c:struct:`nrf_cloud_alert_info` structure :
 
@@ -53,10 +53,10 @@ The :c:func:`nrf_cloud_rest_alert_send` function initiates the connection as nee
 Configuration
 *************
 
-Configure the following options to enable or disable the library and to select the data transport method:
+Configure the following Kconfig options to enable or disable the library and to select the data transport method:
 
 * :kconfig:option:`CONFIG_NRF_CLOUD_ALERT`
-* :kconfig:option:`CONFIG_NRF_CLOUD_MQTT` or :kconfig:option:`CONFIG_NRF_CLOUD_REST`
+* :kconfig:option:`CONFIG_NRF_CLOUD_MQTT`, :kconfig:option:`CONFIG_NRF_CLOUD_REST`, or :kconfig:option:`CONFIG_NRF_CLOUD_COAP`.
 
 See :ref:`configure_application` for information on how to change configuration options.
 
@@ -73,7 +73,8 @@ To use this library, complete the following steps:
    * :c:member:`value` - Use ``0`` if not otherwise needed.
    * :c:member:`description` - Use NULL to suppress transmission of this field.
 
-#. Call the :c:func:`nrf_cloud_alert_send` function when connected to nRF Cloud using MQTT or :c:func:`nrf_cloud_rest_alert_send` when using REST.
+#. Call the :c:func:`nrf_cloud_alert_send` function when connected to nRF Cloud using MQTT or CoAP.
+#. Call the :c:func:`nrf_cloud_rest_alert_send` when using REST.
 
 Samples using the library
 *************************
@@ -95,6 +96,7 @@ This library uses the following |NCS| libraries:
 
 * :ref:`lib_nrf_cloud`
 * :ref:`lib_nrf_cloud_rest`
+* :ref:`lib_nrf_cloud_coap`
 * :ref:`lib_date_time`
 
 API documentation

@@ -10,6 +10,7 @@ nRF Cloud CoAP
 This library is an enhancement to the :ref:`lib_nrf_cloud` library.
 It enables applications to communicate with nRF Cloud using the nRF Cloud CoAP service.
 This service uses UDP network packets, encrypted using DTLS, containing compact data encoded using CBOR.
+JSON data encoding is also supported.
 This service is lighter weight than MQTT or REST and consumes less power on the device and uses less data bandwidth.
 
 Overview
@@ -32,7 +33,7 @@ The :c:func:`nrf_cloud_coap_shadow_get` function returns ``0`` whether there is
 Set the delta parameter to ``true`` to request the delta.
 The underlying CoAP result code 2.05 and an empty payload indicate that there is no delta.
 If there is a pending delta, the function returns result code 2.05 and a payload in JSON format.
-When the delta parameter is set to ``false``, the whole current delta state section is returned and it can be quite large.
+When the delta parameter is set to ``false``, the whole current state section is returned and it can be quite large.
 
 If there is a pending job, the :c:func:`nrf_cloud_coap_fota_job_get` function returns ``0`` and updates the job structure.
 If there is no pending job, the function returns ``-ENOMSG``.
@@ -56,7 +57,7 @@ You must first preprovision the device on nRF Cloud as follows:
 #. Specify the ``--coap`` option to ``device_credentials_installer.py`` to have the proper root CA certificates installed in the device.
 
 Call the :c:func:`nrf_cloud_coap_init` function once to initialize the library.
-Connect the device to LTE before calling the :c:func:`nrf_cloud_coap_connect` function.
+Connect the device to the network before calling the :c:func:`nrf_cloud_coap_connect` function.
 
 Configuration
 *************
@@ -67,19 +68,23 @@ Additionally, the following Kconfig options are available:
 
 * :kconfig:option:`CONFIG_NRF_CLOUD_COAP_SERVER_HOSTNAME`
 * :kconfig:option:`CONFIG_NRF_CLOUD_COAP_SEC_TAG`
-* :kconfig:option:`CONFIG_NRF_CLOUD_COAP_RESPONSE_TIMEOUT_MS`
+* :kconfig:option:`CONFIG_NRF_CLOUD_COAP_GF_CONF`
 * :kconfig:option:`CONFIG_NRF_CLOUD_COAP_SEND_SSIDS`
 * :kconfig:option:`CONFIG_NRF_CLOUD_SEND_DEVICE_STATUS`
 * :kconfig:option:`CONFIG_NRF_CLOUD_SEND_DEVICE_STATUS_NETWORK`
 * :kconfig:option:`CONFIG_NRF_CLOUD_SEND_DEVICE_STATUS_SIM`
 * :kconfig:option:`CONFIG_NRF_CLOUD_SEND_DEVICE_STATUS_CONN_INF`
+* :kconfig:option:`CONFIG_COAP_MAX_RETRANSMIT`
+* :kconfig:option:`CONFIG_COAP_INIT_ACK_TIMEOUT_MS`
+* :kconfig:option:`CONFIG_COAP_BACKOFF_PERCENT`
 
 Finally, configure these recommended additional options:
 
 * :kconfig:option:`CONFIG_COAP_CLIENT_BLOCK_SIZE` set to ``1024``.
 * :kconfig:option:`CONFIG_COAP_CLIENT_STACK_SIZE` set to ``6144``.
 * :kconfig:option:`CONFIG_COAP_CLIENT_THREAD_PRIORITY` set to ``0``.
-* :kconfig:option:`CONFIG_COAP_EXTENDED_OPTIONS_LEN_VALUE` set to ``32``.
+* :kconfig:option:`CONFIG_COAP_EXTENDED_OPTIONS_LEN_VALUE` set to ``64``.
+* :kconfig:option:`CONFIG_NRF_CLOUD_COAP_KEEPOPEN` set to ``y`` when using any of the NRF91x1 family of SoCs.
 
 Usage
 *****
@@ -88,10 +93,10 @@ To use this library, complete the following steps:
 
 1. Include the :file:`nrf_cloud_coap.h` file.
 #. Call the :c:func:`nrf_cloud_coap_init` function once to initialize the library.
-#. Connect the device to an LTE network.
+#. Connect the device to the network.
 #. Call the :c:func:`nrf_cloud_coap_connect` function to connect to nRF Cloud and obtain authorization to access services.
 #. Once your device is successfully connected to nRF Cloud, call any of the other functions declared in the header file to access services.
-#. Disconnect from LTE when your device does not need cloud services for a long period (for example, most of a day).
+#. Disconnect from the network when your device does not need cloud services for a long period (for example, most of a day).
 #. Call the :c:func:`nrf_cloud_coap_disconnect` function to close the network socket, which frees resources in the modem.
 
 Samples using the library
@@ -108,12 +113,12 @@ Limitations
 For CoAP-based applications, communications will not be as reliable for all nRF Cloud services as when using MQTT or REST.
 This is a fundamental aspect of the way CoAP works over UDP compared to TCP.
 
-The loss of the LTE connection or closing of the network socket will result in loss of the session information for DTLS inside the modem.
-The device must first call :c:func:`nrf_cloud_coap_disconnect`, and then :c:func:`nrf_cloud_coap_connect` once the LTE connection has been restored.
-This will result in a new full handshake of the DTLS connection and the need to re-establish authentication with the server.
+The loss of the network connection or closing of the network socket will result in loss of the session information for DTLS inside the network stack.
+The ``SO_KEEPOPEN`` socket option, when available and enabled with the :kconfig:option:`CONFIG_NRF_CLOUD_COAP_KEEPOPEN` Kconfig option, keeps the socket open during network connection loss.
+This prevents the loss of session information and eliminates the need to perform a full DTLS handshake.
 
-Due to the same limitations in the modem, a call to :c:func:`nrf_cloud_coap_disconnect` followed by a subsequent call to :c:func:`nrf_cloud_coap_connect` will require a full DTLS handshake and reauthentication.
-This is true whether or not the LTE connection is intact.
+When ``SO_KEEPOPEN`` is not available, and the network connection is lost or the socket is closed, the device must first call :c:func:`nrf_cloud_coap_disconnect`, and then :c:func:`nrf_cloud_coap_connect` once the network connection has been restored.
+This will result in a new full handshake of the DTLS connection and the need to re-establish authentication with the server.
 
 References
 **********