docs: Add docs for nRF Cloud CoAP

Document the new nrf_cloud_coap library.

Signed-off-by: Pete Skeggs <peter.skeggs@nordicsemi.no>
Co-authored-by: Pekka Niskanen <pekka.niskanen@nordicsemi.no>

doc/nrf/external_comp/nrf_cloud.rst

@@ -25,13 +25,15 @@ 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.
 * 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.
 
-Choosing a protocol: MQTT or REST
-*********************************
+Choosing a protocol: CoAP, MQTT or REST
+***************************************
 
 When choosing a protocol, consider the following:
 
@@ -45,6 +47,15 @@ MQTT has a higher (data/power) cost to set up a connection. However, the data s
 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 overview
+=============
+
+* The device initiates a DTLS connection to nRF Cloud.
+* nRF Cloud supports DTLS 1.2 Connection ID in order to keep the UDP connection open and usable for a long time, regardless of any NAT translation changes between the device and cloud.
+* For authentication, the device must send a JSON Web Token (JWT) with the initial connection.
+ The JWT is approximately 450 bytes.
+* Each CoAP transaction contains a CoAP header and API-specific payload.
+
 REST overview
 =============
 
@@ -66,11 +77,14 @@ MQTT overview
 Security
 ********
 
-A device can successfully connect to `nRF Cloud`_ using REST if the following requirements are met:
+A device can successfully connect to `nRF Cloud`_ using CoAP or REST if the following requirements are met:
 
 * The device contains a correct x509 CA certificate, and private key.
 * The public key derived from the private key is registered with an nRF Cloud account.
-* The device calls nRF Cloud REST APIs which require a JSON Web Token (JWT) by providing a JWT signed by the private key
+ 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.
 
 A device can successfully connect to `nRF Cloud`_ using MQTT if the following requirements are met:
 
@@ -82,6 +96,8 @@ A device can successfully connect to `nRF Cloud`_ using MQTT if the following re
 
 * Just in time provisioning
 
+ This is not supported by CoAP connections.
+
  1. In your nRF Cloud account, enter the device ID in a web form, then download a JSON file containing the CA certificate, device certificate, and private key.
 
  Alternatively, use the nRF Cloud REST API to do this.
@@ -93,6 +109,8 @@ 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.
+
  1. Run the `device_credentials_installer.py`_ Python script to create and install credentials on the device:
 
  * You need to specify a number of parameters including the device ID.
@@ -121,6 +139,7 @@ For more information on the various services, see the following documentation:
 #. :ref:`lib_nrf_cloud_pgps`
 #. :ref:`lib_nrf_cloud_alert`
 #. :ref:`lib_nrf_cloud_log`
+#. :ref:`lib_nrf_cloud_coap`
 
 Applications and samples
 ************************
@@ -129,6 +148,9 @@ The following application uses the :ref:`lib_nrf_cloud` for services in |NCS|:
 
 * :ref:`asset_tracker_v2`
 
+The following sample demonstrates nRF Cloud-specific functionality using CoAP:
+
+
 The following sample demonstrates nRF Cloud-specific functionality using MQTT:
 
 * :ref:`nrf_cloud_mqtt_multi_service`

doc/nrf/libraries/networking/nrf_cloud_coap.rst

@@ -0,0 +1,129 @@
+.. _lib_nrf_cloud_coap:
+
+nRF Cloud CoAP
+##############
+
+.. contents::
+ :local:
+ :depth: 2
+
+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.
+This service is lighter weight than MQTT or REST and consumes less power on the device and uses less data bandwidth.
+
+Overview
+********
+
+This library provides an API for CoAP-based applications to send requests to and receive responses from nRF Cloud.
+Like the REST API for nRF Cloud, CoAP is client-driven.
+The server cannot initiate transfers to the device.
+Instead, the device must periodically poll for relevant information.
+
+Polling functions
+=================
+
+The following functions poll for externally created information:
+
+* :c:func:`nrf_cloud_coap_shadow_get` - Retrieve any pending shadow delta (change)
+* :c:func:`nrf_cloud_coap_fota_job_get` - Retrieve any pending FOTA job
+
+The :c:func:`nrf_cloud_coap_shadow_get` function returns ``0`` whether there is a delta or not.
+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.
+
+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``.
+
+Supported features
+==================
+
+This library supports the following nRF Cloud services:
+
+* `nRF Cloud Location Services`_
+* `nRF Cloud FOTA`_
+* `nRF Cloud Device Messages`_
+* `nRF Cloud Device Shadows`_
+
+Requirements
+************
+
+You must first preprovision the device on nRF Cloud as follows:
+
+1. Use the `device_credentials_installer.py`_ and `nrf_cloud_provision.py`_ scripts.
+#. 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.
+
+Configuration
+*************
+
+Configure the :kconfig:option:`CONFIG_NRF_CLOUD_COAP` option to enable or disable the use of this library.
+
+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_NON_RESP_RETRIES`
+* :kconfig:option:`CONFIG_NRF_CLOUD_COAP_SEND_SSIDS`
+
+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``.
+
+Usage
+*****
+
+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.
+#. 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).
+#. Call the :c:func:`nrf_cloud_coap_disconnect` function to close the network socket, which frees resources in the modem.
+
+Samples using the library
+*************************
+
+The following |NCS| samples use this library:
+
+* :ref:`modem_shell_application`
+
+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.
+
+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.
+
+Dependencies
+************
+
+This library uses the following |NCS| libraries:
+
+* :ref:`lib_nrf_cloud`
+
+API documentation
+*****************
+
+| Header file: :file:`include/net/nrf_cloud_coap.h`
+| Source files: :file:`subsys/net/lib/nrf_cloud/src/nrf_cloud_coap.c`
+
+.. doxygengroup:: nrf_cloud_coap
+ :project: nrf
+ :members:

doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst

@@ -472,6 +472,8 @@ Libraries for networking
  * Unused internal codec function ``nrf_cloud_format_single_cell_pos_req_json()``.
  * ``nrf_cloud_location_request_msg_json_encode()`` function and replaced with :c:func:`nrf_cloud_obj_location_request_create`.
 
+* Added the :ref:`lib_nrf_cloud_coap` library for accessing nRF Cloud services using CoAP.
+
 Libraries for NFC
 -----------------
 

include/net/nrf_cloud_coap.h

@@ -47,9 +47,9 @@ int nrf_cloud_coap_connect(void);
  *
  * This function temporarily pauses the nRF Cloud CoAP connection so that
  * another DTLS socket can be opened and used. Once the new socket is no longer needed,
- * close that one, then use nrf_cloud_coap_resume() to resume using CoAP.
+ * close it and use nrf_cloud_coap_resume() to resume using CoAP.
  * Do not call nrf_cloud_coap_disconnect() nor shut down the LTE connection,
- * or else the requisite data for the socket will be discarded in the modem,
+ * or the requisite data for the socket will be discarded in the modem,
  * and the connection cannot be resumed. In that case, call nrf_cloud_coap_connect(),
  * which results in a full DTLS handshake.
  *