Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions .github/test-spec.yml
Original file line number Diff line number Diff line change
Expand Up @@ -432,7 +432,6 @@
- "include/net/nrf_cloud_location.h"
- "include/net/nrf_cloud_os.h"
- "include/net/nrf_cloud_pgps.h"
- "include/net/nrf_cloud_rest.h"
- "include/net/rest_client.h"
- "lib/at_monitor/**/*"
- "lib/at_shell/**/*"
Expand Down Expand Up @@ -466,7 +465,6 @@
- "include/net/nrf_cloud_location.h"
- "include/net/nrf_cloud_os.h"
- "include/net/nrf_cloud_pgps.h"
- "include/net/nrf_cloud_rest.h"
- "include/net/rest_client.h"
- "lib/at_monitor/**/*"
- "lib/date_time/**/*"
Expand Down
4 changes: 0 additions & 4 deletions doc/_zoomin/ncs.tags.yml
Original file line number Diff line number Diff line change
Expand Up @@ -383,9 +383,6 @@ mapping_topics:
- nrf/samples/cellular.html: ["lte"]
- nrf/samples/cellular/*.html: ["lte"]
- nrf/samples/cellular/nrf_cloud_multi_service/README.html: ["nrf-cloud"]
- nrf/samples/cellular/nrf_cloud_rest_device_message/README.html: ["nrf-cloud"]
- nrf/samples/cellular/nrf_cloud_rest_cell_location/README.html: ["nrf-cloud"]
- nrf/samples/cellular/nrf_cloud_rest_fota/README.html: ["nrf-cloud"]
- nrf/samples/cellular/modem_shell/README.html: ["at-commands"]
- nrf/samples/cellular/at_client/README.html: ["at-commands"]
- nrf/samples/dect/*.html: ["dect-nr+"]
Expand Down Expand Up @@ -426,7 +423,6 @@ mapping_topics:
- nrf/libraries/networking/nrf_cloud_location.html: ["nrf-cloud"]
- nrf/libraries/networking/nrf_cloud_log.html: ["nrf-cloud"]
- nrf/libraries/networking/nrf_cloud_pgps.html: ["nrf-cloud"]
- nrf/libraries/networking/nrf_cloud_rest.html: ["nrf-cloud"]
- nrf/libraries/networking/nrf_provisioning.html: ["at-commands"]
- nrf/libraries/networking/softap_wifi_provision.html: ["wifi", "nrf70-series", "nrf7002",
"nrf7001", "nrf7000"]
Expand Down
43 changes: 13 additions & 30 deletions doc/nrf/external_comp/nrf_cloud.rst
Original file line number Diff line number Diff line change
Expand Up @@ -38,10 +38,6 @@ You can use the services offered by nRF Cloud in the following scenarios:

The website or application 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.

The device uses the services by interacting with 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 interact with the `nRF Cloud REST API`_ in a proxy configuration.
Expand Down Expand Up @@ -94,7 +90,7 @@ Before running the script, you must install and run firmware on the device that

If the device already contains certificates, delete the old certificates from the device by adding the ``--delete`` option.

Choosing a protocol: CoAP, MQTT or REST
Choosing a protocol: CoAP and MQTT
***************************************

When choosing a protocol, consider the following:
Expand All @@ -105,11 +101,9 @@ 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 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 has a higher (data/power) cost to set up a connection than CoAP.
The data size of a CoAP transfer is smaller than in MQTT.
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
Expand All @@ -121,15 +115,6 @@ CoAP overview
The JWT is approximately 450 bytes.
* Each CoAP transaction contains a CoAP header and API-specific payload.

REST overview
=============

* The device initiates a TLS connection to nRF Cloud.
* nRF Cloud supports a connection keep-alive/idle time of 60 seconds for REST API sockets.
* For authentication, the device must send a JSON Web Token (JWT) with each REST transaction.
The JWT is approximately 450 bytes, but can be larger depending on the claims.
* Each REST transaction contains HTTP headers, including the JWT, and any API specific payload.

MQTT overview
=============

Expand All @@ -142,7 +127,7 @@ MQTT overview
Security
********

A device can successfully connect to `nRF Cloud`_ using CoAP or REST if the following requirements are met:
A device can successfully connect to `nRF Cloud`_ using CoAP 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.
Expand Down Expand Up @@ -177,7 +162,7 @@ A device can successfully connect to `nRF Cloud`_ using MQTT if the following re

* Preconnect provisioning

This is supported by CoAP, MQTT, and REST connections.
This is supported by CoAP and MQTT connections.

1. Run the `device_credentials_installer.py`_ Python script to create and install credentials on the device:

Expand All @@ -197,7 +182,7 @@ A device can successfully connect to `nRF Cloud`_ using MQTT if the following re
|NCS| library support
*********************

The |NCS| provides the :ref:`lib_nrf_cloud` library, which if enabled, allows you to connect your devices to nRF Cloud and use the update, location, and connectivity services using MQTT or REST.
The |NCS| provides the :ref:`lib_nrf_cloud` library, which if enabled, allows you to connect your devices to nRF Cloud and use the update, location, and connectivity services using MQTT or CoAP.

For more information on the various services, see the following documentation:

Expand All @@ -213,21 +198,19 @@ Applications and samples

The following sample demonstrates nRF Cloud-specific functionality using CoAP:

* :ref:`nrf_cloud_multi_service`
* :ref:`modem_shell_application`
* :ref:`nrf_cloud_coap_device_message`
* :ref:`nrf_cloud_coap_cell_location`
* :ref:`nrf_cloud_coap_fota_sample`

The following sample demonstrates nRF Cloud-specific functionality using MQTT:

* :ref:`nrf_cloud_multi_service`

The following samples demonstrate nRF Cloud-specific functionality using REST:

* :ref:`nrf_cloud_rest_fota`
* :ref:`nrf_cloud_rest_device_message`
* :ref:`nrf_cloud_rest_cell_location`
* :ref:`nrf_cloud_mqtt_device_message`
* :ref:`nrf_cloud_mqtt_cell_location`
* :ref:`nrf_cloud_mqtt_fota`

Other related samples and applications that use nRF Cloud services:

* :ref:`gnss_sample`
* :ref:`modem_shell_application`
* :ref:`location_sample`
* :ref:`nrf_provisioning_sample`
12 changes: 5 additions & 7 deletions doc/nrf/libraries/modem/location.rst
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,7 @@ The supported location methods are as follows:
* A-GNSS and P-GPS are managed with :ref:`lib_nrf_cloud_agnss` and :ref:`lib_nrf_cloud_pgps`.
* The application may also use some other source for the data and use :c:func:`location_agnss_data_process` and :c:func:`location_pgps_data_process` to pass the data to the Location library.
* The data format of A-GNSS or P-GPS must be as received from :ref:`lib_nrf_cloud_agnss`.
* The data transport method for :ref:`lib_nrf_cloud_agnss` and :ref:`lib_nrf_cloud_pgps` can be configured to be either MQTT (:kconfig:option:`CONFIG_NRF_CLOUD_MQTT`) or REST (:kconfig:option:`CONFIG_NRF_CLOUD_REST`).
If different transport is desired for different location methods, (:kconfig:option:`CONFIG_NRF_CLOUD_MQTT`) and (:kconfig:option:`CONFIG_NRF_CLOUD_REST`) can be enabled simultaneously. In such a case, MQTT takes
precedence as the transport method of GNSS assistance data.
* You can configure the data transport method for :ref:`lib_nrf_cloud_agnss` and :ref:`lib_nrf_cloud_pgps` to be either MQTT (:kconfig:option:`CONFIG_NRF_CLOUD_MQTT`) or CoAP (:kconfig:option:`CONFIG_NRF_CLOUD_COAP`).
* Note that acquiring GNSS fix only starts when LTE connection, more specifically Radio Resource Control (RRC) connection, is idle.
Also, if A-GNSS is not used and Power Saving Mode (PSM) is enabled, the Location library will wait for the modem to enter PSM.
* Selectable location accuracy (low/normal/high).
Expand Down Expand Up @@ -76,7 +74,7 @@ Here are details related to the services handling cell information for cellular

* Services can be handled by the application by enabling the :kconfig:option:`CONFIG_LOCATION_SERVICE_EXTERNAL` Kconfig option, in which case rest of the service configurations are ignored.
* The service is selected in the :c:struct:`location_method_config` structure when requesting for location.
* You can configure the data transport method for the `nRF Cloud Location Services <nRF Cloud Location Services documentation_>`_ to either MQTT (:kconfig:option:`CONFIG_NRF_CLOUD_MQTT`) or REST (:kconfig:option:`CONFIG_NRF_CLOUD_REST`).
* You can configure the data transport method for the `nRF Cloud Location Services <nRF Cloud Location Services documentation_>`_ to either MQTT (:kconfig:option:`CONFIG_NRF_CLOUD_MQTT`) or CoAP (:kconfig:option:`CONFIG_NRF_CLOUD_COAP`).

Diagrams
========
Expand Down Expand Up @@ -192,7 +190,7 @@ nRF Cloud certificates
======================

When using nRF Cloud for any location data, you must have the certificate provisioned.
An nRF91 Series DK comes pre-provisioned with certificates for nRF Cloud.
To provision and onboard your device, install `nRF Cloud Utils`_ and follow the instructions in the README.

Location service accounts
=========================
Expand Down Expand Up @@ -269,7 +267,7 @@ Configuring the obstructed visibility detection is always a tradeoff between pow

To enable the transport method, set the :kconfig:option:`CONFIG_NRF_CLOUD` Kconfig option and select one of the following options:

* :kconfig:option:`CONFIG_NRF_CLOUD_REST` - Uses REST APIs to communicate with `nRF Cloud`_ if :kconfig:option:`CONFIG_NRF_CLOUD_MQTT` is not set.
* :kconfig:option:`CONFIG_NRF_CLOUD_COAP` - Uses CoAP transport to communicate with `nRF Cloud`_.
* :kconfig:option:`CONFIG_NRF_CLOUD_MQTT` - Uses MQTT transport to communicate with `nRF Cloud`_.

Both cellular and Wi-Fi location services are handled externally by the application or selected using the runtime configuration, in which case you must first configure the available services.
Expand Down Expand Up @@ -384,7 +382,7 @@ This library uses the following |NCS| libraries:
* :ref:`lib_nrf_cloud`
* :ref:`lib_nrf_cloud_agnss`
* :ref:`lib_nrf_cloud_pgps`
* :ref:`lib_nrf_cloud_rest`
* :ref:`lib_nrf_cloud_coap`

It uses the following `sdk-nrfxlib`_ library:

Expand Down
11 changes: 5 additions & 6 deletions doc/nrf/libraries/networking/nrf_cloud.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,13 @@ The current implementation supports the following technologies:

* 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
* 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 :ref:`lib_nrf_cloud_rest` library and the :ref:`lib_nrf_cloud_coap` library for other connectivity options.
See the :ref:`lib_nrf_cloud_coap` library for extended information on CoAP connectivity.

.. _lib_nrf_cloud_init:

Expand Down Expand Up @@ -118,7 +118,7 @@ Firmware over-the-air (FOTA) updates
The nRF Cloud library supports FOTA updates for your nRF91 Series device.
The :kconfig:option:`CONFIG_NRF_CLOUD_FOTA` Kconfig option is enabled by default when :kconfig:option:`CONFIG_NRF_CLOUD_MQTT` is set.
This enables FOTA functionality in the application.
FOTA support for applications using CoAP or REST is enabled with the :kconfig:option:`CONFIG_NRF_CLOUD_FOTA_POLL` Kconfig option.
FOTA support for applications using CoAP is enabled with the :kconfig:option:`CONFIG_NRF_CLOUD_FOTA_POLL` Kconfig option.

nRF Cloud FOTA enables the following additional features and libraries:

Expand Down Expand Up @@ -222,7 +222,6 @@ The following enhancements to this library can be used to interact with `nRF Clo
* Assisted GNSS - :ref:`lib_nrf_cloud_agnss`
* Predicted GPS - :ref:`lib_nrf_cloud_pgps`
* Cellular Positioning - :ref:`lib_nrf_cloud_cell_pos`
* nRF Cloud REST - :ref:`lib_nrf_cloud_rest`

.. _nrf_cloud_api:

Expand All @@ -248,7 +247,7 @@ nRF Cloud common definitions

.. doxygengroup:: nrf_cloud_defs

nRF Cloud FOTA poll for REST and CoAP
nRF Cloud FOTA poll for CoAP
****************************************

| Header file: :file:`include/net/nrf_cloud_fota_poll.h`
Expand Down
4 changes: 1 addition & 3 deletions doc/nrf/libraries/networking/nrf_cloud_agnss.rst
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,7 @@ Configuration
To enable this library, set the :kconfig:option:`CONFIG_NRF_CLOUD` Kconfig option and configure the following options:

* :kconfig:option:`CONFIG_NRF_CLOUD_AGNSS`
* :kconfig:option:`CONFIG_NRF_CLOUD_MQTT`, :kconfig:option:`CONFIG_NRF_CLOUD_REST`, or :kconfig:option:`CONFIG_NRF_CLOUD_COAP`
* :kconfig:option:`CONFIG_NRF_CLOUD_MQTT` or :kconfig:option:`CONFIG_NRF_CLOUD_COAP`

See :ref:`configure_application` for information on how to change configuration options.

Expand All @@ -45,8 +45,6 @@ A-GNSS data can be requested using one of the following methods:

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.
Expand Down
21 changes: 6 additions & 15 deletions doc/nrf/libraries/networking/nrf_cloud_log.rst
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,8 @@ The logging backend can either use JSON encoding or `Dictionary-based Logging`_
Overview
********

This library provides an API for REST-, MQTT-, or CoAP-based applications to send logs to nRF Cloud.
This library provides an API for MQTT- or CoAP-based applications to send logs to nRF Cloud.
For MQTT- and CoAP-based applications, you can enable or disable logging as well as change the logging level remotely using the nRF Cloud portal or `nRF Cloud Patch Device State`_ REST API.
For REST-based applications, the enabled state and logging level can be controlled at compile time or at run time on the device, but not from the cloud.

Each JSON log message contains the following elements:

Expand Down Expand Up @@ -55,7 +54,7 @@ The sequence number is set to a monotonically-increasing value that resets to ``
Supported backends
==================

When so configured, this library includes a Zephyr logging backend that can transport log messages to nRF Cloud using REST, MQTT, or CoAP.
When so configured, this library includes a Zephyr logging backend that can transport log messages to nRF Cloud using MQTT or CoAP.
The logging backend can also use either JSON messages or dictionary-based compact binary messages.

Multiple JSON log messages are sent together as a JSON array to the `d2c/bulk device message topic <nRF Cloud MQTT Topics_>`_.
Expand All @@ -70,7 +69,6 @@ Requirements
************

The device must be connected to nRF Cloud before calling the :c:func:`nrf_cloud_log_send` function.
The :c:func:`nrf_cloud_rest_log_send` function initiates the connection as needed.

Configuration
*************
Expand All @@ -82,7 +80,7 @@ To enable direct log messages or the logging backend, set the :kconfig:option:`C

If only the first is enabled:

* Calls to the direct log message functions :c:func:`nrf_cloud_log_send` and :c:func:`nrf_cloud_rest_log_send` send messages direct to nRF Cloud immediately.
* Calls to the direct log message function :c:func:`nrf_cloud_log_send` send messages direct to nRF Cloud immediately.
* The cloud logging backend is not available, and consequently, no Zephyr log messages are transmitted to the cloud.

If only the second is enabled:
Expand All @@ -95,7 +93,6 @@ If both options are enabled, calls to the direct log message functions are passe
Configure one of the following Kconfig options to select the data transport method:

* :kconfig:option:`CONFIG_NRF_CLOUD_MQTT`
* :kconfig:option:`CONFIG_NRF_CLOUD_REST`
* :kconfig:option:`CONFIG_NRF_CLOUD_COAP`

Configure the message encoding:
Expand Down Expand Up @@ -141,29 +138,23 @@ Usage
To use this library, complete the following steps:

1. Include the :file:`nrf_cloud_log.h` file.
#. If the :kconfig:option:`CONFIG_NRF_CLOUD_LOG_DIRECT` Kconfig option is enabled, call the :c:func:`nrf_cloud_log_send` function when connected to nRF Cloud using MQTT or CoAP, or call :c:func:`nrf_cloud_rest_log_send` when using REST.
#. If the :kconfig:option:`CONFIG_NRF_CLOUD_LOG_DIRECT` Kconfig option is enabled, call the :c:func:`nrf_cloud_log_send` function when connected to nRF Cloud using MQTT or CoAP.
#. If the :kconfig:option:`CONFIG_NRF_CLOUD_LOG_BACKEND` option is enabled, use the normal Zephyr logging macros :c:macro:`LOG_ERR`, :c:macro:`LOG_WRN`, :c:macro:`LOG_INF`, or :c:macro:`LOG_DBG`, as well as the ``_HEXDUMP_ forms``.

Samples using the library
*************************

The following |NCS| samples use this library:

* :ref:`nrf_cloud_multi_service`
* :ref:`nrf_cloud_rest_device_message`

Limitations
***********

For REST-based applications, you can disable or set a log level for logs only at compile time.
* :ref:`nrf_cloud_mqtt_device_message`
* :ref:`nrf_cloud_coap_device_message`

Dependencies
************

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`

Expand Down
Loading
Loading