NAME
gpsdrive - displays GPS position on a map
SYNOPSIS
gpsdrive [options]
About this manual page
This manual page explains the basic functions of GpsDrive and some
additional info.
In GpsDrive you find tooltips for nearly all buttons, there is also a
HELP button for usage of the keys and mouse buttons.
For special purposes read the README files, i.e. README.kismet,
README.SQL ...
DESCRIPTION
Gpsdrive is a car (bike, ship, plane) navigation system. Displaying
your position on a map and a lot of other functions are implemented.
This manual page describes GpsDrive version 2.x
GpsDrive displays your position provided from your NMEA capable GPS
receiver on a zoomable map . The maps are autoselected depending on
your position. You can set the preferred scale, which the program tries
to get from available maps.
GpsDrive was tested with a GARMIN GPS III, a Crux II GPS PCMCIA card
and a Navilock USB receiver. All Garmin GPS reveivers with a serial
output should be usable. Other GPS receivers that sends NMEA protocol
over the serial output should also work with GpsDrive.
These GPS receivers are reported to work with gpsdrive:
Magellan 310, 315, 320
Garmin GPS III
Garmin etrex
GPS 45
Crux II GPS PCMCIA card
Holux GM-200 serial version
Holux GM-200 USB (needs USB to serial support in kernel)
eMap
GPSMAP 295
GNS 530
Garmin GPS 12MAP
EAGLE Expedition II
DeLorme Earthmate
Rayming TripNav, TN-200
Haicom HI-203E
GM-307 USB-Mouse
Magellan Meridian Gold (works only with NMEA V2.1 GSA setting)
NAVILock GPS Receiver (http://www.navilock.de)
Haicom GPS HI204e
Magellan Nav 6500
BendixKing KLX 100
Motorola i58sr Cellular Phone w/built-in NMEA-compatible GPS
Disclaimer: Do not use for navigation!
OPTIONS
-d Shows some debugging information.
-D <level>
Shows a lot of debugging information. You should also combine
this with -d.
See also the section BUGS.
-T Do some internal unit tests (don't start gpsdrive).
-e use festival-lite (flite) for speech output.
-v Shows program version.
-h Displays a short help message.
-o <outputfile>
With this option, you can write the NMEA sentences to a PTY
master, file or serial device. This is useful if you use
GpsDrive in simulation mode to provide other GPS applications
with test data.
-l <language>
Sets the language for the speech output. You have to provide the
voice files in festival yourself (see below). At the moment
german , spanish and english are provided.
-g <geometry>
Set the geometry of the screen, if autodetection doesn't satisfy
you, geometry is i.e. 1024x768, 800x600, 640x480
-f <friends server>
Define a friends server to exchange position information with
other people. You can also set it in the Settings/Friends menu.
You can start your own friends server with the program friendsd2
, which is included. More details are in section FRIENDSD server
-X Use DBUS for communication with gpsd. This disables socket
communication. Try this option if gpsdrive fails to interpret
output of the gps receiver correctly.
-1 Set special mode if you only have 1 mouse button, i.e. on
touchpads.
-a Display APM stuff (battery status, temperature)
-b <nmea server>
Use a remote NMEA server. You can start gpsd on another host ,
which has the GPS receiver connected and display the position on
your local machine.
-c <waypoint>
Initial position for simulation mode. Specify a waypoint name
from your currently used waypoint list.
-M <mode>
Set GUI mode. <mode> may be 'desktop' (default), 'pda' or 'car'.
-i Ignore NMEA checksum (risky, only for broken GPS receivers).
-q Disables SQL support.
-F Force display of position even if it is invalid.
-S Don't show splash screen.
-P Start in Position Mode
-W <x> Set to 1 to switch WAAS/EGNOS on, set to 0 to switch it off.
-H <altitude>
Correct altitude.
-C <file>
Set config file to <file>.
Use gpsdrive -h to see the actual command line help.
CONNECTING A GPS RECEIVER
First you have to choose if you want use the GARMIN or NMEA mode.
NMEA mode.
This is the most used mode. This mode is provided by most GPS
receivers.
To use NMEA mode, you have to start the provided program gpsd first
Start GPSD This program runs as daemon in background and provides a
server, which sends the GPS data on port number 2947. The settings
/dev/gps and 4800 BPS are precompiled if you start gpsd.
You can also change the gpsd settings i.e. to ttyS1 call it with:
gpsd -p /dev/ttyS1
If you are using a GPS receiver with an USB connection, your port may
be /dev/ttyUSB0 for the first device.
Be sure to select NMEA protocol and a baudrate of 4800 BPS in your GPS
receiver.
To see the output of you GPS do telnet localhost 2947 and after the
connect hit the R key to see the NMEA sentences.
NMEA sentences used
Following NMEA sentences are used for specified informations:
GPRMC: Position, Speed, Heading
GPGSV: Satellite signal level display
GPGGA: Altitude (not available on all receivers) and position if no
GPRMC is available. In this case, speed and heading are calculated by
GpsDrive.
PGRME: Display EPE (estimated position error), perhaps only available
on GARMIN receivers
At least you need GPRMC or GPGGA for using GpsDrive. If you can turn on
GPRMC, please do so.
USAGE
Start GpsDrive as normal user with: gpsdrive from your shell, if you
want another language see section LOCALISATION
On some distributions you may find a "GpsDrive" entry in your Gnome or
KDE menu.
It is important that you have installed GpsDrive as root, so it can
find the necessary files. Don't start GpsDrive as root!
You can use GpsDrive without a GPS device connected. If you do so,
GpsDrive will automatically start in Simulator mode if no working GPS
receiver is connected and no gpsd is running. This mode is shown by a
rotating globe.
In simulator mode the pointer can move on the map (if enabled in
settings menu). You can also stop gpsd if it is already running with
the "Stop GPSD" Button.
If you have connected a GPS-Receiver, you see in the GPS Info window
how many satellites are in view. You can click on this image to switch
to the Satellite position view.
You must have at least 3 satellites in view. If you want to see your
altitude, you need at least 4 satellites. The antenna of your GPS
receiver must have free sight to the sky, so you cannot use it indoors.
More satellites gives you a better accuracy.
If your receiver has not enough satellites with usable signal, the GPS
Info window is red. If your signal is ok and gives a valid position,
the GPS Info window is green.
There are 3 modes in which GpsDrive is operating:
Normal mode:
This mode is entered if you have a GPS receiver connected. The cursor
is at the position your receiver sends.
Black and a red arrows show your position on the map. The black arrow
is pointing to your selected target, the red arrow shows the direction
in which you are moving.
If you have no valid position the arrows are blinking.
Simulation
If GpsDrive finds no GPS-receiver at program start, it shows the last
position and the cursor will move to the targets you set. You can set
your target by right-mouse click on the map or by selecting a waypoint
from the FIND menu.
Position mode
This mode is activated by clicking on the "Pos. mode" button or if you
"Jump" to a target in the FIND menu.
In this mode, you can temporarily change the position for looking
around and jumping to other positions (i.e. for downloading maps). In
this mode this is not your real position and is marked as an rectangle.
You can set the position by a simple left-mouse click on the map.
You can leave the position mode by by clicking on the "Pos. mode"
button or middle-mouse click or right-mouse click (which also sets your
target).
OPENSTREETMAP MAPS
GpsDrive now supports OSM maps with the help of the renderer Mapnik.
To activate this mode you have to choose the mapnik option.
MAP DOWNLOAD
You can easily download maps from the internet with the Download
button. GpsDrive stores an index of your maps in the file map_koord.txt
in your ~/.gpsdrive directory. You can also use any directory for your
maps, but you have to set this in the settings menu.
About maps
There is a file called "map_koord.txt" in your ~/.gpsdrive directory.
Here is a sample:
top_WORLD.jpg 0,00000 0,00000 88226037
map_file0000.gif 53,60751 10,01145 3160000
map_file0001.gif 43,08210 12,24552 3160000
map_file0002.gif 49,81574 9,71454 7900000
map_file0003.gif 47,72837 14,46487 592500
The first row is the filename, then comes the latitude, the longitude
and the scale of the map. The scale of 10000000 is good for Europe, and
100000 is for a town. To see detailed streets in a city, choose a scale
like 10000 or 5000.
GpsDrive selects the map with the best scale for your position. So get
a map i.e for Europe, Austria and Vienna if you want to drive in
Vienna.
There is also the program gpsfetchmap.pl provided to download multiple
maps for a bigger area.
Please consider the copyright information at www.expedia.com if you
want to use their maps!
Don't misuse this service by downloading more maps as you need! You
will risk being blocked by these servers, and possibly cause trouble
for the gpsdrive project.
File formats:
The decimal points in way.txt must always be a dot ('.'), in
map_koord.txt '.' or ',' are possible. If you download maps from within
the program, GpsDrive writes the map_koord.txt respecting your
LC_NUMERIC setting.
Can I use other maps?
You can also use your own (self drawn, scanned...) maps. The maps must
be gif, jpeg, png or other common file formats (the format must be
recognized by the gdk-pixbuf library). The lat/long coordinates you
write into the "map_koord.txt" file has to be the center of the map.
The map must have a size of 1280x1024 pixels!
Important! The maps must be named "map_*" for UTM-like projections
(lat:lon = 1:cos(lat)) and "top_*" for lat/lon Plate carre projection
(lat:lon = 1:1). The prefix is given so that gpsdrive knows how to
scale the maps correctly. Alternatively the maps can be stored without
prefix in subdirectories of $HOME/.gpsdrive/ which end in "_map" or
"_top".
There is an "import assistant" built in. Use it to import your maps.
Importing waypoints:
The easiest way is to use the script "wpget" which does everything for
you if you use a GARMIN receiver. You can use the program "garble"
(included in the package) to read out your waypoints from the Garmin
GPS (Transfer mode must be set to GARMIN here, while GpsDrive needs
NMEA!).
Scripts: "wpget" is a script which calls "garble" in the proper way.
Be sure to have "wpget", "wpcvt" and "garble" in your path. This is
fulfilled, if you did install the program as root and /usr/local/bin is
in your path.
The manual way:
You may create a file "way.txt" in your ~/.gpsdrive directory which
looks like:
DFN-Cert 53.577694 9.991263 FRITZ
Finkenwerder 53.541765 9.842541 AIRPORT
Fritz_Wohnung 53.582700 9.971390 FRITZ
The rows are: label latitude longitude waypoint-type. You may omit the
waypoint type.
There is no need to create the way.txt file yourself, you can add the
waypoints with GpsDrive using the "x" key. See help menu.
Route planning
There is no route planning feature at the moment. Route planning would
need the use of commercial maps and a database license which costs more
than EUR 10.000.
PROXY SERVER
If you must access the internet via a proxy server, you have to set the
enviromental variable HTTP_PROXY or http_proxy to a value like
http://proxy.provider.com:3128 where 3128 in this example is the proxy
port.
MOUSE CONTROL
You can switch on the Position mode by selecting this option in the
menu.
If you switched to "position mode" a rectangle is the cursor and no
position is shown. If you zoom or select another map scale with the
slider, this is done for the position of the rectangle-cursor in the
same manner as it would be your actual position. If you click with the
left button near the border, GpsDrive will scroll the map or load the
next map if you are on the margin of the map.
The middle mouse button or the "Pos. mode" menu entry switches back to
normal mode. The same happens if you select a target with the right
mouse button. Shift-left-mouse-button and shift-right-mouse-button or
using the mouse wheel changes the map scale.
Please have also a look into the Help menu in GpsDrive to be informed
about the actual mouse functions and key shortcuts.
Add new waypoints
You can simply add new waypoints in two ways:
o To add a waypoint at the current (GPS) position, simply press CTRL
and RIGHT-mouse-click. You can also press the x key.
o To add a waypoint at the mouse position, simply press CTRL and LEFT-
mouse-click. You can also press the y key.
In the popup window add the waypoint name (spaces will be converted to
underscores) and choose a waypoint type (see below for predefined
waypoint types).
Icons for waypoints
At the moment there a three different icon themes available, but not
everone has distinct icons for every type. Currently you can choose the
themes only by editing the entry "icon_theme" in the config file
"~/.gpsdrive/gpsdriverc". The possible themes are: "square.big",
"square.small" and "classic".
SQL support
For managing a larger number of waypoints you should use SQL support.
This needs to install a SQL server on your machine. At the moment, only
MySQL is supported.
Don't be afraid, MySQL doesn't need much resources, is very fast, and
makes the management (including selection of waypoint types) of the
waypoints much easier. In SQL mode you can select the waypoints to
display in the setup menu.
GpsDrive use MySQL automatically if it finds the shared library
libmysqlclient.so.10 and the MySQL Server is running and a connection
to the database is possible. For first use you have to run geoinfo.pl
--create-db --fill-defaults once.
Please read README.SQL for information how to setup the SQL database.
Routes
A route is a list of waypoints. GpsDrive guides you from one waypoint
to the next on the route. You can add waypoints to a route using the
waypoint (select target) window. You can also add comments to a
waypoint which will be spoken by the speech system and also be shown in
the map window as scrolling text.
Comments for routes
To add comments create a file with the same name as the waypoint file,
but change the suffix to .dsc, i.e way-trip.txt and way-trip.dsc, then
enter the comments in the way*.dsc file in the kind of:
$waypointname Text which is displayed and spoken
$nextwaypointname another text
Example:
$Fritz_Wohnung Hier wohnt Fritz, der Autor von diesem Programm. Er
freut sich auf Besuch und eine Einladung zu einem saftigen Steak.
$Hubertus Hier wohnt Hubertus, ein Freund von Fritz.
There is no limit of the length of the comment. Important is to start
the line with '$name' and the comment in the next lines.
KISMET support
Gpsdrive supports kismet. Kismet is a 802.11b wireless network (WLAN)
sniffer. If you have kismet running, gpsdrive will detect it and
program starts and shows new WLAN access points in real time on the
map. SQL mode is necessary to use Gpsdrive with Kismet. WLAN
accesspoints which are already stored in the SQL database from prior
wardrivings are ignored. If you have voice output in gpsdrive, you hear
information about the newly found accesspoint.
Please see also the file README.kismet
LOCALISATION
If you have installed the program it will display messages in english,
german, french, italian, dutch, dansk, hungarian, slovak, swedish,
turkish or spanish if your language is set either with LANG or
LANGUAGE. LANGUAGE overrides all other settings. Call "locale" to see
the settings and call "set" if LANG or LANGUAGE is set. For german do:
export LANGUAGE=de
and then call gpsdrive in this shell.
You can also start it with the line LANGUAGE=de gpsdrive without
setting the language for the shell.
Sometimes you have to do use LANG instead of LANGUAGE.
If your own language isn't available, please contact me if you want to
make the translations.
SPEECH OUTPUT
If you want speech output you have to install the festival speech
output system. See http://fife.speech.cs.cmu.edu/festival for
information.
For german output you have to get the german festival from www.ims.uni-
stuttgart.de/phonetik/synthesis/index.html
If you have a functional festival software call it as server with:
festival --server
When you start GpsDrive it will detect the server on port 1314 and puts
out some status information as speech. You also have an additional
button (Mute) to switch off sound output.
GpsDrive tries to select the correct language for your locale. The -l
option can force the languages for speech output. At the moment
english, spanish, and german are supported. GpsDrive sets festival into
the proper language. If the initialisation is not correct, have a look
into gpsdrive.c and edit following defines do your needs:
#define FESTIVAL_ENGLISH_INIT "(voice_ked_diphone)"
#define FESTIVAL_GERMAN_INIT "(voice_german_de3_os)"
#define FESTIVAL_SPANISH_INIT "(voice_el_diphone)"
For this, you need the voices ked_diphone for english, german_de3_os
for german (this is a MBROLA voice) and el_diphone for spanish.
There is now an unsupported build of festival including english, german
and spanish support. Download it from GpsDrive homepage mirrors and
extract the tar file in the directory /usr/local as root:
cd /usr/local
tar -xvzf festivalbuild.tar.gz
Start the server with /usr/local/festival/bin/festival --server
FRIENDSD server
There is a server program, called friendsd which acts as server for the
position of your friends. If you enable it in the settings menu, then
you can see the position of all gpsdrive connected with this server.
You will see the position of your friends as a car symbol on the map,
including the name, time, day of week and the speed of his last
connection. The blue arrow shows the last reported direction of your
friend.
The time is transmitted as UTC, but shown on the display as your local
time, so it is also correct if your friend lives in another time zone.
The server uses port 50123 (UDP), so be sure that you open the port in
your firewall. The server needs no root privileges and should run as
normal user or a special user with no privileges. The server was NOT
tested for security.
There is a friends server running on friends.gpsdrive.de, you can try
it if you enable it in the settings menu.
You can also send messages to other mobile targets (Misc.
Menu/Messages)
MAILING LIST
The address for the mailing list is gpsdrive@lists.gpsdrivers.org
You can browse the archive or subscribe at
http://lists.gpsdrivers.org/mailman/listinfo/gpsdrive
BUGS
Please send bug reports to the author. Report version (gpsdrive -v),
screen size and info how to reproduce the bug. It is also a big help to
run gpsdrive for a minute with the -d option and send me the output.
If gpsdrive crashes with a segfault, I need a backtrace of the program
in addition. To create a backtrace do following:
Extract the tar file, change to gpsdrive directory and do
./configure --with-debug
make clean
make
cd src
gdb ./gpsdrive
Inside the debugger do:
run (if you use arguments write it after run)
When you get the segfault type in:
bt
and send me this output.
AUTHORS
Fritz Ganter,
Joerg Ostertag,
Gpsdrive Development Team
and others.
http://www.gpsdrive.de
WARRANTY
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
COPYRIGHT
Copyright (c) 2001-2006 by Fritz Ganter
Copyright (c) 2006-2007 The GpsDrive Development Team
This program is free software; you can redistribute it and/or modify it
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.
SEE ALSO
gpsd(8), friendsd(1), gpsfetchmap(1), osm2pgsql(1), kismet(1),
festival(1), flite(1)