From 81921c2ded4842ed06c795736d53eb9692df8fab Mon Sep 17 00:00:00 2001 From: Pete Skeggs Date: Wed, 28 Jun 2023 17:08:42 -0700 Subject: [PATCH] docs: Add docs for nRF Cloud CoAP Document the new nrf_cloud_coap library. Signed-off-by: Pete Skeggs Co-authored-by: Pekka Niskanen --- doc/nrf/external_comp/nrf_cloud.rst | 30 +++- .../libraries/networking/nrf_cloud_coap.rst | 129 ++++++++++++++++++ .../releases/release-notes-changelog.rst | 2 + include/net/nrf_cloud_coap.h | 4 +- 4 files changed, 159 insertions(+), 6 deletions(-) create mode 100644 doc/nrf/libraries/networking/nrf_cloud_coap.rst diff --git a/doc/nrf/external_comp/nrf_cloud.rst b/doc/nrf/external_comp/nrf_cloud.rst index 63053106132..cc9e896bfa9 100644 --- a/doc/nrf/external_comp/nrf_cloud.rst +++ b/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` diff --git a/doc/nrf/libraries/networking/nrf_cloud_coap.rst b/doc/nrf/libraries/networking/nrf_cloud_coap.rst new file mode 100644 index 00000000000..91e29737173 --- /dev/null +++ b/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: diff --git a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst b/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst index 6c6a2cfc199..68337d8155a 100644 --- a/doc/nrf/releases_and_maturity/releases/release-notes-changelog.rst +++ b/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 ----------------- diff --git a/include/net/nrf_cloud_coap.h b/include/net/nrf_cloud_coap.h index 6b4c4459038..5552ab6ded3 100644 --- a/include/net/nrf_cloud_coap.h +++ b/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. *