GPS Glossary

This glossary defines important constants and functions from the GPS driver code and example program. The library functions listed below (useful for instrumentation) are well documented, and cover all available capabilities for this Wildcard.

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:

The presence of both C and Forth prototypes conveys a lot of information. The C prototype explicitly states the type of each input and output parameter. The Forth prototype provides a descriptive name for the output parameter (a detail that is missing from the C prototype).

Let’s look at the sample C prototype first. The leading int tells us that a 16-bit integer is returned. The input parameter list is simply int module_num which tells us that the only parameter is an integer representing the Wildcard module number (corresponding to its hardware jumper address).

The Forth prototype includes a standard stack picture in parentheses, with the input parameters to the left of the -- and the output parameter(s) to the right. The only input parameter is again the module number. When there is a \ character in the stack picture it is read as under; this character separates the stack items. The output parameter, or returned value, is also a 16 bit integer. The input and the output parameters have the default 16-bit integer size: all Forth parameters are 16 bits unless otherwise indicated, as shown in the Stack Symbols table below. This routine returns only a single value, but Forth, unlike C, is capable or returning any number of values.

Note that C is case-sensitive, while Forth is case-insensitive. For simplicity and clarity, both C and Forth versions of the functions in this glossary are spelled identically using the same case.

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.

C: long GPS_Altitude_Meters_Times_10 ( void )
4th: GPS_Altitude_Meters_Times_10 ( -- d )

The Garmin GPS subsystem reports altitude as the height of the GPS antenna relative to mean sea level in meters, with a resolution of 0.1 meter. The altitude can range from -9999.9 to +99999.9 meters, where positive values are above sea level. To maximize flexibility in the selection of fast integer math or slower floating point math when performing longitude computations, the current altitude value returned by this function is scaled up by a factor of 10 and returned as a 32-bit signed integer in the range -99999 to 999,999. The numeric value of the number returned by this routine is the current altitude meters times 10. The dimensions (units) of the returned values are tenths of a meter.

Implementation detail: This function returns the contents of the sgps_altitude_tenth_meters field.

The struct fields are updated by GPS_Update; see its glossary entry.

C: GPS_BUFSIZE
4th: GPS_BUFSIZE ( -- n )

A constant whose value equals decimal 600, used to dimension the gps_default_inbuf as initialized by GPS_Init. This size is enough to hold 7 maximum size GPS sentences from the Garmin GPS subsystem as required by GPS_Next_Frame. See GPS_Inbuf and gps_default_inbuf.

C: GPS_CENTRAL_TIME
4th: GPS_CENTRAL_TIME ( -- n )

A constant whose value equals -6, used as the local_hour_offset passed to the GPS_Struct_Init, GPS_Init and GPS_Run functions to specify central standard time. The local_hour_offset is the number of hours that must be added to the universal "UTC" (Greenwich) time to obtain the correct local time. In general, the local_hour_offset for a location with "West" longitude such as the United States has a negative local_hour_offset, while a location with "East" longitude has a positive local_hour_offset. To specify daylight savings time, add 1 to this time zone constant before passing it to this function.

See also GPS_PACIFIC_TIME, GPS_MOUNTAIN_TIME, GPS_EASTERN_TIME, and GPS_DAYLIGHT_TIME

C: int GPS_Course_Degrees_Times_10 ( void )
4th: GPS_Course_Degrees_Times_10 ( -- n )

The Garmin GPS subsystem reports course over the ground with respect to true north in degrees, with 0.1 degree resolution. Values range from 0.0 to 359.9 degrees with respect to true (not magnetic) north. To maximize flexibility in the selection of fast integer math or slower floating point math when performing speed computations, the current course value returned by this function is scaled up by a factor of 10 and returned as a 16-bit integer in the range 0 to 3599. The numeric value of the number returned by this routine is the current course degrees times 10. The dimensions (units) of the returned values are tenths of a degree.

Implementation detail: This function returns the contents of the sgps_course_tenth_degrees struct field.

The struct fields are updated by GPS_Update; see its glossary entry.

C: GPS_DAYLIGHT_TIME
4th: GPS_DAYLIGHT_TIME ( -- n )

A constant whose value equals +1, which is added to the local_hour_offset passed to the GPS_Struct_Init, GPS_Init and GPS_Run functions to specify daylight savings time for the specified time zone. The local_hour_offset is the number of hours that must be added to the universal "UTC" (Greenwich) time to obtain the correct local time. In general, the local_hour_offset for a location with "West" longitude such as the United States has a negative local_hour_offset, while a location with "East" longitude has a positive local_hour_offset. To specify daylight savings time, add GPS_DAYLIGHT_TIME to the time zone constant before passing it to this function. For example, to specify pacific daylight time, pass to GPS_Init the sum of GPS_PACIFIC_TIME and GPS_DAYLIGHT_TIME.

See also GPS_PACIFIC_TIME, GPS_MOUNTAIN_TIME, GPS_CENTRAL_TIME, and GPS_EASTERN_TIME.

C: gps_default_inbuf [ GPS_BUFSIZE ]
4th: gps_default_inbuf ( -- xaddr )

