doc: nrf_cloud_pgps: Add P-GPS partition documentation

Document new Kconfig options related to the new dedicated
P-GPS partition in flash. Add to release notes and
known issues.

This includes doc review edits.

Signed-off-by: Pete Skeggs <[email protected]>
Signed-off-by: Francesco Domenico Servidio <[email protected]>

Author: plskeggs

doc/nrf/glossary.rst

@@ -13,6 +13,10 @@ Glossary
    Access Port Protection (APPROTECT)
       A register used to prevent read and write access to all CPU registers and memory-mapped addresses.
 
+   Almanac data
+      In the :term:`Global Navigation Satellite System (GNSS)`, the data providing coarse orbit and status information for each satellite in the constellation.
+      Each satellite broadcasts Almanac data for all the satellites in the constellation.
+
    Anycast addressing
       An addressing type that routes datagrams to a single member of a group of potential receivers that are all identified by the same destination address.
       This is a one-to-nearest association.
@@ -28,6 +32,11 @@ Glossary
    Application Programming Interface (API)
       A language and message format used by an application program to communicate with an operating system, application, or other services.
 
+   Assisted GPS (A-GPS)
+      A form of assistance provided to devices trying to obtain a :term:`Global Navigation Satellite System (GNSS)` fix.
+      It improves the :term:`Time to First Fix (TTFF)` by utilizing a connection (for example, over cellular) to the internet to retrieve the :term:`Almanac data` and :term:`Ephemeris data`.
+      A connection to an internet server that has the Almanac and Ephemeris data is several times quicker than using the data link to the GPS satellites.
+
    Attribute Protocol (ATT)
       "[It] allows a device referred to as the server to expose a set of attributes and their associated values to a peer device referred to as the client."
       `Bluetooth Core Specification`_, Version 5.3, Vol 3, Part F, Section 1.1.
@@ -148,6 +157,10 @@ Glossary
    Endpoint
       In the context of a :ref:`Matter <ug_matter>` or :ref:`Zigbee <ug_zigbee>` network, an addressable container that contains *clusters* appropriate for a single device type such as a sensor or a light bulb.
 
+   Ephemeris data
+      In the :term:`Global Navigation Satellite System (GNSS)`, the data providing information about the orbit of the satellite transmitting it.
+      This data is valid for four hours and becomes inaccurate after that.
+
    Evaluation Kit (EK)
       A platform used to evaluate different development platforms.
 
@@ -448,6 +461,11 @@ Glossary
       A feature introduced in 3GPP Release 12 to improve the battery life of IoT (Internet of Things) devices by minimizing energy consumption.
       The device stays dormant during the PSM window.
 
+   Predicted GPS (P-GPS)
+      A form of assistance provided to devices trying to obtain a :term:`Global Navigation Satellite System (GNSS)` fix, where the device can download up to two weeks of predicted satellite Ephemerides data.
+      It enables devices to determine the exact orbital location of the satellite without connecting to the network every two hours with a trade-off of reduced accuracy of the calculated position over time.
+      It is available through :term:`nRF Cloud`.
+
    Preview Development Kit (PDK)
       A development platform used for application development.
       A Preview Development Kit uses an engineering sample of the chip and it is not production-ready in comparison to the Development Kit that uses a production-ready version of the chip.
@@ -570,6 +588,9 @@ Glossary
    Target
       The goal of an operation, for example, programming a specific image on a device, compiling a specific set of files, or removing previously generated files.
 
+   Time to First Fix (TTFF)
+      The time needed by a :term:`Global Navigation Satellite System (GNSS)` module to estimate its position.
+
    Transmission Control Protocol (TCP)
       A connection-oriented protocol that provides reliable transport.
       This reliability comes at the cost of control packets overhead of the protocol itself, making it unsuitable for bandwidth-constrained applications.

doc/nrf/known_issues.rst

