Chaeron GPS Library - Version 1.02

02/20/2003


Introduction

This library (and sample programs) provide a high level interface to GPS (Global Position System) devices . It provides an event-driven, listener model that is simple to use (relative to doing all the serial I/O and packet parsing for different protocols) and abstracts the events/values that are passed back to be independent of the GPS device and protocol being used (so far NMEA and Garmin protocols).

The GPS library and sample programs will run unchanged and have been tested on the following platforms (it should run unchanged or with only minor modifications on other Java-capable platforms like Sun/Solaris, Linux, Apple Macs, PocketPCs, etc., though these have not been tested). We will be glad to port/test to a specific platform if you provide the appropriate hardware):

Hardware Platform Java VM GPS Unit Connection Comments
Windows PC Standard JVM Garmin eTrex Summit (ver 2.40) Serial Cable  
Palm PDA Jump/WabaJump or SuperWaba Garmin eTrex Summit (ver 2.40) Serial Cable Jump is the faster platform (5x or so)
Palm PDA with Bluetooth SDIO card Jump/WabaJump or SuperWaba Emtac Bluetooth GPS Bluetooth 1.1 Wireless No cables! ;-)
Systronix SaJe/JStamp/JStik, etc. aJile Embedded Java development kit (Java on a chip) Garmin eTrex Summit (ver 2.40) Serial Cable Support for aJile platforms is not included in this distribution. Please contact us if you are interested in running the Chaeron GPS Library on the aJile platform.
PocketPC SuperWaba N/A Serial Cable or Bluetooth Not Tested (but should run fine)
Linux Standard JVM N/A Serial Cable Not Tested (but should run fine)

