cbgps.h File Reference

Set of functions for handling NMEA GGA sentences and positioning. More...

#include "cbser.h"

Go to the source code of this file.

Data Structures

struct  t_cbgps
 Type for the handle of the GPS reading job. More...

Defines

#define DEFAULT_SYSTEM   WGS84
 Default system for converting polar coordinates to UTM.

Typedefs

typedef void(*) t_cbgpscb (double, double, double, double, double, double, void *)
 Type for the callback function for successfully retrieved coordinates.

Enumerations

enum  t_cbgps_utmsys {
  WGS84 = 0, GRS80 = 1, WGS72 = 2, AUSTRALIAN1965 = 3,
  KRASOVSKY1940 = 4, INTERNATIONAL1924 = 5, CLAKE1880 = 6, CLARKE1866 = 7,
  AIRY1830 = 8, BESSEL1841 = 9, EVEREST1830 = 10
}
 System to use for converting polar coordinates into UTM. More...

Functions

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.

Detailed Description

Set of functions for handling NMEA GGA sentences and positioning.

Example of use: 

 #include "cbgps.h"
 #include <stdio.h>

 static void _gpsread(double utc, double nlat, double elon, double alt,
                      double utmn, double utme) {
   printf("%010.3lf lat=%lf lon=%lf alt=%lf utmn=%lf utme=%lf\n",
          utc, nlat, elon, alt, utmn, utme);
 }

 void main(int argc, char **argv) {
   t_cbgps     hgps;
   const char  *comport, *baud, *databits, *parity, *stopbits;
   
   cbgpsinit(&hgps);
   if (cbgpsopenstr(&hgps,
                    comport,
                    baud,
                    databits,
                    parity,
                    stopbits,
                    DEFAULT_TIMEOUT,
                    WGS84,
                    _gpsread) == 0) goto end;
   fgetc(stdin);
   end:
   cbgpsclose(&hgps);
  + }

Define Documentation

#define DEFAULT_SYSTEM   WGS84

Default system for converting polar coordinates to UTM.

Use this one if you don't know a better choice.

Typedef Documentation

typedef void(*) t_cbgpscb(double, double, double, double, double, double, void *)

Type for the callback function for successfully retrieved coordinates.

The function gets the following parameters:

  1. UTC time, format HHmmss.SSS
  2. latitude in decimal degrees, positive for North, negative for South
  3. longitude in decimal degrees, positive for East, negative for West
  4. altitude in meters
  5. UTM northing in kilometers
  6. UTM easting in kilometers
  7. context passed to cbgpsopen(), cbgpsopenstr(), cbgpsopenwstr()

Enumeration Type Documentation

enum t_cbgps_utmsys

System to use for converting polar coordinates into UTM.

Enumerator:
WGS84  NAD83/WGS84 use Global.
GRS80  GRS use US.
WGS72  WGS72 use NASA, DOD.
AUSTRALIAN1965  Australian use Australia.
KRASOVSKY1940  Krasovsky use Soviet Union.
INTERNATIONAL1924  International (1924) -Hayford (1909) use Global.
CLAKE1880  Clake use France, Africa.
CLARKE1866  Clarke use North America.
AIRY1830  Airy use Great Britain.
BESSEL1841  Bessel use Central Europe, Chile, Indonesia.
EVEREST1830  Everest use South Asia.

Function Documentation

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()

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