Provided by: gpsdrive_2.10~pre4-6.dfsg-5.2ubuntu1_amd64 bug


       gpsdrive - displays GPS position on a map


       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 ...


       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)
       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 (
       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!


       -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

       -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.


       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


       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.


       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).


       GpsDrive  now  supports  OSM  maps with the help of the renderer Mapnik.  To activate this
       mode you have to choose the mapnik option.


       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 provided to download multiple maps for a bigger
       Please consider the copyright information at if  you  want  to  use  their
       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 carrée 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.


       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 where
       3128 in this example is the proxy port.


       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  and
       the  MySQL  Server  is running and a connection to the database is possible. For first use
       you have to run --create-db --fill-defaults once.

       Please read README.SQL for information how to setup the SQL database.


       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


       $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

       Please see also the file README.kismet


       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


       If  you  want  speech  output  you have to install the festival speech output system.  See for information.

       For  german  output  you   have   to   get   the   german   festival   from   www.ims.uni-

       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

       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


       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, you can try it if you enable  it
       in the settings menu.

       You can also send messages to other mobile targets (Misc. Menu/Messages)


       The address for the mailing list is
       You        can        browse        the        archive        or        subscribe       at


       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
        cd src
        gdb ./gpsdrive

       Inside the debugger do:

       run (if you use arguments write it after run)

       When you get the segfault type in:


       and send me this output.


       Fritz Ganter,
       Joerg Ostertag,
       Gpsdrive Development Team
       and others.


       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 (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.


       gpsd(8), friendsd(1), gpsfetchmap(1), osm2pgsql(1), kismet(1), festival(1), flite(1)