gps.h File Reference


Detailed Description

GNSS core 'c' function library: GPS specific functions.

Author:
Glenn D. MacGougan (GDM)
Date:
2005-08-14
Since:
2005-07-31
"LICENSE INFORMATION"
Copyright (c) 2007, refer to 'author' doxygen tags
All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided the following conditions are met:

THIS SOFTWARE IS PROVIDED BY THE CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Definition in file gps.h.

#include "basictypes.h"

Go to the source code of this file.

Data Structures

struct  GPS_structEphemeris
 A set of satellite orbit parameters that is used to calculate GPS satellite positions and velocities. In the ephemeris structure below, the parameters for computing satellite clock corrections are also included. More...
struct  GPS_structAlmanac
 A limited set of satellite orbit parameters that is used to calculate rough GPS satellite positions and velocities. The parameters for computing rough satellite clock corrections are also included. More...

Functions

void GPS_ComputeSatelliteClockCorrectionAndDrift (const unsigned short transmission_gpsweek, const double transmission_gpstow, const unsigned short ephem_week, const unsigned toe, const unsigned toc, const double af0, const double af1, const double af2, const double ecc, const double sqrta, const double delta_n, const double m0, const double tgd, const unsigned char mode, double *clock_correction, double *clock_drift)
void GPS_ComputeSatellitePositionAndVelocity (const unsigned short transmission_gpsweek, const double transmission_gpstow, const unsigned short ephem_week, const unsigned toe, const double m0, const double delta_n, const double ecc, const double sqrta, const double omega0, const double i0, const double w, const double omegadot, const double idot, const double cuc, const double cus, const double crc, const double crs, const double cic, const double cis, const double estimateOfTrueRange, const double estimteOfRangeRate, double *x, double *y, double *z, double *vx, double *vy, double *vz)
void GPS_ComputeUserToSatelliteRange (const double userX, const double userY, const double userZ, const double satX, const double satY, const double satZ, double *range)
void GPS_ComputeUserToSatelliteRangeAndRangeRate (const double userX, const double userY, const double userZ, const double userVx, const double userVy, const double userVz, const double satX, const double satY, const double satZ, const double satVx, const double satVy, const double satVz, double *range, double *range_rate)
void GPS_ComputeSatellitePositionVelocityAzimuthElevationDoppler_BasedOnAlmanacData (const double userX, const double userY, const double userZ, const unsigned short gpsweek, const double gpstow, const double toa, const unsigned short almanac_week, const unsigned short prn, const double ecc, const double i0, const double omegadot, const double sqrta, const double omega0, const double w, const double m0, const double af0, const double af1, double *clock_correction, double *clock_drift, double *satX, double *satY, double *satZ, double *satVx, double *satVy, double *satVz, double *azimuth, double *elevation, double *doppler)
void GPS_ComputeSatellitePositionVelocityAzimuthElevationDoppler_BasedOnEphmerisData (const double userX, const double userY, const double userZ, const unsigned short gpsweek, const double gpstow, const unsigned short ephem_week, const unsigned toe, const unsigned toc, const double af0, const double af1, const double af2, const double tgd, const double m0, const double delta_n, const double ecc, const double sqrta, const double omega0, const double i0, const double w, const double omegadot, const double idot, const double cuc, const double cus, const double crc, const double crs, const double cic, const double cis, double *clock_correction, double *clock_drift, double *satX, double *satY, double *satZ, double *satVx, double *satVy, double *satVz, double *azimuth, double *elevation, double *doppler)
BOOL GPS_DecodeRawGPSEphemeris (const unsigned char subframe1[30], const unsigned char subframe2[30], const unsigned char subframe3[30], unsigned short prn, unsigned *tow, unsigned short *iodc, unsigned char *iode, unsigned *toe, unsigned *toc, unsigned short *week, unsigned char *health, unsigned char *alert_flag, unsigned char *anti_spoof, unsigned char *code_on_L2, unsigned char *ura, unsigned char *L2_P_data_flag, unsigned char *fit_interval_flag, unsigned short *age_of_data_offset, double *tgd, double *af2, double *af1, double *af0, double *m0, double *delta_n, double *ecc, double *sqrta, double *omega0, double *i0, double *w, double *omegadot, double *idot, double *cuc, double *cus, double *crc, double *crs, double *cic, double *cis)