@@ -124,6 +124,11 @@ CIA-463: Wrong network mode parameter reported to cloud
 NCSDK-14235: Timestamps that are sent in cloud messages drift over time
   Due to a bug in the :ref:`lib_date_time` library, timestamps that are sent to cloud drift because they are calculated incorrectly.
 
+.. rst-class:: v1-8-0 v1-7-1 v1-7-0 v1-6-1 v1-6-0 v1-5-0
+
+CIA-604: ATv2 cannot be built for the ``thingy91_nrf9160_ns`` build target with ``SECURE_BOOT`` enabled
+  Due to the use of static partitions with the Thingy:91, there is insufficient room in the flash memory to enable both the primary and secondary bootloaders.
+
 Serial LTE Modem
 ================
 

doc/nrf/libraries/networking/nrf_cloud_pgps.rst

@@ -7,32 +7,40 @@ nRF Cloud P-GPS
    :local:
    :depth: 2
 
-The nRF Cloud P-GPS library enables applications to request and process predicted GPS data from `nRF Cloud`_ to be used with the nRF9160 SiP.
+The nRF Cloud P-GPS library enables applications to request and process :term:`Predicted GPS (P-GPS)` data from `nRF Cloud`_ to be used with the nRF9160 SiP.
 This library is an enhancement to the :ref:`lib_nrf_cloud` library.
-It can be used with or without Assisted GPS (`A-GPS`_) data from nRF Cloud.
+It can be used with or without :term:`Assisted GPS (A-GPS)` data from nRF Cloud.
 
-P-GPS is intended for specific use cases.
-It is not targeted for general use cases that already work with A-GPS.
-P-GPS is designed for devices that are frequently disconnected from the cloud but need periodic GNSS fixes as quickly as possible to save power.
+Overview
+********
 
-To get a position fix, a GNSS receiver needs information such as the satellite orbital data, exact date and time of the day, and accurate hardware clock frequency data.
+To get a position fix, a :term:`Global Navigation Satellite System (GNSS)` receiver needs information such as the satellite orbital data, exact date and time of the day, and accurate hardware clock frequency data.
 GPS satellites broadcast this information in a pattern, which repeats every 12.5 minutes.
-Predicted GPS data contains information about the estimated orbits (`Ephemerides <Ephemeris_>`_) of the 32 GPS satellites for up to a two-week period, with each set of ephemerides predictions being valid for a specific four-hour period within the set of all provided predictions.
-These ephemeris predictions are downloaded from the cloud, stored by the device in flash memory, and later injected into the GNSS module when needed.
+
+Predicted GPS (P-GPS) is a form of assistance that reduces the :term:`Time to First Fix (TTFF)`, the time needed by a GNSS module to estimate its position.
+It is provided through :term:`nRF Cloud` services.
+In P-GPS, nRF Cloud provides data containing information about the estimated orbits (`Ephemerides <Ephemeris_>`_) of the 32 GPS satellites for up to two weeks.
+Each set of ephemerides predictions is valid for a specific four-hour period within the set of all provided predictions.
+A device using P-GPS downloads the ephemeris predictions from the cloud, it stores them in its flash memory, and later it injects them into the GNSS module when needed.
+
+P-GPS is designed for devices that are frequently disconnected from the cloud but need periodic GNSS fixes as quickly as possible to save power.
+This is possible because a device can download the broadcasted information and predictions of satellite data provided through P-GPS (or also A-GPS) at a faster rate from nRF Cloud than from the data links of the satellites.
+However, P-GPS should not be used for general use cases that already work with :term:`Assisted GPS (A-GPS)` only.
 
 .. note::
+   When using two-week ephemeris prediction sets, the TTFF towards the end of the second week will increase due to the accumulated errors in the predictions and the decrease in the number of satellite ephemerides in the later prediction periods.
 
-   If two-week prediction sets are used, TTFF towards the end of the second week will increase due to accumulated errors in the predictions and decrease in number of satellite ephemerides in the later prediction periods.
+P-GPS requires a cloud connection approximately once a week, depending on the configuration settings.
+A-GPS requires a cloud connection each time.
 