The code base makes heavy use of compile time flags (static finals in com.chaeron.GPS.Compile.java) to allow you to selectively enable/disable functionality and thus reduce memory footprint of the executable. Defaults are to include all functionality. For example, you can disable specific protocols (eg. disable Garmin if you don't have a Garmin GPS receiver), disable specific NMEA sentences, or specific functionality (eg. Waypoint, Route or TrackLog downloads). You need to rebuild to take advantage of this feature.

This code is being released as open source under the GPL license. Other licenses are also available for commercial (ie, non-GPL'ed, non-open source) use of this library. Please contact the author for if you wish to discuss license arrangements for commercial use of this library. We can also create custom versions to support unique requirements (specialty GPS hardware, custom/reduced API, etc.). See end of this document for conditions and other legalese.

NOTE to prior users of the Chaeron GPS Library: As of the 1.00 release, the distribution directories have been restructured, and ANT is now used to build and run the demos. Best to install in a clean location and review the directory and build changes. This should make it a lot easier for me to maintain, and for others to use (and build if necessary) the library on different platforms such as Linux and Macs.


Contents of this archive

Filename/Directory Description

readme.html This file
history.html The version history for the Chaeron GPS Library
license.txt GPL license under which this code is made available
build/classes Contains the compiled Chaeron GPS library classes.
build/doc a directory containing javadocs
build/lib Chaeron GPS library jar files (common & platform-specific, see Caveats!)
build/bin/palm/jump directory for GPSDemo PalmOS Jump executables
build/bin/palm/superwaba directory for GPSDemo PalmOS SuperWaba executables
src/common Source code for the Chaeron GPS Library and demo program
src/platform Platform specific Chaeron GPS Library source code
build.xml ANT build file (also used to run PC/JVM demo)
config-build.properties Custom properties for ANT build file (eg. classpaths, directories)


Installation/Usage Instructions

Unzip this archive into your favorite place, making sure you preserve/restore subdirectory names.

There is a GUI-based demo program called GPSDemo provided that runs on a PC (JVM) on on a Palm (Jump executable). There is also a test program provided (in the src directory). This demo allows you to dynamically pick whether your GPS is in NMEA or native Garmin mode. Note that you cannot download Waypoints/Routes/TrackLogs in NMEA mode.


Running the GPSDemo example program:

You can find pre-compiled versions of the sample programs for PalmOS and Windows as follows:

Sample Program Platform Location Filename(s) Comments
GPSDemo Palm/Jump build\bin\palm\jump GPSDemo.prc Standalone PalmOS executable. SEE Caveats below!
GPSDemo Palm/SuperWaba build\binpalm\superwaba GPSSWaba.prc/pdb Requires SuperWaba 3.3 VM intalled on Palm
GPSDemo PC\JVM build\classes ant demo Needs JVM, Waba & WabaExtras installed on PC (edit paths in config-build.properties file to match installation locations)

Default COM ports for the demo/test programs are COM2 for Windows, dev/ttyS0 for Linux and COM0 (default) for PalmOS.

To run the demo on a Windows machine, once you have ANT installed, type: ant demo from the directory where you installed the Chaeron GPS Library.
To run the demo on a Linux machine, once you have ANT installed, type: ant demo-linux from the directory where you installed the Chaeron GPS Library.
To run the demos on a Palm PDA, install either the Jump and/or SuperWaba executables provided in the distribution on your PDA and just tap on them.

Entering a Serial Port value of "bluetooth" or "bt" in the GPSDemo application on a Bluetooth-enabled Palm PDA will attempt to connect to a bluetooth-enabled GPS that supports the BT Serial Port Profile (SPP), such as an Emtac CRUXII/BTGPS device.

 

You will need the following prerequisite packages:

NOTE: Read the installation instructions for each package carefully. I will NOT provide any support nor answer any inquiries on the installation nor use of these prerequisite packages under ANY circumstances.

To run the demo program on a PC/JVM or to rebuild any of the code:

Ant You need the Apache Jakarta ANT tool to run the PC demo or to build the code


To use the GPS library with your own code (no GPSDemo program):

On a workstation (eg. Win/Linux using a normal JVM)

build/lib/gps_common.jar The common Chaeron GPS Library classes
build/lib/gps_windows.jar The Windows platform-specific Chaeron GPS Library classes
javax.comm.* You need the comm.jar file for windows-based access to serial ports from Java (or the Linux equivalent)

On a PalmOS PDA device (native executable, using Jump):

build/lib/gps_common.jar The common Chaeron GPS Library classes
build/lib/gps_jump.jar The PlamOS/Jump platform-specific Chaeron GPS Library classes
Jump distribution You will need Jump 2.0 since the new SerialPort code (since 0.98 beta) depends on that release.

On a PalmOS PDA device (using SuperWaba):

build/lib/gps_common.jar The common Chaeron GPS Library classes
build/lib/gps_superwaba.jar The PlamOS/SuperWaba platform-specific Chaeron GPS Library classes
SuperWaba VM Used to provide JVM on Palm platform (PocketPC not tested yet)

 

To rebuild the GPSDemo program, in addition to core GPS Library and ANT prerequisites above, you also need:

On a workstation (eg. Win/Linux using a normal JVM)

Waba class libraries Note: You can use the normal JVM. WabaVM is not needed, just the classes.
WabaExtras class libraries Used for UI functions

On a PalmOS device (native executable, using Jump & WabaJump):

WabaJump classes Used to provide Waba UI Class library support in Jump
WabaExtras class libraries Used for UI functions

On a PalmOS device (using Superwaba):

WabaExtras class libraries Used for UI functions

If you are rebuilding any of the library code, just type ant from the directory where you installed the Chaeron GPS Library, and it will display a list of build targets for you.

The following software versions were used by the author:

GPSml XMLSchema version 0.50 (for XML output)
Jump 2.1.4 - Peter Dickerson's optimized Jump code, using Huge Memory Model, new Memory Manager and the latest Peephole Optimizer...thanks Peter!
WabaJump beta 0.6
WabaExtras 1.30
Waba 1.0 class libraries (Palm VM not used)
SuperWaba 3.4 (will not run on versions earlier than 3.3)
Apache Ant version 1.5.1

My testing has been done with a Garmin eTrex Summit running version 2.40 software. This library may or may not run correctly with other Garmin devices at this time. Please email me with any issue/problems so I can add support for other Garmin GPS units. It has also been successfully tested with the Emtac Bluetooth-enabled GPS unit, in NMEA mode, with the demo program running on a Bluetooth equiped (SDIO card) Palm M505 PDA.

You will need correct GPS cables (and null modem adapters) to make this work (or you can change the test programs to use static strings as input (look at the source...sample NMEA stuff is already in there). I have found that using the TAL Serial Port Breakout Box software in the middle (if you have a 2nd PC around with two serial ports) can be very useful to ensure that you are getting output from your GPS and to debug the strings coming in (free at www.taltech.com), but be careful, since the breakout software can buffer input when you least expect it.....and not send it through right when it should. Best to always also test with a direct connection if you run into funny lockups because data was not coming down the serial line.

If you are running an overclocking accelerator app/hack on your Palm (eg. Afterburner) you might have to slow it down or even disable it to get proper operation of the serial port!


Development Notes

This code was built using Sun's JDK 1.4.1 on a Win2000 SP2 platform. The JPadPro editor/IDE (www.modelworks.com) was used to develop all of the code from scratch. 4 space indents are used...if the code does not line up nicely, be sure you have 4 space indentation set in your editor.


Future Enhancements (In no particular order)

1) Refactoring and rationalization of the GPS events that are propagated
2) XML wrappers (decorators) for all other GPS events (ie. real-time, non-download events).
3) Simulation of GPS data. That is, log to/read from a file (for NMEA sentences and Garmin Packets)
4) Constants for Waypoint Classes, Colours, Display Type, Symbols with common values across GPS Device types
5) Support for the uploading (waypoints, tracks and routes) to Garmin GPS's.
6) Better/more documentation
7) Native support for other GPS units (besides Garmin and NMEA).
8) Ability to upload maps for Garmin GPS's.
9) Support for other industry protocols, such as: Motorola Binary, Trimble TSIP/TAIP protocols, etc.
10) Geoid and other co-ordinate transformations (probably a separate package)
11) Support for SiRF binary message formats
12) Change demo program to use a different UI library (possibly the MIDP LCDUI classes).
13) Whatever the general consensus is as to what the library needs.