A character array buffer whose size equals GPS_BUFSIZE (decimal 600). This size is enough to hold 7 maximum size GPS sentences from the Garmin GPS subsystem as required by GPS_Next_Frame. The base xaddress of this buffer is passed to GPS_Struct_Init by GPS_Init, and is stored into the sgps_inbuf field in the gps_info struct. After GPS_Init has run, the GPS_Inbuf function returns the 32-bit base address of this buffer.

See also GPS_Inbuf

C: void GPS_Default_UART_Init ( int module_num )
4th: GPS_Default_UART_Init ( module_num -- )

This low-level function initializes the UART chip on the GPS Wildcard that communicates with the Garmin GPS subsystem. This function is automatically called by the standard high level initialization function GPS_Init.

Implementation detail: Configures the UART for 8 bits per character, 1 stop bit, no parity, 4800 baud, with 64byte input and output first in/first out (FIFO) buffers. Sets the /3.3v_shutdown (/out2) hardware pin inactive high, thus powering up the Garmin GPS subsystem.

C: void GPS_Demo ( void )
4th: GPS_Demo ( -- )

A high level function in the demonstration program; see its source code listing at the end of this document. This function passes a default local_hour_offset (GPS_PACIFIC_TIME in the demo code listing) and the GPS_MODULE_NUM constant to the GPS_Run function. The value of the GPS_MODULE_NUM constant must match the hardware jumper settings of J1 and J2 on the GPS Wildcard.

The local_hour_offset is the number of hours that must be added to the universal "UTC" (Greenwich) time to obtain the correct local time. In general, the local_hour_offset for a location with "West" longitude such as the United States has a negative local_hour_offset, while a location with "East" longitude has a positive local_hour_offset. The pre-defined constants GPS_PACIFIC_TIME, GPS_MOUNTAIN_TIME, GPS_CENTRAL_TIME, and GPS_EASTERN_TIME can be used in this routine to specify the named time zones. To specify daylight savings time, add 1 to the specified time zone constant. After initializing the GPS, the function prints a descriptive text introduction, and enters a loop that repeatedly calls GPS_Update to get a frame of data from the GPS subsystem, and periodically calls GPS_Info_Dump to print to the serial port a formatted version of the extracted data from the gps_info struct.

Depending on the prior state of the GPS, a valid fix can be acquired in a few seconds, or it can take as long as 5 minutes if the GPS subsystem does not have enough stored time and location information to speed its acquisition process. Typing any key terminates the function. This data logger demonstration function is meant to be invoked interactively using the Mosaic terminal.

See also GPS_Run..

C: void GPS_Dump ( int module_num )
4th: GPS_Dump ( module_num -- )

Dumps the raw ASCII data stream from the Garmin GPS subsystem to the serial port. The module_num passed to this function must match the hardware jumper settings of J1 and J2 on the GPS Wildcard. This routine is provided for debugging purposes, as it allows you to examine the raw GPS sentences using a terminal. This routine invokes PauseOnKey, so you can abort the listing by typing a carriage return at the terminal. This function requires that the GPS Wildcard has been initialized using GPS_Init. Once the GPS has been initialized, it outputs 6 or 7 sentence types each second. The $PGRMT sentence is output only once per minute. An example 1-second frame of data resulting from execution of the GPS_Dump function is as follows:

$GPRMC,223324,A,3732.3793,N,12201.1625,W,0.0,194.8,220207,15.1,E*5D
$GPGGA,223324,3732.3793,N,12201.1625,W,1,08,0.9,11.3,M,-28.0,M,,*48
$GPGSA,A,3,03,,07,09,,16,18,19,21,,,26,1.6,0.9,1.3*32
$GPGSV,3,2,12,14,24,188,00,16,13,244,39,18,71,018,46,19,15,319,48*7B
$PGRME,5.0,M,5.8,M,7.7,M*26
$PGRMT,Bravo PDA Ver. 2.01,P,P,R,R,P,,21,*6C
$PGRMM,WGS 84*06

C: GPS_EASTERN_TIME
4th: GPS_EASTERN_TIME ( -- n )

A constant whose value equals -5, used as the local_hour_offset passed to the GPS_Struct_Init, GPS_Init and GPS_Run functions to specify eastern standard time. The local_hour_offset is the number of hours that must be added to the universal "UTC" (Greenwich) time to obtain the correct local time. In general, the local_hour_offset for a location with "West" longitude such as the United States has a negative local_hour_offset, while a location with "East" longitude has a positive local_hour_offset. To specify daylight savings time, add 1 to this time zone constant before passing it to this function.

See also GPS_PACIFIC_TIME, GPS_MOUNTAIN_TIME, GPS_CENTRAL_TIME, and GPS_DAYLIGHT_TIME.

C: int GPS_Frame_Extract ( xaddr xbuf, int numchars )
4th: GPS_Frame_Extract ( xbuf\numchars -- error )