Function Documentation

void GPS_ComputeSatelliteClockCorrectionAndDrift ( const unsigned short  transmission_gpsweek,
const double  transmission_gpstow,
const unsigned short  ephem_week,
const unsigned  toe,
const unsigned  toc,
const double  af0,
const double  af1,
const double  af2,
const double  ecc,
const double  sqrta,
const double  delta_n,
const double  m0,
const double  tgd,
const unsigned char  mode,
double *  clock_correction,
double *  clock_drift 
)

Computes the satellite clock and clock dirft corrections given the clock model and ephemeris information.

Author:
Glenn D. MacGougan (GDM)
Date:
2005-08-12
Since:
2005-08-12
Remarks:
(1) The clock correction parameter is sensitive to the polynomial coefficient source which is either ephemeris related from subframe 1 or from the gps almanac (subframes 4,5). The ephemeris parameters have higher precision 22 & 16 vs 11 & 11 bits.
(2) User must compensate for the GPS week rollover
REFERENCES
[1] ICD-GPS-200C, p. 88-101
[2] Teunissen, P. J. G. & A. Kleusberg (editors) (1998). GPS for Geodesy, 2nd Edition. pp. 43-107 [3] Hofmann-Wellenhof, B. & J. Collins (1994). GPS Theory and Practice, 3rd Edition.
Springer-Verlag Wien New York, pp. 43-74
[4] Wong, R.V.C & K.P. Schwarz (1985). Dynamic Positioning with an Integrated GPS-INS. Formulae and Baseline Tests. University of Calgary. UCSE Report #30003. pp. 22
Parameters:
transmission_gpsweek  GPS week when signal was transmit (0-1024+) [weeks]
transmission_gpstow  GPS time of week when signal was transmit [s]
ephem_week  ephemeris: GPS week (0-1024+) [weeks]
toe  ephemeris: time of week [s]
toc  ephemeris: clock reference time of week [s]
af0  ephemeris: polynomial clock correction coefficient [s], Note: parameters from ephemeris preferred vs almanac (22 vs 11 bits)
af1  ephemeris: polynomial clock correction coefficient [s/s], Note: parameters from ephemeris preferred vs almanac (16 vs 11 bits)
af2  ephemeris: polynomial clock correction coefficient [s/s^2]
ecc  ephemeris: eccentricity of satellite orbit []
sqrta  ephemeris: square root of the semi-major axis of orbit [m^(1/2)]
delta_n  ephemeris: mean motion difference from computed value [rad]
m0  ephemeris: mean anomaly at reference time [rad]
tgd  ephemeris: group delay differential between L1 and L2 [s]
mode  0=L1 only, 1=L2 only (see p. 90, ICD-GPS-200C)
clock_correction  satellite clock correction [m]
clock_drift  satellite clock drift correction [m/s]

Definition at line 72 of file gps.c.

void GPS_ComputeSatellitePositionAndVelocity ( const unsigned short  transmission_gpsweek,
const double  transmission_gpstow,
const unsigned short  ephem_week,
const unsigned  toe,
const double  m0,
const double  delta_n,
const double  ecc,
const double  sqrta,
const double  omega0,
const double  i0,
const double  w,
const double  omegadot,
const double  idot,
const double  cuc,
const double  cus,
const double  crc,
const double  crs,
const double  cic,
const double  cis,
const double  estimateOfTrueRange,
const double  estimteOfRangeRate,
double *  x,
double *  y,
double *  z,
double *  vx,
double *  vy,
double *  vz 
)

Computes the satellite position and velocity in WGS84 based on the supplied ephemeris/almanac parameters.

