cbgps.c File Reference

Implementation of GPS oriented functions. More...

#include "cbgps.h"
#include <stdlib.h>
#include <string.h>
#include <math.h>

Defines

#define TOKENLEN   15
 Maximal length of a value string in NMEA GGA.

Functions

static int _listrtod (double *theNum, const char *anStr)
 Locale independend strtod.
static double _dms2dec (double dms)
 Converts degrees in NMEA GGA format to decimal degrees.
static void _toUTM (double *utmnorthing, double *utmeasting, double n_lat, double e_long, t_cbgps_utmsys system)
 Converts latitude and longitude to UTM northing and easting.
static void _rdfkt (const char *aLine, size_t aLen, void *aCtx)
 The implementation of the callback function for reading lines of text from the serial port.
int cbgps_gga (const char *aGGASeq, t_cbgps_utmsys aUTMSystem, double *theUTC, double *theNLat, double *theELong, double *theAlt, double *theUTMN, double *theUTME)
 Extracts UTC time, latitude, longitude and altitude from the given NMEA GGA sequence string.
int cbgpsopen (t_cbgps *theHandle, const char *aComPort, const t_cbserparam *aSpeed, const t_cbserparam *databits, const t_cbserparam *aParity, const t_cbserparam *stopbits, int aTimeout, t_cbgps_utmsys aSystem, t_cbgpscb rdCb, void *aCtx)
 Starts retrieving GPS data from a serial port.
int cbgpsopenstr (t_cbgps *theHandle, const char *aComPort, const char *aSpeed, const char *databits, const char *aParity, const char *stopbits, int aTimeout, t_cbgps_utmsys aSystem, t_cbgpscb rdCb, void *aCtx)
 Starts retrieving GPS data from a serial port.
int cbgpsopenwstr (t_cbgps *theHandle, const wchar_t *aComPort, const wchar_t *aSpeed, const wchar_t *databits, const wchar_t *aParity, const wchar_t *stopbits, int aTimeout, t_cbgps_utmsys aSystem, t_cbgpscb rdCb, void *aCtx)
 Starts retrieving GPS data from a serial port.
int cbgpsclose (t_cbgps *aHandle)
 Closes the background job for retrieving GPS data from a serial port.
void cbgpsinit (t_cbgps *theHandle)
 Initializes the given handle with empty values.

Variables

static const double PI = 3.14159265358979323846
 PI.
static const double _AA []
 Equatorial radius in meters, UTM.
static const double _BB []
 Polar Radius in meters, UTM.

Detailed Description

Implementation of GPS oriented functions.

Define Documentation

#define TOKENLEN   15

Maximal length of a value string in NMEA GGA.

Function Documentation

static double _dms2dec ( double  dms  )  [static]

Converts degrees in NMEA GGA format to decimal degrees.

Parameters:
dms the degrees in format used in NMEA sequences, eg. 1234.8765 means 12 degress, 34.8765 minutes, equaling 12 def 34 min and 52.59 sec or 12.581275 deg.
Returns:
decimal degrees, 12.581275 for the example above.

static int _listrtod ( double *  theNum,
const char *  anStr 
) [static]

Locale independend strtod.

Parameters:
theNum the double number resulting from the string anStr.
anStr the string representation of the number, always a dot as decimal separator.
Returns:
!= 0 if everything went OK, 0 on error.

static void _rdfkt ( const char *  aLine,
size_t  aLen,
void *  aCtx 
) [static]

The implementation of the callback function for reading lines of text from the serial port.

Tries to parse the given lines of text using cbgps_gga(). It it succeeds, the it calls the callback function passing the extracted UTC time and coordinates as parameters to it. The pointer to the callback function is expected in the context variable.

Parameters:
aLine the line of text.
aLen the length of the line of text.
aCtx context casted to t_cbgps.

static void _toUTM ( double *  utmnorthing,
double *  utmeasting,
double  n_lat,
double  e_long,
t_cbgps_utmsys  system 
) [static]

Converts latitude and longitude to UTM northing and easting.

Based on the theoretical description and an Excel sheet from Prof. Steve Dutch, see: http://www.uwgb.edu/DutchS/UsefulData/UTMFormulas.HTM and http://www.uwgb.edu/DutchS/UsefulData/UTMConversions1.xls

Parameters:
utmnorthing out, the resulting UTM northing in km.
utmeasting out, the resulting UTM easting in km.
n_lat North latitude (negative for South) in decimal degress.
e_long East longitude (negative for West) in decimal degrees.
system the system used for recomputing, WGS84, GRS80 etc.

int cbgps_gga ( const char *  aGGASeq,
t_cbgps_utmsys  aUTMSystem,
double *  theUTC,
double *  theNLat,
double *  theELong,
double *  theAlt,
double *  theUTMN,
double *  theUTME 
)