Examines up to numchars characters in the specified buffer xbuf containing ASCII sentences from the GPS subsystem, and parses the GPS sentences in the order that they appear, extracting data from these sentences and storing the data into the gps_info struct. This function expects that GPS_Next_Frame (which returns the numchars parameter passed to this function) has been called to receive 7 GPS sentences; this ensures that a full "frame" of sentence data from the Garmin GPS subsystem is stored in the xbuf buffer. The high level GPS_Update function calls both GPS_Next_Frame and GPS_Frame_Extract; see their glossary entries. GPS_Frame_Extract searches the specified buffer for the next ASCII ‘$’ sentence start character, and then checks the sentence identifier string to see if it is one of the GPRMC, GPGGA, GPGSV, or PGRME sentences that we extract data from. If so, it calls one of the appropriate lower level functions GPS_Parse_Pos_Speed_Course_Time, GPS_Parse_Altitude_Fix_Numsats, GPS_Parse_Sats_In_View, or GPS_Parse_Pos_Errors (see their glossary entries) to extract and store the data into the gps_info struct. If all of the relevant sentences have a valid checksum and all required fields are present, a false error flag is returned; otherwise a true flag is returned.

C: int GPS_Get_Altitude_Fix_Numsats ( xaddr xbuf, int maxchars )
4th: GPS_Get_Altitude_Fix_Numsats ( xbuf\maxchars -- error )

This function expects that GPS_Get_Frame or GPS_Next_Frame has run so that a valid frame of data is in the buffer starting at xbuf; the maxchars parameter returned by these functions is passed to GPS_Get_Altitude_Fix_Numsats to specify the number of characters present in the buffer. This function examines the contents of the buffer beginning at xbuf looking for the sentence identifying sequence $GPGGA. Once the $GPGGA sentence has been found in the buffer, GPS_Parse_Altitude_Fix_Numsats is called to extract the relevant fields of the sentence. It extracts the GPS fix quality (0= fix not available, 1=non-differential gps fix available), number of GPS satellites in use, and altitude (antenna height in meters with respect to sea level). If parsing of the sentence fails due to a bad checksum or other error, no data is stored and a -1 error flag is returned. If parsing of the sentence is successful, this routine returns 0 and updates the following fields in the gps_info struct: sgps_fix_quality, sgps_numsats_in_use, and sgps_altitude_tenth_meters

C: int GPS_Get_Frame (xaddr bufbase,int starting_os,int max_os,int numsentences,int module)
4th: GPS_Get_Frame ( xbufbase\starting_os\max_os\numsentences\module -- numchars )

A low level function called by GPS_Next_Frame (see its glossary entry). This function receives numsentences GPS sentences which start with ASCII ‘$’ and end with a carriage return/linefeed. The ASCII sentences are emplaced starting at the specified starting_os offset from the bufbase buffer base xaddress. The module_num passed to this function must match the hardware jumper settings of J1 and J2 on the GPS Wildcard. The number of characters stored is limited to the difference between the max_os and starting_os offsets. This function returns the number of characters emplaced in the buffer. GPS_Get_Frame can take over 1 second to obtain 7 sentences, so it is best placed in its own task where it will not block time-critical code.

Implementation detail: Flushes all existing characters out of the UART input FIFO (first in/first out buffer) on the GPS Wildcard to get rid of any partial sentences that might be in the FIFO, and then puts characters into the specified xbufbase buffer as described above. Each sentence is recognized by its starting ‘$’ and its ending linefeed character, but the terminating ASCII linefeed (0x0A) is not stored in the buffer. Thus each sentence in the buffer ends with the ASCII carriage return (0x0D) character. After each sentence (except the last one received) this routine calls PAUSE while waiting for the starting ASCII ‘$’ of the next sentence. This ensures that the function is calling PAUSE to share processor time while waiting for the next sentence.

C: int GPS_Get_Pos_Errors ( xaddr xbuf, int maxchars )
4th: GPS_Get_Pos_Errors ( xbuf\maxchars -- error )

This function expects that GPS_Get_Frame or GPS_Next_Frame has run so that a valid frame of data is in the buffer starting at xbuf; the maxchars parameter returned by these functions is passed to GPS_Get_Pos_Errors to specify the number of characters present in the buffer. This function examines the contents of the buffer beginning at xbuf looking for the sentence identifying sequence $PGRM. Once the $PGRM sentence has been found in the buffer, GPS_Parse_Pos_Errors is called to extract the relevant fields of the sentence. It extracts the estimated horizontal, vertical, and overall position errors reported by the Garmin GPS subsystem. Reported errors are in the range 0 to 999.9 meters. If parsing of the sentence fails due to a bad checksum or other error, no data is stored and a -1 error flag is returned. If parsing of the sentence is successful, this routine returns 0 and updates the following fields in the gps_info struct: sgps_hor_error_tenth_meters, sgps_vert_error_tenth_meters, and sgps_position_error_tenth_meters

C: int GPS_Get_Pos_Speed_Course_Time ( xaddr xbuf, int maxchars )
4th: GPS_Get_Pos_Speed_Course_Time ( xbuf\maxchars -- error )

