JavaGPS Readme

Introduction

The JavaGPS package enables Java applications to talk to attached GPS devices that conform to the NMEA0183 protocol.

JavaGPS has the following features:

Auto-detection of attached GPS device
Recording and playback of GPS data
Supports raw GPS logs and has an optimised log file format. JavaGPS converts between the two formats on the fly.
VRMI (WhereAmI) API
Supports trigger callbacks based on time (i.e. every 5 seconds, user does not move for 60 seconds) or location (i.e. if user enters or leaves a given region).
Management GUI
Displays current location in a map, GPS can be set up, log records can be started or logs can be played back and traced graphically.

System Requirements

Operating System: any that supports Java
Java: JDK or JRE Version >= 1.2 (http://java.sun.com)
Java Communications API (http://java.sun.com/products/javacomm/)

Note: In order to be able to communicate with an attached GPS over a serial port, the Java Communications API is required. Otherwise, you can only use the simulation features (or replay logfiles), and you will get the following warning on stdout:

Warning! *** Cannot access GPS

Distribution

The JavaGPS distribution file contains the following files and directories:

File: run.bat (Win32), run.sh (Unix shell script)	This file is used to start up the GPS driver and management GUI. Starts org.iu.gps.MapView
Folder: gpsdata	The gps user data files (GPS logs, GPS positions, GPS configuration files, map images) are stored within this subdirectory. The root directory must be visible in the CLASSPATH.
File: javagps.jar	This Java Archive contains all Java class files necessary to run JavaGPS.
Folder: org/iu/gps	Contains all JavaGPS source files. For detailed information, look at the JavaDoc documentation available in the javadoc folder.
Folder: javadoc	Contains JavaDOC documentation of the JavaGPS org.iu.gps classes.

Running the JavaGPS GUI

Use the run.bat (Win32) or run.sh (Linux) script to start the JavaGPS GUI. The GPS driver reads its configuration from the file gps.cfg (in folder gpsdata), if gps.cfg does not exist, it enumerates all serial devices and tries to find a GPS device on one of these serial lines. If no GPS device can be detected, a default gps.cfg will be created and used in subsequent startups.

Then the GUI comes up (note that the initial location is read from file gpsdata/default.gpspos):

The GUI has the following components:

- map display area: A bitmap of the current location (if available) will be displayed, otherwise the map for the current location is retrieved from the www.shellgeostar.com site (therefore, it only works with WWW access; otherwise, an error message will be shown in stdout after timeout of 60 seconds).
If you click within the map area, the user’s location will be set to the location you clicked on (Follow GPS must be disabled).
If you want to simulate a movement, do a right-click on the destination location. The following message box comes up:

To use the currently selected speed (3.0 meters/second in the example), just click “Simulate” and the movement starts. If you want to change the speed, click on “Setup” and adjust the setting. If you want to set the location without moving, click on the “Set w/o Sim” button, or cancel the operation by clicking the “Cancel” button.

- N/S/W/E buttons: clicking these buttons will move the map to the appropriate position.

- Follow GPS: if you enable this checkbox, it will display the current position from the GPS device. Additionaly, a new window pops up that displays the GPS fields as retrieved from the GPS device. IMPORTANT: you cannot set the user’s location or simulate movements if this is enabled.

- In/Out: Use to zoom in/out of the map.

- Compass: Displays the user’s heading. Can also be used (if Follow GPS disabled) to set the user’s heading.

- Long/Lat and Gauss-Krüger: Numerical display of the current position, in latitude/longitude and Gauss-Krüger coordinate systems. You can also change the values within these fields (if Follow GPS is disabled)

Description of Application Menus:

File
- Load Position:
  load a location from a .gpspos file
- Store Position:
  save the current location (and map display settings) in .gpspos file
- Exit: guess what ;)
GPS
- Setup GPS Receiver:
  setup the GPS serial line settings
- Log GPS data to file:
  log the GPS device reportings to a .gpslog file
- Disable logging:
  stop GPS logging into file
- Replay GPS log:
  replay a previously logged .gpslog.
  NOTE: this simulates a hardware GPS device, therefore, to be able to view the currently replayed location, you have to activate the “Follow GPS” checkbox
- Stop GPS log:
  stops the replay (this menu item only appears during replay)
Coordinate Settings:
Sets the earth datum of the GPS device.
Default: WGS84