GPS Wildcard User Guide

The GPS Wildcard enables your instrument to know where it is, how fast it is moving, the direction it is moving, and the current time and date. Latitude, longitude, altitude, speed, course heading, universal (Greenwich) and local time and date, position error estimates, GPS fix quality, and the number of satellites in view and in use are all available to your application program. The Wildcard incorporates a GPS subsystem made by industry leader Garmin, and includes a connection for a remote-mounted active antenna for good signal reception. This tiny 2" by 2.5" board is a member of the Wildcard™ series that connects to Mosaic controllers.

This document describes the capabilities of the GPS Wildcard, tells how to configure the hardware, and presents an overview of the GPS driver software that runs on the Mosaic controller. A glossary of the Mosaic software device driver functions, demonstration program source code, and hardware schematics are presented.

Physical Specifications
Current:
Weight:	25 gram
Size :	2" x 2.5" x 0.365"1) (50.8mm x 63.5mm x 9.3mm)

The Global Positioning System (GPS) relies on more than two dozen GPS satellites orbiting the Earth. Each satellite transmits signals including a very precise clock plus satellite position information that allows a GPS receiver to determine its location, speed and direction. A GPS receiver calculates its position by measuring the distance between itself and three or more GPS satellites. Because the signal from the GPS satellite travels at a known speed, measuring the time delay between transmission and reception of each GPS radio signal allows the receiver to calculate the distance to each satellite. By determining the position of, and distance to, at least three satellites, the receiver can compute its position. GPS receivers typically do not have perfectly accurate clocks and therefore track one or more additional satellites to correct the receiver's clock error.

The GPS signal is circularly polarized with a typical center frequency of 1.575 gigahertz. For best results, an active antenna amplifies the signal before delivering it via a coaxial cable to the GPS receiver. The GPS antenna should be mounted in a position that has a clear view of the sky so that the satellite signals can be received. GPS receivers typically do not work inside buildings, and may have trouble in vehicles or areas where the view of the sky is obstructed by tall buildings or dense foliage. Operating in urban areas can confuse the receiver due to signal reflections off buildings that result in multipath effects that lengthen the time it takes for a signal to reach the receiver, causing errors in the reported position.

Some GPS receivers have a built-in Wide Area Augmentation System, or WAAS, that improves accuracy using a network of ground stations to provide additional information to the GPS receiver. The Garmin GPS-15 receiver on the GPS Wildcard is not WAAS enabled.

When a GPS receiver is first turned on, it must go through an acquisition process to locate and lock onto the satellite signals. The more initial information the GPS has about its location and time, the faster the acquisition process. A warm acquisition occurs when the initial receiver location, time, and satellite location (ephemeris) data is known. A cold acquisition occurs when the initial receiver location, and time is known, but the satellite location data is unknown. If even less information is known, a sky search is required to complete the acquisition process and obtain a position fix.

The Garmin GPS subsystem specifications are summarized in Table 1-1.

Table 1-1 Garmin GPS-15 subsystem specifications.

The key component of this Wildcard is the GPS-15 subsystem manufactured by Garmin, the industry leader in GPS instrumentation. It implements a 12-channel GPS receiver, and includes a rechargeable backup battery to maintain the contents of the subsystem's clock and memory for up to 21 days in the absence of external power. The battery recharges whenever power is applied to the unit. The GPS subsystem outputs standard NMEA (National Marine Electronics Association) ASCII strings, called sentences, using the NMEA 0183 Version 2.20 protocol. Each sentence reports information about one or more GPS logger parameters such as location, speed, heading (direction), time, or position error estimates. A frame of 6 to 7 sentence types is output each second at 4800 baud by the subsystem. The NMEA sentence format is explained in more detail below.

This Garmin GPS subsystem is encased in a shielded metal enclosure, and includes a female MCX connector for an active GPS antenna. Mosaic sells a mating antenna with a male MCX connector that can be mounted in a location that provides a good view of the sky for optimal operation.

The Garmin GPS subsystem performs a warm satellite acquisition in about 15 seconds, and a cold acquisition in about 45 seconds. These relatively fast acquisitions rely on initial position and time data that is stored in the battery-backed RAM in the subsystem. If the stored information has been lost or is not correct (for example, if the internal backup battery is discharged or the receiver has been transported to a new location since it was last used), then a sky search acquisition is performed, requiring up to 5 minutes to acquire a fix.