Author:
Glenn D. MacGougan (GDM)
Date:
2005-07-31
Since:
2005-07-31
REFERENCES
[1] ICD-GPS-200C, p. 94-101
[2] Teunissen, P. J. G. & A. Kleusberg (editors) (1998). GPS for Geodesy, 2nd Edition. pp. 43-107
[3] Hofmann-Wellenhof, B. & J. Collins (1994). GPS Theory and Practice, 3rd Edition. Springer-Verlag Wien New York, pp. 43-74
[4] Wong, R.V.C & K.P. Schwarz (1985). Dynamic Positioning with an Integrated GPS-INS. Formulae and Baseline Tests. University of Calgary. UCSE Report #30003. pp. 22
Parameters:
transmission_gpsweek  GPS week when signal was transmit (0-1024+) [weeks]
transmission_gpstow  GPS time of week when signal was transmit [s]
ephem_week  ephemeris: GPS week (0-1024+) [weeks]
toe  ephemeris: time of week [s]
m0  ephemeris: mean anomaly at reference time [rad]
delta_n  ephemeris: mean motion difference from computed value [rad]
ecc  ephemeris: eccentricity []
sqrta  ephemeris: square root of the semi-major axis [m^(1/2)]
omega0  ephemeris: longitude of ascending node of orbit plane at weekly epoch [rad]
i0  ephemeris: inclination angle at reference time [rad]
w  ephemeris: argument of perigee [rad]
omegadot  ephemeris: rate of right ascension [rad/s]
idot  ephemeris: rate of inclination angle [rad/s]
cuc  ephemeris: amplitude of the cosine harmonic correction term to the argument of latitude [rad]
cus  ephemeris: amplitude of the sine harmonic correction term to the argument of latitude [rad]
crc  ephemeris: amplitude of the cosine harmonic correction term to the orbit radius [m]
crs  ephemeris: amplitude of the sine harmonic correction term to the orbit radius [m]
cic  ephemeris: amplitude of the cosine harmonic correction term to the angle of inclination [rad]
cis  ephemeris: amplitude of the sine harmonic correction term to the angle of inclination [rad]
estimateOfTrueRange  best estimate of the signal propagation time (in m) for Sagnac effect compensation [m]
estimteOfRangeRate  best estimate of the true signal Doppler (in m/s) for Sagnac effect compensation [m/s]
x  satellite x [m]
y  satellite y [m]
z  satellite z [m]
vx  satellite velocity x [m/s]
vy  satellite velocity y [m/s]
vz  satellite velocity z [m/s]

Definition at line 151 of file gps.c.

void GPS_ComputeSatellitePositionVelocityAzimuthElevationDoppler_BasedOnAlmanacData ( const double  userX,
const double  userY,
const double  userZ,
const unsigned short  gpsweek,
const double  gpstow,
const double  toa,
const unsigned short  almanac_week,
const unsigned short  prn,
const double  ecc,
const double  i0,
const double  omegadot,
const double  sqrta,
const double  omega0,
const double  w,
const double  m0,
const double  af0,
const double  af1,
double *  clock_correction,
double *  clock_drift,
double *  satX,
double *  satY,
double *  satZ,
double *  satVx,
double *  satVy,
double *  satVz,
double *  azimuth,
double *  elevation,
double *  doppler 
)

Computes the satellite position and velocity in WGS84 based on almanac data.

