Mateusz Loskot :: hacking on, working out, living up

A first glance at the GPS API in Windows Mobile 5.0

07 Jan 2006 | mloskot

Windows Mobile LogoIn the middle of 2005 Microsoft introduced new Windows Mobile 5.0. This is the next generation of Windows CE platform. It was prepared to provide access to new features of latest mobile devices such as better multimedia support, better screen with 2D & 3D drawing capabilities, integration with cameras as well as integration with Global Positioning System. More and more mobile devices appearing on the market are equipped with GPS receiver, built-in or as an attachment.

Update: Today, I published this article on Pocket PC Developer Network. Thanks to Joao Paulo Figueira for encouraging me to do it.

There are many aspects involved in accessing GPS capabilities, so developers need to solve quite complex problems: communicating serial port, parsing NMEA sentences and running separate threads. So, latest Windows Mobile 5.0 brings dedicated API for accessing GPS receiver in more straightforward way. It is called GPS Intermediate Driver (GPSID). Let’s take a closer look at it.

Internally, GPSID is a common device driver. From user’s point GPSID is, as you may guess, a kind of glue - intermediate layer - between GPS hardware and client application accessing GPS. GPSID is the first step to unify access to all GPS receivers by indirection.

Among others, the main advantages is that the same code will work with any GPS hardware. Second advantage is that GPSID allows multiple applications to query GPS at the same time. It seems like cloning hardware virtually. Third, GPSID will parse NMEA sentences for you, so you can obtain GPS position (and more) by simple API. Nice, isn’t it :-)

Along the new APIs, GPSID provides access to GPS hardware using old-good serial API. Shortly, there are two GPS access modes: Parsed Mode - fully based on the GPSID API and Raw Mode - in which you can access GPS data using well known CreateFile, ReadFile, etc.

Using GPS Intermediate Driver you are able to access internal GPS device or attached to one of mobile device I/O ports. In order to be able to work with wide range of GPS receivers GPSID is very configurable by dedicated registry settings. For more information follow this link GPS Intermediate Driver Registry Settings

Note: Currently, GPS Intermediate Driver API targets native developers, but managed version is planned.

After the short introduction to GPS Intermediate Driver coming with Windows Mobile 5.0 I’d like to walk through GPSID API calls and see what we can do with this stuff. I also suggest you to take a look at the API reference manual.

First two functions create and close connection do the GPS Intermediate Driver: GPSOpenDevice and GPSCloseDevice. Next function is called GPSGetDeviceState which takes a pointer to a GPSDEVICE_ structure. This function allows you to retrive detailed information about the GPS hardware. You can query for e.g. GPSID state, hardware state, UTC time indicating when last data was received from GPS and GPS hardware identifications.

Now, let’s look at the most interesting function called GPSGetPosition. As you may guess, it retrieves GPS location information. GPSGetPosition takes four parameters:

DWORD GPSGetPosition( HANDLE hGPSDevice, GPS_POSITION* pGPSPosition, DWORD dwMaximumAge, DWORD dwFlags );

  • hGPSDevice - Handle to GPS Intermediate Driver returned by GPSOpenDevice

  • pGPSPosition - Pointer to a GPSPOSITION_ structure

  • dwMaximumAge - Maximum age of information you want to retrieve, in milliseconds

  • dwFlags - Flags, currently must be set to 0

Most interesting parameter is pointer to a GPSPOSITION_. This structure contains so called GPS data. It’s a combination of parameters retrieved from NMEA sentences retrived and parsed by GPSID, and finally returned in user friendly form of GPSPOSITION_ structure.

Because most of us usually works with NMEA protocol directly (at least till now, when we get GPSID), thus I’ll try to explain GPSPOSITION_ members in relation to NMEA sentences. Certainly, I recommend you to visit MSDN for reference too.

So, let’s walk through GPSPOSITION_ members one-by-one:

  • stUTCTime