The position accuracy of the GPS-15 subsystem is better than 15 meters 95% of the time. The velocity accuracy is 0.1 knot if the receiver is moving at a steady speed. A knot is a nautical mile per hour, equal to 1.152 miles per hour (MPH). The maximum reportable speed is 999.9 knots.

The picture in Figure 1-1 illustrates the Wildcard’s hardware.

Figure 1-1 The GPS Wildcard.

As shown in the Figure, the GPS Wildcard comprises a Wildcard bus header, a Garmin GPS-15 subsystem with active antenna connector, a UART chip, and digital logic circuitry. Jumpers enable address selection for the card. The Wildcard bus header interfaces to the host processor (QCard, QScreen, Handheld, or PDQ series controller). A flex cable passes through a slot in the board to interface the Garmin GPS subsystem to the UART serial-to-parallel converter chip and power conditioning circuitry on the bottom of the Wildcard.

As shown in Figure 1-1, the Garmin GPS subsystem is encased in a shielded metal enclosure, and includes a female MCX connector for an active GPS antenna. The GPS will not work unless an active antenna is attached. Mosaic sells a mating antenna with a male MCX connector that can be mounted in a location that provides a good view of the sky for optimal operation.

To connect the GPS Wildcard to the Wildcard bus on the controller board:

With the power off, connect the female 24-pin side of the stacking go-through Wildcard bus header on the bottom of the GPS Wildcard to Wildcard Port 0 or Wildcard Port 1 on the controller or its mating Docking Panel (formerly the PowerDock). The corner mounting holes on the Wildcard should line up with the standoffs on the controller board. The Wildcard ports are labeled on the silkscreen of the controller board. Note that the GPS Wildcard headers are configured to allow direct stacking onto the controller board, even if other Wildcards are also installed. Do not use ribbon cables to connect the GPS Wildcard to the Wildcard bus.

Once you have connected the GPS Wildcard to the Wildcard bus, you must set the address of the Wildcard (also called the module number) using jumper shunts across J1 and J2.

The Wildcard Select Jumpers, labeled J1 and J2, select a 2-bit code that sets a unique address on the Wildcard port of the controller board. Each Wildcard port on the controller accommodates up to 4 Wildcards. Wildcard Port 0 provides access to Wildcards 0-3 while Wildcard Port 1 provides access to Wildcards 4-7. Two Wildcards on the same port cannot have the same address (jumper settings). These are the possible jumper settings with their corresponding addresses:

A package of pre-coded device driver functions is provided to make it easy to control the GPS Wildcard. This code is available as a pre-compiled kernel extension library to C and Forth programmers. Both C and Forth source code versions of a demonstration program are provided. The demo program illustrates how to initialize and use the GPS Wildcard in a multitasking application.

In the following sections we examine the formatted data that is transmitted by the Garmin GPS subsystem, and summarize how the Mosaic GPS driver software extracts the data and makes the GPS information available to your application program. The gps_info data structure that holds the collected GPS information is described, and a comprehensive glossary of functions is available.

The glossary contains the following functions (the use of many of these is summarized in the following sections). Clicking on the following function names should popup their glossary entries:

The NMEA (National Marine Electronics Association) 0183 standard specifies the format of ASCII serial data output by the GPS receiver. On the GPS Wildcard, this serial data is transmitted by the Garmin GPS subsystem and received by a UART (Universal Asynchronous Receiver Transmitter) chip. The processor can read the data out of the UART receive buffer via the Wildcard bus, and the driver functions facilitate extraction of the GPS parameters from the serial data stream.

The GPS serial data is organized into sentences. Each sentence starts with the ASCII $ character, followed by the sentence name field, followed by the data fields, followed by an ASCII * character and the hexadecimal ASCII checksum. The checksum is calculated as the 8-bit exclusive-OR sum of all ASCII characters between the $ and * characters (not including the $ and *). The sentence is terminated by the carriage return (0x0D) and linefeed (0x0A) characters. There is a comma after the name field, and after each data field except the last one before the checksum. Any alphabetic letters in the sentence must be upper case. In the Garmin implementation of the NMEA protocol, a sentence may contain up to 82 characters.

The following table summarizes the four NMEA sentences from which data is extracted by the GPS Wildcard driver software. Each of these sentences is discussed in turn.