This function expects that GPS_Get_Frame or GPS_Next_Frame has run so that a valid frame of data is in the buffer starting at xbuf; the maxchars parameter returned by these functions is passed to GPS_Get_Pos_Speed_Course_Time to specify the number of characters present in the buffer. This function examines the contents of the buffer beginning at xbuf looking for the sentence identifying sequence $GPRMC. Once the $GPRMC sentence has been found in the buffer, GPS_Parse_Pos_Speed_Course_Time is called to extract the relevant fields of the sentence. It extracts the universal (UTC) time and date, position validity flag, latitude and longitude (degrees, minutes, hemisphere), speed in knots, course over ground in degrees true, and magnetic variation. Based on the local_hour_offset parameter passed to GPS_Run, GPS_Init or GPS_Struct_Init, this routine calculates the local time and date. If parsing of the sentence fails due to a bad checksum or other error, no data is stored and a -1 error flag is returned. If parsing of the sentence is successful, this routine returns 0 and updates the following fields in the gps_info struct: sgps_utc_hour, sgps_utc_date, sgps_utc_month, sgps_utc_year, sgps_local_second, sgps_local_minute, sgps_local_hour, sgps_local_date, sgps_local_month, sgps_local_year, sgps_position_valid, sgps_lat_degrees, sgps_lat_minutes_intpart, sgps_lat_minutes_fraction, sgps_lat_hemisphere, sgps_long_degrees, sgps_long_minutes_intpart, sgps_long_minutes_fraction, sgps_long_hemisphere, sgps_tenth_knots, sgps_course_tenth_degrees, sgps_mag_var_tenth_degrees, and sgps_mag_var_direction.

C: int GPS_Get_Sats_In_View ( xaddr xbuf, int maxchars )
4th: GPS_Get_Sats_In_View ( xbuf\maxchars -- error )

This function expects that GPS_Get_Frame or GPS_Next_Frame has run so that a valid frame of data is in the buffer starting at xbuf; the maxchars parameter returned by these functions is passed to GPS_Get_Sats_In_View to specify the number of characters present in the buffer. This function examines the contents of the specified buffer beginning at xbuf looking for the sentence identifying sequence $GPGSV. This sentence contains a 2-byte field in the range 00 to 12 representing the number of GPS satellites that are currently visible (but not necessarily in use) by the Garmin GPS subsystem. Once the $GPGSV sentence has been found in the buffer, GPS_Parse_Sats_In_View is called to extract the third numeric field of the sentence. If a valid 2-byte field is found in the sentence, this function returns 0 and stores the binary representation of the field in the sgps_numsats_in_view element of the gps_info struct. If valid data is not found, this routine stores nothing and returns a -1 error flag. This function is automatically called by the higher level functions GPS_Frame_Extract and GPS_Update; see their glossary entries.

C: int GPS_Good_Fix ( void )
4th: GPS_Good_Fix ( -- n )

This routine returns a nonzero value if the current GPS data can be relied upon. Returns true (-1) if the contents of the struct field sgps_fix_quality = 1 and if the contents of the struct field sgps_position_valid is true. Returns false if either sgps_fix_quality or sgps_position_valid contains 0. The struct fields are updated by GPS_Update; see its glossary entry.

C: xaddr GPS_Inbuf ( void )
4th: GPS_Inbuf ( -- xaddr )

Returns the xaddress of the buffer used to hold the raw serial sentences from the GPS subsystem by fetching the 32-bit contents of the sgps_inbuf field in the gps_info struct. This routine requires that GPS_Struct_Init or GPS_Init has already been invoked. If GPS_Init has been invoked, then GPS_Inbuf will return gps_default_inbuf as the input buffer specifier; see its glossary entry.

C: gps_info
4th: gps_info ( -- xaddr )

The struct instance in common RAM that contains 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. The elements of the gps_info struct are described at the start of this glossary.

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.

C: void GPS_Info_Dump ( void )
4th: GPS_Info_Dump ( -- )

A useful debugging function that prints a formatted summary of the data stored in the gps_info struct to the serial port. This function is typically called after GPS_Update has executed to populate the gps_info struct with the latest data. Note that the units are converted and reported as miles per hour and feet (instead of knots and meters). Latitude and longitude are expressed in degrees (deg) and minutes (‘). The reported local time is based on the local_hour_offset parameter passed to GPS_Run, GPS_Init or GPS_Struct_Init. Here is a sample of the formatted printout generated by the GPS_Info_Dump function:

UTC Universal time (hh:mm:ss): 20:46:07 and date (mm/dd/yy): 02/22/07
Local time (hh:mm:ss): 12:46:07 and date (mm/dd/yy): 02/22/07
Latitude: 37 deg 32.3814’ N
Longitude: 122 deg 01.1624’ W
Altitude (feet):     55.1
Ground speed (Miles Per Hour):      0.0
Ground course (degrees true): 194.8
Magnetic variation (degrees): 015.1 E
Satellites: 6  in use.   12 in view.
Fix available: Yes.   Valid position: Yes.
Position error (feet): Horizontal:    23.9   Vertical:    36.1   Overall:    43.3

See also GPS_Dump, GPS_Run and GPS_Demo.

C: int GPS_Init ( int local_hour_offset, int module_num )
4th: GPS_Init ( local_hour_offset\module_num -- error )

This is the high level initialization function for the GPS Wildcard; it must be called after each powerup or software reset before using any of the GPS driver functions. This routine globally enables interrupts, starts the timeslicer, and calls GPS_Default_UART_Init to initialize the UART chip that communicates with the Garmin GPS subsystem. It then calls GPS_Struct_Init, passing it the base xaddress of the gps_info struct which holds all of the GPS result fields, and the base xaddress of the gps_default_inbuf buffer which holds the raw serial sentences from the GPS subsystem. The module_num passed to this function is the Wildcard’s bus address and it must match the hardware jumper settings of J1 and J2 on the GPS Wildcard.