Author:
Glenn D. MacGougan (GDM)
Date:
2005-08-15
Since:
2005-08-15
Remarks:
(1) Assumes L1 for the clock correction mode
(2) This calculation solves for the satellite position at the true GPS time of week specified. It includes compensation for the satellite clock correction and the Saganc effect, which is a function of the user position.
REFERENCES
[1] ICD-GPS-200C
Parameters:
userX  user X position WGS84 ECEF [m]
userY  user Y position WGS84 ECEF [m]
userZ  user Z position WGS84 ECEF [m]
gpsweek  user gps week (0-1024+) [week]
gpstow  user time of week [s]
toa  time of applicability [s]
almanac_week  gps week of almanac (0-1024+) [week]
prn  GPS prn number []
ecc  eccentricity []
i0  orbital inclination at reference time [rad]
omegadot  rate of right ascension [rad/s]
sqrta  square root of the semi-major axis [m^(1/2)]
omega0  longitude of ascending node of orbit plane at weekly epoch [rad]
w  argument of perigee [rad]
m0  mean anomaly at reference time [rad]
af0  polynomial clock correction coefficient (clock bias) [s], Note: parameters from ephemeris preferred vs almanac (22 vs 11 bits)
af1  polynomial clock correction coefficient (clock drift) [s/s], Note: parameters from ephemeris preferred vs almanac (16 vs 11 bits)
clock_correction  clock correction for this satellite for this epoch [m]
clock_drift  clock drift correction for this satellite for this epoch [m/s]
satX  satellite X position WGS84 ECEF [m]
satY  satellite Y position WGS84 ECEF [m]
satZ  satellite Z position WGS84 ECEF [m]
satVx  satellite X velocity WGS84 ECEF [m/s]
satVy  satellite Y velocity WGS84 ECEF [m/s]
satVz  satellite Z velocity WGS84 ECEF [m/s]
azimuth  satelilte azimuth [rad]
elevation  satelilte elevation [rad]
doppler  satellite doppler with respect to the user position [m/s], Note: User must convert to Hz

Definition at line 390 of file gps.c.

void GPS_ComputeSatellitePositionVelocityAzimuthElevationDoppler_BasedOnEphmerisData ( const double  userX,
const double  userY,
const double  userZ,
const unsigned short  gpsweek,
const double  gpstow,
const unsigned short  ephem_week,
const unsigned  toe,
const unsigned  toc,
const double  af0,
const double  af1,
const double  af2,
const double  tgd,
const double  m0,
const double  delta_n,
const double  ecc,
const double  sqrta,
const double  omega0,
const double  i0,
const double  w,
const double  omegadot,
const double  idot,
const double  cuc,
const double  cus,
const double  crc,
const double  crs,
const double  cic,
const double  cis,
double *  clock_correction,
double *  clock_drift,
double *  satX,
double *  satY,
double *  satZ,
double *  satVx,
double *  satVy,
double *  satVz,
double *  azimuth,
double *  elevation,
double *  doppler 
)

Computes the satellite position and velocity in WGS84 based on ephemeris data.

Author:
Glenn D. MacGougan (GDM)
Date:
2005-08-15
Since:
2005-08-15
Remarks:
(1) Assumes L1 for the clock correction mode
(2) This calculation solves for the satellite position at the true GPS time of week specified. It includes compensation for the satellite clock correction and the Saganc effect, which is a function of the user position.
(3) This function can be called with almanac data by inputting the almanac information and zero for the terms not available. toe and toc are the toa in that case.
REFERENCES
[1] ICD-GPS-200C
Parameters:
userX  user X position WGS84 ECEF [m]
userY  user Y position WGS84 ECEF [m]
userZ  user Z position WGS84 ECEF [m]
gpsweek  gps week of signal transmission (0-1024+) [week]
gpstow  time of week of signal transmission (gpstow-psr/c) [s]
ephem_week  ephemeris: GPS week (0-1024+) [weeks]
toe  ephemeris: time of week [s]
toc  ephemeris: clock reference time of week [s]
af0  ephemeris: polynomial clock correction coefficient [s], Note: parameters from ephemeris preferred vs almanac (22 vs 11 bits)
af1  ephemeris: polynomial clock correction coefficient [s/s], Note: parameters from ephemeris preferred vs almanac (16 vs 11 bits)
af2  ephemeris: polynomial clock correction coefficient [s/s^2]
tgd  ephemeris: group delay differential between L1 and L2 [s]
m0  ephemeris: mean anomaly at reference time [rad]
delta_n  ephemeris: mean motion difference from computed value [rad/s]
ecc  ephemeris: eccentricity []
sqrta  ephemeris: square root of the semi-major axis [m^(1/2)]
omega0  ephemeris: longitude of ascending node of orbit plane at weekly epoch [rad]
i0  ephemeris: inclination angle at reference time [rad]
w  ephemeris: argument of perigee [rad]
omegadot  ephemeris: rate of right ascension [rad/s]
idot  ephemeris: rate of inclination angle [rad/s]
cuc  ephemeris: amplitude of the cosine harmonic correction term to the argument of latitude [rad]
cus  ephemeris: amplitude of the sine harmonic correction term to the argument of latitude [rad]
crc  ephemeris: amplitude of the cosine harmonic correction term to the orbit radius [m]
crs  ephemeris: amplitude of the sine harmonic correction term to the orbit radius [m]
cic  ephemeris: amplitude of the cosine harmonic correction term to the angle of inclination [rad]
cis  ephemeris: amplitude of the sine harmonic correction term to the angle of inclination [rad]
clock_correction  clock correction for this satellite for this epoch [m]
clock_drift  clock drift correction for this satellite for this epoch [m/s]
satX  satellite X position WGS84 ECEF [m]
satY  satellite Y position WGS84 ECEF [m]
satZ  satellite Z position WGS84 ECEF [m]
satVx  satellite X velocity WGS84 ECEF [m/s]
satVy  satellite Y velocity WGS84 ECEF [m/s]
satVz  satellite Z velocity WGS84 ECEF [m/s]
azimuth  satelilte azimuth [rad]
elevation  satelilte elevation [rad]
doppler  satellite doppler with respect to the user position [m/s], Note: User must convert to Hz