The GPRMC sentence delivers the fundamental position, time, course, and direction information. The Mosaic software driver extracts all of the fields from this sentence and stores them in the gps_info data structure described below. For those who are interested in the details of the sentence structure, the format is as follows:

$GPRMC,<hhmmss_utc>,<A|V>,<ddmm.mmmm_lat>,<N|S>,<dddmm.mmmm_long>,<E|W>,
<kkk.k_knots>,<ddd.d_degrees_course>,<ddmmyy>,<ddd.d_mag_var>,<E|W_mag_var_dir>*hhcrlf

After the sentence name, the universal time is presented in hours, minutes and seconds. The Coordinated Universal Time is somewhat surprisingly abbreviated as UTC; it is the time in Greenwich England that serves as the global time reference. The next field is a single-character A or V, where A indicates a valid position, and V indicates an invalid position warning. The next field is the latitude expressed as a 2-digit number of degrees in the range 00 to 89 degrees, followed by the number of minutes expressed with 2 digits to the left of the decimal point and 4 digits to the right in the range 00.0000 to 59.9999 minutes. The next field is N or S to indicate North or South latitude (relative to the equator). The longitude is expressed in similar fashion, except that there are 3 longitude degree digits in the range 000 to 179 degrees, followed by the longitude minutes and the W or E hemisphere. The longitude hemisphere is relative to the prime meridian which passes through Greenwich England. The next field is the ground speed in the range 000.0 to 999.9 knots (a knot is 1.152 miles per hour). The next field is the course (also known as the heading or direction) expressed in degrees with respect to true north in the range 000.0 to 359.9 degrees. The next field is the UTC date expressed as a 2-digit date (01-31), 2-digit month (01-12), and 2-digit year (00-99). The next field is the magnetic variation in degrees in the range 000.0 to 180.0 degrees; this variation quantifies the difference between true north and the magnetic north indicated by a compass. The next field is the direction of the magnetic variation; westerly magnetic variation adds to the true course. The * checksum indicator, hexadecimal ASCII checksum, and carriage return/linefeed complete the sentence.

As explained in detail below, the function GPS_Frame_Extract and its calling function GPS_Update automatically parse this sentence, extract the fields, and store them in the gps_info data struct so your application program can use the data. The fields are stored as binary quantities. As summarized in the glossary, a family of additional driver functions is available to fetch the fields out of the gps_info data struct and return them for use in your program.

The GPGGA sentence describes whether a GPS fix is available, the number of satellites in use, and the current altitude of the GPS antenna in meters. For those interested in the sentence structure, here it is:

$GPGGA,<hhmmss_utc>,<ddmm.mmmm_lat>,<N|S>,<dddmm.mmmm_long>,<E|W>,<0|1>,
<00-12_numsats_in_use>,<0.5-99.9_horiz_DOP>,<antenna_height>,M,
<geoidal_hght>,M,,*hhcrlf

After the GPGGA sentence name is the UTC time field, the latitude field, the latitude hemisphere, the longitude, and the longitude hemisphere. All of these are redundant with information from the GPRMC sentence and are ignored. The next field is an ASCII 0 or 1, where 0 means that the GPS fix is not available, and 1 means that a standard non-differential GPS fix is available. The next field is the 2-digit number of satellites in use. We ignore the following dilution of precision field. The next field is the antenna height (altitude) in meters expressed as a number in the range -9999.9 to 99999.9. The following field is an ASCII M to indicate that the altitude is expressed in meters. The final fields present the geoidal height in meters, followed by the M for meters, followed by two empty fields, hex checksum, and the carriage return linefeed terminators. Only the fix availability indicator, number of satellites in use, and altitude fields are extracted by GPS_Frame_Extract and its calling function GPS_Update. These fields are stored in the gps_info data struct. Your application program can access them directly, or invoke a family of additional driver functions to fetch the fields.

The GPGSV sentence is used to extract a single field: the number of satellites in view. The sentence structure is as follows:

$GPGSV,<num_gpgsv_sentences>,<index_of_this_sentence>,<00-12_numsatinview>,
<01-32_sat_prn>,<00-90deg_sat_elev>,<000-359_sat_azim>,<00-99db_snr>,
<repeat the above line for each satellite up to max of 4 per sentence>*hhcrlf

