nRF Cloud P-GPS¶
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. This library is an enhancement to the nRF Cloud library. It can be used with or without 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 GPS fixes as quickly as possible to save power.
To get a position fix, a GPS 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) 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 GPS unit when needed.
Note
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.
If nRF Cloud services such as P-GPS or A-GPS are used either individually or in combination, the broadcasted information and future estimates of position can be downloaded at a faster rate from nRF Cloud than from the GPS satellites.
The use of P-GPS reduces Time to First Fix (TTFF) (time for a GPS device 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.
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.
Configuration¶
Configure the following options to enable or disable the use of this library:
Configure these additional options to refine the behavior of P-GPS:
Configure both of the following options if you need your application to use A-GPS as well, for coarse time and position data and to get the fastest TTFF:
If A-GPS is not desired (due to data costs, low power requirements, or expected frequent loss of cloud connectivity), both options listed above must be disabled.
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:
See Configuring your application for information on how to change configuration options.
Initialization¶
Ideally, once the device has connected to the cloud, the application must call the P-GPS initialization function. If a connection is not available, initialization must still be called. In this case, predictions will be unavailable if all valid predictions have expired, until a connection is established to the cloud in the future.
Note
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 nrf_cloud_pgps_init()
function takes a pointer to a 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.
It can optionally pass a pointer to a pgps_event_handler_t()
callback function.
As an example, the nRF9160: A-GPS sample shows how to pass the address of the secondary MCUboot partition.
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 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.
Time¶
The proper operation of the P-GPS subsystem depends on an accurate sense of time. For use cases where a cloud connection can be established easily, use the Date-Time library with NTP enabled. Otherwise, a battery-backed real-time clock calendar chip must be used so that accurate time is available regardless of cloud availability after reset.
Requesting and processing P-GPS data¶
P-GPS data can be requested from the cloud using one of the following methods:
Directly:
By calling the function
nrf_cloud_pgps_request_all()
to request a full set of predictions.By passing a properly initialized
gps_pgps_request
structure to thenrf_cloud_pgps_request()
function.
Indirectly:
By calling
nrf_cloud_pgps_init()
, with no valid predictions present in flash, or with some or all of the predictions expired.By calling
nrf_cloud_pgps_preemptive_updates()
.By calling
nrf_cloud_pgps_notify_prediction()
.
The indirect methods are used in the nRF9160: A-GPS sample and in the nRF9160: Asset Tracker application. They are simpler to use than the direct methods.
When nRF Cloud responds with the requested P-GPS data, the application’s cloud_evt_handler_t()
function must call the nrf_cloud_pgps_process()
function when it receives the CLOUD_EVT_DATA_RECEIVED
event.
The function parses the data and stores it.
Finding a prediction and injecting to modem¶
A P-GPS prediction for the current date and time can be retrieved using one of the following methods:
Directly, by calling the function
nrf_cloud_pgps_find_prediction()
Indirectly, by calling the function
nrf_cloud_pgps_notify_prediction()
The indirect method is used in the nRF9160: A-GPS sample and in the nRF9160: Asset Tracker application.
The application can inject the data contained in the prediction to the GPS unit in the modem by calling the nrf_cloud_pgps_inject()
function.
This must be done when the GPS driver callback indicates that assistance is 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).
Interaction with the GPS driver¶
The P-GPS subsystem, like several other nRF Cloud subsystems, is event driven.
Following are the two GPS events relating to P-GPS that an application receives through the GPS driver callback:
GPS_EVT_AGPS_DATA_NEEDED
- Occurs when the GPS module requires assistance data.GPS_EVT_PVT_FIX
- Occurs once a fix is attained.
When the application receives the GPS_EVT_AGPS_DATA_NEEDED
event, it must call nrf_cloud_pgps_notify_prediction()
.
This event results in the call back of the application’s pgps_event_handler_t()
function when a valid P-GPS prediction set is available.
It will pass the PGPS_EVT_AVAILABLE
event and a pointer to nrf_cloud_pgps_prediction
to the handler.
The application must pass this prediction to nrf_cloud_pgps_inject()
, along with either the gps_agps_request
passed to the GPS driver callback earlier with the GPS_EVT_AGPS_DATA_NEEDED
event or NULL.
If the use case for the application is such that the device will not move distances greater than a few dozen kilometers before it gets a new GPS fix, it can pass the latitude and longitude provided in GPS_EVT_PVT_FIX
to nrf_cloud_pgps_set_location()
.
The P-GPS subsystem will use this stored location for the next GPS request for position assistance when A-GPS assistance is not enabled or is unavailable.
If the use case involves possible long-distance travel between fix attempts, such a mechanism can be detrimental to short TTFF, as the saved position might be too inaccurate to be a benefit.
The application can also call nrf_cloud_pgps_preemptive_updates()
to discard expired predictions and replace them with newer ones, prior to the expiration of the entire set of predictions.
This can be useful for customer use cases where cloud connections are available infrequently.
The CONFIG_NRF_CLOUD_PGPS_REPLACEMENT_THRESHOLD
sets the minimum number of valid predictions remaining before such an update occurs.
For best performance, applications can call the P-GPS functions mentioned in this section from workqueue handlers rather than directly from various callback functions.
The P-GPS subsystem itself generates events that can be passed to a registered callback function.
See nrf_cloud_pgps_event
.
API documentation¶
include/net/nrf_cloud_pgps.h
subsys/net/lib/nrf_cloud/src/
-
group
nrf_cloud_pgps
Defines
-
NRF_CLOUD_PGPS_NUM_SV
¶
-
ETIMEUNKNOWN
¶ P-GPS error code: current time unknown.
-
ELOADING
¶ P-GPS error code: not found but loading in progress.
-
NRF_CLOUD_PGPS_EMPTY_EPHEM_HEALTH
¶ Value to mark the ephemeris as unavailable for satellites for which no predictions are available from the cloud.
Typedefs
-
typedef void (*
pgps_event_handler_t
)(enum nrf_cloud_pgps_event event, struct nrf_cloud_pgps_prediction *p)¶ Event handler registered with the module to handle asynchronous events from the module.
- Parameters
event – [in] The event that just occurred.
p – [in] For event PGPS_EVT_AVAILABLE, a pointer to the prediction; otherwise, NULL.
Enums
-
enum
nrf_cloud_pgps_event
¶ P-GPS event passed to the registered pgps_event_handler.
Values:
-
enumerator
PGPS_EVT_INIT
¶ P-GPS initialization beginning.
-
enumerator
PGPS_EVT_UNAVAILABLE
¶ There are currently no P-GPS predictions available.
-
enumerator
PGPS_EVT_LOADING
¶ P-GPS predictions are being loaded from the cloud.
-
enumerator
PGPS_EVT_AVAILABLE
¶ A P-GPS prediction is available now for the current date and time.
-
enumerator
PGPS_EVT_READY
¶ All P-GPS predictions are available.
-
enumerator
Functions
-
void
nrf_cloud_pgps_set_location_normalized
(int32_t latitude, int32_t longitude)¶ Update storage of the most recent known location, in modem-specific normalized format (int32_t). Current time is also stored. Normalization: (latitude / 90.0) * (1 << 23) (longitude / 360.0) * (1 << 24)
- Parameters
latitude – Current latitude normalized.
longitude – Current longitude in normalized.
-
void
nrf_cloud_pgps_set_location
(double latitude, double longitude)¶ Update the storage of the most recent known location in degrees. This will be injected along with the current time and relevant predicted ephemerides to the GPS unit in order to get the fastest possible fix, when the P-GPS subsystem is built with A-GPS disabled, or when A-GPS data is unavailable due to lack of a cloud connection. Current time is also stored.
- Parameters
latitude – Current latitude in degrees.
longitude – Current longitude in degrees.
-
void
nrf_cloud_pgps_clear_location
(void)¶ If location has previously been set, clear it. The application should do this if significant distances might have been travelled since the previous location was saved.
-
void
nrf_cloud_pgps_set_leap_seconds
(int leap_seconds)¶ Update the storage of the leap second offset between GPS time and UTC. This called automatically by the A-GPS subsystem (if enabled) when it receives a UTC assistance element, setting leap_seconds to the delta_tls field.
- Parameters
leap_seconds – Offset in seconds.
-
int
nrf_cloud_pgps_notify_prediction
(void)¶ Schedule a callback when prediction for current time is available. Callback could be immediate, if data already stored in Flash, or later, after loading from the cloud.
- Returns
0 if scheduled successfully, or negative error code if could not send request to cloud.
-
int
nrf_cloud_pgps_find_prediction
(struct nrf_cloud_pgps_prediction **prediction)¶ Tries to find an appropriate GPS prediction for the current time.
- Parameters
prediction – Pointer to a pointer to a prediction; the pointer at this pointer will be modified to point to the prediction if the return value is 0. Will be set to NULL on failure.
- Returns
0..NumPredictions-1 if successful; -ETIMEUNKNOWN if current date and time not known; -ETIMEDOUT if all predictions stored are expired; -EINVAL if prediction for the current time is invalid.
-
int
nrf_cloud_pgps_request
(const struct gps_pgps_request *request)¶ Requests specified P-GPS data from nRF Cloud.
- Parameters
request – Pointer to structure specifying what P-GPS data is desired. The request may fail if there no cloud connection; if the specified GPS day and GPS time of day is in the past or more than 2 weeks in the future; if the GPS time of day is larger than 86339; or if the prediction_period_min field is not within the range 120 to 480.
- Returns
0 if successful, otherwise a (negative) error code.
-
int
nrf_cloud_pgps_request_all
(void)¶ Requests all available P-GPS data from nRF Cloud.
- Returns
0 if successful, otherwise a (negative) error code.
-
int
nrf_cloud_pgps_process
(const char *buf, size_t buf_len)¶ Processes binary P-GPS data received from nRF Cloud.
- Parameters
buf – Pointer to data received from nRF Cloud.
buf_len – Buffer size of data to be processed.
- Returns
0 if successful, otherwise a (negative) error code.
-
int
nrf_cloud_pgps_inject
(struct nrf_cloud_pgps_prediction *p, const struct gps_agps_request *request, const int *socket)¶ Injects binary P-GPS data to the modem. If request is NULL, it is assumed that only ephemerides assistance should be injected.
- Parameters
p – Pointer to a prediction.
request – Which assistance elements the modem needs. May be NULL.
socket – Pointer to GNSS socket to which P-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.
-
bool
nrf_cloud_pgps_loading
(void)¶ Find out if P-GPS update is in progress.
- Returns
True if request sent but loading not yet completed.
-
int
nrf_cloud_pgps_preemptive_updates
(void)¶ Download more predictions if less than CONFIG_NRF_CLOUD_PGPS_REPLACEMENT_THRESHOLD predictions remain which are still valid.
- Returns
0 if successful, otherwise a (negative) error code.
-
int
nrf_cloud_pgps_init
(struct nrf_cloud_pgps_init_param *param)¶ Initialize P-GPS subsystem. Validates what is stored, then requests any missing predictions, or full set if expired or missing. When successful, it is ready to provide valid ephemeris predictions.
Warning
It must return successfully before using P-GPS services.
- Parameters
param – [in] Initialization parameters.
- Returns
0 if valid or request begun; nonzero on error.
-
struct
nrf_cloud_pgps_system_time
¶ - #include <nrf_cloud_pgps.h>
nrf_cloud_pgps_system_time is a special version of nrf_cloud_agps_system_time that does not include the full array of sv_tow values; this is transferred from the cloud as part of each prediction, to indicate the date_day and time_full_s for the center of each prediction’s validity period.
Public Members
-
uint16_t
date_day
¶ Number of days since GPS time began on 6 Jan 1980 for the center of a prediction’s validity period.
-
uint32_t
time_full_s
¶ Seconds into GPS day for center of validity period.
-
uint16_t
time_frac_ms
¶ Will be 0.
-
uint32_t
sv_mask
¶ Will be 0.
-
uint32_t
pad
¶ Placeholder where sv_tow[32] is for A-GPS.
-
uint16_t
-
struct
nrf_cloud_pgps_prediction
¶ - #include <nrf_cloud_pgps.h>
P-GPS prediction Flash storage format.
Public Members
-
uint8_t
time_type
¶ Set to NRF_CLOUD_AGPS_GPS_SYSTEM_CLOCK.
-
uint16_t
time_count
¶ Will be 1.
-
struct nrf_cloud_pgps_system_time
time
¶ Information about when this prediction is applicable.
-
uint8_t
schema_version
¶ Not from cloud; inserted during storage to ease reusing A-GPS code.
-
uint8_t
ephemeris_type
¶ Set to NRF_CLOUD_AGPS_EPHEMERIDES.
-
uint16_t
ephemeris_count
¶ Usually will be NRF_CLOUD_PGPS_NUM_SV.
-
struct nrf_cloud_agps_ephemeris
ephemerii
[(32U)]¶ Array of satellite orbital equation coefficients.
-
uint32_t
sentinel
¶ Not from cloud; appended during storage to verify integrity on retrieval.
-
uint8_t
-
struct
gps_pgps_request
¶ - #include <nrf_cloud_pgps.h>
P-GPS request type.
Public Members
-
uint16_t
prediction_count
¶ Number of predictions desired.
-
uint16_t
prediction_period_min
¶ Validity time per prediction, in minutes. Valid range 120 to 480.
-
uint16_t
gps_day
¶ Number of days since GPS time began on 6 Jan 1980 for the center of the first prediction desired.
-
uint32_t
gps_time_of_day
¶ Number of seconds since the start of this GPS day for the center of the first prediction desired. Valid range 0 to 86399.
-
uint16_t
-
struct
nrf_cloud_pgps_init_param
¶ - #include <nrf_cloud_pgps.h>
Initialization parameters for the module.
Public Members
-
pgps_event_handler_t
event_handler
¶ Event handler that is registered with the module.
-
uint32_t
storage_base
¶ Flash storage address. Must be on a Flash page boundary.
-
uint32_t
storage_size
¶ Flash storage size. Must be a multiple of a Flash page in size, in bytes.
-
pgps_event_handler_t
-