1 Introduction

1.1 Features
1.2 Documentation Set
1.3 Key Codes
1.4 Example Program Segment
1.5 Installation
1.6 Uninstalling
1.7 Ordering
1.8 Updates

2 Library Overview

2.1 Dynamic Link Libraries
2.2 Static Linking
2.3 Compiling Programs

3 Example Programs
4 Revision History

1 Introduction

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 computing great circle distances and bearings.

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.

The evaluation and registered versions are identical except that the evaluation version displays the evaluation (SW_Info) screen.

1.1 Features

Some of the many features of the MarshallSoft GPS Component (MGC) are:

1. Uses the Windows Win32 API for serial port input. No special Windows driver is required.
2. Runs as a background thread unattended.
3. The most current GPS data is always available on demand.
4. Support functions (such as mgcGreatCircle) are included.
5. Function can be called from eVC or eVB programs.
6. Most commonly used NMEA sentence types are automatically decoded.
7. The MGC is a standard Windows DLL that does not depend on support DLLs.
   
   
   

1.2 Documentation Set

The complete set of documentation consists of three manuals in three formats. This is the first manual (WSC_eVC) in the set.

• MGC/CE Programmer's Manual (MGC_eVC or MGC_eVB)
• MGC/CE User's Manual (MGC_eUSR.DOC, MGC_eUSR.TXT, MGC_eUSR.HTM)
• MGC/CE Reference Manual (MGC_eREF.DOC, MGC_eREF.TXT, MGC_eREF.HTM)

Each manual comes in three formats:

• Microsoft Word (files ending in .DOC). The best format for printing manuals.
• Hyper Text (files ending in .HTM). Use any web browser to read.
• ASCII Text (files ending in .TXT).

The MGC_4eVC Programmer's Manual is the language specific manual. All language dependent programming issues such as compiling, compilers and example programs are discussed in this manual. Read this manual first.

The MarshallSoft GPS Component 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 second.

The MarshallSoft GPS Component Reference Manual (MGC_eREF) contains details on each individual MGC function.

Use Microsoft Word or Microsoft WordPad to print the document files.

1.3 Key Codes (License Key)

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 named "KEYCODE". The keycode for the evaluation version is 0. 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.

1.4 Example Program Segment

The following example code segment demonstrates the use of some of the library functions. This code runs inside a timer loop, a little more often than once per second.

     double Latitude;
     double Longitude;
     char DataBuffer[128];

     // get # lines received from GPS device
     LinesRX = mgcGetInteger(MGC_GET_LINES_RECEIVED);
     wsprintf((LPWSTR)Temp,L"%d", LinesRX % 100000);
     SetWindowText(hWnd,Temp);
     DrawMenuBar(hWnd);
     // lock data buffer
     mgcLockData(1);
     // get timestamp
     Code = mgcGetData(GPGGA_UTC_TIME,(LPSTR)DataBuffer);
     if(Code<0) ShowMGC32Error(Code);
     if(Code==1)
       {// reference count = 1 (1st time seen this data)
        // get latitude (units of thousandths of a minute) & display in degrees
        Latitude = (double)mgcLatitude() / 60000.0;
        // get longitude (units of thousandths of a minute) & display in degrees
        Longitude = (double)mgcLongitude() / 60000.0;
        // display on screen as static text
        wsprintf((LPWSTR)Temp, L"Lat=%0.4f, Lon=%0.4f ", Latitude, Longitude);
        SetButtonText(hWnd, MSG_STATIC,(LPWSTR)Temp);
       }
     // unlock data buffer (finished with this buffer)
     mgcLockData(0);

1.5 Installation

1. Unzip MGC4eVC33.ZIP (or MGC4eVC.ZIP for registered users) using WINZIP or PKZIP for Windows.
   
   
2. Run the installation program SETUP.EXE that will install all MGC4eVC files to your desktop computer.

