nrf_cloud_pgps.h File Reference

Module to provide nRF Cloud Predicted GPS (P-GPS) support to nRF9160 SiP. More...

#include <zephyr/kernel.h>
#include <nrf_modem_gnss.h>
#include "nrf_cloud_agnss_schema_v1.h"

Go to the source code of this file.

Data Structures
struct	nrf_cloud_pgps_system_time
	nrf_cloud_pgps_system_time is a special version of nrf_cloud_agnss_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. More...
struct	nrf_cloud_pgps_prediction
	P-GPS prediction Flash storage format. More...
struct	gps_pgps_request
	P-GPS request type. More...
struct	nrf_cloud_pgps_result
	nRF Cloud Predicted GPS (P-GPS) result; the location of the P-GPS data file which is to be downloaded and provided to nrf_cloud_pgps_process(). More...
struct	nrf_cloud_pgps_event
struct	nrf_cloud_pgps_init_param
	Initialization parameters for the module. More...

Macros
#define	NRF_CLOUD_PGPS_NUM_SV   (32U)
#define	NRF_CLOUD_PGPS_REQ_NO_COUNT   0
#define	NRF_CLOUD_PGPS_REQ_NO_INTERVAL   0
#define	NRF_CLOUD_PGPS_REQ_NO_GPS_DAY   0
#define	NRF_CLOUD_PGPS_REQ_NO_GPS_TOD   (-1)
#define	ETIMEUNKNOWN   8000
	P-GPS error code: current time unknown.
#define	ELOADING   8001
	P-GPS error code: not found but loading in progress.
#define	NRF_CLOUD_PGPS_EMPTY_EPHEM_HEALTH   (0xff)
	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) (struct nrf_cloud_pgps_event *event)
	Event handler registered with the module to handle asynchronous events from the module.

Enumerations
enum	nrf_cloud_pgps_event_type {   PGPS_EVT_INIT , PGPS_EVT_UNAVAILABLE , PGPS_EVT_LOADING , PGPS_EVT_AVAILABLE ,   PGPS_EVT_READY , PGPS_EVT_REQUEST }
	P-GPS event passed to the registered pgps_event_handler. More...

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)
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-GNSS disabled, or when A-GNSS data is unavailable due to lack of a cloud connection. Current time is also stored.
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-GNSS subsystem (if enabled) when it receives a UTC assistance element, setting leap_seconds to the delta_tls field.
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.
int	nrf_cloud_pgps_find_prediction (struct nrf_cloud_pgps_prediction **prediction)
	Tries to find an appropriate GPS prediction for the current time.
int	nrf_cloud_pgps_request (const struct gps_pgps_request *request)
	Requests specified P-GPS data from nRF Cloud via MQTT. Not used for other transports.
int	nrf_cloud_pgps_request_all (void)
	Requests all available P-GPS data from nRF Cloud via MQTT. Not used for other transports.
int	nrf_cloud_pgps_begin_update (void)
	Use this function when you use a custom transport mechanism for downloading prediction data. When your pgps_event_handler_t receives a PGPS_EVT_REQUEST event, send the P-GPS request to the cloud over your transport, then call this function. This function resets the internal state of the library and prepares the flash storage to receive incoming data.
int	nrf_cloud_pgps_process_update (uint8_t *buf, size_t len)
	Call this function when your transport receives a block of prediction data. Prediction data must be received in file order.
int	nrf_cloud_pgps_finish_update (void)
	Call this function regardless of whether the download succeeded or failed.
void	nrf_cloud_pgps_request_reset (void)
	If previous request for P-GPS data failed, re-enable future retries. This should be called by the application after it attempts to handle PGPS_EVT_REQUEST, but is unable to complete it successfully. For example, it should be called if the cloud connection being used to transmit the request is temporarily unavailable.
int	nrf_cloud_pgps_process (const char *buf, size_t buf_len)
	Processes binary P-GPS data received from nRF Cloud over MQTT or REST.
int	nrf_cloud_pgps_update (struct nrf_cloud_pgps_result *file_location)
	Processes binary P-GPS data using URL received from nRF Cloud.
int	nrf_cloud_pgps_inject (struct nrf_cloud_pgps_prediction *p, const struct nrf_modem_gnss_agnss_data_frame *request)
	Injects binary P-GPS data to the modem. If request is NULL, it is assumed that only ephemerides assistance should be injected.
bool	nrf_cloud_pgps_loading (void)
	Find out if P-GPS update is in progress.
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.
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.

Detailed Description

Module to provide nRF Cloud Predicted GPS (P-GPS) support to nRF9160 SiP.