-If nRF Cloud services such as A-GPS or P-GPS are used either individually or in combination, the broadcasted information and predictions of satellite data can be downloaded at a faster rate from nRF Cloud than from the satellites.
+A device can use P-GPS together with A-GPS.
+This provides the following advantages:
 
-The use of P-GPS reduces Time to First Fix (TTFF) (time for a GNSS module to estimate its position) when compared to using no assistance at all.
-Further, it only requires a cloud connection approximately once a week, depending on configuration.
-On the other hand, when only A-GPS is used, a cloud connection is needed each time.
-If you use P-GPS along with A-GPS, TTFF is faster compared to an implementation with P-GPS only.
-The amount of cloud data needed for each fix is smaller during each fix compared to an implementation with A-GPS only.
-With proper configuration, A-GPS can be used with P-GPS, when a cloud connection is available, and acquire fast fixes even without a cloud connection.
-This is possible as long as the stored P-GPS data is still valid, and current date and time (accurate to a few seconds) and the most recent location (accurate to a few dozen kilometers) are known.
+* It shortens TTFF compared to using only P-GPS.
+* It requires less cloud data during each fix compared to using only A-GPS.
+
+With proper configuration, A-GPS can be used with P-GPS when a cloud connection is available, and it can acquire fast fixes even without a cloud connection.
+This is possible as long as the stored P-GPS data is still valid, and the current date and time (accurate to a few seconds) and the most recent location (accurate to a few dozen kilometers) are known.
 
 .. note::
    To use the nRF Cloud P-GPS service, an nRF Cloud account is needed, and the device needs to be associated with a user's account.
@@ -53,21 +61,37 @@ Configure these additional options to refine the behavior of P-GPS:
 * :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_DOWNLOAD_FRAGMENT_SIZE`
 * :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_REQUEST_UPON_INIT`
 
-Configure the following option if you need your application to use A-GPS as well, for coarse time and position data and to get the fastest TTFF:
+Configure the following option if you need your application to also use A-GPS, for coarse time and position data and to get the fastest TTFF:
 
 * :kconfig:option:`CONFIG_NRF_CLOUD_AGPS`
 
-If A-GPS is not desired (due to data costs, low power requirements, or expected frequent loss of cloud connectivity), you must disable the option.
+  .. note::
+     Disable this option if you do not want to use A-GPS (due to data costs, low power requirements, or expected frequent loss of cloud connectivity).
 
-For an application that uses P-GPS, the following options must be configured for storing settings, for having accurate clock time, and for having a location to store predictions:
+You must also configure the following options for storing settings, for having accurate clock time, and for having a location to store predictions:
 
 * :kconfig:option:`CONFIG_FLASH`
 * :kconfig:option:`CONFIG_FCB`
 * :kconfig:option:`CONFIG_SETTINGS_FCB`
 * :kconfig:option:`CONFIG_DATE_TIME`
-* :kconfig:option:`CONFIG_BOOTLOADER_MCUBOOT`
-* :kconfig:option:`CONFIG_IMG_MANAGER`
-* :kconfig:option:`CONFIG_MCUBOOT_IMG_MANAGER`
+
+The P-GPS library requires a storage location in the flash memory where to store the P-GPS prediction data.
+There are three ways to define this storage location:
+
+* To use a dedicated partition, enable the :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_STORAGE_PARTITION` option.
+* To use the MCUboot secondary partition as storage, enable the :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_STORAGE_MCUBOOT_SECONDARY` option.
+
+  Use this option if the flash memory for your application is too full to use a dedicated partition, but the application uses MCUboot for FOTA updates but not for MCUboot itself.
+  Do not use this option if you are using MCUboot as a second-stage upgradable bootloader and also have FOTA updates enabled for MCUboot itself, and not just the application (using :kconfig:option:`CONFIG_SECURE_BOOT` and :kconfig:option:`CONFIG_BUILD_S1_VARIANT`).
+  The P-GPS library will otherwise prevent the MCUboot update from fully completing, and the first-stage immutable bootloader will revert MCUboot to its previous image.
+
+* To use an application-specific storage, enable the :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_STORAGE_CUSTOM` option.
+  You must also pass the address and the size of your custom location in the flash memory to the :c:func:`nrf_cloud_pgps_init` function.
+
+  .. note::
+     The address must be aligned to a flash page boundary, and the size must be equal to or greater than 2048 bytes times the :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_NUM_PREDICTIONS` option.
+
+  Use this third option if you do not use MCUboot and if you want complete control over where to store P-GPS data in the flash memory.
 
 See :ref:`configure_application` for information on how to change configuration options.
 