After the sentence name is a field that tells the total number of GPGSV sentences, followed by a sentence index as described below. The next field is a 2-digit number of satellites visible to the GPS receiver in the range 00 to 12; this field is extracted by the driver functions. If the GPS receiver is inside a building, this field will typically report zero satellites in view, while in unobstructed outside situations all 12 GPS receiver channels may have a satellite in view. The remainder of the sentence presents satellite-specific elevation, azimuth and signal-to-noise ratio information that is ignored by the Mosaic GPS driver.

In a single 1-second frame of sentences from the GPS subsystem, there is one GPGSV sentence describing up to 4 of the satellites in view; let’s say this is the GPGSV statement with sentence index 1. If there are more than 4 satellites in view, the next frame includes a GPGSV sentence describing up to 4 of the additional satellites in view, say with index 2. If there are more than 8 satellites in view, the next frame will include GPGSV sentence with index = 3 to describe the remaining satellites, and the process starts again with GPGSV index 1 present in the subsequent frame. This is explained further in the commentary describing Listing 1-1 on page 8.

The PGRME sentence is a proprietary statement created by Garmin to describe the estimated position errors. The sentence structure is as follows:

$PGRME,<0.0-999.9meter_hor_pos_err>,M,<0.0-999.9meter_vert_pos_err>,M,
<0.0-999.9meter_overall_position_err>,M*hhcrlf

After the sentence name, the horizontal position error field presents a number in the range 0.0 to 999.9, followed by an ASCII M field to indicate that the units are meters. In parallel fashion, the vertical position error and overall position error fields and their M unit fields are presented. These estimated errors are extracted by GPS_Frame_Extract and its calling function GPS_Update, and are stored in the gps_info data struct so your application program can access them

Three additional sentences are transmitted by the GPS subsystem: GPGSA (dilution of precision report), PGRMT (sensor status information, output only once per minute), and PGRMM (name of map currently in use; the default is WGS84). The Mosaic GPS Wildcard driver software does not extract data from these sentences.

The following table summarizes the sentences transmitted by the GPS subsystem each second, and shows which provide data extracted by the GPS driver functions. The NMEA sentences are listed in the order in which they are transmitted, but note that the PGRMT sentence is transmitted only once per minute, while the other 6 sentences are transmitted every second.

The following listing presents a sample of four 1-second frames of data as transmitted by the Garmin GPS subsystem. Carriage returns have been inserted after each frame for clarity; the actual GPS output does not include any blank lines. You can generate a listing similar to this by passing the Wildcard address and local hour offset to GPS_Init and then invoking the GPS_Dump function. Your controller and GPS Wildcard will then stream the raw NMEA sentence frames to your Mosaic terminal window.

There are a few key items to notice while inspecting the listing. Notice that the first 3 frames shown contain 6 sentences, while the last one contains 7, including the PGRMT sentence which is transmitted only once per minute (that is, once every 60 frames). Also note while there is only one GPGSV sentence present in each frame of data, there are 3 distinct GPGSV sentences that present themselves in successive frames. The first numeric field of each GPGSV sentence is the number of distinct GPGSV sentences, and the second numeric field is the GPSSV sentence index. Each GPGSV sentence summarizes the information about a maximum of 4 satellites, and there can be as many as 12 satellites in use. The Mosaic driver software extracts only the number of satellites in view from this sentence, and this information is present in each instance of the sentence. The satellite specific information is not extracted or stored.

Listing 1-1 Four 1-second frames of NMEA sentences from the GPS.

$GPRMC,223321,A,3732.3791,N,12201.1625,W,0.0,194.8,220207,15.1,E*5A
$GPGGA,223321,3732.3791,N,12201.1625,W,1,08,1.1,11.0,M,-28.0,M,,*45
$GPGSA,A,3,03,,07,09,,16,18,19,21,,,26,1.7,1.1,1.3*3A
$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
$PGRMM,WGS 84*06

$GPRMC,223322,A,3732.3792,N,12201.1625,W,0.0,194.8,220207,15.1,E*5A
$GPGGA,223322,3732.3792,N,12201.1625,W,1,08,0.9,11.1,M,-28.0,M,,*4D
$GPGSA,A,3,03,,07,09,,16,18,19,21,,,26,1.6,0.9,1.3*32
$GPGSV,3,3,12,21,56,082,47,22,63,268,00,24,11,102,00,26,13,037,42*7B
$PGRME,5.0,M,5.8,M,7.7,M*26
$PGRMM,WGS 84*06

