Table of Contents

The GPS Wildcard User Guide

<< Previous | Next>>

Glossary of GPS Driver Functions

This glossary defines important constants and functions from the GPS driver code and demo program.

Overview of Glossary Notation

The main glossary entries presented in this document are listed in case-insensitive alphabetical order (the underscore character comes at the end of the alphabet).  The keyword name of each entry is in bold typeface.  Each function is listed with both a C-style declaration and a Forth-style stack comment declaration as described below.  The "C:" and "4th:" tags at the start of the glossary entry distinguish the two declaration styles.

The Forth language is case-insensitive, so Forth programmers are free to use capital or lower case letters when typing keyword names in their program.  Because C is case sensitive, C programmers must type the keywords exactly as shown in the glossary.  The case conventions are as follows:

   ◙  Function names begin with a capital letter, and every letter after an underscore is capitalized.  Other letters are lower case, except for capitalized acronyms such as "GPS".

    ◙  Constant names and C macros use capital letters.

    ◙  Variable names use lower case letters.

Each glossary entry starts with C-style and Forth-style declarations, and presents a description of the function.  Here is a sample glossary entry:

C:   int GPS_Update ( int module_num )

4th: GPS_Update ( module -- error )

This high level function invokes GPS_Next_Frame to get a frame of GPS ASCII data into the gps_inbuf, then calls GPS_Frame_Extract to parse the GPS sentences in the order that they appear, extracting data from these sentences and storing the data into the gps_info struct. The module_num passed to this function is the address of the Wildcard and it must match the hardware jumper settings of J1 and J2 on the GPS Wildcard. GPS_Update can take over 1 second to obtain a frame of data from the GPS subsystem, so it is best placed in its own task where it will not block time-critical code.  Make sure to call GPS_Init before invoking GPS_Update. For an example of use, see the GPS_Run and GPS_Demo functions which are provided in source code form in the demonstration program listing at the end of this document.

The C declaration specifies that return data type before the function name, and lists the comma-delimited input parameters between parentheses, showing the type and a descriptive name for each.

The Forth declaration contains a "stack picture" between parentheses; this is recognized as a comment in a Forth program.  The items to the left of the double-dash ( -- ) are input parameters; multiple parameters are separated by a \ character which is read as “under”. The item to the right of the double-dash is the output parameter.  Forth is stack-based, and the first item shown is lowest on the stack. In the Forth declaration the parameter names and their data types are combined.  All unspecified parameters are 16-bit integers.  Forth promotes all characters to integer type. 

The presence of both C and Forth declarations is helpful: the C syntax shows the types of the parameters, and the Forth declaration provides a descriptive name of the output parameter.

Glossary Quick Reference

This overview categorizes the driver function into four groups:

    ◙  Initialization functions initialize the GPS and describe the driver’s data structures; the high level GPS_Init function must be called after each powerup or restart.

    ◙  Data Extraction functions convert ASCII data coming from the Garmin GPS subsystem into useable parameters that describe position, time, speed, and heading.  GPS_Update is the highest level data extraction function; it calls GPS_Next_Frame to get ASCII data from the GPS subsystem, and then calls GPS_Frame_Extract to parse the data and store it into the relevant fields in the gps_info structure.

    ◙  Most of the Data Reporting functions fetch the elements from the gps_info structure and return them.  They are made available as a convenience, ant their functionality can be mimicked by directly reading the corresponding elements out of the gps_info struct.  The GPS_Dump and GPS_Info_Dump routines are serial output functions that are useful during debugging.

    ◙  The Demonstration functions are presented in source code form in the listing at the end of this document.

Data Extraction

int GPS_Frame_Extract ( xaddr xbuf, int numchars )

int GPS_Get_Altitude_Fix_Numsats ( xaddr xbuf, int maxchars )

C: int GPS_Get_Frame (xaddr bufbase,int starting_os,int max_os,int numsentences,int module)

int GPS_Get_Pos_Errors ( xaddr xbuf, int maxchars )

int GPS_Get_Pos_Speed_Course_Time ( xaddr xbuf,  int maxchars )

int GPS_Get_Sats_In_View ( xaddr xbuf, int maxchars )

int GPS_Next_Frame ( int module_num )

int GPS_Parse_Altitude_Fix_Numsats ( xaddr xbuf, int dollar_offset, int maxchars )

int GPS_Parse_Pos_Errors ( xaddr xbuf, int dollar_offset, int maxchars )

int GPS_Parse_Pos_Speed_Course_Time ( xaddr xbuf, int dollar_offset, int maxchars )

int GPS_Parse_Sats_In_View ( xaddr xbuf, int dollar_offset, int maxchars )

int GPS_Update ( int module_num )

Data Reporting

long GPS_Altitude_Meters_Times_10 ( void )

int GPS_Course_Degrees_Times_10 ( void )

void GPS_Dump ( int module_num )

int GPS_Good_Fix ( void )

void GPS_Info_Dump ( void )

int GPS_Knots_Times_10 ( void )

int GPS_Lat_Degrees ( void )

char GPS_Lat_Hemisphere ( void )

long GPS_Lat_Minutes_Times_10000 ( void )

int GPS_Long_Degrees ( void )

char GPS_Long_Hemisphere ( void )

long GPS_Long_Minutes_Times_10000 ( void )

