Building the MIDlet

Requirements

Sun's Wireless Toolkit, version 2.2
Antenna, version 0.9.13
Proguard, version 3.5
Ant, version 1.6.5

Settings

Configure the following settings in etc/goooops.properties:

gps.receiver.url: the connection string for your GPS device. The MIDlet doesn't attempt Bluetooth service-discovery because my device isn't discoverable. (Also in principle there is no reason which this has to be a Bluetooth URL: if your device is accessible over TCP/IP you could use a socket:// URL instead.)
gps.channels: the number of satellite signals your GPS device can receive simultaneously.
gps.midlet.maps: the directory on your MIDP device in which to store downloaded maps. (This implies you have JSR75, the file-connection API; if you do not, you must modify the MIDlet to use the RmsMapCache class instead of FileMapCache.)
gps.coordinate.mapper: the class which maps coordinates into, er, maps. (Currently only Googler2 makes sense, the original mapper no longer applying. Consider writing one for another map provider, or even Google's satellite images.)

The Ant-build-file, build.xml, assumes the existence of a package repository in which the above packages reside. The root of this repository is determined from the environment variable, PACKAGES. (It also contains targets for building various Personal Profile programs, which use the code here but are not released under an Open Source license. More information about these programs may be found here.)

Software Organisation

This program evolved over the course of about a year's worth of spare time from almost nothing. The original codebase was non-CLDC, i.e., Personal Java, Personal Profile, J2SE and ran on a Sharp Zaurus. The org.syzygy.gps package contains beans and interfaces common to both platforms while the org.syzygy.gps.midp package contains MIDlet-specific code to display the information on a Limited, Connected Device's screen.

All code is distributed under the terms of the GNU GPL.

NMEA Sentence Parsing

Standard NMEA sentences recognised are:

GGA. Fix Information.
RMC. Recommended Minimum C.
GSV. Satellites in View

Fetching and Caching Maps

Two cache implementations for storing map images are provided for CLDC:

FileMapCache: if your target device has the file-connection API you are in luck, this is the default cache used in the MIDlet.
RmsMapCache: this cache uses the basic Record Management System of CLDC. To use this (which you should only do as a last resort) you must edit WhereMIDlet.java and instantiate it instead of FileMapCache.

(Neither of these caches is bounded --- this should be fixed. However I'm not in a hurry to do this because my phone has 1GB of flash memory!)

Plotting Position on a Map

Plotting the correct position on a map requires calculation of the Gudermannian function. As I understand it this describes the Mercator projection of a point on a sphere onto a cylinder. (This projection is referred to as "equal-area", I believe because the surface area of a sphere (radius r) and the area of the vertical part of a cylinder (radius r, height 2r) are equal. This is what is known as "developing" the sphere onto a cylinder in technical-drawing parlance: visualise wrapping the sphere with the cylinder and you get the idea.)

Unfortunately the Gudermannian requires transcendental functions which aren't available in CLDC's java.lang.Math so power-series approximations are provided, which I am amazed I remembered from College.

To Do

Please feel free to help with these! Also suggest more features!

Investigate waypoints: add functionality for processing the WPL and AAM sentences.
Add bounds-checking to the map caches.
Use other sources of Map data (implement CoordinateMapper).

Download

If you've read all of the foregoing, I suppose you'd better download the code

Last Updated: Sun Jul 16 12:33:00 IST 2006 jscrane at gmail.com