MarshallSoft GPS Component
for Windows /CE
Users Manual
(MGC_eUSR)
Version 1.2
August 26, 2003
This software is provided as-is.
There are no warranties, expressed or implied.
Copyright (C) 2003
All rights reserved
MarshallSoft Computing, Inc.
Post Office Box 4543
Huntsville AL 35815 USA
Voice: 1.256.881.4630
FAX: 1.256.880.0925
Email: info@marshallsoft.com
Web: www.marshallsoft.com
MARSHALLSOFT is a registered trademark of MarshallSoft Computing.
1 Introduction
1.1 Features2 Applications Notes
1.2 Documentation Set
1.3 User Support
1.4 Ordering
1.5 Updates
2.1 Dynamic Link Libraries3 GPS Background
2.2 Using the Library
2.3 Using MGC with other Languages
2.4 Key Codes (License Key)
3.1 What is GPS ?4 GPS Units
3.2 How GPS Works
3.3 WGS-84
4.1 Latitude and Longitude5 Using the MGC Software
4.2 Altitude
4.3 Ground Distance
4.4 Calculations
5.1 Coordinates Used in MGC6 NMEA Sentence Structure
5.2 How the MGC Software Works.
7 Versions of MGC
7.1 Evaluation Version8 Problems
7.2 Academic Version
7.3 Professional Version
9 Legal Issues
9.1 Registration10 Summary
9.2 License
9.3 Warranty
10.1 MGC Function Summary
The MarshallSoft GPS Component for Win/CE (MGCeVC and MGC4eVB) is a 32-bit dynamic link library (DLL) which reads and decodes standard GPS NMEA 183 sentences from the RS232 serial port as well as computes great circle distances and bearings.
This is the User's Manual for both MGC4eVC (MarshallSoft GPS Component for eVC) and MGC4eVB (MarshallSoft GPS Component for eVB).
Both the eVC (Embedded Visual C/C++) and eVB (Embedded Visual Basic) versions of MGC require Microsoft Embedded Tools 3.0, which can be downloaded from the Microsoft Web site..
Check http://www.marshallsoft.com for the latest version of our GPS communications software.
Some of the many features of the MarshallSoft GPS Component (MGC) are:
The complete set of documentation consists of four manuals in three formats. This is the second manual (WSC_eUSR) in the set.
Each manual comes in three formats:
The MGC Programmer's Manual is the language specific (eVC or eVB) manual. All language dependent programming issues such as compiling, compilers and example programs are discussed in this manual. Other language specific manuals are as follows:
[NAME] [DESCRIPTION] MGC_4eVC : MGC Programmer's Manual for eVC (Embedded VC). MGC_4eVB : MGC Programmer's Manual for eVB (Embedded Visual Basic).
The MGC User's Manual (MGC_eUSR) discusses GPS (Global Positioning System) fundamentals as well as language independent programming issues such as application notes and licensing. Read this manual after reading the MGC Programmer's Manual.
The MGC Reference Manual (MGC_eREF) contains details on each individual MGC function.
Use Microsoft Word or Microsoft WordPad to print the document files.
We want you to be successful in developing your applications using MGC! We are committed to providing the best library that we can. If you have any suggestions or comments, please let us know.
If you are having a problem using the MarshallSoft GPS Component, refer to Section 8.0 "Problems". If you still cannot resolve your problem, email us at
support@marshallsoft.com
You can also reach us at +1-256-881-4630 between 7:00 AM and 7:00 PM CST Monday through Friday. You can also often reach us on Saturday.
The latest versions of our products are available on our web site at
http://www.marshallsoft.com/mgc4evc.htm (eVC)
http://www.marshallsoft.com/mgc4evb.htm (eVB)
and on our anonymous FTP site at
ftp://ftp.marshallsoft.com/pub/wce
The developer's license for the MarshallSoft GPS Component (MGC) may be obtained for $115 (USD) for email delivery. MGC with source is available for $195 (USD).
The fastest and easiest way to order is on our web site at
http://www.marshallsoft.com/order.htm
You can also order by completing INVOICE.TXT (contained within the MGC zip file) and emailing (order@marshallsoft.com), mailing (see our address at top), or faxing (+1.256.880.0925) it to us.
Multiple copy discounts (3 or more) and site licenses are available. Please call for details.
We accept American Express, VISA, MasterCard, Discover, checks in US dollars drawn on a US bank, International Postal Money Orders, and purchase orders (POs) within the USA from recognized US schools and companies listed in Dun & Bradstreet.
For credit card orders, be sure to include the following: account number, the expiration date, the exact name on the credit card, and the complete card billing address (the address to which the credit card bill is mailed- not the bank's). Please include card holder's signature on faxed orders.
Print the file INVOICE.TXT if a "Pro Forma" invoice is needed. The registered package includes:
There are two ways to order Source Code for the MarshallSoft GPS Component software.
We offer an "academic price" of 30% off the normal price for prepaid email orders to faculty and full time students currently enrolled in any accredited high school, college, or university. To qualify for the discount, your school must have a web site and you must have an email address at your school.
When ordering, ask for the "academic discount", or enter "student at" (or "faculty at") and your schools web site address (URL) in the comments field of the order form on our web site order page. Your order will be sent to your email address at your school.
This offer is not retroactive and cannot be used with any other discount. Products bought with academic pricing are for educational use only. They can not be used for any commercial purpose.
When ordering the MarshallSoft GPS Component, a 3.5" HD disk can be purchased for $5 for delivery to the, US, Canada, and Mexico. For all other destinations, the disk is $8.
See INVOICE.TXT or http://www.marshallsoft.com/order.htm
Printed manuals (see Section 1.1 "Documentation Set") are the same as in the MGC shareware distribution. Printed manuals can be purchased for $20 for delivery to the US, Canada, and Mexico. For all other destinations, printed manuals are $25. Printed manuals also come with a 3.5" HD disk.
See INVOICE.TXT or http://www.marshallsoft.com/order.htm
When you register MGC4C you receive a registered DLL (MGC32.DLL) plus a license file (MGCxxxx.LIC) that can be used to update your registered DLL for a period of one year from purchase. Updates can be downloaded from
http://www.marshallsoft.com/oem.htm
After one year, your license must be updated if you want to be able to download updates. Your license can be updated for $30 if ordered within one year of the original purchase (or previous update). After one year, licenses can be updated for $55.
Note that the registered DLL's do not expire.
Also see file UPDATES.TXT.
The MarshallSoft GPS Component (MGC) is implemented as a Win32 dynamic link library (MGC32.DLL). A DLL is characterized by the fact that it need not be loaded until required by an application program and that only one copy of the DLL is necessary regardless of the number of application programs that use it. Contrast this to a static library that is bound at link time to each and every application that uses it.
The best way to get familiar with the MarshallSoft GPS Component (MGC) is to try out one of the example programs. The example programs are described in the MGC Programmer's Manual:
[NAME] [DESCRIPTION] MGC_4eC : MGC Programmer's Manual for eVC MGC_4eVB : MGC Programmer's Manual for eVB
The MarshallSoft GPS Component DLL (MGC32.DLL) can also be used with any application written in any language capable of calling the Win/CE 32-bit API.
Declaration files have been defined by the following languages:
[LANGUAGE] [FILE] eVC (C/C++) MGC.H eVB (Visual Basic) MGC32.BAS
Additional declaration files will be added. Give us a call if you need a declaration not listed above.
MGC32.DLL has a keycode encoded within it. Your keycode is a 9 or 10 digit decimal number (unless it is 0), and will be found in the file KEYCODE.H. The keycode for the evaluation version is 0. It is NOT your Customer ID. You will receive a new key code when registering.
If you get an error message (value -74) when calling mgcAttach, it means that the keycode in your application does not match the keycode in the DLL. After registering, it is best to remove the evaluation version of MGC32.DLL from the Windows search path.
The following provides a high level background for discussion of GPS.
The Global Positioning System (GPS) is a constellation of 24 satellites that orbits the earth and used for navigation by anyone with a GPS receiver.
The GPS satellites were placed into orbit by the U.S. Department of Defense for military applications. In the 1980s, the US government made the GPS system available for civilian use. The accuracy of the GPS signal was intentionally degraded (known as Selective Availability) for non-US military users, but has recently been removed (May 2nd, 2000).
There are many good sites on the internet dealing with GPS. Some good ones are
http://www.colorado.Edu/geography/gcraft/notes/gps/gps_f.html
http://www.aero.org/publications/GPSPRIMER/
The 24 GPS satellites (21 active plus 3 spares) are in orbit at 10,600 miles above the surface of the earth. The satellites are spaced such that four satellites will be above the horizon when viewed from any point on the surface of the earth.
GPS satellites circle the earth twice each day. The GPS receiver compares the time that a signal was transmitted by a satellite with the time that it was received. The time difference determines the distance between the GPS receiver and the satellite.
A GPS receiver must be locked to the signal of at least three satellites in order to calculate a position (by spherical triangulation) on the surface of the earth, giving latitude and longitude of the GPS receiver. With four or more satellites in view, the receiver can also determine the altitude.
WGS-84 (World Geodetic System 1984) is a global reference frame for the earth. It was accepted in March 1989 as the standard world reference frame by the International Civil Aviation Organization (ICAO).
Most GPS receivers today model the earth as a geode as defined by WGS-84 (World Geodetic System 1984).
Earth's radius as defined by WGS-84 is as follows:
Equatorial radius = 6,378,137.0 m
Polar radius = 6,356,752.3142 m
For more information on WGS-84, refer to:
http://www.wgs84.com
A great circle is the intersection of a sphere with a plane that passes through the center of the sphere. Note that the shortest distance (on the surface of the sphere) between two points is always part of a great circle.
Latitude and longitude are spherical coordinates on the surface of the earth.
Lines of latitude, also called parallels, are horizontal to each other and run east and west. Latitude is measured north (+) or south (-) of the Equator, resulting in a range of -90 to +90 degrees. The Equator is the parallel (also a great circle) that divides the globe into two halves, the Northern and Southern Hemispheres. Any point on the globe below the equator has a negative value for latitude, while points above the equator have positive latitude values.
Lines of longitude, also called meridians, are great circles that run between the North Pole and the South Pole. Thus, lines of latitude and lines of longitude always meet at right angles on the surface of the earth. Longitude is measured east (+) or west (-) of the prime meridian which passes through Greenwich, England. Longitude is measured east or west from 0 to 180 degrees.
Both latitude and longitude are measured in degrees (360 degrees in a circle). Each degree can be subdivided into 60 minutes, and each minute can be subdivided in 60 seconds. In the NMEA Sentence format, latitude and longitude are measured in degrees, minutes, and thousandths of minutes. In the MarshallSoft GPS Component (MGC), latitude and longitude are measured in integral degrees, integral minutes, and integral units of thousandths of a minute.
Every location on the surface of the earth has unique latitude and longitude coordinates. Determining the latitude and longitude of your location is the primary purpose of a GPS receiver.
Altitude is the distance above the WGS-84 reference geode, measured in feet or meters (default). Altitude measurements in GPS are typically not as accurate as latitude and longitude measurements.
Ground distance is the distance along a great circle (arc length) between two points on the WGS-84 reference geode, measured in feet or meters (default).
There are 4 ways that latitude and longitude values are commonly expressed:
Value = (60000 Deg) + (1000 Min) + Dec
where
Deg = integral degrees (86)
Min = integral minutes (34)
Dec = integral thousandths of a minute (124)
Note that the GPS latitude and longitude are accurate to at best 15 meters.
MGC uses (deg,min,dec) and an integral coded value to represent latitude and longitude.
See the COMPUTE and COMPUTE2 example programs.
It is advantageous to represent latitude and longitude values as integers rather than as floating point, real, or packed decimal numbers. This allows the MGC DLL (MGC32.DLL) functions to be called by any application regardless of the type of floating point (real) numbers supported by the language.
Latitude and longitude coordinates are specified by three non-negative integer values: degrees, minutes, and thousandths of a minute. Thus, latitude 34 degrees, 18.251 minutes north is represented by (34, 18, 251), while 86 degrees, 32.001 minutes west is represented by - (86, 32, 1)
These three values may also be specified by a single integer calculated as the integral number of thousandths of a minute. That is,
N = (60000 * WholeDegrees) + (1000 * WholeMinutes) + Thousandths
In applications that have floating point data types, latitude and longitude values are easily converted to floating point (real) values by dividing by 60000. For example, in C/C++,
RealDegrees = (float)IntegralThousandths / 60000.0
Altitude in MGC can be returned in units feet (F) or meters (M), depending on the value (*) set when calling
mgcSetInteger(MGC_SET_ALTITUDE_UNIT, * )
The default is meters. Refer to the MGC Reference Manual (MGC_REF) for more details.
Ground distance in MGC can be returned in units of feet (F), meters (M), kilometers (KM), statue miles (SM), or nautical miles (NM), depending on the value (*) set when calling
mgcSetInteger(MGC_SET_DISTANCE_UNIT, * )
The default is meters. Refer to the MGC Reference Manual (MGC_REF) for more details.
The MarshallSoft GPS Component (MGC) software (implemented in MGC32.DLL) reads NMEA sentences from the selected serial port.
Calling mgcOpen in the MGC32.DLL starts a Win32 thread that periodically reads the selected serial port, making a copy of the incoming sentence. While one sentence is in the process of being read, the previously read sentence (which has been completely read) may be copied by the calling application program.
There are quite a few sentence types, and the individual fields of any sentence can be read by the application. Two sentence types (GPRMC and GPGGA) have predefined field names and functions (such as mgcLatitude and mgcLongitude) that can retrieve specifically defined fields.
Note that the application program always has access to the most current sentence.
Calling mgcClose closes the serial port connection.
Typical program logic is as follows:
For more details on program logic, refer to the example programs that are included with MGC.
The MarshallSoft GPS Component (MGC) is designed to read GPS data from the serial port according to the NMEA (National Marine Electronics Association) specification. For specification details, see
http://www.nmea.org
The NMEA 183 standard specifies 4800 baud, 8 bit data, and no stop bits.
MGC can read any GPS NMEA 183 sentence, extracting each field. In addition, it can read and decode the four major sentences used for navigation: GPGGA, GPRMC, GPGLL, and GPGSV.
The NMEA 0183 INTERFACE STANDARD (printed document) can be ordered from the National Marine Electronics Association (410-975-9425).
Version 6.3 of the "NMEA FAQ" contains details of the NMEA sentence structure and can be found at
http://vancouver-webpages.com/peter/nmeafaq.txt
The MarshallSoft GPS Component (MGC) library is available in three versions. All three versions have identical functionality.
The evaluation version can be differentiated from the other two versions by:
The academic version can be differentiated from the other two versions by:
The professional version (developer license) can be differentiated from the other two versions by:
The professional version may be distributed with your application as specified by the software license. See Section 1.4 "Ordering" for details on ordering and Section 8.2 for the license information.
We recommend the following steps if you believe that you have discovered a bug in the library:
If the problem is an error in the library and can be solved with an easy work-around, we will publish the work-around. If the problem requires a modification to the library, we will make the change and make the modified library available to our customers without charge.
See Section 1.4 "Ordering" for information on ordering.
MarshallSoft Computing, Inc. grants the registered user of MarshallSoft GPS Component (MGC) the right to use one copy of the MGC32.DLL on a single computer in the development of any software product. The user may not use the library on more than one computer at the same time.
The "academic" registered DLL may not be distributed under any circumstances and may not be used for any commercial purpose.
The "professional" registered DLL may be distributed (without royalty) in object form only, as part of the user's compiled application. The registered DLL may NOT be distributed as part of any software development system (compiler or interpreter) without our express written permission. The source code for the library (MGC.C and WSC32MGC.C) is copyrighted by MarshallSoft Computing and may not be released in whole or in part.
MARSHALLSOFT COMPUTING, INC. DISCLAIMS ALL WARRANTIES RELATING TO THIS SOFTWARE, WHETHER EXPRESSED OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, AND ALL SUCH WARRANTIES ARE EXPRESSLY AND SPECIFICALLY DISCLAIMED. NEITHER MARSHALLSOFT COMPUTING, INC. NOR ANYONE ELSE WHO HAS BEEN INVOLVED IN THE CREATION, PRODUCTION, OR DELIVERY OF THIS SOFTWARE SHALL BE LIABLE FOR ANY INDIRECT, CONSEQUENTIAL, OR INCIDENTAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE SUCH SOFTWARE EVEN IF MARSHALLSOFT COMPUTING, INC. HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES OR CLAIMS. IN NO EVENT SHALL MARSHALLSOFT COMPUTING, INC.'S LIABILITY FOR ANY SUCH DAMAGES EVER EXCEED THE PRICE PAID FOR THE LICENSE TO USE THE SOFTWARE, REGARDLESS OF THE FORM OF THE CLAIM. THE PERSON USING THE SOFTWARE BEARS ALL RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE.
Some states do not allow the exclusion of the limit of liability for consequential or incidental damages, so the above limitation may not apply to you.
This agreement shall be governed by the laws of the State of Alabama and shall inure to the benefit of MarshallSoft Computing, Inc. and any successors, administrators, heirs and assigns. Any action or proceeding brought by either party against the other arising out of or related to this agreement shall be brought only in a STATE or FEDERAL COURT of competent jurisdiction located in Madison County, Alabama. The parties hereby consent to in personam jurisdiction of said courts.
Refer to the MGC Reference Manual (MGC_eREF) for detailed information on the MGC functions. A one line summary of each function follows.
There are 19 functions in the MGC library.
mgcAltitude Returns last altitude value. mgcAttach Attaches MGC32.DLL. mgcBearing Returns bearing from one position to another. mgcClose Closes MGC. mgcErrorText Returns error message text. mgcGetData Returns data field value. mgcGetInteger Returns named integer parameter. mgcGetString Returns named string parameter. mgcGreatCircle Returns great circle distance. mgcLatitude Returns last latitude value. mgcLockData Locks (and unlocks) current data record. mgcLongitude Returns last longitude value. mgcOpen Open serial port for NMEA sentence input. mgcRelease Releases MGC32.DLL mgcSeaLevel Returns last sea level value. mgcSetInteger Sets named integer parameter. mgcSleep Sleeps specified time. mgcSysTime Returns milliseconds since boot-up. mgcTimestamp Returns last timestamp value.