@@ -83,14 +107,11 @@ In these cases, predictions might be unavailable until a connection is establish
    Each prediction requires 2 KB of flash. For prediction periods of 240 minutes (four hours), and with 42 predictions per week, the flash requirement adds up to 84 KB.
 
 The P-GPS subsystem's :c:func:`nrf_cloud_pgps_init` function takes a pointer to a :c:struct:`nrf_cloud_pgps_init_param` structure.
-The structure at a minimum must specify the storage base address and the storage size in flash, where P-GPS subsystem stores predictions.
+The structure must specify, if :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_STORAGE_CUSTOM` is enabled, the storage base address and the storage size in the flash memory where the P-GPS subsystem stores predictions.
 It can optionally pass a pointer to a :c:func:`pgps_event_handler_t` callback function.
 
-As an example, the :ref:`gnss_sample` sample shows how to pass the address of the :ref:`secondary MCUboot partition <mcuboot_ncs>`.
-The address is defined by the ``PM_MCUBOOT_SECONDARY_ADDRESS`` macro and the ``PM_MCUBOOT_SECONDARY_SIZE`` macro.
-These are automatically defined by the build system in the file :file:`pm_config.h`.
-This partition is safe to store data until a FOTA job is received.
-To avoid loss during FOTA, application developers can opt to store predictions in another location.
+.. note::
+   The storage base address must be aligned to a flash memory page boundary.
 
 Time
 ****
@@ -114,6 +135,8 @@ P-GPS data can be requested from the cloud using one of the following methods:
   * If :kconfig:option:`CONFIG_NRF_CLOUD_REST` is enabled:
 
    * Pass a properly initialized :c:struct:`nrf_cloud_rest_pgps_request` structure to the :c:func:`nrf_cloud_rest_pgps_data_get` function.
+   * Pass the response to the :c:func:`nrf_cloud_pgps_process` function.
+   * If either call fails, call the :c:func:`nrf_cloud_pgps_request_reset` function.
 
 * Indirectly:
 
@@ -125,7 +148,8 @@ P-GPS data can be requested from the cloud using one of the following methods:
 
   * If :kconfig:option:`CONFIG_NRF_CLOUD_REST` is enabled:
 
-   * N/A
+   * Call :c:func:`nrf_cloud_pgps_preemptive_updates`.
+   * Call :c:func:`nrf_cloud_pgps_notify_prediction`.
 
 The indirect methods are used in the :ref:`asset_tracker_v2` application.
 They are simpler to use than the direct methods.
@@ -146,6 +170,7 @@ The indirect method is used in the :ref:`gnss_sample` sample and in the :ref:`as
 
 The application can inject the data contained in the prediction to the GNSS module in the modem by calling the :c:func:`nrf_cloud_pgps_inject` function.
 This must be done when event :c:enumerator:`NRF_MODEM_GNSS_EVT_AGPS_REQ` is received from the GNSS interface.
+After injecting the prediction, call the :c:func:`nrf_cloud_pgps_preemptive_updates` function to update the prediction set as needed.
 
 A prediction is also automatically injected to the modem every four hours whenever the current prediction expires and the next one begins (if the next one is available in flash).
 

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