Extracts UTC time, latitude, longitude and altitude from the given NMEA GGA sequence string.

NMEA GGA string format: 

 GGA - Global Positioning System Fix Data
 Time, Position and fix related data for a GPS receiver.

  0      1         2       3 4        5 6 7  8   9  10 |  12 13  14   15
  |      |         |       | |        | | |  |   |   | |   | |   |    |
  $--GGA,hhmmss.ss,llll.ll,a,yyyyy.yy,a,x,xx,x.x,x.x,M,x.x,M,x.x,xxxx*hh

  Field Number:
   1) Universal Time Coordinated (UTC)
   2) Latitude
   3) N or S (North or South)
   4) Longitude
   5) E or W (East or West)
   6) GPS Quality Indicator,
      0 - fix not available,
      1 - GPS fix,
      2 - Differential GPS fix
      (values above 2 are 2.3 features)
      3 - PPS fix
      4 - Real Time Kinematic
      5 - Float RTK
      6 - estimated (dead reckoning)
      7 - Manual input mode
      8 - Simulation mode
   7) Number of satellites in view, 00 - 12
   8) Horizontal Dilution of precision (meters)
   9) Antenna Altitude above/below mean-sea-level (geoid) (in meters)
  10) Units of antenna altitude, meters
  11) Geoidal separation, the difference between the WGS-84 earth
      ellipsoid and mean-sea-level (geoid), "-" means mean-sea-level
      below ellipsoid
  12) Units of geoidal separation, meters
  13) Age of differential GPS data, time in seconds since last SC104
      type 1 or 9 update, null field when DGPS is not used
  14) Differential reference station ID, 0000-1023
  15) Checksum

 Example:
 $GPGGA,200329.000,4932.7248,N,01159.2531,E,1,06,1.5,401.0,M,47.4,M,,0000*5A
This function neighter uses nor validates the entire GGA string. For this method it is enough, that the fields 1, 2, 4 and 9 are valid floting point numbers with a dot as decimal separator, the fields 3 and 5 contain respectively N/S and E/W and that the field 0 has the format $..GGA meaning: char[0] is '$', char[3] and char[4] are both 'G' and char[5] is 'A'.
Parameters:
aGGASeq the string from which to try to extract the GGA values. Usually it is the whole line of text read from the serial port of the GPS chip. Only one NMEA sequence allowed here, further sequences will be eighter ignored or will lead to errors.
aUTMSystem the system to use for convering coordinates from the gga sentence into UTM.
theUTC the extracted UTC time as HHmmss.SSS, 0.0 on error.
theNLat the extracted latitude, positive for North, negative for South, in decimal degrees, 0.0 on error.
theELong the extracte longitude, positive for East, negative for West, in decimal degrees, 0.0 on error.
theAlt the extracted altitude, 0.0 on error.
theUTMN UTM northing recomputed from the longitude and latitude according to the given UTM system. 0.0 on error.
theUTME UTM easting recomputed from the longitude and latitude according to the given UTM system. 0.0 on error.
Returns:
!= 0 if everything went OK, 0 on error. Errors may be generally not well formated NMEA GGA sequences or wrong input parameters. In the first case the function is able to check very quickly, if the given sentence is GGA and it may be used for filtering out non GGA sentences.

int cbgpsclose ( t_cbgps *  aHandle  ) 

Closes the background job for retrieving GPS data from a serial port.

Parameters:
aHandle the GPS port handle retrieved from cbgpsopen().

void cbgpsinit ( t_cbgps *  theHandle  ) 

Initializes the given handle with empty values.

May be used in order to have a safely initialized handle. It is not mandatory, as long, as cbgpsopen(), cbgpsopenstr() or cbgpsopenwstr() has been called before.

Parameters:
theHandle the handle to initialize, type t_comport*.

int cbgpsopen ( t_cbgps *  theHandle,
const char *  aComPort,
const t_cbserparam *  aSpeed,
const t_cbserparam *  databits,
const t_cbserparam *  aParity,
const t_cbserparam *  stopbits,
int  aTimeout,
t_cbgps_utmsys  aSystem,
t_cbgpscb  rdCb,
void *  aCtx 
)

Starts retrieving GPS data from a serial port.

The function starts a background serial port reading thread using cbseropen(). The callback routine for this port reading thread uses cbgps_gga() in order to filter and parse NMEA GGA sentences for each line of text retrieved from the serial port. For each successfully parsed GGA sentence the given callback function is called with the recent UTM time and coordinates as parameters.