$GPRMC,223323,A,3732.3792,N,12201.1625,W,0.0,194.8,220207,15.1,E*5B
$GPGGA,223323,3732.3792,N,12201.1625,W,1,08,0.9,11.2,M,-28.0,M,,*4F
$GPGSA,A,3,03,,07,09,,16,18,19,21,,,26,1.6,0.9,1.3*32
$GPGSV,3,1,12,03,39,301,34,06,08,157,00,07,18,163,33,09,09,096,46*7E
$PGRME,5.0,M,5.8,M,7.7,M*26
$PGRMM,WGS 84*06

$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

The Mosaic GPS Wildcard driver software does not send any sentences to the GPS. Thus the sentences named PGRMI, PGRMC, and PGRMO that configure various options and parameters in the GPS subsystem are not supported or used. The Mosaic driver accept the default performance of the GPS, which does its best to remember the proper time and location information to minimize acquisition time. Experts who are interested in the details of these configuration sentences can consult the Garmin GPS-15 datasheet.

On the GPS Wildcard, the NMEA sentence serial data is transmitted by the Garmin GPS subsystem and received by a UART (Universal Asynchronous Receiver Transmitter) chip. The serial data is transmitted at 4800 baud (bits per second). The UART contains a 64-byte receiver FIFO (First In/First Out) buffer that buffers the data until it is read by the processor via the Wildcard bus.

Data is continuously streaming out of the GPS subsystem, one multi-sentence frame per second. While some applications may need to continuously extract data to perform navigation functions, other applications may need only infrequent updates of GPS information. The Mosaic GPS driver is written to accommodate this broad range of application needs.

For applications with infrequent needs for GPS updates, the data streaming out of the GPS subsystem can be safely ignored until an update is needed. The unused data will overflow the FIFO buffer in the UART, and will effectively be discarded. At any point in time, the GPS_Update function can be called to flush any old characters from the UART FIFO, accept a valid frame of data sentences from the GPS subsystem, and extract the GPS data to a structure where it is accessible to the application program. Applications that need frequent updates from the GPS can run a tight loop in a task that continually calls GPS_Update and uses the resulting data as it becomes available.

GPS_Update is the highest level function in the GPS driver. It calls GPS_Next_Frame which waits for 7 sentences from the GPS subsystem and puts them into the GPS_Inbuf, a 600 byte character buffer allocated in common RAM. (To be precise, GPS_Inbuf is a function that returns the 32-bit base xaddress of the gps_default_inbuf character array.) GPS_Update then invokes GPS_Frame_Extract. This workhorse function parses the sentences in the GPS_Inbuf, extracts the relevant data parameters, and stores them into the gps_info structure for use by the application program. Your application program can access the gps_info struct fields in common RAM directly, or invoke a family of additional driver functions to fetch the fields out of the struct and return them.

The defining source code for the gps_info struct is presented in Listing 1-2 on page 19 (for the C language) and Listing 1-3 on page 33 (for the Forth language). Please take a moment now to examine the listing in your chosen programming language. The field names should be familiar, as they correspond to the data fields from the GPS sentences as described in the prior section. The comments accompanying each field provide additional descriptive information. While the NMEA sentences transmit the numeric data fields as ASCII values, the gps_info data structure stores the numeric data as binary integers (but the directions N S E and W are stored as ASCII values in the struct). This maximizes the programmer’s flexibility in performing computations with the numeric data.

As an example, let’s take the latitude of Mosaic Industries headquarters, which is approximately 37 degrees, 32.3793 minutes North of the equator. Recall that a minute is one sixtieth (1/60) of a degree. This latitude is reported in the GPRMC sentence as:

3732.3793,N

You can see this latitude report in Listing 1-1 on page 8 in the GPRMC sentence; the latitude is reported in the field after the A. The first 2 digits are the latitude degrees (37), the next 2 digits are the integer part of the latitude minutes (32), then there is a decimal point, followed by the decimal fractional part of the latitude (.3793), followed by the N field for North. After executing GPS_Update (or its component functions GPS_Next_Frame and GPS_Frame_Extract). the latitude is available in the following fields of the gps_info struct:

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'

