readme

qt gps ,linux redhat9.0,

This is the GPS moving-map display program, written by Mike Banahan
([e-mail]). If you want to mail me about it you are welcome
to do so but this is a free-time project, written for my personal use,
taking the lowest of low priorities. I'm not able necessarily to reply
either at all or rapidly.

It is written for and compiled for recent versions of Linux.
It should easily be compiled for most other Unix systems that support
the Qt widgets and with some modest effort should also be portable to
Windows (a task I have *no* intention of undertaking). Porting to Windows
systems ought to involve only arranging for its serial port handling
to be implemented.

USE THIS PROGRAM AT YOUR OWN RISK. IT IS NOT WRITTEN FOR USE IN SAFETY
CRITICAL OR OTHER IMPORTANT APPLICATIONS. I just use it in my car to
make sure I haven't taken wrong turnings.

INSTALLATION

After unpacking the tar file (if you are reading this you have done
that already) you will find a binary called 'gps'. For this to run you
will have to have X up and running, the usual set of run-time libraries
for Linux AND the Qt run-time support. On my system this library is libqt.so.1
located at /usr/lib/libqt.so.1. If you have installed KDE or any other
Qt-based programs you should have this already. The tarfile includes a copy
of the library just in case; if you don't already have it then move the
untar-ed version to /usr/lib and all should be well. I have done this once
only so I don't warrant that it will work for everyone.

SETUP

The program supports simultaneously the Latitude/Longitude 
coordinate system and the British Ordnance Survey NGR system.
Since I live in the UK this is important to me. I am not a
geometer nor a cartographer - errors may be present in the way that
locations are converted to screen coordinates but I'm not aware of
anything drastic yet.

The program seems to work well within the UK but in particular it's not likely
to work well at latitudes approaching +/- 90 degrees. If you live in or travel
through the Polar regions you will need to use something else or run this program
just for the entertainment value. The lat/long -> NGR conversion code
was transcribed from Ordnance Survey documentation to the best of my
ability.

For the program to run, you will need to provide it with maps and two
configuration files. These live in the 'maps' directory.

Maps can be bitmaps (.bmp), gifs, jpegs or any other file format that the
Qt QPixmap widget can handle automatically. I have only tried it with
.bmp files since my maps database was originally created under Windows
using Paintshop Pro. I scan maps in, squash them down to 16 colours to
reduce their space requirements and then enter their details into the
maps description file 'maps.dat'. The comments at the head of this file
describe its format and there is one example provided. Each line that isn't
comment looks like this:
	bfdos.bmp:1275:1656, 86, 101, se 100 390, 1169, 1623, se 190 260
This is the name of the map file, its width in pixels (1275), its
height in pixels (1656), the x/y coordinate of its top left corner
(86, 101), the corresponding point on Earth (se 100 390 in NGR) and
then the equivalent for the lower-right point. Scanning-in maps and
adding them to the database is not a huge amount of fun but once done
it's done. If you are not using NGR then replace (for example)
se 182 269 with degrees and fractional minutes along the lines of
5344.28N,00143.44W - note that latitude has only two degree digits,
latitude has three and they must all be present.

You will also want a highlights.dat file, containing at least one line
which represents your 'home' location. These have a location, a name
and a description. In the original version of this program the description
selected a particular bitmap to display on the map at that point, but the
current version ignores it. Here are some examples: a location in Scotland,
two service stations on the M1 road from Leeds to London and the important 'home'
line that I use.

	5514.00N,00345W Thornhill, point
	5336.91N,00132.88W Woolley, services
	5318.91N,00116.91W Woodall, services
	se 1446 3585 home, point

USING THE PROGRAM

Start it running. If all is well, your home map and location will appear
on the screen. You can click around the map and that will move the clicked point
to the centre of the screen. If you have multiple scales of map available for a given
point, a set of buttons appears on the left which allows you to choose between
them. Pressing 'space' cycles around these.

Moving the mouse within the map display updates the location boxes (top left) to
show the corresponding latitude/longitude of the point under the cursor.
If you are within the range of the NGR coordinates (i.e. the UK) this will also show.

To get a moving-map display you will need a GPS receiver plugged into the
serial port. At the moment the software is hard-coded to use /dev/cua0 (you
will probably need to set the permissions so this can be opened by a non-root
user) and a speed of 4800 baud. I use a Magellan hand-held and a small home-made
RS232 converter so that it can talk to the serial port. The software listens for
NMEA sentences that start with "$GPGGA" and ignores others; I have no idea whether
this will work with other GPS receivers but it should do. You may have to tell your
receiver what baud rate to use.

With the receiver plugged-in and receiving fixes, select the 'File' menu and
click on 'Plot'.  If the software is able to read and recognise the input data
it will start to track the position.

If nothing happens, you could try turning on verbose mode by running the program
as "gps -v" and see if it's reading anything from the serial port - it prints to 
its standard output so look on the terminal window where you started it from.
Check that the receiver thinks it's locked-on to the satellites; mine remains
mute even for some time after it starts showing position fixes on its own display.

Whilst plotting the software logs positions into the file maps/logfile. This file can
be replayed (if one exists) by selecting File->Replay. You can stop a replay
but at present not continue from where you stopped.

If I want to keep a logfile I simply rename 'logfile' to something else, then back
again when I want to replay it. 

Plotting always appends to the current logfile, so you won't trash a valuable one
if you forget and then start plotting again later.

During plotting or replaying a speed and course box will appear on the left. Be
very suspicious of the figures in here, they do not appear to be very reliable.
They are calculated from smoothed lat/long coordinates but the smoothing is
evidently not working well. This is a highly frustrating rat-hole for time and I've
given up on it for the moment. A wiser man would have used the course/speed figures
that can be got from the GPS receiver but I wanted to be 'clever'.

RECOMPILING / CHANGING THE SOFTWARE.

The software is written in C++ that compiles (for me) on Linux using egcs-2.90.29.
It uses a home-made library of Strings and collection types (list_of<xxx>)
that was written years before the standard library appeared and which I'm
familiar with. I was limited in time and chose not to covert it to the
standard C++ STL library - though that would be possible.

You will need the Qt development package installed to recompile it. You probably have
this already (though it may not be installed) if you have access to a recent
Linux distribution. I'm using Red Hat 5.1 and installed it from RPMS that came
when we installed KDE, though I don't remember the location; we probably got
it from www.kde.org.

Typing 'make' should recompile it.

DON'T COMPLAIN

I *know* that some of the code is foul and unspeakable, especially in gpslib.cpp
and maplist.cpp. These were written originally to live an a Windows DLL that was
fronted by Visual Basic. Unless you have also had to do the same DO NOT COMPLAIN
TO ME about the hideous mess that resulted. That stuff was ported to Linux
under a severe lack of time. Coding for Windows is like having to live in a sewer.

FIXES AND ENHANCEMENTS

If you think you have added real value (I'd particularly like a maps database that
isn't going to cause copyright problems but will happily also accept code upgrades),
please *test* *test* *test* your code first then email me the changes.

COPYRIGHT

This code is released under the GPL. You can do what you like with it.

Best of luck!

Mike Banahan, September 1999.