The local_hour_offset is the number of hours that must be added to the universal "UTC" (Greenwich) time to obtain the correct local time. In general, the local_hour_offset for a location with "West" longitude such as the United States has a negative local_hour_offset, while a location with "East" longitude has a positive local_hour_offset. The pre-defined constants GPS_PACIFIC_TIME, GPS_MOUNTAIN_TIME, GPS_CENTRAL_TIME, and GPS_EASTERN_TIME can be passed to this routine to specify the named time zones. To specify daylight savings time, add 1 to the specified time zone constant before passing it to this function (see GPS_DAYLIGHT_TIME). GPS_Init returns a true error flag if an ASCII ‘$’ character is not received from the Garmin GPS subsystem within 1 second. A nonzero value returned by this function indicates that the GPS is not present or is malfunctioning.

See also GPS_Shutdown..

C: int GPS_Knots_Times_10 ( void )
4th: GPS_Knots_Times_10 ( -- n )

The Garmin GPS subsystem reports speed over the ground in "knots", or nautical miles per hour. A nautical mile is 1.152 times longer than a standard (statute) mile. The speed can range from 000.0 to 999.9 knots. To maximize flexibility in the selection of fast integer math or slower floating point math when performing speed computations, the current speed value returned by this function is scaled up by a factor of 10 and returned as a 16-bit integer in the range 0 to 9,999. The numeric value of the number returned by this routine is the current ground speed knots times 10. The dimensions (units) of the returned values are tenths of a knot. To calculate a floating point speed in miles per hour, convert the value returned by this field to a floating point number and multiply by 0.1152.

Implementation detail: This function returns the contents of the sgps_tenth_knots field.

The struct fields are updated by GPS_Update; see its glossary entry.

C: int GPS_Lat_Degrees ( void )
4th: GPS_Lat_Degrees ( -- n )

The Garmin GPS subsystem reports latitude in degrees and minutes, where a minute is 1/60 of a degree. This function returns the most recent latitude expressed as an integer number of degrees north or south of the equator. Values range from 0 to 89 degrees. The latitude hemisphere (N or S) is returned by GPS_Lat_Hemisphere. For a latitude resolution better than 1 degree, use the GPS_Lat_Minutes_Times_10000 function to access the latitude minutes.

Implementation detail: This function returns the contents of the sgps_lat_degrees struct field.

The struct fields are updated by GPS_Update; see its glossary entry.

C: char GPS_Lat_Hemisphere ( void )
4th: GPS_Lat_Hemisphere ( -- char ) ascii ‘N’ or ‘S’

Returns the current latitude hemisphere. Returns ASCII ‘N’ (=0x4E) for latitudes north of the equator, or ASCII ‘S’ (0x53) for latitudes south of the equator.

Implementation detail: Returns the contents of the sgps_lat_hemisphere struct field.

The struct fields are updated by GPS_Update; see its glossary entry.

C: long GPS_Lat_Minutes_Times_10000 ( void )
4th: GPS_Lat_Minutes_Times_10000 ( -- d )

The Garmin GPS subsystem reports latitude in degrees and minutes, where a minute is 1/60 of a degree. Degrees are expressed as an integer between 0 and 89, while the minutes represented as numbers in the range 0.0000 to 59.9999. To maximize flexibility in the selection of fast integer math or slower floating point math when performing latitude computations, the current latitude minute value returned by this function is scaled up by a factor of 10000 and returned as a 32-bit integer in the range 0 to 599,999. The numeric value of the number returned by this routine is the current latitude minutes times 10000. The dimensions (units) of the returned values are ten-thousandths of a minute.

Implementation detail: This function returns the sum of contents of the sgps_lat_minutes_fraction field, plus 10000 times the contents of the sgps_lat_minutes_intpart field.

The struct fields are updated by GPS_Update; see its glossary entry.

See also GPS_Lat_Hemisphere and GPS_Lat_Degrees..

C: int GPS_Long_Degrees ( void )
4th: GPS_Long_Degrees ( -- n )

The Garmin GPS subsystem reports longitude in degrees and minutes, where a minute is 1/60 of a degree. This function returns the most recent longitude expressed as an integer number of degrees east or west of the "prime meridian" which runs through Greenwich England. Values range from 0 to 179 degrees. The longitude hemisphere (E or W) is returned by GPS_Long_Hemisphere. For a longitude resolution better than 1 degree, use the GPS_Long_Minutes_Times_10000 function to access the longitude minutes.

Implementation detail: This function returns the contents of the sgps_long_degrees struct field.

The struct fields are updated by GPS_Update; see its glossary entry.

C: char GPS_Long_Hemisphere ( void )
4th: GPS_Long_Hemisphere ( -- char )

Returns the current longitude hemisphere with respect to the "prime meridian" which runs through Greenwich England. Returns ASCII ‘W’ (=0x57) for longitudes west of the prime meridian, or ASCII ‘E’ (0x45) for longitudes east of the prime meridian.

Implementation detail: Returns the contents of the sgps_long_hemisphere struct field.

The struct fields are updated by GPS_Update; see its glossary entry.