Each field name begins with s to indicate that it is a struct field, and the field name is descriptive. In this example, the sgps_lat_degrees field contains a binary representation of the latitude degrees (37), and the sgps_lat_minutes_intpart field contains a binary representation of the integer part of the latitude minutes (32). The sgps_lat_minutes_fraction field contains a binary representation of the fractional part of the latitude minutes (3793); its dimensions (units) are ten-thousandths of a minute. The driver provides these fields to preserve all of the latitude information reported by the GPS subsystem in a useable form.

To directly fetch the latitude degrees into a variable named latitude_degrees, a C application program could use the statements:

int latitude_degrees;
latitude_degrees = gps_info.sgps_lat_degrees;

An application program can also use the function GPS_Lat_Degrees that fetches the parameter from the gps_info struct and returns it for use in the program. The following two C statements have the same effect as the statements above:

int latitude_degrees;
latitude_degrees = GPS_Lat_Degrees;

The function named GPS_Lat_Minutes_Times_10000 scales up the latitude minutes by a factor of 10000 and returns it as a 32-bit integer in the range 0 to 599,999. 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 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.

If desired, your application program can convert the latitude minutes into a single floating point number. For example,

float latitude_minutes;
latitude_minutes = GPS_Lat_Minutes_Times_10000 / 10000.0 ;

Some programmers may want to use fast integer math and avoid converting to the slower floating point math. (Forth programmers using the V4.xx kernels should also be aware of the 5 decimal digit resolution of the legacy floating point package; C programmers and V6.xx Forth programmers have a floating point package with about 7 decimal digits of resolution).

The GPS_Lat_Hemisphere function returns the ASCII N or S latitude character, or your program can fetch it out of the gps_info field using an assignment statement.

The longitude is reported in a parallel set of fields in the gps_info struct:

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'

The driver functions GPS_Long_Degrees, GPS_Long_Minutes_Times_10000, and GPS_Long_Hemisphere can be used to return the longitude information to the application program.

The GPS reports altitude as a number in the range -9999.9 to 99999.9 meters relative to mean sea level. The GPS driver software multiplies this by ten to convert it to a 32-bit long value in the range -99999 to 999999 in the sgps_altitude_tenth_meters field. The GPS_Altitude_Meters_Times_10 function returns this value for use in the application program.

Ground speed is reported by the GPS subsystems in knots, or nautical miles per hour. A nautical mile is 1.152 times longer than a standard (statute) mile, and corresponds to 1 second of latitude arc. A knot is equivalent to 1.152 miles per hour. The GPS reports speed as a number in the range 0.0 to 999.9 knots, and the driver software multiplies this by ten to convert it to an integer in the range 0 to 9999 stored in the sgps_tenth_knots field. The GPS_Knots_Times_10 function returns this value for use in the application program.

Course heading (direction) is reported by the GPS as the number of degrees in the range 0.0 to 359.9 relative to true north. The Mosaic GPS driver software multiplies this by ten to convert it to an integer in the range 0 to 3599 stored in the sgps_course_tenth_degrees field. The GPS_Course_Degrees_Times_10 function returns this value for use in the application program.

The GPS reports the universal UTC time and date at the prime meridian that runs through Greenwich England. These time and date fields are saved as binary quantities in the gps_info struct where they can be accessed directly by the application program. There are no pre-defined driver functions that fetch the time and date quantities. The universal time/date differs from the local time/date by an integer number of hours. For convenience, the GPS_Init function accepts a local_hour_offset parameter which 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 the GPS_Init 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 the glossary entry for GPS_DAYLIGHT_TIME). The GPS_Update function (via its callee, GPS_Frame_Extract) extracts the universal UTC time and date from the GPRMC sentence, and uses the local_hour_offset to calculate the local time and date. These are stored in the following gps_info fields:

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

The GPS_Good_Fix function returns a true (-1) value if the contents of the struct field sgps_fix_quality = 1 and if the contents of the struct field sgps_position_valid is true. In other words, if GPS_Good_Fix returns a nonzero value, the GPS information can be relied upon (according to the GPS receiver itself). The GPS_Numsats_In_Use and GPS_Numsats_In_View functions also report information that is useful for determining the status of the GPS receiver.

The GPS_Init function initializes the data structures and the GPS Wildcard hardware. To force a reset and satellite reacquisition, pass a true flag to the GPS_Shutdown function to shut down the GPS, and then pass a false flag to the GPS_Shutdown function to restart the GPS.

If the GPS will not be used for significant periods of time, you can save power by shutting it down using GPS_Shutdown. Of course, when the GPS is turned back on there will be a delay while it reacquires the satellite fix.