Definition at line 549 of file gps.c.

void GPS_ComputeUserToSatelliteRange ( const double  userX,
const double  userY,
const double  userZ,
const double  satX,
const double  satY,
const double  satZ,
double *  range 
)

Computes the user to satellite range given the user and satellite position.

Author:
Glenn D. MacGougan (GDM)
Date:
2006-11-23
Since:
2006-11-23
Parameters:
userX  user X position WGS84 ECEF [m]
userY  user Y position WGS84 ECEF [m]
userZ  user Z position WGS84 ECEF [m]
satX  satellite X position WGS84 ECEF [m]
satY  satellite Y positoin WGS84 ECEF [m]
satZ  satellite Z position WGS84 ECEF [m]
range  user to satellite range [m]

Definition at line 331 of file gps.c.

void GPS_ComputeUserToSatelliteRangeAndRangeRate ( const double  userX,
const double  userY,
const double  userZ,
const double  userVx,
const double  userVy,
const double  userVz,
const double  satX,
const double  satY,
const double  satZ,
const double  satVx,
const double  satVy,
const double  satVz,
double *  range,
double *  range_rate 
)

Computes the user to satellite range and range rate given the user and satellite position and velocities.

Author:
Glenn D. MacGougan (GDM)
Date:
2005-08-15
Since:
2005-08-15
Parameters:
userX  user X position WGS84 ECEF [m]
userY  user Y position WGS84 ECEF [m]
userZ  user Z position WGS84 ECEF [m]
userVx  user X velocity WGS84 ECEF [m/s]
userVy  user Y velocity WGS84 ECEF [m/s]
userVz  user Z velocity WGS84 ECEF [m/s]
satX  satellite X position WGS84 ECEF [m]
satY  satellite Y positoin WGS84 ECEF [m]
satZ  satellite Z position WGS84 ECEF [m]
satVx  satellite X velocity WGS84 ECEF [m/s]
satVy  satellite Y velocity WGS84 ECEF [m/s]
satVz  satellite Z velocity WGS84 ECEF [m/s]
range  user to satellite range [m]
range_rate  user to satellite range rate [m/s]

Definition at line 354 of file gps.c.