@@ -89,6 +89,7 @@ nRF9160: Asset Tracker v2
   * Support for :ref:`Bosch Software Environmental Cluster (BSEC) library <bosch_software_environmental_cluster_library>` driver.
   * Support for Indoor Air Quality (IAQ) readings retrieved from the BME680 sensor on Thingy:91. For more information, see the :ref:`asset_tracker_v2_sensor_module`.
   * Support for QEMU x86 emulation.
+  * Support for the :ref:`lib_nrf_cloud_pgps` flash memory partition under certain conditions.
 
 * Updated:
 
@@ -112,6 +113,11 @@ nRF9160: Serial LTE modem
   * Enhanced the ``#XSLEEP`` AT command to support data indication when idle.
   * Enhanced the MQTT client to support the reception of large PUBLISH payloads.
 
+* Fixed:
+
+  * The secondary MCUboot partition information is no longer passed to the P-GPS library if the P-GPS partition is enabled.
+  * The combined use of A-GPS and P-GPS so that ephemeris and almanac data is not requested via A-GPS, saving both power and bandwidth.
+
 nRF Desktop
 -----------
 
@@ -200,6 +206,7 @@ nRF9160 samples
       * Iperf3 usage over Zephyr native TCP/IP stack and nRF9160 LTE default context.
       * Support for the GNSS features introduced in modem firmware v1.3.2.
         This includes several new fields in the PVT notification and a command to query the expiry times of assistance data.
+      * Support for the :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_STORAGE_PARTITION` option.
 
   * :ref:`nrf_cloud_rest_fota` sample:
 
@@ -226,6 +233,10 @@ nRF9160 samples
 
     * Updated the default HTTPS URL and certificate due to the old link being broken.
 
+  * :ref:`gnss_sample` sample:
+
+    * Added support for the :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_STORAGE_PARTITION` option.
+
 OpenThread samples
 ------------------
 
@@ -378,6 +389,9 @@ Modem libraries
 
     * Added:
 
+      * Support for the :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_STORAGE_PARTITION` option.
+      * Improved integration of A-GPS and P-GPS when both are enabled.
+      * A missing call to the :c:func:`nrf_cloud_pgps_notify_prediction` function, when using the REST interface with P-GPS.
       * Support for P-GPS data retrieval from an external source, implemented separately by the application.
         Enabled by setting the :kconfig:option:`CONFIG_LOCATION_METHOD_GNSS_PGPS_EXTERNAL` option.
         The library triggers a :c:enum:`LOCATION_EVT_GNSS_PREDICTION_REQUEST` event when assistance is needed.
@@ -469,6 +483,18 @@ Libraries for networking
 
     * Added :kconfig:option:`CONFIG_AZURE_IOT_HUB_NATIVE_TLS` option to configure the socket to be native for TLS instead of offloading TLS operations to the modem.
 
+ * :ref:`lib_nrf_cloud_pgps` library:
+
+    * Added:
+
+      * The passing of the current prediction, if one is available, along with the ``PGPS_EVT_READY`` event.
+      * The following three ways to define the storage location in the flash memory:
+
+        * A dedicated P-GPS partition, enabled with the :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_STORAGE_PARTITION` option.
+        * The use of the MCUboot secondary partition as storage, enabled with the :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_STORAGE_MCUBOOT_SECONDARY` option.
+        * An application-specific storage, enabled with the :kconfig:option:`CONFIG_NRF_CLOUD_PGPS_STORAGE_CUSTOM` option.
+
+
 Libraries for NFC
 -----------------
 
@@ -528,6 +554,10 @@ Other libraries
 
     * Fixed a compilation error for nRF52833.
 
+  * Partition Manager:
+
+    * Added the :file:`ncs/nrf/subsys/partition_manager/pm.yml.pgps` file.
+
 Common Application Framework (CAF)
 ----------------------------------