A typical GPS application program initializes the GPS by calling GPS_Init, and then repeatedly invokes the high level GPS_Update function to accept a frame of data from the GPS subsystem and populate the fields in the gps_info data structure. GPS_Update calls GPS_Next_Frame which can take over 1 second to obtain a frame of data from the GPS subsystem. If the GPS_Update or GPS_Next_Frame function is invoked in a single-task system, all other instrument tasks could be halted for over a second.

To avoid this problem, create a separate task and call GPS_Update from within that task's infinite loop. Invoke StartTimeslicer (START.TIMESLICER in Forth) to run the multitasker. In this way the GPS will be serviced without blocking time-critical code running in other tasks.

As described above, the GPS driver is designed to allow GPS data to be ignored and discarded when it is not needed by the application. Once the application requires data, GPS_Update (or its callee function GPS_Next_Frame) must be able to obtain an unadulterated frame of data from the GPS and store it in the 600 byte GPS_Inbuf buffer. At the serial data rate of 4800 baud, and given that there are 10 bits per character (1 start bit, 8 data bits, and 1 stop bit), each character is transmitted in approximately 2 milliseconds. Thus the 64 byte UART FIFO will not overflow if the processor services the GPS Wildcard at least 8 times per second. This constraint is easily met in a multitasking system with the timeslicer running.

The demonstration program presents a simple example of how to use the GPS Wildcard.

The GPS_Demo function (or the main function in C) starts and runs the demonstration using the GPS Wildcard. The demonstration program source code is presented in both C and Forth.

The demo initializes the GPS by passing the local_hour_offset and module_num (the Wildcard address) to the GPS_Init function. If there is no initialization error, the following descriptive text header is printed to the terminal:

Starting GPS info dump.  Type any key to exit this function.
This function gets a data frame from the GPS once per second,
and prints a statement telling of the fix validity.
If the fix is not valid, make sure your antenna is outside,
and give the GPS some time (5 minutes worst case) to acquire its satellites.
This function periodically calls GPS_Info_Dump to summarize the GPS data.

Then the demo enters a loop calling GPS_Update. If GPS_Update returns a true error flag, the demo prints a statement telling us that no GPS fix is available. If the error flag is zero, the demo prints a statement that a fix is available. Every 5 seconds, the demo program calls GPS_Info_Dump to print a formatted summary of the GPS parameters.

This simple demo program runs from the default task and uses the default serial port to print data to the Mosaic terminal program running on your PC. In a real application, the GPS_Update function would be called from within a task dedicated to servicing the GPS.

The GPS Wildcard device driver software is provided as a pre-coded modular runtime library, known as a "kernel extension" because it enhances the on-board kernel's capabilities. The library functions are accessible from C and Forth.

Installing the driver software on the PDQ Board or PDQ Screen

Installing the driver software on the QVGA, QScreen, QCard or Handheld controllers

COLD

COLD

The C demo is located in your installation directory. It is also provided here for reference.

Using the C language demo program on the PDQ Board or PDQ Screen

#include <mosaic/allqed.h>
//__GNUC__ is true for Mosaic PDQ IDE
 
#ifdef __GNUC__
#include <wcfm.h>
#else
#include "library.h"
#include "library.c"
#endif

Using the C language demo program on the QVGA, QScreen, QCard or Handheld controllers

#include "library.c"

#include "library.h"

The Forth demo is located in your installation directory. It is also provided here for reference.

Using the Forth language demo program on the PDQ Board or PDQ Screen

MosaicPDQ\forth\demos\GPS_Wildcard\gpsdemo_loader.4TH

gps_demo

Using the Forth language demo program on the QVGA, QScreen, QCard or Handheld controllers

WHICH.MAP 0=
IFTRUE 4 PAGE.TO.RAM  \ if in standard.map...
       5 PAGE.TO.RAM
       6 PAGE.TO.RAM
      DOWNLOAD.MAP
ENDIFTRUE

4 PAGE.TO.FLASH
5 PAGE.TO.FLASH
6 PAGE.TO.FLASH
STANDARD.MAP
SAVE

See the GPS Glossary

Downloadable, high resolution schematic of the GPS Wildcard

See also →

• GPS Glossary
• GPS C Demo
• GPS Forth Demo
• GPS Wildcard