Various changes on GPS.h HAL definitions
- Support for all GnssSvInfo
- Support for more than 32 satellites
- CellID support for LTE
- Mandatory support for Pseudoranges
- New field in GpsClock
- New callback to report GPS hardware version
- Moved deprecated/retired structs into separate file
Change-Id: I114aa3f651998c17c7222575d148595cc303b6f4
diff --git a/include/hardware/gps.h b/include/hardware/gps.h
index 76b6cb7..6fd47a9 100644
--- a/include/hardware/gps.h
+++ b/include/hardware/gps.h
@@ -53,7 +53,7 @@
#define GPS_POSITION_MODE_MS_BASED 1
/**
* AGPS MS-Assisted mode. This mode is not maintained by the platform anymore.
- * It is strongly recommended to use GPS_POSITION_MODE_MS_BASE instead.
+ * It is strongly recommended to use GPS_POSITION_MODE_MS_BASED instead.
*/
#define GPS_POSITION_MODE_MS_ASSISTED 2
@@ -98,28 +98,31 @@
/** Flags for the gps_set_capabilities callback. */
-/** GPS HAL schedules fixes for GPS_POSITION_RECURRENCE_PERIODIC mode.
- If this is not set, then the framework will use 1000ms for min_interval
- and will start and call start() and stop() to schedule the GPS.
+/**
+ * GPS HAL schedules fixes for GPS_POSITION_RECURRENCE_PERIODIC mode. If this is
+ * not set, then the framework will use 1000ms for min_interval and will start
+ * and call start() and stop() to schedule the GPS.
*/
-#define GPS_CAPABILITY_SCHEDULING 0x0000001
+#define GPS_CAPABILITY_SCHEDULING (1 << 0)
/** GPS supports MS-Based AGPS mode */
-#define GPS_CAPABILITY_MSB 0x0000002
+#define GPS_CAPABILITY_MSB (1 << 1)
/** GPS supports MS-Assisted AGPS mode */
-#define GPS_CAPABILITY_MSA 0x0000004
+#define GPS_CAPABILITY_MSA (1 << 2)
/** GPS supports single-shot fixes */
-#define GPS_CAPABILITY_SINGLE_SHOT 0x0000008
+#define GPS_CAPABILITY_SINGLE_SHOT (1 << 3)
/** GPS supports on demand time injection */
-#define GPS_CAPABILITY_ON_DEMAND_TIME 0x0000010
+#define GPS_CAPABILITY_ON_DEMAND_TIME (1 << 4)
/** GPS supports Geofencing */
-#define GPS_CAPABILITY_GEOFENCING 0x0000020
+#define GPS_CAPABILITY_GEOFENCING (1 << 5)
/** GPS supports Measurements */
-#define GPS_CAPABILITY_MEASUREMENTS 0x0000040
+#define GPS_CAPABILITY_MEASUREMENTS (1 << 6)
/** GPS supports Navigation Messages */
-#define GPS_CAPABILITY_NAV_MESSAGES 0x0000080
+#define GPS_CAPABILITY_NAV_MESSAGES (1 << 7)
-/** Flags used to specify which aiding data to delete
- when calling delete_aiding_data(). */
+/**
+ * Flags used to specify which aiding data to delete when calling
+ * delete_aiding_data().
+ */
typedef uint16_t GpsAidingData;
// IMPORTANT: Note that the following values must match
// constants in GpsLocationProvider.java.
@@ -210,9 +213,11 @@
/** AGPS data connection failed */
#define GPS_AGPS_DATA_CONN_FAILED 5
+typedef uint16_t AGpsRefLocationType;
#define AGPS_REF_LOCATION_TYPE_GSM_CELLID 1
#define AGPS_REF_LOCATION_TYPE_UMTS_CELLID 2
#define AGPS_REG_LOCATION_TYPE_MAC 3
+#define AGPS_REF_LOCATION_TYPE_LTE_CELLID 4
/** Network types for update_network_state "type" parameter */
#define AGPS_RIL_NETWORK_TYPE_MOBILE 0
@@ -246,9 +251,14 @@
* Enumeration of the available values for the GPS Clock type.
*/
typedef uint8_t GpsClockType;
-/** The type is not available ot it is unknown. */
+/** The type is not available or it is unknown. */
#define GPS_CLOCK_TYPE_UNKNOWN 0
-/** The source of the time value reported by GPS clock is the local hardware clock. */
+/**
+ * The source of the time value reported by GPS clock is the local hardware
+ * clock. This is a mandatory flag. When the GpsSystemInfo's year_of_hw is 2016
+ * or higher, it is mandatory that 'time' is populated with the local hardware
+ * clock value, and this flag must always be set.
+ */
#define GPS_CLOCK_TYPE_LOCAL_HW_TIME 1
/**
* The source of the time value reported by GPS clock is the GPS time derived from satellites
@@ -296,7 +306,12 @@
#define GPS_MEASUREMENT_HAS_DOPPLER_SHIFT_UNCERTAINTY (1<<16)
/** A valid 'used in fix' flag is stored in the data structure. */
#define GPS_MEASUREMENT_HAS_USED_IN_FIX (1<<17)
-/** The value of 'pseudorange rate' is uncorrected. */
+/**
+ * The value of 'pseudorange rate' is uncorrected.
+ * This is a mandatory flag. It is mandatory that 'pseudorange rate' is
+ * populated with the uncorrected value, and this flag must always be set.
+ * See comments of GpsMeasurement::pseudorange_rate_mps for more details.
+ */
#define GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE (1<<18)
/**
@@ -316,9 +331,9 @@
typedef uint8_t GpsMultipathIndicator;
/** The indicator is not available or unknown. */
#define GPS_MULTIPATH_INDICATOR_UNKNOWN 0
-/** The measurement has been indicated to use multipath. */
+/** The measurement is indicated to be affected by multipath. */
#define GPS_MULTIPATH_INDICATOR_DETECTED 1
-/** The measurement has been indicated Not to use multipath. */
+/** The measurement is indicated to be not affected by multipath. */
#define GPS_MULTIPATH_INDICATOR_NOT_USED 2
/**
@@ -377,6 +392,27 @@
#define NAV_MESSAGE_STATUS_PARITY_REBUILT (1<<1)
/**
+ * Flag that indicates which extra data GnssSvInfo includes.
+ */
+typedef uint8_t GnssSvFlags;
+#define GNSS_SV_FLAGS_NONE 0
+#define GNSS_SV_FLAGS_HAS_EPHEMERIS_DATA (1 << 0)
+#define GNSS_SV_FLAGS_HAS_ALMANAC_DATA (1 << 1)
+#define GNSS_SV_FLAGS_USED_IN_FIX (1 << 2)
+
+/**
+ * Constellation type of GnssSvInfo
+ */
+typedef uint8_t GnssConstellationType;
+#define GNSS_CONSTELLATION_UNKNOWN 0
+#define GNSS_CONSTELLATION_GPS 1
+#define GNSS_CONSTELLATION_SBAS 2
+#define GNSS_CONSTELLATION_GLONASS 3
+#define GNSS_CONSTELLATION_QZSS 4
+#define GNSS_CONSTELLATION_BEIDOU 5
+#define GNSS_CONSTELLATION_GALILEO 6
+
+/**
* Name for the GPS XTRA interface.
*/
#define GPS_XTRA_INTERFACE "gps-xtra"
@@ -437,8 +473,9 @@
double latitude;
/** Represents longitude in degrees. */
double longitude;
- /** Represents altitude in meters above the WGS 84 reference
- * ellipsoid. */
+ /**
+ * Represents altitude in meters above the WGS 84 reference ellipsoid.
+ */
double altitude;
/** Represents speed in meters per second. */
float speed;
@@ -471,43 +508,124 @@
float azimuth;
} GpsSvInfo;
-/** Represents SV status. */
typedef struct {
- /** set to sizeof(GpsSvStatus) */
- size_t size;
-
- /** Number of SVs currently visible. */
- int num_svs;
-
- /** Contains an array of SV information. */
- GpsSvInfo sv_list[GPS_MAX_SVS];
-
- /** Represents a bit mask indicating which SVs
- * have ephemeris data.
- */
- uint32_t ephemeris_mask;
-
- /** Represents a bit mask indicating which SVs
- * have almanac data.
- */
- uint32_t almanac_mask;
+ /** set to sizeof(GnssSvInfo) */
+ size_t size;
/**
- * Represents a bit mask indicating which SVs
- * were used for computing the most recent position fix.
+ * Pseudo-random number for the SV, or Amanac/slot number for Glonass. The
+ * distinction is made by looking at constellation field. Values should be
+ * in the range of:
+ *
+ * - GPS: 1-32
+ * - SBAS: 120-151, 183-192
+ * - GLONASS: 1-24 (slot number)
+ * - QZSS: 193-200
+ * - Galileo: 1-25
+ * - Beidou: 1-35
*/
- uint32_t used_in_fix_mask;
+ int prn;
+
+ /** Signal to noise ratio. */
+ float snr;
+
+ /** Elevation of SV in degrees. */
+ float elevation;
+
+ /** Azimuth of SV in degrees. */
+ float azimuth;
+
+ /**
+ * Contains additional data about the given SV. Value should be one of those
+ * GNSS_SV_FLAGS_* constants
+ */
+ GnssSvFlags flags;
+
+ /**
+ * Defines the constellation of the given SV. Value should be one of those
+ * GNSS_CONSTELLATION_* constants
+ */
+ GnssConstellationType constellation;
+
+} GnssSvInfo;
+
+/**
+ * Represents SV status.
+ *
+ * When switching from pre-N to N version of GpsSvStatus:
+ *
+ * 1) Fill in the fields from num_svs through used_in_fix_mask the same way as
+ * was done before, e.g. using the range of 65-88 to report Glonass info,
+ * 201-235 for Beidou, etc. (but with no used_in_fix_mask info - those are
+ * index by prn, and thus for GPS only). This will help ensure compatibility
+ * when a newer GPS HAL is used with an older version of Android.
+ *
+ * 2) Fill in the gnss_sv_list with information about SVs from all
+ * constellations (GPS & other GNSS's) - when this is filled in, this will be
+ * the only source of information about satellite status (e.g. for working with
+ * GpsStatus facing applications), the earlier fields will be ignored.
+ */
+typedef struct {
+ /** set to sizeof(GpsSvStatus) */
+ size_t size;
+
+ /** Number of GPS SVs currently visible, refers to the SVs stored in sv_list */
+ int num_svs;
+
+ /** Contains an array of GPS SV information in legacy GPS format. */
+ GpsSvInfo sv_list[GPS_MAX_SVS];
+
+ /**
+ * Represents a bit mask indicating which GPS SVs have ephemeris data,
+ * refers to sv_list.
+ */
+ uint32_t ephemeris_mask;
+
+ /**
+ * Represents a bit mask indicating which GPS SVs have almanac data, refers
+ * to sv_list.
+ */
+ uint32_t almanac_mask;
+
+ /**
+ * Represents a bit mask indicating which GPS SVs
+ * were used for computing the most recent position fix,
+ * refers to sv_list.
+ */
+ uint32_t used_in_fix_mask;
+
+ /**
+ * Size of the array which contains SV info for all GNSS constellation
+ * except for GPS.
+ */
+ size_t gnss_sv_list_size;
+
+ /**
+ * Pointer to an array of SVs information for all GNSS constellations,
+ * except GPS, which is reported using sv_list
+ */
+ GnssSvInfo* gnss_sv_list;
+
} GpsSvStatus;
-
-/* 2G and 3G */
-/* In 3G lac is discarded */
+/* CellID for 2G, 3G and LTE, used in AGPS. */
typedef struct {
- uint16_t type;
+ AGpsRefLocationType type;
+ /** Mobile Country Code. */
uint16_t mcc;
+ /** Mobile Network Code .*/
uint16_t mnc;
+ /** Location Area Code in 2G, 3G and LTE. In 3G lac is discarded. In LTE,
+ * lac is populated with tac, to ensure that we don't break old clients that
+ * might rely in the old (wrong) behavior.
+ */
uint16_t lac;
+ /** Cell id in 2G. Utran Cell id in 3G. Cell Global Id EUTRA in LTE. */
uint32_t cid;
+ /** Tracking Area Code in LTE. */
+ uint16_t tac;
+ /** Physical Cell id in LTE (not used in 2G and 3G) */
+ uint16_t pcid;
} AGpsRefLocationCellID;
typedef struct {
@@ -516,20 +634,22 @@
/** Represents ref locations */
typedef struct {
- uint16_t type;
+ AGpsRefLocationType type;
union {
AGpsRefLocationCellID cellID;
AGpsRefLocationMac mac;
} u;
} AGpsRefLocation;
-/** Callback with location information.
- * Can only be called from a thread created by create_thread_cb.
+/**
+ * Callback with location information. Can only be called from a thread created
+ * by create_thread_cb.
*/
typedef void (* gps_location_callback)(GpsLocation* location);
-/** Callback with status information.
- * Can only be called from a thread created by create_thread_cb.
+/**
+ * Callback with status information. Can only be called from a thread created by
+ * create_thread_cb.
*/
typedef void (* gps_status_callback)(GpsStatus* status);
@@ -539,18 +659,21 @@
*/
typedef void (* gps_sv_status_callback)(GpsSvStatus* sv_info);
-/** Callback for reporting NMEA sentences.
- * Can only be called from a thread created by create_thread_cb.
+/**
+ * Callback for reporting NMEA sentences. Can only be called from a thread
+ * created by create_thread_cb.
*/
typedef void (* gps_nmea_callback)(GpsUtcTime timestamp, const char* nmea, int length);
-/** Callback to inform framework of the GPS engine's capabilities.
- * Capability parameter is a bit field of GPS_CAPABILITY_* flags.
+/**
+ * Callback to inform framework of the GPS engine's capabilities. Capability
+ * parameter is a bit field of GPS_CAPABILITY_* flags.
*/
typedef void (* gps_set_capabilities)(uint32_t capabilities);
-/** Callback utility for acquiring the GPS wakelock.
- * This can be used to prevent the CPU from suspending while handling GPS events.
+/**
+ * Callback utility for acquiring the GPS wakelock. This can be used to prevent
+ * the CPU from suspending while handling GPS events.
*/
typedef void (* gps_acquire_wakelock)();
@@ -560,12 +683,57 @@
/** Callback for requesting NTP time */
typedef void (* gps_request_utc_time)();
-/** Callback for creating a thread that can call into the Java framework code.
- * This must be used to create any threads that report events up to the framework.
+/**
+ * Callback for creating a thread that can call into the Java framework code.
+ * This must be used to create any threads that report events up to the
+ * framework.
*/
typedef pthread_t (* gps_create_thread)(const char* name, void (*start)(void *), void* arg);
-/** GPS callback structure. */
+/**
+ * Provides information about how new the underlying GPS/GNSS hardware and
+ * software is.
+ *
+ * This information will be available for Android Test Applications. If a GPS
+ * HAL does not provide this information, it will be considered "2015 or
+ * earlier".
+ *
+ * If a GPS HAL does provide this information, then newer years will need to
+ * meet newer CTS standards. E.g. if the date are 2016 or above, then N+ level
+ * GpsMeasurement support will be verified.
+ */
+typedef struct {
+ /** Set to sizeof(GpsSystemInfo) */
+ size_t size;
+ /* year in which the last update was made to the underlying hardware/firmware
+ * used to capture GNSS signals, e.g. 2016 */
+ uint16_t year_of_hw;
+} GpsSystemInfo;
+
+/**
+ * Callback to inform framework of the engine's hardware version information.
+ */
+typedef void (*gps_set_system_info)(const GpsSystemInfo* info);
+
+/**
+ * Legacy GPS callback structure.
+ * See GpsCallbacks for more information.
+ */
+typedef struct {
+ /** set to sizeof(GpsCallbacks_v1) */
+ size_t size;
+ gps_location_callback location_cb;
+ gps_status_callback status_cb;
+ gps_sv_status_callback sv_status_cb;
+ gps_nmea_callback nmea_cb;
+ gps_set_capabilities set_capabilities_cb;
+ gps_acquire_wakelock acquire_wakelock_cb;
+ gps_release_wakelock release_wakelock_cb;
+ gps_create_thread create_thread_cb;
+ gps_request_utc_time request_utc_time_cb;
+} GpsCallbacks_v1;
+
+/** New GPS callback structure. */
typedef struct {
/** set to sizeof(GpsCallbacks) */
size_t size;
@@ -578,8 +746,17 @@
gps_release_wakelock release_wakelock_cb;
gps_create_thread create_thread_cb;
gps_request_utc_time request_utc_time_cb;
-} GpsCallbacks;
+ /**
+ * Callback for the chipset to report system information.
+ *
+ * This field is newly introduced since N. The driver implementation must
+ * check 'size' field against 'sizeof(GpsCallbacks)' and
+ * 'sizeof(GpsCallbacks_v1)' to decide whether the new field is valid before
+ * calling it.
+ */
+ gps_set_system_info set_system_info_cb;
+} GpsCallbacks;
/** Represents the standard GPS interface. */
typedef struct {
@@ -604,10 +781,10 @@
int (*inject_time)(GpsUtcTime time, int64_t timeReference,
int uncertainty);
- /** Injects current location from another location provider
- * (typically cell ID).
- * latitude and longitude are measured in degrees
- * expected accuracy is measured in meters
+ /**
+ * Injects current location from another location provider (typically cell
+ * ID). Latitude and longitude are measured in degrees expected accuracy is
+ * measured in meters
*/
int (*inject_location)(double latitude, double longitude, float accuracy);
@@ -623,10 +800,10 @@
* preferred_accuracy represents the requested fix accuracy in meters.
* preferred_time represents the requested time to first fix in milliseconds.
*
- * 'mode' parameter should be one of GPS_POSITION_MODE_MS_BASE
+ * 'mode' parameter should be one of GPS_POSITION_MODE_MS_BASED
* or GPS_POSITION_MODE_STANDALONE.
* It is allowed by the platform (and it is recommended) to fallback to
- * GPS_POSITION_MODE_MS_BASE if GPS_POSITION_MODE_MS_ASSISTED is passed in, and
+ * GPS_POSITION_MODE_MS_BASED if GPS_POSITION_MODE_MS_ASSISTED is passed in, and
* GPS_POSITION_MODE_MS_BASED is supported.
*/
int (*set_position_mode)(GpsPositionMode mode, GpsPositionRecurrence recurrence,
@@ -636,9 +813,10 @@
const void* (*get_extension)(const char* name);
} GpsInterface;
-/** Callback to request the client to download XTRA data.
- * The client should download XTRA data and inject it by calling inject_xtra_data().
- * Can only be called from a thread created by create_thread_cb.
+/**
+ * Callback to request the client to download XTRA data. The client should
+ * download XTRA data and inject it by calling inject_xtra_data(). Can only be
+ * called from a thread created by create_thread_cb.
*/
typedef void (* gps_xtra_download_request)();
@@ -673,36 +851,11 @@
size_t (*get_internal_state)(char* buffer, size_t bufferSize);
} GpsDebugInterface;
-#pragma pack(push,4)
-// We need to keep the alignment of this data structure to 4-bytes, to ensure that in 64-bit
-// environments the size of this legacy definition does not collide with _v2. Implementations should
-// be using _v2 and _v3, so it's OK to pay the 'unaligned' penalty in 64-bit if an old
-// implementation is still in use.
-
-/** Represents the status of AGPS. */
+/*
+ * Represents the status of AGPS augmented to support IPv4 and IPv6.
+ */
typedef struct {
- /** set to sizeof(AGpsStatus_v1) */
- size_t size;
-
- AGpsType type;
- AGpsStatusValue status;
-} AGpsStatus_v1;
-
-#pragma pack(pop)
-
-/** Represents the status of AGPS augmented with a IPv4 address field. */
-typedef struct {
- /** set to sizeof(AGpsStatus_v2) */
- size_t size;
-
- AGpsType type;
- AGpsStatusValue status;
- uint32_t ipaddr;
-} AGpsStatus_v2;
-
-/* Represents the status of AGPS augmented to support IPv4 and IPv6. */
-typedef struct {
- /** set to sizeof(AGpsStatus_v3) */
+ /** set to sizeof(AGpsStatus) */
size_t size;
AGpsType type;
@@ -717,14 +870,13 @@
/**
* Must contain the IPv4 (AF_INET) or IPv6 (AF_INET6) address to report.
* Any other value of addr.ss_family will be rejected.
- * */
+ */
struct sockaddr_storage addr;
-} AGpsStatus_v3;
+} AGpsStatus;
-typedef AGpsStatus_v3 AGpsStatus;
-
-/** Callback with AGPS status information.
- * Can only be called from a thread created by create_thread_cb.
+/**
+ * Callback with AGPS status information. Can only be called from a thread
+ * created by create_thread_cb.
*/
typedef void (* agps_status_callback)(AGpsStatus* status);
@@ -734,42 +886,12 @@
gps_create_thread create_thread_cb;
} AGpsCallbacks;
-
-/** Extended interface for AGPS support. */
-typedef struct {
- /** set to sizeof(AGpsInterface_v1) */
- size_t size;
-
- /**
- * Opens the AGPS interface and provides the callback routines
- * to the implementation of this interface.
- */
- void (*init)( AGpsCallbacks* callbacks );
- /**
- * Notifies that a data connection is available and sets
- * the name of the APN to be used for SUPL.
- */
- int (*data_conn_open)( const char* apn );
- /**
- * Notifies that the AGPS data connection has been closed.
- */
- int (*data_conn_closed)();
- /**
- * Notifies that a data connection is not available for AGPS.
- */
- int (*data_conn_failed)();
- /**
- * Sets the hostname and port for the AGPS server.
- */
- int (*set_server)( AGpsType type, const char* hostname, int port );
-} AGpsInterface_v1;
-
/**
* Extended interface for AGPS support, it is augmented to enable to pass
* extra APN data.
*/
typedef struct {
- /** set to sizeof(AGpsInterface_v2) */
+ /** set to sizeof(AGpsInterface) */
size_t size;
/**
@@ -803,9 +925,7 @@
int (*data_conn_open_with_apn_ip_type)(
const char* apn,
ApnIpType apnIpType);
-} AGpsInterface_v2;
-
-typedef AGpsInterface_v2 AGpsInterface;
+} AGpsInterface;
/** Error codes associated with certificate operations */
#define AGPS_CERTIFICATE_OPERATION_SUCCESS 0
@@ -936,8 +1056,9 @@
} GpsNiNotification;
-/** Callback with NI notification.
- * Can only be called from a thread created by create_thread_cb.
+/**
+ * Callback with NI notification. Can only be called from a thread created by
+ * create_thread_cb.
*/
typedef void (*gps_ni_notify_callback)(GpsNiNotification *notification);
@@ -1280,7 +1401,6 @@
void (*remove_geofence_area) (int32_t geofence_id);
} GpsGeofencingInterface;
-
/**
* Represents an estimate of the GPS clock time.
*/
@@ -1302,7 +1422,7 @@
/**
* Indicates the type of time reported by the 'time_ns' field.
- * This is a Mandatory field.
+ * This is a mandatory field.
*/
GpsClockType type;
@@ -1321,7 +1441,11 @@
* Sub-nanosecond accuracy can be provided by means of the 'bias' field.
* The value contains the 'time uncertainty' in it.
*
- * This is a Mandatory field.
+ * This field is mandatory.
+ *
+ * For devices where GpsSystemInfo's year_of_hw is set to 2016+, it is
+ * mandatory that it contains the value from the 'local hardware clock, and
+ * thus GPS_CLOCK_TYPE_LOCAL_HW_TIME must be set in 'type' field.
*/
int64_t time_ns;
@@ -1329,8 +1453,9 @@
* 1-Sigma uncertainty associated with the clock's time in nanoseconds.
* The uncertainty is represented as an absolute (single sided) value.
*
- * This value should be set if GPS_CLOCK_TYPE_GPS_TIME is set.
- * If the data is available 'flags' must contain GPS_CLOCK_HAS_TIME_UNCERTAINTY.
+ * If the data is available, 'flags' must contain
+ * GPS_CLOCK_HAS_TIME_UNCERTAINTY. If GPS has computed a position fix, this
+ * field is mandatory and must be populated.
*/
double time_uncertainty_ns;
@@ -1345,8 +1470,9 @@
* true time (GPS time) = time_ns + (full_bias_ns + bias_ns)
*
* This value contains the 'bias uncertainty' in it.
- * If the data is available 'flags' must contain GPS_CLOCK_HAS_FULL_BIAS.
-
+ * If GPS has computed a position fix this field is mandatory and must be
+ * populated. If the data is available 'flags' must contain
+ * GPS_CLOCK_HAS_FULL_BIAS.
*/
int64_t full_bias_ns;
@@ -1354,7 +1480,9 @@
* Sub-nanosecond bias.
* The value contains the 'bias uncertainty' in it.
*
- * If the data is available 'flags' must contain GPS_CLOCK_HAS_BIAS.
+ * If the data is available 'flags' must contain GPS_CLOCK_HAS_BIAS. If GPS
+ * has computed a position fix, this field is mandatory and must be
+ * populated.
*/
double bias_ns;
@@ -1362,7 +1490,9 @@
* 1-Sigma uncertainty associated with the clock's bias in nanoseconds.
* The uncertainty is represented as an absolute (single sided) value.
*
- * If the data is available 'flags' must contain GPS_CLOCK_HAS_BIAS_UNCERTAINTY.
+ * If the data is available 'flags' must contain
+ * GPS_CLOCK_HAS_BIAS_UNCERTAINTY. If GPS has computed a position fix this
+ * field is mandatory and must be populated.
*/
double bias_uncertainty_ns;
@@ -1373,8 +1503,10 @@
* The value contains the 'drift uncertainty' in it.
* If the data is available 'flags' must contain GPS_CLOCK_HAS_DRIFT.
*
- * If GpsMeasurement's 'flags' field contains GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE,
- * it is encouraged that this field is also provided.
+ * If GpsMeasurement's 'flags' field contains
+ * GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE, it is encouraged that
+ * this field is also provided. If GPS has computed a position fix this
+ * field is mandatory and must be populated.
*/
double drift_nsps;
@@ -1382,9 +1514,30 @@
* 1-Sigma uncertainty associated with the clock's drift in nanoseconds (per second).
* The uncertainty is represented as an absolute (single sided) value.
*
- * If the data is available 'flags' must contain GPS_CLOCK_HAS_DRIFT_UNCERTAINTY.
+ * If the data is available 'flags' must contain
+ * GPS_CLOCK_HAS_DRIFT_UNCERTAINTY. If GPS has computed a position fix this
+ * field is mandatory and must be populated.
*/
double drift_uncertainty_nsps;
+
+ /**
+ * When the GPS_CLOCK_TYPE_LOCAL_HW_TIME is set, this field is mandatory.
+ *
+ * A "discontinuity" is meant to cover the case of a switch from one source
+ * of clock to another. A single free-running crystal oscillator (XO)
+ * should generally not have any discontinuities, and this can be set to 0.
+ * If, however, the time_ns value (HW clock) is derived from a composite of
+ * sources, that is not as smooth as a typical XO, then this value shall be
+ * set to the time_ns value since which the time_ns has been derived from a
+ * single, high quality clock (XO like, or better, that's typically used
+ * during continuous GPS signal sampling.)
+ *
+ * It is expected, esp. during periods where there are few GNSS signals
+ * available, that the HW clock be discontinuity-free as long as possible,
+ * as this avoids the need to use (waste) a GPS measurement to fully
+ * re-solve for the clock bias and drift.
+ */
+ int64_t time_of_last_hw_clock_discontinuity_ns;
} GpsClock;
/**
@@ -1399,7 +1552,7 @@
/**
* Pseudo-random number in the range of [1, 32]
- * This is a Mandatory value.
+ * This is a mandatory value.
*/
int8_t prn;
@@ -1412,7 +1565,7 @@
* measurement time = GpsClock::time_ns + time_offset_ns
*
* It provides an individual time-stamp for the measurement, and allows sub-nanosecond accuracy.
- * This is a Mandatory value.
+ * This is a mandatory value.
*/
double time_offset_ns;
@@ -1420,7 +1573,7 @@
* Per satellite sync state. It represents the current sync state for the associated satellite.
* Based on the sync state, the 'received GPS tow' field should be interpreted accordingly.
*
- * This is a Mandatory value.
+ * This is a mandatory value.
*/
GpsMeasurementState state;
@@ -1454,7 +1607,7 @@
* Carrier-to-noise density in dB-Hz, in the range [0, 63].
* It contains the measured C/N0 value for the signal at the antenna input.
*
- * This is a Mandatory value.
+ * This is a mandatory value.
*/
double c_n0_dbhz;
@@ -1463,13 +1616,9 @@
* The correction of a given Pseudorange Rate value includes corrections for receiver and
* satellite clock frequency errors.
*
- * If GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE is set in 'flags' field, this field must
- * be populated with the 'uncorrected' reading.
- * If GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE is not set in 'flags' field, this field
- * must be populated with the 'corrected' reading. This is the default behavior.
- *
* It is encouraged to provide the 'uncorrected' 'pseudorange rate', and provide GpsClock's
- * 'drift' field as well.
+ * 'drift' field as well. When providing the uncorrected pseudorange rate,
+ * do not apply the corrections described above.
*
* The value includes the 'pseudorange rate uncertainty' in it.
* A positive 'uncorrected' value indicates that the SV is moving away from the receiver.
@@ -1478,15 +1627,22 @@
* shift' is given by the equation:
* pseudorange rate = -k * doppler shift (where k is a constant)
*
- * This is a Mandatory value.
+ * This field should be based on the signal energy doppler measurement. (See
+ * also pseudorate_rate_carrier_mps for a similar field, based on carrier
+ * phase changes.)
+ *
+ * This is a mandatory value. It is mandatory (and expected) that it
+ * contains the 'uncorrected' reading, and
+ * GPS_MEASUREMENT_HAS_UNCORRECTED_PSEUDORANGE_RATE must be set in 'flags'
+ * field.
*/
double pseudorange_rate_mps;
/**
- * 1-Sigma uncertainty of the pseudurange rate in m/s.
+ * 1-Sigma uncertainty of the pseudorange_rate_mps.
* The uncertainty is represented as an absolute (single sided) value.
*
- * This is a Mandatory value.
+ * This is a mandatory value.
*/
double pseudorange_rate_uncertainty_mps;
@@ -1494,7 +1650,7 @@
* Accumulated delta range's state. It indicates whether ADR is reset or there is a cycle slip
* (indicating loss of lock).
*
- * This is a Mandatory value.
+ * This is a mandatory value.
*/
GpsAccumulatedDeltaRangeState accumulated_delta_range_state;
@@ -1651,7 +1807,7 @@
* Azimuth in degrees, in the range [0, 360).
* The value contains the 'azimuth uncertainty' in it.
* If the data is available, 'flags' must contain GPS_MEASUREMENT_HAS_AZIMUTH.
- * */
+ */
double azimuth_deg;
/**
@@ -1667,6 +1823,41 @@
* If the data is available, 'flags' must contain GPS_MEASUREMENT_HAS_USED_IN_FIX.
*/
bool used_in_fix;
+
+ /**
+ * Pseudorange rate (based on carrier phase changes) at the timestamp in m/s.
+ *
+ * The correction of a given Pseudorange Rate value includes corrections for
+ * receiver and satellite clock frequency errors.
+ *
+ * It is mandatory to provide the 'uncorrected' 'pseudorange rate' in this
+ * field. (Do not apply the corrections described above.)
+ *
+ * The value includes the 'pseudorange rate (carrier) uncertainty' in it. A
+ * positive 'uncorrected' value indicates that the SV is moving away from
+ * the receiver.
+ *
+ * The sign of the 'uncorrected' 'pseudorange rate' and its relation to the
+ * sign of 'doppler shift' is given by the equation:
+ *
+ * pseudorange rate = -k * doppler shift (where k is a constant)
+ *
+ * This field must be based on changes in the carrier phase measurement.
+ * (See pseudorange_rate_mps for a similar field, based on signal energy
+ * doppler.)
+ *
+ * It is mandatory that this value be provided, when signals are
+ * sufficiently strong, e.g. signals from a GPS simulator at >= 30 dB-Hz.
+ */
+ double pseudorange_rate_carrier_mps;
+ /**
+ * 1-Sigma uncertainty of the pseudorange_rate_carrier_mps.
+ * The uncertainty is represented as an absolute (single sided) value.
+ *
+ * This is a mandatory value when pseudorange_rate_carrier_mps is provided.
+ */
+ double pseudorange_rate_carrier_uncertainty_mps;
+
} GpsMeasurement;
/** Represents a reading of GPS measurements. */
@@ -1740,13 +1931,13 @@
/**
* Pseudo-random number in the range of [1, 32]
- * This is a Mandatory value.
+ * This is a mandatory value.
*/
int8_t prn;
/**
* The type of message contained in the structure.
- * This is a Mandatory value.
+ * This is a mandatory value.
*/
GpsNavigationMessageType type;
@@ -1778,7 +1969,7 @@
* If this value is different from zero, 'data' must point to an array of the same size.
* e.g. for L1 C/A the size of the sub-frame will be 40 bytes (10 words, 30 bits/word).
*
- * This is a Mandatory value.
+ * This is a mandatory value.
*/
size_t data_length;