nRF Cloud A-GPS

The nRF Cloud A-GPS library enables applications to request and process Assisted GPS (A-GPS) data from nRF Cloud to be used with the nRF9160 SiP. This library is an enhancement to the nRF Cloud library.

Overview 

Using A-GPS reduces the time for a Global Navigation Satellite System (GNSS) module to estimate its position, which is also called Time to First Fix (TTFF). To get a position fix, a GNSS module needs information such as the satellite orbital data broadcasted by the satellites. If nRF Cloud A-GPS service is used, the broadcasted information can be downloaded at a faster rate from nRF Cloud.

In addition to reducing the time to fix, A-GPS also provides ionospheric correction data to the device. Ionospheric corrections enable GNSS to estimate the ionospheric delay for each satellite, making the position data more accurate. While ionospheric corrections can also be downloaded from the satellite broadcast, this is often not practical because the whole GPS navigation message takes 12.5 minutes.

Note

To use the nRF Cloud A-GPS service, you need an nRF Cloud account and the device needs to be associated with the account.

Configuration 

Configure the following options to enable or disable the use of this library:

See Configuring your application for information on how to change configuration options.

Usage 

A-GPS data can be requested using one of the following methods:

By specifying an array of A-GPS types.
By requesting all the available assistance data.

If CONFIG_NRF_CLOUD_MQTT is enabled, the nrf_cloud_agps_request() function is used to request by type, and the nrf_cloud_agps_request_all() function is used to return all available assistance data. If CONFIG_NRF_CLOUD_REST is enabled, the nrf_cloud_rest_agps_data_get() function is used to request A-GPS data.

When nRF Cloud responds with the requested A-GPS data, the nrf_cloud_agps_process() function processes the received data. The function parses the data and passes it on to the modem.

Practical considerations 

When A-GPS data is downloaded using LTE network, the LTE link is in RRC connected mode. The GNSS module can only operate when the device is in RRC idle mode or Power Saving Mode (PSM). The time to switch from RRC connected mode to RRC idle mode depends on the network. The switching time is usually not controlled by the device and is typically in the range of 5 to 70 seconds. If the GNSS module has already been started before the device enters the RRC idle mode, this time may make TTFF appear longer than the actual time GNSS has spent running.

The validity time of a particular type of assistance data is different for each type of assistance data. As an example, Almanac data has a far longer validity than Ephemeris data. Usually, the best practice is to download only the assistance data requested by GNSS to reduce data traffic and save power, see Determining the assistance data needed by GNSS.

Data usage 

The size of full assistance data is around three kB. Ephemerides for 32 GPS satellites are two kB, while everything else (almanacs, UTC parameters, ionospheric corrections, GPS system time, location and satellite integrity) is roughly one kB. Ephemerides are only valid for two to four hours. To have valid ephemerides at all times, new ephemerides need to be downloaded on average every two hours. The cumulative amount of data for ephemerides for a day would then be 24 kB (24 / 2 * 2 kB). Of rest of the data types, almanacs are by far the largest. Almanacs are valid for weeks, so the data usage depends mostly on the need of ephemerides.

Filtered ephemerides

When the application only requires a GNSS fix once every two hours, it can reduce LTE data charges by enabling the CONFIG_NRF_CLOUD_AGPS_FILTERED Kconfig option (A-GPS filtered mode). This option causes nRF Cloud to send ephemerides data for only those satellites whose elevation is at or above the CONFIG_NRF_CLOUD_AGPS_ELEVATION_MASK angle at the current moment.

When using the A-GPS filtered mode with the GNSS unit in periodic tracking mode, applications should disable scheduled downloads in the GNSS unit. Applications do this when initializing the GNSS unit by bitwise ORing the NRF_MODEM_GNSS_USE_CASE_SCHED_DOWNLOAD_DISABLE bitmask with any other needed use case values, then passing the resulting value to the nrf_modem_gnss_use_case_set() function. This ensures the GNSS unit does not stay on longer than needed due to the lack of a full set of ephemerides.

When the application requires multiple GNSS fixes within two hours, it can avoid unnecessary A-GPS data downloads from nRF Cloud by having the CONFIG_NRF_CLOUD_AGPS_FILTERED Kconfig option disabled. This ensures that the ephemerides are available also for SVs that are not visible upon A-GPS data download, but become visible before the GNSS is started again.

Energy consumption 

Downloading A-GPS data over LTE consumes energy. However, considering the energy consumption of both LTE and GNSS, the total energy consumption with A-GPS is lower than without it in most cases, even for a single fix. Downloading the data using LTE is much quicker and the time GNSS needs to be active to get a fix is significantly reduced.

The example images illustrate the difference in energy consumption with and without A-GPS. The time required to download the A-GPS data and to get a fix depend on the conditions, so the actual energy consumption and time needed varies.

LTE is configured to use the Power Saving Mode (PSM) with eight second active time in both cases. nRF Cloud over MQTT is used to download the assistance data. A cloud connection is established before the measurement starts, so the measurement only includes the assistance data download.

With A-GPS enabled, assistance data is first downloaded using LTE. GNSS starts when the assistance data has been downloaded and the modem enters the RRC idle mode.

It takes approximately 15 seconds to download assistance data, get the GNSS fix and switch LTE back to PSM. The total consumed charge is approximately 0.5 C.

Without A-GPS, GNSS needs to run for a longer time. LTE remains in PSM and the total energy consumption depends only on how long GNSS runs.

It takes approximately 39 seconds to get the fix and the total consumed charge is 1.7 C.

Limitations 

Approximate location assistance data is based on LTE cell location. Not all cell locations are always available. If they are not available, the location data will be absent in the A-GPS response.

Dependencies 

This library uses the following nRF Connect SDK libraries:

It uses the following sdk-nrfxlib library:

GNSS interface

API documentation 

Header file: include/net/nrf_cloud_agps.h

Source files: subsys/net/lib/nrf_cloud/src/

group nrf_cloud_agps

Functions

int nrf_cloud_agps_request(const struct nrf_modem_gnss_agps_data_frame *request)

Requests specified A-GPS data from nRF Cloud via MQTT.

Parameters:

request – Structure containing specified A-GPS data to be requested.

Return values:

0 – Request sent successfully.
-EACCES – Cloud connection is not established; wait for NRF_CLOUD_EVT_READY.

Returns:

A negative value indicates an error.

int nrf_cloud_agps_request_all(void)

Requests all available A-GPS data from nRF Cloud via MQTT.

Returns:: 0 if successful, otherwise a (negative) error code.

int nrf_cloud_agps_process(const char *buf, size_t buf_len)

Processes binary A-GPS data received from nRF Cloud.

Parameters:

buf – Pointer to data received from nRF Cloud.
buf_len – Buffer size of data to be processed.

Return values:

0 – A-GPS data successfully processed.
-EFAULT – An nRF Cloud A-GPS error code was processed.
-ENOMSG – No nRF Cloud A-GPS error code found, invalid error code or wrong app_id/msg_type.
-EINVAL – buf was NULL or buf_len was zero.
-EBADMSG – Non-JSON payload is not in the A-GPS format.

Returns:

A negative value indicates an error.

void nrf_cloud_agps_processed(struct nrf_modem_gnss_agps_data_frame *received_elements)

Query which A-GPS elements were actually received.

Parameters:

received_elements – return copy of requested elements received since A-GPS request was made

bool nrf_cloud_agps_request_in_progress(void)

Query whether A-GPS data has been requested from cloud.

Returns:: True if request is outstanding.