Parameters:
theHandle out, the resulting handle of the GPS port. The handle shall be used in order to close the job with cbgpsclose().
aComPort in, the name of the serial port, eg. COM1:, /dev/ttyS0.
aSpeed in, the baudrate.
databits in, number of databits.
aParity in, the parity.
stopbits in, the number of stopbits.
aTimeout in, the timeout in milliseconds used for retrieving information from the serial port, eg. DEFAULT_TIMEOUT.
rdCb in, callback function called for each successfully retrieved from the GPS port and parsed NMEA GGA string.
aSystem system used for converting coordinates to UTM.
aCtx in/out, context for the callback function.
Returns:
!= 0 for OK, 0 on any kind of errors.
See also:
cbgpsopenstr()

cbgpsopenwstr()

int cbgpsopenstr ( t_cbgps *  theHandle,
const char *  aComPort,
const char *  aSpeed,
const char *  databits,
const char *  aParity,
const char *  stopbits,
int  aTimeout,
t_cbgps_utmsys  aSystem,
t_cbgpscb  rdCb,
void *  aCtx 
)

Starts retrieving GPS data from a serial port.

The function does totally the same like cbgpsopen(), but it uses string names for the serial port parameters rather than the cryptic description structures and therefore it uses cbseropenstr() rather than cbseropen() for opening the serial port.

Parameters:
theHandle out, the resulting handle of the GPS port. The handle shall be used in order to close the job with cbgpsclose().
aComPort in, the name of the serial port, eg. COM1:, /dev/ttyS0.
aSpeed in, the name of the baudrate, one of the names defined in COMSPEEDS and returned by cbserinfo().
databits in, the name for the number of databits, one of the strings defined in COMDATABITS and returned by cbserinfo().
aParity in, the name of the parity, one of the strings defined in COMPARITIES and returned by cbserinfo().
stopbits in, the name for the number of stopbits, one of the strings defined int COMSTOPBITS and returned by cbseringo().
aTimeout in, the timeout in milliseconds used for retrieving information from the serial port, eg. DEFAULT_TIMEOUT.
aSystem system used for converting coordinates to UTM.
rdCb in, callback function called for each successfully retrieved from the GPS port and parsed NMEA GGA string.
aCtx in/out, context for the callback function.
Returns:
!= 0 for OK, 0 on any kind of errors.
See also:
cbgpsopen()

cbgpsopenwstr()

int cbgpsopenwstr ( t_cbgps *  theHandle,
const wchar_t *  aComPort,
const wchar_t *  aSpeed,
const wchar_t *  databits,
const wchar_t *  aParity,
const wchar_t *  stopbits,
int  aTimeout,
t_cbgps_utmsys  aSystem,
t_cbgpscb  rdCb,
void *  aCtx 
)

Starts retrieving GPS data from a serial port.

The function does totally the same like cbgpsopen(), but it uses unicode string names for the serial port parameters rather than the cryptic description structures and therefore it uses cbseropenwstr() rather than cbseropen() for opening the serial port.

Parameters:
theHandle out, the resulting handle of the GPS port. The handle shall be used in order to close the job with cbgpsclose().
aComPort in, the name of the serial port, eg. COM1:, /dev/ttyS0.
aSpeed in, the name of the baudrate, one of the names defined in COMSPEEDS and returned by cbserinfo().
databits in, the name for the number of databits, one of the strings defined in COMDATABITS and returned by cbserinfo().
aParity in, the name of the parity, one of the strings defined in COMPARITIES and returned by cbserinfo().
stopbits in, the name for the number of stopbits, one of the strings defined int COMSTOPBITS and returned by cbseringo().
aTimeout in, the timeout in milliseconds used for retrieving information from the serial port, eg. DEFAULT_TIMEOUT.
aSystem system used for converting coordinates to UTM.
rdCb in, callback function called for each successfully retrieved from the GPS port and parsed NMEA GGA string.
aCtx in/out, context for the callback function.
Returns:
!= 0 for OK, 0 on any kind of errors.
See also:
cbgpsopen()

cbgpsopenwstr()

Variable Documentation

const double _AA[] [static]

Initial value:

 {
      6378137.0,6378137.0,6378135.0,6378160.0,6378245.0,6378388.0,
      6378249.1,6378206.4,6377563.4,6377397.2,6377276.3
  }
Equatorial radius in meters, UTM.

For systems like in t_cgps_utmsys.

const double _BB[] [static]

Initial value:

 {
      6356752.3142,6356752.3141,6356750.5000,6356774.7000,
      6356863.0000,6356911.9000,6356514.9000,6356583.8000,
      6356256.9000,6356079.0000,6356075.4000
  }
Polar Radius in meters, UTM.

For systems like in t_cgps_utmsys.

const double PI = 3.14159265358979323846 [static]

PI.

M_PI is not always defined in math.h, even for _USE_MATH_DEFINES.

Generated on Thu Feb 12 11:09:26 2009 for cb by  doxygen 1.4.7