From 9b689fa1f11864a27b097bc44d8032085b9af9d0 Mon Sep 17 00:00:00 2001 From: Pete Skeggs Date: Wed, 21 Jun 2023 11:42:36 -0700 Subject: [PATCH] docs: Add docs for the nRF Cloud CoAP Client sample WIP. Signed-off-by: Pete Skeggs --- doc/nrf/links.txt | 5 + .../cellular/nrf_cloud_coap_client/README.rst | 143 ++++++++++++++++++ 2 files changed, 148 insertions(+) create mode 100644 samples/cellular/nrf_cloud_coap_client/README.rst diff --git a/doc/nrf/links.txt b/doc/nrf/links.txt index 9d51ad648f37..ce36a6191dba 100644 --- a/doc/nrf/links.txt +++ b/doc/nrf/links.txt @@ -772,6 +772,11 @@ .. _`CoAP response codes`: https://datatracker.ietf.org/doc/html/rfc7252#section-12.1.2 .. _`RFC 7252 - The Constrained Application Protocol`: https://datatracker.ietf.org/doc/html/rfc7252 +.. _`RFC 7959 - Block-Wise Transfer in CoAP`: https://datatracker.ietf.org/doc/html/rfc7959 +.. _`RFC 7049 - Concise Binary Object Representation`: https://datatracker.ietf.org/doc/html/rfc7049 +.. _`RFC 8610 - Concise Data Definition Language (CDDL)`: https://datatracker.ietf.org/doc/html/rfc8610 +.. _`RFC 8132 - PATCH and FETCH Methods for CoAP`: https://datatracker.ietf.org/doc/html/rfc8132 +.. _`RFC 9146 - Connection Identifier for DTLS 1.2`: https://datatracker.ietf.org/doc/html/rfc9146 .. _`Content-Range requests (IETF RFC 7233)`: https://datatracker.ietf.org/doc/html/rfc7233 diff --git a/samples/cellular/nrf_cloud_coap_client/README.rst b/samples/cellular/nrf_cloud_coap_client/README.rst new file mode 100644 index 000000000000..a552e5dfa1f8 --- /dev/null +++ b/samples/cellular/nrf_cloud_coap_client/README.rst @@ -0,0 +1,143 @@ +.. _nrf_cloud_coap_client_sample: + +nRF9160: nRF Cloud CoAP Client +############################## + +.. contents:: + :local: + :depth: 2 + +The nRF Cloud CoAP Client sample demonstrates the communication between the nRF Cloud CoAP server and an nRF9160 SiP that acts as the CoAP client. + +The sample exercises all of the nRF Cloud services: + +* FOTA +* Cellular location +* A-GPS +* P-GPS +* Device messages + +Requirements +************ + +The sample supports the following development kit: + +.. table-from-rows:: /includes/sample_board_rows.txt + :header: heading + :rows: nrf9160dk_nrf9160_ns + +.. include:: /includes/tfm.txt + +Modem firmware version 1.3.5 or above is recommended, in order to benefit from the power savings provided by DTLS Connection ID + +Overview +******** + +The nRF Cloud CoAP Client sample performs the following actions: + +#. Connect to the nRF Cloud CoAP server. +#. Gain authorization to use services by means of a JWT. +#. Request a URL for P-GPS data, then download and store it. +#. Periodically cycle through each service: + + #. Check for a FOTA job. + #. Send a fake temperature reading. + #. Get device location using cellular and/or Wi-Fi data. + #. Send a GNSS PVT location. + #. Request A-GPS data (if needed), and inject into the modem. + #. Check for a shadow delta; if one received, acknowledge back to server. + +Configuration +************* + +.. include:: /libraries/modem/nrf_modem_lib/nrf_modem_lib_trace.rst + :start-after: modem_lib_sending_traces_UART_start + :end-before: modem_lib_sending_traces_UART_end + +Building and running +******************** + +.. |sample path| replace:: :file:`samples/cellular/nrf_cloud_coap_client` + +.. include:: /includes/build_and_run_ns.txt + +Provisioning device on nRF Cloud +******************************** + +For more information, see `nRF Cloud Utilities documentation`_. + +Only do the first step below once. + + .. code-block:: console + + python3 create_ca_cert.py -c US -st OR -l Portland -o "My Company" -ou "RD" -cn example.com -e admin@example.com -f CA + Creating self-signed CA certificate... + File created: CA0x3bc7f3b014a8ad492999c594f08bbc2fcffc5fd1_ca.pem + File created: CA0x3bc7f3b014a8ad492999c594f08bbc2fcffc5fd1_prv.pem + File created: CA0x3bc7f3b014a8ad492999c594f08bbc2fcffc5fd1_pub.pem + + python3 device_credentials_installer.py --ca CA0x3bc7f3b014a8ad492999c594f08bbc2fcffc5fd1_ca.pem \ + --ca_key CA0x3bc7f3b014a8ad492999c594f08bbc2fcffc5fd1_prv.pem --id_str nrf- --id_imei -s -d --coap + ... + <- OK + Saving provisioning endpoint CSV file provision.csv... + Provisioning CSV file saved + +Once the script creates the provision.csv file, visit http://nrfcloud.com/#/provision-devices to provision the device in nRF Cloud. + +Testing +======= + +After programming the sample and all prerequisites to the development kit, test it by performing the following steps: + +1. Connect your nRF9160 DK to the PC using a USB cable and power on or reset your nRF9160 DK. +#. Open a terminal emulator and observe that the following information is displayed: + + The nRF Cloud CoAP client sample started +#. Observe that the discovered IP address of the CoAP server is displayed on the terminal emulator. +#. Observe that the nRF9160 DK sends periodic CoAP GET requests to the configured server for a configured resource after it gets LTE connection. +#. Observe that the sample either displays the response data received from the server or indicates a timeout on the terminal. + For more information on the response codes, see `COAP response codes`_. + + + +Sample output +============= + +The sample displays the data in the following format: + +.. code-block:: console + + CoAP request sent: token 0x9772 + CoAP response: code: 0x45, token 0x9772, payload: 15:39:40 + +Instead of displaying every single CoAP frame content, the sample displays only the essential data. +For the above sample output, the information displayed on the terminal conveys the following: + +* ``code:0x45`` - CoAP response code (2.05 - Content), which is constant across responses +* ``token 0x9772`` - CoAP token, which is unique per request/response pair +* ``payload: 15:39:40`` - the actual message payload (current time in UTC format) from the resource that is queried in this sample + +References +********** + +`RFC 7252 - The Constrained Application Protocol`_ + +Dependencies +************ + +This sample uses the following |NCS| libraries: + +* :ref:`lte_lc_readme` + +It uses the following `sdk-nrfxlib`_ library: + +* :ref:`nrfxlib:nrf_modem` + +It uses the following Zephyr library: + +* :ref:`CoAP ` + +In addition, it uses the following secure firmware component: + +* :ref:`Trusted Firmware-M `