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.

The use of A-GPS reduces the time for a 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, exact timing data, and a rough position estimate. GPS satellites broadcast this information in a pattern, which repeats every 12.5 minutes. If nRF Cloud A-GPS service is used, the broadcasted information can be downloaded at a faster rate from nRF Cloud.

Note

To use the nRF Cloud A-GPS service, an nRF Cloud account is needed, and the device needs to be associated with a user’s 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.

Request and process A-GPS data

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.

Optimizing cloud data downloads

When the application only requires a fast GNSS fix at most once per 2 hour period, it can reduce LTE data charges by enabling CONFIG_NRF_CLOUD_AGPS_FILTERED (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 fast GNSS fixes multiple times within a 2 hour period, it can avoid unnecessary A-GPS data downloads from nRF Cloud by keeping CONFIG_NRF_CLOUD_AGPS_FILTERED disabled.

Practical considerations

The type of assistance data needed at a certain point of time may vary. Since the library requests only partial data, data traffic reduction and battery conservation might be observed. The duration for which a particular type of assistance data is valid is different for each type of assistance data. As an example, Almanac data has a far longer validity (several months) than Ephemeris data (2 to 4 hours).

Since the library receives a partial assistance data set, it may cause GNSS to download the missing data from satellites.

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 go from RRC connected mode to RRC idle mode is network-dependent. This 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 started before the device enters the RRC idle mode, this RRC inactivity may make TTFF appear longer than the actual time spent searching for the GNSS satellite signals.

Limitation

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.

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.