Version History can be found in the history.html file included in this distribution.


Caveats

1) When building your application or running code, your classpath should have the platform-specific Chaeron GPS Library classes before the common ones. For example, the gps_windows.jar file should come before gps_common.jar in your classpath under Windows!

2) The current PalmOS/Jump config-build.properties file uses the Huge (-hw flag) Jump memory model by default, and I have successfully downloaded over 1100 Track Log points on my M505 without any difficulty. Response seems to get quite sluggish at times when you use this much memory however. I would not recommend that you manage huge numbers of Waypoints or Track Log Points on a Palm device. If you want to change this, change the config-build.properties file to use the large model (-mw flag) and rebuild the demo Jump program!

3) In the interests of getting this library out to those that could benefit from it, the documentation on how to use the library is a bit slim right now. Your best bet is to read and understand how the sample program works. Looking at GPSDemo.html in the javadoc subdirectory is a good place to start.

4) If you are running an overclocking accelerator app/hack on your Palm (eg. Afterburner) you may have to slow it down or even disable it to get proper operation of the serial port! It works fine on my overclocked M505 with afterburner.

5) Slow Palm units may not be able to keep up with the GPS data stream, which can cause the parsing process to generate error events. I run an overclocked M505 for my testing and am not sure whether the slower Palm III's will be able to keep up. This can also cause problems if you are connected over a Bluetooth virtual serial port, since the connection can drop if it takes too long to process everything during a poll() invocation. This can be mitigated by setting compile-time values for packet and/or GPS event queues to balance workload per poll() invocation versus polling interval (see comments in the Compile.java file for details).

6) Play with the packet/sentence parsing code at your own risk. This is very complex and intricate code that can be broken easily

7) Waypoint attribute types (Class, Colour, Symbol, etc) will not necessarily be consistent across different Garmin GPS's at this time. This may be rectified in a future release.