The SETUP program creates a directory (default MGC4eVC) on the desktop machine with the following sub-directories (folders).

    APPS : All example code.
    DOCS : All documentation.
    LIBS : All LIB files for each of the different CPUs.
    DLLS : All DLL files for each of the different CPUs.
    COPY : Files to copy to your Win/CE machine's \WINDOWS directory.

After SETUP completes, the DLL's in the COPY directory (folder) must be copied to your Win/CE machine's \WINDOWS directory (folder) using ActiveSync.

Microsoft Embedded Tools must be installed on your desktop in order to compile the example programs.

1.6 Uninstalling

Uninstalling MGC4eVC is very easy. MGCeVC does not modify the registry. First, delete the MGCeVC project directory created when installing MGC4eVC. Second, delete MGC32.DLL from your Win/CE machine's \WINDOWS directory (folder) using ActiveSync.

1.7 Ordering

MGC4eVC can be registered for $115 (or $195 with source code). See Section-1.4, "Ordering" in the MGC4eVC User's Manual (MGC_eUSR) for details on ordering.

1.8 Updates

When you register MGC4C, you receive registered DLL's (MGC32.DLL for each supported processor) 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.

2 Library Overview

2.1 Dynamic Link Libraries

MGC4eVC is implemented as a Win/CE dynamic link library (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 the traditional static library which is bound to each and every application that uses it at link time.

2.2 Static Linking

Registered users (who have ordered MGC4eVC with source code) can easily compile MGC32.CPP into their application, so that MGC32.DLL is not needed.

In the MGC prototype file mgc.h, change

     #ifdef WSC_IMPLEMENTATION
     #define WSCDLLEXPORT _declspec(dllexport)
     #else
     #define WSCDLLEXPORT _declspec(dllimport)
     #endif

to

     #define WSCDLLEXPORT

2.3 Compiling Programs

Microsoft Embedded Tools must be installed on your desktop computer in order to compile the example programs.

1. Use the "Open Project" menu item in Microsoft Embedded Tools to open the eVC project files (*.vcp) in the APPS directory (folder).
   
   
2. From the main menu, choose "Project / Settings...". When the "Project Settings" window is displayed, choose the "Link" tab.
   
   
3. Add MGC32.LIB to "Object/library modules:" if not already there (which it should be for all example programs).
   
   
4. From the main menu, choose "Build", then choose "Rebuild All" .
   
   
5. After compiling the program, copy it to the your Win/CE machine using ActiveSync where it can be executed. You can copy the program executable to any Win/CE directory that you choose.

3 Example Programs

3.1 MGCVER

The first example program is the MGCVER ("MGC Version") program that displays the MGC library version number.

MGCVER ("WSC Version") displays the version, build number, and registration string from MGC32.DLL. Run this program to verify that MGC32.DLL can be loaded by Win/CE at runtime and also to check the MGC version and build number.

3.2 LATLON

LATLON is an example program that continuously displays latitude and longitude from your GPS receiver.

3.3 RAW

RAW is an example program that displays all incoming NMEA sentences.

This is a good program to use to check what types of incoming NMEA sentences you are receiving from your GPS receiver.

3.4 GPGGA

GPGGA is an example program that displays all incoming NMEA GPGGA sentences from your GPS receiver.

3.5 GPRMC

GPRMC is an example program that displays all incoming NMEA GPRMC sentences from your GPS receiver.

3.6 GPGLL

GPGLLC is an example program that displays all incoming NMEA GPGLL sentences from your GPS receiver.

[Example program not in initial release].

3.7 GPGSV

GPGSV is an example program that displays all incoming NMEA GPGSV sentences from your GPS receiver.

[Example program not in initial release].

3.8 COMPUTE

COMPUTE is an example program that computes great circle distances and bearings from a pair of latitude/longitude values.

3.9 COMPUTE2

COMPUTE2 is an example program that coverts latitude (or longitude) between (deg, min, min/1000), (deg, min, sec), and single integer encoding.

4 Revision History

Version 1.2.2: August 26, 2003.

• The initial release of MGC4eVC, based on version 1.2.2 of the desktop version (MGC4C).