C: long GPS_Long_Minutes_Times_10000 ( void )
4th: GPS_Long_Minutes_Times_10000 ( -- d )

The Garmin GPS subsystem reports longitude in degrees and minutes, where a minute is 1/60 of a degree. Degrees are expressed as an integer between 0 and 179, while the minutes represented as numbers in the range 0.0000 to 59.9999. To maximize flexibility in the selection of fast integer math or slower floating point math when performing longitude computations, the current longitude minute value returned by this function is scaled up by a factor of 10000 and returned as a 32-bit integer in the range 0 to 599,999. The numeric value of the number returned by this routine is the current longitude minutes times 10000. The dimensions (units) of the returned values are ten-thousandths of a minute.

Implementation detail: This function returns the sum of contents of the sgps_long_minutes_fraction field, plus 10000 times the contents of the sgps_long_minutes_intpart field.

The struct fields are updated by GPS_Update; see its glossary entry.

See also GPS_Long_Hemisphere and GPS_Long_Degrees..

C: GPS_MODULE_NUM
4th: GPS_MODULE_NUM ( -- n )

A constant in the demonstration program whose value equals the Wildcard module number. This number is the Wildcard’s bus address and it must correspond to its address jumper settings. Edit the source code of the demonstration program so that the value of this constant matches your hardware jumper settings. This constant is used in the GPS_Demo function.

C: GPS_MOUNTAIN_TIME
4th: GPS_ MOUNTAIN_TIME ( -- n )

A constant whose value equals -7, used as the local_hour_offset passed to the GPS_Struct_Init, GPS_Init and GPS_Run functions to specify mountain standard time. The local_hour_offset is the number of hours that must be added to the universal "UTC" (Greenwich) time to obtain the correct local time. In general, the local_hour_offset for a location with "West" longitude such as the United States has a negative local_hour_offset, while a location with "East" longitude has a positive local_hour_offset. To specify daylight savings time, add 1 to this time zone constant before passing it to this function.

See also GPS_PACIFIC_TIME, GPS_CENTRAL_TIME, GPS_EASTERN_TIME, and GPS_DAYLIGHT_TIME.

C: int GPS_Next_Frame ( int module_num )
4th: GPS_Next_Frame ( module -- numchars )

This function receives 7 GPS sentences which start with ASCII ‘$’ and end with a carriage return/linefeed; this ensures that a full "frame" of sentence data from the Garmin GPS subsystem is stored. Once the GPS has been initialized, it outputs 6 or 7 sentence types each second, with sentence identifiers $GPRMC, $GPGGA, $GPGSA, $GPGSV, $PGRME, $PGRMT (only once per minute), and PGRMM. The $PGRMT sentence is output only once per minute. This function emplaces the ASCII sentences at the gps_inbuf buffer, and the number of characters stored is clamped to GPS_BUFSIZE which is adequate to accommodate the full 1-second frame of data.

The module_num passed to this function is the Wildcard’s bus address and it must match the hardware jumper settings of J1 and J2 on the GPS Wildcard.

This function returns the number of characters emplaced in the buffer. GPS_Get_Frame can take over 1 second to obtain 7 sentences, so it is best placed in its own task where it will not block time-critical code. The ASCII character sentences stored by this function are used by GPS_Frame_Extract to parse the data into the gps_info struct fields where they become easily accessible by the application program. The high level function GPS_Update invokes GPS_Next_Frame and GPS_Frame_Extract; see their glossary entries.

Implementation detail: Flushes all existing characters out of the UART input FIFO (first in/first out buffer) on the GPS Wildcard to get rid of any partial sentences that might be in the FIFO, and then puts characters into the specified xbufbase buffer as described above. Each sentence is recognized by its starting ‘$’ and its ending linefeed character, but the terminating ASCII linefeed (0x0A) is not stored in the buffer. Thus each sentence in the buffer ends with the ASCII carriage return (0x0D) character. After each sentence (except the last one received) this routine calls PAUSE while waiting for the starting ASCII ‘$’ of the next sentence. This ensures that the function is calling PAUSE to share processor time while waiting for the next sentence. Once the GPS has been initialized, it outputs 6 or 7 sentence types each second. The $PGRMT sentence is output only once per minute. An example 1-second frame of data stored by this function is as follows:

$GPRMC,223324,A,3732.3793,N,12201.1625,W,0.0,194.8,220207,15.1,E*5D
$GPGGA,223324,3732.3793,N,12201.1625,W,1,08,0.9,11.3,M,-28.0,M,,*48
$GPGSA,A,3,03,,07,09,,16,18,19,21,,,26,1.6,0.9,1.3*32
$GPGSV,3,2,12,14,24,188,00,16,13,244,39,18,71,018,46,19,15,319,48*7B
$PGRME,5.0,M,5.8,M,7.7,M*26
$PGRMT,Bravo PDA Ver. 2.01,P,P,R,R,P,,21,*6C
$PGRMM,WGS 84*06

C: int GPS_Numsats_In_Use ( void )
4th: GPS_Numsats_In_Use ( -- n )

Returns the number of GPS satellites currently in use by the 12-channel Garmin GPS receiver. This value can range from 0 to 12. Note that, in most cases, the GPS antenna must be outside with a clear view of the sky for the Wildcard to acquire and use GPS satellites.

