More about how to use GPSKit for Real Studio

While I was completing the GPSKit documentation, I felt like I may share the some bits of it on this blog. I hope you'll find them useful and feel free to leave a comment if you wish to.
Just as a reminder, GPSKit 1.0beta2 is downloadable here.

The design of GPSKit.

GPSKit is based on a separation of tasks design. They are 4 layers of them:

1. The first layer is the hardware connection. It gets the data from the GPS device and spit out valid chunks of data 'tokenized' according to the protocol specifications. It's the zdGPSDataProvider interface.
2. The second layer is the data validator and parser. It receives the tokens from the zdGPSDataProvider, check their validity and turn each of them into an object that represents the GPS raw data in a more human understandable way. It's the zdGPSDataListener interface .
3. The third layer is a GPS fix factory. It uses the objects instances provided by the zdGPSDataListener to create a zdGPSFix instance and make it available to the entire application. it's the zdGPSFixProvider interface.
4. As in any I/O protocol, errors may happen, so there is a fourth layer that will handle these errors and perform the actions needed in such case. It's the zdGPSErrorHandler interface.

In order to know where to send the data, the zdGPSDataListener needs to say hello, 'to register' itself to the zdGPSDataProvider. As the zdGPSFixProvider is meant to be implemented within the same class as the zdGPSDataListener, there is no need to register it. However, it isn't mandatory for the zdGPSDataListener to implement the zdGPSFixProvider as some protocols may not provide geolocation information.

Currently, only the NMEA 00183 protocol via a serial port is available in GPSKit. For this format, the zdGPSDataProvider layer is implemented by the zdNMEASerial class. The zdGPSDataListener and the zdGPSFixProvider are both implemented by the zdNMEAParser. The zdGPSErrorHandler is implemented by the zdGPSDeviceConnection.

Getting started.

If you need to get the geolocation data provided by the GPS device connected to a serial port, you'll have to create a data provider, a data listener that is also a fix provider, register the listener to the provider, store the references to all these class instances and finally open the connection. Fortunately, zdGPSDeviceConnection is here to automate this process. It implements a method with the following syntax:

  Sub BuildSerialConnection( _
        inProtocol As zdGPSDeviceConnection.Protocol, _
        inSerialPort As SerialPort)

Where inProtocol is one of the value of the zdGPSDeviceConnection.Protocol ('UserImplemented' and 'NMEA0183' are the only currently available values), and inSerialPort is the SerialPort instance the GPS device is connected to. It will handle the serial settings depending on the protocol specifications (e.g. 4800 bauds, 8N1 for the NMEA 0183).
Note: The 'UserImplemented' protocol is currently used for internal testing purpose only. This may change in a future release.

So to build and open a connection, proceed as following:

  Dim theConnection As New zdGPSDeviceConnection

  theConnection.BuildSerialConnection( _
        zdGPSDeviceConnection.Protocol.NMEA0183, _
        System.SerialPort( 0 ) )

  If theConnection.Open Then
    MsgBox "Connection is open"
  Else
    MsgBow "theConnection failed to open"
  End If

Of course, you'll have to adapt the code depending on the serial port you are using and set your GPS device interface type to 'NMEA 0183'.

If the connection is successful, you can access the

  zdGPSDeviceConnection.NMEAParser.GetLatestGPSFix() As zdGPSFix

to get the geolocation data. Don't forget to test for 'Nil' before using the returned reference.

Something you should be aware of.

The BuildSerialConnection() method will raise a zdGPSKitException if the passed serial port reference is 'Nil' or if the chosen protocol is 'UserImplemented'. In both cases, the Message property content explains, in english, why the exception has been raised.

Why using a more complicated design when a single class handling all the data processing would have been simpler?

While the format of data may be the same (e.g. NMEA 00183), the type of hardware connection may be different depending on the GPS device you're using (e.g. serial port, USB, even TCP/IP). So to avoid duplicate code for each connection type, a multiple layering with interfaces was chosen. Actually, the first reason was to allow the testing of the code by using a file that simulates the input of serial data. A little application, developed with Real Studio, was used to record the data coming from the GPS device along with the timing information to a binary file while driving a car. Back to the IDE, A class implementing the zdGPSDataProvider interface was used to replay the flow of data with the same timing. The application and the replay class are not included in the current release because they really can use some refactoring, but may be in another release...

How GPSKit was developed.

Two Garmin GPS receivers are used to develop GPSKit: A GPS 72 and an eTrex H. A Nokia Navigator 6110 cell phone was also used via Bluetooth as well as some serial data from a Garmin Rhino 130 and a GPS III previously recorded to binary files.

The code was written and tested with Real Studio 2009r4 ( Enterprise edition ) on a MacBook 13". A HP nw9400 laptop and a Acer Aspire One ZG5 notebook are used to test on Windows XP. The Acer notebook is equipped with A 32GB SSD disk and is mostly used to record the GPS serial data when driving a car.

One more thing...

Doing something else than driving when your vehicle is moving is very dangerous. Always park your vehicle safely before using a GPS device, a computer, a cell phone or any other kind of stuff that needs at least one of your hands and draws your attention away from driving or riding.