Man Linux: Main Page and Category List


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

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

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


       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


       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

       There  is also the program provided to download multiple
       maps for a bigger area.
       Please consider the copyright information  at  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

       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

       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


       You  can  switch  on  the Position mode by selecting this option in the

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

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


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

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


       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

       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.


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