nRF Cloud A-GPS

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

The use of A-GPS reduces the time for a GPS device to estimate its position, which is also called Time to First Fix (TTFF). To get a position fix, a GPS 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 Connect for Cloud A-GPS service is used, the broadcasted information can be downloaded at a faster rate from nRF Connect for Cloud.

Note

To use the nRF Connect for Cloud A-GPS service, an nRF Connect for 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

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.

When nRF Connect for 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

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 GPS 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 GPS can only operate only when the device is in RRC idle mode. 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 GPS service 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 GPS satellite signals.

Limitations

Approximate location assistance data is based on LTE cell location. Since all cell locations are not always available, the location data is sometimes 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 gps_agps_request request)

Requests specified A-GPS data from nRF Cloud.

Parameters

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

Returns

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

int nrf_cloud_agps_request_all(void)

Requests all available A-GPS data from nRF Cloud.

Returns

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

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

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.

  • socket – Pointer to GNSS socket to which A-GPS data will be injected. If NULL, the nRF9160 GPS driver is used to inject the data.

Returns

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

void nrf_cloud_agps_processed(struct gps_agps_request *received_elements)

Query which A-GPS elements were actually received.

Parameters

  • received_elements – return copy of requested elements received since agps request 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.