Universal time according to Global Positioning System. NMEA sentence: $GPGGA and $GPGLL.

  • dblLatitude

Latitude of position of GPS user. NMEA sentence: $GPGGA and $GPGLL.

  • dblLongitude

Longtitude of position of GPS user. NMEA sentence: $GPGGA and $GPGLL.

  • flSpeed

Speed of moving, in knots. NMEA sentence: $GPRMC or $GPVTG.

  • flHeading

Direction in which GPS user is moving, in degrees units with respect to true north. NMEA sentence: $GPVTG.

  • dblMagneticVariation

Angle between the direction (bearing) to an object and a reference direction which is magnetic North. NMEA sentence: $GPVTG.

  • flAltitudeWRTSeaLevel

Altitude with respect to sea level, in meters. NMEA sentence: $GPGGA.

  • flAltitudeWRTEllipsoid

Altitude with respect to WGS84 ellipsoid, in meters. NMEA sentence: $GPGGA.

  • FixQuality

Value indicating quality of the GPS fix, which may be unknown, achived with utiliation of GPS or GPS + DGPS stations. NMEA sentence: $GPGGA.

  • FixType

Indicates how many satellites were used to calculate user’s position: 2D - three satellites or 3D - four or more satellites. NMEA sentence: $GPGSA.

  • SelectionType

This value relates to FixType and says whether 2D or 3D mode is selected automatically or manually. NMEA sentence: $GPGSA.

Next three parameters describe constellation of satellites used to determine a position and they need longer explanation. This group of values is called as Dilution of precision (DOP) and every value has it’s own name and meaning.

  • flPositionDilutionOfPrecision

Position Dilution Of Precision (PDOP). NMEA sentence: $GPGSA.

  • flHorizontalDilutionOfPrecision

Horizontal Dilution Of Precision (HDOP). NMEA sentence: $GPGSA or $GPGGA.

  • flVerticalDilutionOfPrecision

Vertical Dilution Of Precision (VDOP). NMEA sentence: $GPGSA.

  • dwSatelliteCount

Number of satellites used to determine user’s position. NMEA sentence: $GPGSA.

  • dwSatellitesInView

Number of satellites in view of GPS antena. NMEA sentence: $GPGSV.

Next four members represent arrays with number of elements equal to GPSMAX_SATELLITES_ constant. GPSMAX_SATELLITES_ indicates maximum number of GPS satellites used by the GPS Intermediate Driver.

  • rgdwSatellitesUsedPRNs

Array of Pseudo-Range Noise numbers of satellites used to obtain position. Every satellite has its own unique PRN number which is an identifying signature of signal transmitted by each GPS satellite. PRN number is used to identify the particular satellites used to arrive at a position solution. NMEA sentence: $GPGSV.

  • rgdwSatellitesInViewPRNs

Array of Pseudo-Range Noise numbers of satellites in view of GPS antena. NMEA sentence: $GPGSV.

  • rgdwSatellitesInViewElevation

Aray of elevation values for all satellites in view, in degrees, 90 is maximum. NMEA sentence: $GPGSV.

  • rgdwSatellitesInViewAzimuth

Array of values of azimuth from true north for all satellites in view, within range from 000 to 359. NMEA sentence: $GPGSV.

  • rgdwSatellitesInViewSignalToNoiseRatio

Array of values of Signal to Noise Ratio (SNR), also called as signal level, measured indB (0-99). NMEA sentence: $GPGSV.

Unfortunately, I don’t have any device running Windows Mobile 5.0 as well as I don’t have Visual Studio 2005, yet. So, I’m not able to present any working and interesting piece of code but I believe in the near future I will provide some.

I’m strongly curious what are your impressions about GPS Intermediate Driver, its performance and usability. So, I’m looking forward your comments.

References

What’s new for developers in Windows Mobile 5.0 by Jim Wilson

A View of Windows Mobile 5.0 from 10,000 Feet by Jim Wilson

All About GPS by Trimble

GPS World magazine

Fork me on GitHub