Implementation detail: This function returns the contents of the sgps_numsats_in_use struct field.

The struct fields are updated by GPS_Update; see its glossary entry.

See also GPS_Numsats_In_View and GSP_Good_Fix..

C: int GPS_Numsats_In_View ( void )
4th: GPS_Numsats_In_View ( -- n )

Returns the number of GPS satellites currently in view by the 12-channel Garmin GPS receiver. This value can range from 0 to 12. A satellite may be "in view" but not "in use". Note that, in most cases, the GPS antenna must be outside with a clear view of the sky for the Wildcard to acquire and use GPS satellites.

Implementation detail: This function returns the contents of the sgps_numsats_in_view struct field.

The struct fields are updated by GPS_Update; see its glossary entry.

See also GPS_Numsats_In_Use and GSP_Good_Fix..

C: GPS_PACIFIC_TIME
4th: GPS_PACIFIC_TIME ( -- n )

A constant whose value equals -8, used as the local_hour_offset passed to the GPS_Struct_Init, GPS_Init and GPS_Run functions to specify pacific standard time. The local_hour_offset is the number of hours that must be added to the universal "UTC" (Greenwich) time to obtain the correct local time. In general, the local_hour_offset for a location with "West" longitude such as the United States has a negative local_hour_offset, while a location with "East" longitude has a positive local_hour_offset. To specify daylight savings time, add 1 to this time zone constant before passing it to this function.

See also GPS_MOUNTAIN_TIME, GPS_CENTRAL_TIME, GPS_EASTERN_TIME, and GPS_DAYLIGHT_TIME.

C: int GPS_Parse_Altitude_Fix_Numsats ( xaddr xbuf, int dollar_offset, int maxchars )
4th: GPS_Parse_Altitude_Fix_Numsats ( xbuf\ dollar_offset \maxchars -- error )

This low level utility function expects that the $GPGGA sentence is in the specified xbuf buffer with the specified dollar_offset pointing to the ASCII ‘$’ at the start of the $GPGGA sentence, and maxchars specifying the maximum size of the buffer. In other words, the sum of xbuf and dollar_offset must yield the xaddress of the ASCII ‘$’ at the start of the $GPGGA sentence in the buffer. This function is called by GPS_Get_Altitude_Fix_Numsats, and is automatically called by the higher level functions GPS_Frame_Extract and GPS_Update; see their glossary entries. GPS_Parse_Altitude_Fix_Numsats extracts the GPS fix quality (0= fix not available, 1=non-differential gps fix available), number of GPS satellites in use, and altitude (antenna height in meters with respect to sea level). If parsing of the sentence fails due to a bad checksum or other error, no data is stored and a -1 error flag is returned. If parsing of the sentence is successful, this routine returns 0 and updates the following fields in the gps_info struct: sgps_fix_quality, sgps_numsats_in_use, and sgps_altitude_tenth_meters

C: int GPS_Parse_Pos_Errors ( xaddr xbuf, int dollar_offset, int maxchars )
4th: GPS_Parse_Pos_Errors ( xbuf\dollar_offset\maxchars -- error )

This low level utility function expects that the $PGRME sentence is in the specified xbuf buffer with the specified dollar_offset pointing to the ASCII ‘$’ at the start of the $PGRME sentence, and maxchars specifying the maximum size of the buffer. In other words, the sum of xbuf and dollar_offset must yield the xaddress of the ASCII ‘$’ at the start of the $PGRME sentence in the buffer. This function is called by GPS_Get_Pos_Errors, and is automatically called by the higher level functions GPS_Frame_Extract and GPS_Update; see their glossary entries. GPS_Parse_Pos_Errors extracts the estimated horizontal, vertical, and overall position errors reported by the Garmin GPS subsystem. Reported errors are in the range 0 to 999.9 meters. If parsing of the sentence fails due to a bad checksum or other error, no data is stored and a -1 error flag is returned. If parsing of the sentence is successful, this routine returns 0 and updates the following fields in the gps_info struct: sgps_hor_error_tenth_meters, sgps_vert_error_tenth_meters, and sgps_position_error_tenth_meters

C: int GPS_Parse_Pos_Speed_Course_Time ( xaddr xbuf, int dollar_offset, int maxchars )
4th: GPS_Parse_Pos_Speed_Course_Time ( xbuf\ dollar_offset\ maxchars -- error )