8) Downloading large quantities of Waypoints, Routes or Track Logs (especially Tracks since they can easily consiste of thousands of points each) may cause you to run out of memory on PalmOS devices if you use the Large (-lw flag) Jump memory model. I can get a few hundred Track Points downloaded on my M505 with the Large model before it runs out of memory and forces a reset.

9) SuperWaba (V3.3 or later) is supported, however, it runs a lot slower on a Palm than the Jump version. The original Waba VM is no longer supported since it cannot handle the size of the library and sample program executables.

10) This library is currently NOT thread-safe!

11) Saving collections of Waypoints/Routes/Tracklogs can take a long, long time on a Palm PDA at the moment! Not recommended that you save tracklogs on a Palm (since they are typically rather large). This might be a problem with the Jump garbage collector, since I have noticed that once you download a large amount of track points, things seem to slow down a lot, with 5 second delays not uncommon, every few track points (which leads me to believe the gc() is the culprit). Took over 15 MINUTES to save about 1100 track points on my overclocked M505!


Support

We will ABSOLUTELY not provide any support/assistance/guidance for Java, Jump/WabaJump or ANT issues. If you cannot figure out how to install/use these JVM's and utilities, then you should not be messing about this this library.

That being said, for all other issues that relate to the GPS Library, feel free to mail the author about any issues/bugs/suggestions you have with the GPS Library code.

We are able to offer a priority development services for the Chaeron GPS Library. If there is a feature or customization that you urgently require to have incorporated in the Chaeron GPS Library, Chaeron can be engaged to make such changes on a fixed-rate, daily basis under the following terms:

- source code will be released to you under the terms of the GNU GPL (the Chaeron GPS Library);
- copyright in the source code will be retained by Chaeron Corporation.
- fixed price quotes can be given for short or very well specified projects.

Contact us for rates and availability.


Disclaimers

MAKE SURE YOU BACKUP YOUR PALM before using any of the demo programs on a PalmOS PDA.

This code is provided as a public service . Use at your own risk. Andrzej Jan Taramina and/or Chaeron Corporation makes no representations as to the useability of this code and will accept no responsibility for any damages arising from the use of this code, no matter how caused.


Brought To You By

This GPS library has been brought to you as a public service by:

Andrzej Jan Taramina
Chaeron Corporation
email: andrzej "at" chaeron "dot" com

If you make any useful changes or additions to this GPS library please email copies back to the author so that they can be incorporated in the official distribution. Credit for such additions will be retained in the source and the archive.


License & Copyright Information

Copyright (c) 2001-2003 Chaeron Corporation, All rights reserved.

Chaeron grants you a non-exclusive license to use, modify and re-distribute this program under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version, provided that this copyright notice and license appear on all copies of the software.

Other licenses are also available for commercial (ie, non-GPL'ed, non-open source) use of this library. Please contact the author for if you wish to discuss license arrangements for commercial use of this library. We can also create custom versions to support unique requirements (specialty GPS hardware, custom/reduced API, etc.)

Software is provided "AS IS," without a warranty of any kind. ALL EXPRESS OR IMPLIED REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE HEREBY EXCLUDED. THE ENTIRE RISK ARISING OUT OF USING THE SOFTWARE IS ASSUMED BY THE LICENSEE. See the GNU General Public License for more details.

CHAERON AND ITS LICENSORS SHALL NOT BE LIABLE FOR ANY DAMAGES SUFFERED BY LICENSEE OR ANY THIRD PARTY AS A RESULT OF USING OR DISTRIBUTING SOFTWARE. IN NO EVENT WILL CHAERON OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR DIRECT, INDIRECT, SPECIAL, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES, HOWEVER CAUSED AN REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF CHAERON HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

If you make any useful changes or additions to this GPS library please email copies back to the author so that they can be incorporated in the official distribution. Credit for such additions will be retained in the source and the archive. Any/all such submissions, if they are incorporated in the official distribution, will become the exclusive copyright and property of Chaeron Corporation.