BOOL GPS_DecodeRawGPSEphemeris ( const unsigned char  subframe1[30],
const unsigned char  subframe2[30],
const unsigned char  subframe3[30],
unsigned short  prn,
unsigned *  tow,
unsigned short *  iodc,
unsigned char *  iode,
unsigned *  toe,
unsigned *  toc,
unsigned short *  week,
unsigned char *  health,
unsigned char *  alert_flag,
unsigned char *  anti_spoof,
unsigned char *  code_on_L2,
unsigned char *  ura,
unsigned char *  L2_P_data_flag,
unsigned char *  fit_interval_flag,
unsigned short *  age_of_data_offset,
double *  tgd,
double *  af2,
double *  af1,
double *  af0,
double *  m0,
double *  delta_n,
double *  ecc,
double *  sqrta,
double *  omega0,
double *  i0,
double *  w,
double *  omegadot,
double *  idot,
double *  cuc,
double *  cus,
double *  crc,
double *  crs,
double *  cic,
double *  cis 
)

Decodes the raw gps ephemeris (note, with the parity bits removed).

Author:
Glenn D. MacGougan (GDM)
Date:
2005-08-15
Since:
2005-08-15
Returns:
TRUE(1) if successful, FALSE(0) otherwise
Remarks:
(1) Parity bits must be removed from the input subframe data
(2) Returns TRUE(1) if data is successfully decoded
(3) Returns FALSE(0) if the subframe id's are incorrect, i.e. must be subframe1, subframe2, subframe3 in that order
(4) Returns FALSE(0) if the iode's are not consistent for all subframes, note 8 LSB bits of the iodc should equal subframe2 and subframe3 iode
(5) Uses IBM PC format byte alignment
REFERENCES
[1] ICD-GPS-200C

code_on_L2

Parameters:
subframe1  subframe 1 data, 30 bytes * 8bits/byte = 240 bits, thus parity bits have been removed
subframe2  subframe 2 data, 30 bytes * 8bits/byte = 240 bits, thus parity bits have been removed
subframe3  subframe 3 data, 30 bytes * 8bits/byte = 240 bits, thus parity bits have been removed
prn  GPS PRN number (helps with debugging)
tow  time of week in subframe1, the time of the leading bit edge of subframe 2 [s]
iodc  10 bit issue of data (clock), 8 LSB bits will match the iode []
iode  8 bit issue of data (ephemeris) []
toe  reference time ephemeris (0-604800) [s]
toc  reference time (clock) (0-604800) [s]
week  10 bit gps week 0-1023 (user must account for week rollover ) [week]
health  6 bit health parameter, 0 if healthy, unhealth othersize [0=healthy]
alert_flag  1 = URA may be worse than indicated [0,1]
anti_spoof  anti-spoof flag from 0=off, 1=on [0,1]
code_on_L2  0=reserved, 1=P code on L2, 2=C/A on L2 [0,1,2]
ura  User Range Accuracy lookup code, 0 is excellent, 15 is use at own risk [0-15], see p. 83 GPSICD200C
L2_P_data_flag  flag indicating if P is on L2 1=true [0,1]
fit_interval_flag  fit interval flag (four hour interval or longer) 0=4 fours, 1=greater [0,1]
age_of_data_offset  age of data offset [s]
tgd  group delay [s]
af2  polynomial clock correction coefficient (rate of clock drift) [s/s^2]
af1  polynomial clock correction coefficient (clock drift) [s/s]
af0  polynomial clock correction coefficient (clock bias) [s]
m0  mean anomaly at reference time [rad]
delta_n  mean motion difference from computed value [rad/s]
ecc  eccentricity []
sqrta  square root of the semi-major axis [m^(1/2)]
omega0  longitude of ascending node of orbit plane at weekly epoch [rad]
i0  inclination angle at reference time [rad]
w  argument of perigee [rad]
omegadot  rate of right ascension [rad/s]
idot  rate of inclination angle [rad/s]
cuc  amplitude of the cosine harmonic correction term to the argument of latitude [rad]
cus  amplitude of the sine harmonic correction term to the argument of latitude [rad]
crc  amplitude of the cosine harmonic correction term to the orbit radius [m]
crs  amplitude of the sine harmonic correction term to the orbit radius [m]
cic  amplitude of the cosine harmonic correction term to the angle of inclination [rad]
cis  amplitude of the sine harmonic correction term to the angle of inclination [rad]

Definition at line 714 of file gps.c.