This low level utility function expects that the $GPRMC sentence is in the specified xbuf buffer with the specified dollar_offset pointing to the ASCII ‘$’ at the start of the $GPRMC sentence, and maxchars specifying the maximum size of the buffer. In other words, the sum of xbuf and dollar_offset must yield the xaddress of the ASCII ‘$’ at the start of the $GPRMC sentence in the buffer. This function is called by GPS_Get_Pos_Speed_Course_Time, and is automatically called by the higher level functions GPS_Frame_Extract and GPS_Update; see their glossary entries. GPS_Parse_Pos_Speed_Course_Time extracts the universal (UTC) time and date, position validity flag, latitude and longitude (degrees, minutes, hemisphere), speed in knots, course over ground in degrees true, and magnetic variation. Based on the local_hour_offset parameter passed to GPS_Run, GPS_Init or GPS_Struct_Init, this routine calculates the local time and date. If parsing of the sentence fails due to a bad checksum, missing field, or other error, no data is stored and a -1 error flag is returned. If parsing of the sentence is successful, this routine returns 0 and updates the following fields in the gps_info struct: sgps_utc_hour, sgps_utc_date, sgps_utc_month, sgps_utc_year, sgps_local_second, sgps_local_minute, sgps_local_hour, sgps_local_date, sgps_local_month, sgps_local_year, sgps_position_valid, sgps_lat_degrees, sgps_lat_minutes_intpart, sgps_lat_minutes_fraction, sgps_lat_hemisphere, sgps_long_degrees, sgps_long_minutes_intpart, sgps_long_minutes_fraction, sgps_long_hemisphere, sgps_tenth_knots, sgps_course_tenth_degrees, sgps_mag_var_tenth_degrees, and sgps_mag_var_direction.

C: int GPS_Parse_Sats_In_View ( xaddr xbuf, int dollar_offset, int maxchars )
4th: GPS_Parse_Sats_In_View ( xbuf \ dollar_offset\ maxchars -- error )

This low level utility function expects that the $GPGSV sentence is in the specified xbuf buffer with the specified dollar_offset pointing to the ASCII ‘$’ at the start of the $GPGSV sentence, and maxchars specifying the maximum size of the buffer. In other words, the sum of xbuf and dollar_offset must yield the xaddress of the ASCII ‘$’ at the start of the $GPGSV sentence in the buffer. This function extracts the third numeric field of the $GPGSV sentence, which is the satellites in view field. If a valid 2-byte field is found, this function returns 0 and stores the binary representation of the field in the sgps_numsats_in_view element of the gps_info struct. If valid data is not found, this routine stores nothing and returns a -1 error flag. This function is called by GPS_Get_Sats_In_View, and is automatically called by the higher level functions GPS_Frame_Extract and GPS_Update; see their glossary entries.

C: int GPS_Run ( int local_hour_offset, int module_num )
4th: GPS_Run ( local_hour_offset\module_num -- )

A high level function in the demonstration program; see its source code listing at the end of this document. This function passes the specified local_hour_offset and module_num to the GPS_Init function.

The module_num passed to this function is the Wildcard’s bus address and it must match the hardware jumper settings of J1 and J2 on the GPS Wildcard.

The local_hour_offset is the number of hours that must be added to the universal "UTC" (Greenwich) time to obtain the correct local time. In general, the local_hour_offset for a location with "West" longitude such as the United States has a negative local_hour_offset, while a location with "East" longitude has a positive local_hour_offset. The pre-defined constants GPS_PACIFIC_TIME, GPS_MOUNTAIN_TIME, GPS_CENTRAL_TIME, and GPS_EASTERN_TIME can be passed to this routine to specify the named time zones. To specify daylight savings time, add 1 to the specified time zone constant before passing it to this function (see GPS_DAYLIGHT_TIME). After initialization, the function prints a descriptive text introduction, and enters a loop that repeatedly calls GPS_Update to get a frame of data from the GPS subsystem, and periodically calls GPS_Info_Dump to print to the serial port a formatted version of the extracted data from the gps_info struct. Depending on the prior state of the GPS, a valid fix can be acquired in a few seconds, or it can take as long as 5 minutes if the GPS subsystem does not have enough stored time and location information to speed its acquisition process. Typing any key terminates the function. This demonstration function is meant to be invoked interactively using the Mosaic terminal.

See also GPS_Demo..

C: void GPS_Shutdown ( int shutdown_flag, int module_num )
4th: GPS_Shutdown ( shutdown_flag\module_num -- )

This routine shuts down the Garmin GPS subsystem if the shutdown_flag is nonzero, or powers up the GPS subsystem if the shutdown_flag is zero. Shutting down the GPS typically saves 1.25 watt, equivalent to 0.25 amp at 5 volts.

The module_num passed to this function is the Wildcard’s bus address and it must match the hardware jumper settings of J1 and J2 on the GPS Wildcard.

To force a Garmin GPS subsystem reset and satellite reaquisition, call this routine with a true shutdown_flag, then call it again with a false shutdown_flag. The GPS is powered up by GPS_Default_UART_Init and its calling function GPS_Init.

C: GPS_STRUCT
4th: GPS_STRUCT ( -- n )

This struct specifier is used to declare the gps_info struct in common RAM. 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.

C: void GPS_Struct_Init ( xaddr gps_info_xbase, xaddr xinbuf, int local_hour_offset )
4th: GPS_Struct_Init ( gps_info_xbase \xinbuf\local_hour_offset -- )

This function zeros the GPS_STRUCT starting at the specified gps_info_xbase, and blanks the GPS_BUFSIZE bytes starting at the specified xinbuf which holds the raw serial sentences from the GPS subsystem. This routine then stores the specified xinbuf into the spgs_inbuf field of the GPS_STRUCT, and stores the specified local_hour_offset into the sgps_local_hour_offset field of the GPS_STRUCT. This low-level function is called by GPS_Init; see its glossary entry for additional details.

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 Wildcard’s bus address 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.

See also → GPS Wildcard User Guide
GPS C Demo
GPS Forth Demo