int GPS_Numsats_In_Use ( void )

int GPS_Numsats_In_View ( void )

Initialization

GPS_BUFSIZE

GPS_CENTRAL_TIME

GPS_DAYLIGHT_TIME

gps_default_inbuf [ GPS_BUFSIZE ]

void GPS_Default_UART_Init ( int module_num )

GPS_EASTERN_TIME

xaddr GPS_Inbuf ( void )

gps_info

int GPS_Init ( int local_hour_offset, int module_num )

GPS_MOUNTAIN_TIME

GPS_PACIFIC_TIME

void GPS_Shutdown ( int shutdown_flag, int module_num )

GPS_STRUCT

void GPS_Struct_Init ( xaddr gps_info_xbase, xaddr xinbuf, int local_hour_offset )

Demonstration Program

void GPS_Demo ( void )

int GPS_Run ( int local_hour_offset, int module_num )

GPS_MODULE_NUM

GPS_STRUCT Definition

The position, time, date, speed, heading, and error estimation parameters extracted from the Garmin GPS subsystem are stored in the gps_info struct in common RAM.  The elements of this struct can be accessed from your application program to obtain the latest GPS data after each invocation of GPS_Update.  Listing 1‑2 on page 19 presents the commented C source code definition of the structure, and Listing 1‑3 on page 33 presents the commented Forth source code definition of the structure. In C, this is a typedef, and in Forth, it returns the struct size of the gps_info struct.  The elements of the gps_info struct are described at the start of this glossary; they hold data obtained from the Garmin GPS subsystem. The struct elements are updated by the functions GPS_Run, GPS_Update, GPS_Frame_Extract, and by functions having names that start with GPS_Parse. 

C structure use example: To read the contents of the structure element named sgps_lat_degrees in C, use the standard C construct:

      gps_info.sgps_lat_degrees

as the right-hand side of an assignment statement.

Forth structure use example: To read the contents of the structure element named sgps_lat_degrees in Forth, use the standard Forth construct:

      gps_info sgps_lat_degrees @

to fetch the contents to the data stack.

Listing 1‑2     C GPS_STRUCT commented source code definition.

typedef struct gps_struct     // holds information for the gps wildcard

{ 

xaddr sgps_inbuf;    // holds base xaddr of buffer for sentences coming from gps

xaddr sgps_outbuf;   // holds base xaddr of buffer for outgoing sentences: unused!

int sgps_local_hour_offset; // eg, pst (pac std time) = -8, pdt = -7

 // the following are from the $gprmc data from gps sensor:

int sgps_utc_hour; // 00-23 hour

int sgps_utc_date; // 01-31 date of the month

int sgps_utc_month; // 01-12 month of the year

int sgps_utc_year; // 00-99 2-digit year

int sgps_local_second; // 00-59 seconds after minute; utc_second = local_second

int sgps_local_minute; // 00-59 minutes after hour; utc_minute = local_minute

int sgps_local_hour; // 00-23 hour = (utc_hour + local_time_hour_offset) mod 24

int sgps_local_date; // 01-31 date of the month, result of utclocal conversion

int sgps_local_month; // 01-12 month of the year, result of utclocal conversion

int sgps_local_year; // 00-99 2-digit year, result of utclocal conversion

int sgps_position_valid; // holds boolean flag; -1=valid pos; 0=rcvr warning

int sgps_lat_degrees; // 00-89 degrees latitude

int sgps_lat_minutes_intpart; // 00-59 integer latitude minutes

int sgps_lat_minutes_fraction; // .xxxx lat minutes fractional part (tenthousandths)

int sgps_lat_hemisphere; // ascii ‘N’ or ‘S’

int sgps_long_degrees;   // 000-179 degrees longitude

int sgps_long_minutes_intpart; // 00-59 integer longitude minutes

int sgps_long_minutes_fraction; // .xxxx long minutes fraction part (ten-thousandths)

int sgps_long_hemisphere; // ascii ‘E’ or ‘W’

int sgps_tenth_knots;    // = 0-9999 speed over ground; field = 000.0 to 999.9 knots

int sgps_course_tenth_degrees; // = 0-3599 course; field= 000.0 to 359.9 degrees true

int sgps_mag_var_tenth_degrees; // 0-1800 magnetic variation,field= 000.0 to 180.0 deg

int sgps_mag_var_direction; // ‘E’ or ‘W’ mag var dir;west var adds to true course

  // the following is from the $gpgsv data from gps sensor:

int  sgps_numsats_in_view; // 00-12

   // the following are from the $gpgga data from gps sensor:

int sgps_fix_quality; // contains binary: 0= fix not available; 1 = non-diff fix avail

int sgps_numsats_in_use; // 00-12 = number of satellites in use

double sgps_altitude_tenth_meters; // field = -9999.9 to 99999.9 meters rel to SeaLev

// the following are from the $pgrme data from gps sensor:

int sgps_hor_error_tenth_meters; // 0-9999 est horiz pos err;field=0.0 to 999.9 meters

int sgps_vert_error_tenth_meters; // 0-9999 est vert pos err;field=0.0 to 999.9 meters

int sgps_position_error_tenth_meters; // 0-9999 overall pos err;fld=0 to 999.9 meters

} GPS_STRUCT

<< Previous | Next>>