1GPSDRIVE(1) General Commands Manual GPSDRIVE(1)
2
6 gpsdrive v2.x - displays GPS position on a map
7
9 gpsdrive [options]
10
13 This manual page explain the basic functions of GpsDrive and some addi‐
14 tional info.
15 In GpsDrive you find tooltips for nearly all buttons, there is also a
17 HELP button for usage of the keys and mouse buttons.
18 For special purposes read the README files, i.e. README.kismet,
20 README.SQL ...
21
24 Gpsdrive is a car (bike, ship, plane) navigation system. Displaying
25 your position on a map and a lot of other functions are implemented.
26 This manual page describes GpsDrive version 2.x
28 GpsDrive displays your position provided from your NMEA capable GPS
30 receiver on a zoomable map . The maps are autoselected depending on
31 your position. You can set prefered scale, which the program tries to
32 get from available maps.
33 GpsDrive was tested with a GARMIN GPS III, a Crux II GPS PCMCIA card
35 and a Navilock USB receiver. All Garmin GPS reveivers with a serial
36 output should be usable. Other GPS reveivers that sends NMEA protocol
37 over the serial output should also work with GpsDrive.
38 These GPS receivers are reported to work with gpsdrive:
40 Magellan 310, 315, 320
42 Garmin GPS III
43 Garmin etrex
44 GPS 45
45 Crux II GPS PCMCIA card
46 Holux GM-200 serial version
47 Holux GM-200 USB (needs USB to serial support in kernel)
48 eMap
49 GPSMAP 295
50 GNS 530
51 Garmin GPS 12MAP
52 EAGLE Expedition II
53 DeLorme Earthmate
54 Rayming TripNav, TN-200
55 Haicom HI-203E
56 GM-307 USB-Mouse
57 Magellan Meridian Gold (works only with NMEA V2.1 GSA setting)
58 NAVILock GPS Receiver (http://www.navilock.de)
59 Haicom GPS HI204e
60 Magellan Nav 6500
61 BendixKing KLX 100
62 Motorola i58sr Cellular Phone w/built-in NMEA-compatible GPS
63 Disclaimer: Do not use for navigation!
65
68 -d Shows some debugging information.
69 -D Shows a lot of debugging information. If you have problems or
71 program crashes, send this output to the author. You should also
72 combine this with -d. See also the section BUGS
73 -v Shows program version together with the CVS version of the main‐
75 file gpsdrive.c. If you send a bug report, also include this
76 output.
77 -h Displays a short help message.
79 -o outputfile
81 With this option, you can write the NMEA sentences to a PTY mas‐
82 ter, file or serial device. This is useful if you use GpsDrive
83 in simulation mode to provide other GPS applications with test
84 data.
85 -t device
87 Serial port device (e.g. /dev/ttyS0 ). You can also set it in
88 the setup menu.
89 -l language
91 Sets the language for the speech output. You have to provide the
92 voice files in festival yourself (see below). At the moment ger‐
93 man , spanish and english are provided.
94 -x Creates own window for the menu buttons, status and map. This is
96 helpful on small displays as the Compaq iPaq or on Head Mounted
97 Displays, where the menu should be hidden.
98 -s height
100 Set the height of the screen, if autodetection don't satisfy
101 you, height is i.e. 768,600,480,200
102 -r width
104 Set the width of the screen, if autodetection don't satisfy you.
105 Works only in combination with -s
106 -f friendsserver
108 Define a friendsserver to exchange position information with
109 other people. You can also set it in the Settings/Friends menu.
110 You can start your own friendsserver with the program friendsd ,
111 which is included. More details are in section FRIENDSD server
112 -1 Set special mode if you only have 1 mouse button, i.e. on touch‐
115 pads.
116 -a Disable display of battery status. Some implementations of the
118 APM-BIOS are broken, so use this option if gpsdrive crashes.
119 -b servername
121 Use a remote NMEA server. You can start gpsd on another host ,
122 which has the GPS receiver connected and display the position on
123 your local machine.
124 -c waypointname
126 Initial position for simulation mode. Specify a waypoint name
127 from your currently used waypoint list.
128 -q Disables SQL support. Only usefull if you have SQL support com‐
130 piled in.
131 -z Don't show zoom and scaling on the map.
133 -n Disables the direct serial connection. You have to use Garmin
135 mode or start gpsd
136 Use gpsdrive -h to see the actual command line help.
139
143 First you have to choose if you want use the GARMIN or NMEA mode.
144 NMEA mode.
146 This is the most used mode. This mode is provided by most GPS
147 receivers.
148 New!!!
150 Since Version 2.08 GpsDrive is now able to handle the serial connection
152 itself, so you don't need to start (and use) gpsd anymore.
153 To enable this feature go into the settings menu, switch to settings 2
154 and select Use serial connection.
155 Make sure that your GPS receiver is connected and running before you
156 start GpsDrive, so the program is able to detect the GPS device.
157 You can also use gpsd, i.e. if you want to share the GPS data over the
159 network or if you need additional features.
160 You can force the use of gpsd by adding the -n commandline parameter,
161 even if you enabled the direct serial connection in the settings menu.
162 To use NMEA mode with gpsd, you have to start the provided program gpsd
164 first or do this by pressing the Start GPSD button in the GpsDrive menu
165 after setting the parameters in the settings menu. This program runs
166 as daemon in background and provides a server, which sends the GPS data
167 on port number 2947. The settings /dev/gps and 4800 BPS are precom‐
168 piled if you start gpsd by yourself. If you start it from GpsDrive, the
169 settings defined in the Settings menu are used.
170 You can also change the gpsd settings i.e. to ttyS1 call it with:
172 gpsd -p /dev/ttyS1
173 but as mentioned, it's easier to do this in GpsDrive.
175 If you are using a GPS receiver with an USB connection, your port may
176 be /dev/ttyUSB0 for the first device.
177 Be sure to select NMEA protocol and a baudrate of 4800 BPS in your GPS
179 receiver.
180 To see the output of you GPS do telnet localhost 2947 and after the
182 connect hit the R key to see the NMEA sentences.
183 NMEA sentences used
185 Following NMEA sentences are used for specified informations:
186 GPRMC: Position, Speed, Heading
188 GPGSV: Satellite signal level display
189 GPGGA: Altitude (not available on all receivers) and position if no
190 GPRMC is available. In this case, speed and heading are calculated by
191 GpsDrive.
192 PGRME: Display EPE (estimated position error), perhaps only available
193 on GARMIN receivers
194 At least you need GPRMC or GPGGA for using GpsDrive. If you can turn on
196 GPRMC, please do so.
197 GARMIN mode
199 In this mode, the program only gets lat/long data, the speed and direc‐
200 tion it calculates itself. There is also no display of the satellite
201 signal level (this data is not supported by GARMIN protocol).
202 GARMIN mode is faster (more data packets per second, in NMEA mode there
204 are only 1-2 packets every 2 seconds), but the calculations the program
205 makes may not be as accurate.
206 If you want to use Garmin mode, simply connect the GPS receiver to your
208 serial port. Garmin mode is only provided by some GARMIN receivers.
209 GpsDrive autodetects GARMIN or NMEA mode if enabled in settings menu. I
211 would recommend to use NMEA mode.
212
215 If you don't need the GARMIN protocol (i.e if you use only NMEA), you
216 can compile GpsDrive yourself to not include the GARMIN protocol sup‐
217 port. Do this with:
218 ./configure --disable-garmin
220 make clean
221 make
222 su
223 make install
224 This has the advantage to produce a smaller and faster executable.
226
229 Start GpsDrive as normal user with: gpsdrive from your shell, if you
230 want another language see section LOCALISATION
231 On some distribution you may find a "GpsDrive" entry in your Gnome or
233 KDE menu.
234 It is important that you have installed GpsDrive as root, so it can
236 find the necessary files. Don't start GpsDrive as root!
237 You can use GpsDrive without a GPS device connected. If you do so, Gps‐
239 Drive will automatically start in Simulator mode if no working GPS
240 receiver is connected and no gpsd is running. This mode is shown by a
241 rotating globe.
242 In simulator mode the pointer can move on the map (if enabled in set‐
244 tings menu). You can also stop gpsd if it is already running with the
245 "Stop GPSD" Button.
246 If you have connected a GPS-Receiver, you see in the GPS Info window
248 how much satellites are in view. You can click on this image to switch
249 to the Satellite position view.
250 You must have at least 3 satellites in view. If you want to see your
251 altitude, you need at least 4 satellites. The antenna of your GPS
252 receiver must have free sight to the sky, so you cannot use it indoor.
253 More satellites gives you a better accuracy.
254 If your receiver have not enough satellites with usable signal, the GPS
256 Info window is red. If your signal is ok and gives a valid position,
257 the GPS Info window is green.
258 There are 3 modes in which GpsDrive is operating:
260 Normal mode:
262 This mode is entered if you have a GPS receiver connected. The cursor
264 is at the position your receiver sends.
265 The black and a red arrow shows your position on the map. The black
267 arrow is pointing to your selected target, the red arrow shows the
268 direction in which you are moving.
269 If you have no valid position the arrows are blinking.
270 Simulation
272 If GpsDrive finds no GPS-receiver at program start, it shows the last
274 position and the cursor will move to the targets you set. You can set
275 your target by right-mouse click on the map or by selecting a waypoint
276 from the FIND menu.
277 Position mode
279 This mode is activated by clicking on the "Pos. mode" button or if you
281 "Jump" to a target in the FIND menu.
282 At this mode, you can temporary change the position for looking around
284 and jump to another positions (i.e. for downloading maps). In this mode
285 this is not your real position and is marked as an rectangle.
286 You can set the position by simple left-mouse click on the map.
288 You can leave the position mode by by clicking on the "Pos. mode" but‐
290 ton or middle-mouse click or right-mouse click (which also sets your
291 target).
292
297 You can easily download maps from internet with the Download button.
298 GpsDrive stores an index of your maps in the file map_koord.txt in your
299 ~/.gpsdrive directory. You can also use any directory for your maps,
300 but you have set the directory in the settings menu.
301
304 There is a file called "map_koord.txt" in your ~/.gpsdrive directory.
305 Here is a sample:
306 top_WORLD.jpg 0,00000 0,00000 88226037
308 map_file0000.gif 53,60751 10,01145 3160000
309 map_file0001.gif 43,08210 12,24552 3160000
310 map_file0002.gif 49,81574 9,71454 7900000
311 map_file0003.gif 47,72837 14,46487 592500
312 The first row is the filename, then comes the latitude, the longitude
315 and the scale of the map. The scale of 10000000 is good for Europe, and
316 100000 is for a town. To see detailed streets in a city, choose a scale
317 like 10000 or 5000.
318 GpsDrive selects the map with the best scale for your position. So get
320 a map i.e for Europe, Austria and Vienna if you want to drive in
321 Vienna.
322 There is also the programs gpsfetchmap.pl provided to download multiple
325 maps for a bigger area.
326 Please consider the copyright information www.expedia.com if you want
327 to use their maps!
328 Don't missuse this service by downloading more maps as you need! You
329 will risc that you will be blocked by this servers.
330 File formats:
332 The decimal points in way.txt must always be a dot ('.'), in
334 map_koord.txt '.' or ',' are possible. If you download maps from within
335 the program, GpsDrive writes the map_koord.txt respecting your
336 LC_NUMERIC setting.
337
341 You can also use your own (self drawn, scanned...) maps. The maps must
342 be gif, jpeg, png or other common file formats (the format must be rec‐
343 ognized by the gdk-pixbuf library). The lat/long coordinates you write
344 into the "map_koord.txt" file must be the center of the map. The map
345 must have a size of 1280x1024 pixels!
346 Important! The maps must now be named map_* for streetmaps and top_*
348 for topographical maps. If not, gpsdrive won't display the maps.
349 There is an "import assistant" build in. Use this to import your maps.
351
354 The easiest way is to use the script "wpget" which does all for you if
355 you use a GARMIN receiver. You can use the program "garble" (included
356 in the package) to read out your waypoints from the Garmin GPS (Trans‐
357 fer mode must be set to GARMIN here, while GpsDrive needs NMEA!).
358 Scripts: "wpget" is a script which calls "garble" in the proper way.
360 Be sure to have "wpget", "wpcvt" and "garble" in your path. This is
362 fullfilled, if you did install the program as root and /usr/local/bin
363 is in your path.
364 The manual way:
366 You may create a file "way.txt" in your ~/.gpsdrive directory which
368 looks like:
369 DFN-Cert 53.577694 9.991263 FRITZ
371 Finkenwerder 53.541765 9.842541 AIRPORT
372 Fritz_Wohnung 53.582700 9.971390 FRITZ
373 The rows are: label latitude longitude waypoint-type. You may omit the
375 waypoint type.
376 There is no need to create the way.txt file yourself, you can add the
378 waypoints with GpsDrive using the "x" key. See help menu.
379
384 There is no route planing feature at the moment. Route planing would
385 need the use of commercial maps and a database license which costs more
386 than EUR 10.000.
387
390 If you must access the internet via a proxy server, you have to set the
391 enviroment variable HTTP_PROXY or http_proxy to a value like
392 http://proxy.provider.com:3128 where 3128 in this example is the proxy
393 port.
394
397 You can switch on the Position mode by selecting this option in the
398 menu.
399 If you switched to "position mode" there a rectangle is the cursor and
401 no position is shown. If you zoom or select another map scale with the
402 slider, this is done for the position of the rectangle-cursor in the
403 same manner as it would be your actual position. If you click with the
404 left button near the border, GpsDrive will scroll the map or load the
405 next map if you are on the margin of the map.
406 The middle mouse button switches back to normal mode, or select the
408 "Pos. mode" menu entry. The same if you select a target with the right
409 mouse button. Shift-left-mouse-button and shift-right-mouse-button
410 changes the map scale.
411 Please have also a look into the Help menu in GpsDrive to be informed
413 about the actual mouse functions and key shortcuts.
414
417 You can simply add new waypoints in two ways:
418 o To add a waypoint at the current (GPS) position, simply press CTRL
420 and RIGHT-mouse-click. You can also press the x key.
421 o To add a waypoint at the mouse position, simply press CTRL and LEFT-
423 mouse-click. You can also press the y key.
424 In the popup window add the waypoint name (spaces will be converted to
426 underscores) and a waypoint type (see below for predefined waypoint
427 types). You can create a new waypoint type by typing it into the text
428 field or choose a existing waypoint type from the list. Important: The
429 list (in SQL mode only) shows already used waypoint types, NOT the pre‐
430 defined.
431
433 You can define freely your waypoint type names. But there are special
434 names, which results in special icons display in GpsDrive:
435 WLAN open WLAN accesspoint
437 WLAN-WEP
439 crypted WLAN accesspoint
440 Rest a restaurant
442 McDonalds
444 a kind of restaurant
445 BurgerKing
447 another kind of restaurant
448 Hotel A hotel
450 Shop Shop
452 Monu Monument, touristic attraction
454 Speedtrap
456 Speedtrap (Radar), gives warning if this is in front of you
457 Nightclub
459 Pssst...
460 Airport
462 a Airport
463 Golf Golf course
465 Gasstation
467 a gas station
468 Cafe coffee bar
470 Geocache
472 Geocache point
473 The names are case insensitive.
476 Please have also a look on README.SQL , for a actual list of waypoint
478 types.
479
482 If you are using SQL (see below) for your waypoints, you can define
483 your own waypoint icons.
484 Do the following steps:
485 Create the directory: $HOME/.gpsdrive/icons and place your icons (image
486 type must be PNG) into this directory, with the name of the waypoint
487 type (the filename must be lowercase). In example for waypoint type
488 "HOTEL" the file must have the name "hotel.png".
489 The PNG image can have transparency, and should have a size around
490 16x16 until 32x32, bigger icons may result in a performance hit.
491 Your user defined waypoints override the built-in waypoint icons.
493
496 For managing a larger number of waypoints you should use SQL support.
497 This needs to install a SQL server on your machine. At the moment, only
498 MySQL is supported.
499 Don't be afraid, MySQL don't need much resources, is very fast, but
501 makes the management (including selection of waypoint types) of the
502 waypoints much easier. In SQL mode you can select the shown waypoints
503 in the setup menu.
504 GpsDrive use MySQL automatically if it finds the shared library lib‐
506 mysqlclient.so.10 and the MySQL Server is running and a connection to
507 the database is possible. For first use you have to run create.sql
508 once.
509 Please read README.SQL for information how to setup the SQL database.
511
516 A route is a list of waypoints. GpsDrive guides you from one waypoint
517 to the next on the route. You can add waypoints to a route using the
518 waypoint (select target) window. You can also add comments to a way‐
519 point which will be spoken by the speech system and also be shown in
520 the map window as scrolling text.
521
524 To add comments create a file with the same name as the waypoint file,
525 but change the suffix to .dsc, i.e way-trip.txt and way-trip.dsc, then
526 enter the comments in the way*.dsc file in the kind of:
527 $waypointname Text which is displayed and spoken
529 $nextwaypointname another text
531 Example:
533 $Fritz_Wohnung Hier wohnt Fritz, der Autor von diesem Programm. Er
535 freut sich auf Besuch und eine Einladung zu einem saftigen Steak.
536 $Hubertus Hier wohnt Hubertus, ein Freund von Fritz.
538 There is no limit of the length of the comment. Important is to start
540 the line with '$name' and the comment in the next lines.
541
544 Gpsdrive supports kismet. Kismet is a 802.11b wireless network (WLAN)
545 sniffer. If you have kismet running, gpsdrive will detect it and pro‐
546 gram start and shows new WLAN accesspoints in realtime on the map. SQL
547 mode is necessary to run Gpsdrive in Kismet mode. WLAN accesspoints
548 which are already stored in the SQL database from prior wardrivings are
549 ignored. If you have voice output in gpsdrive, you hear information
550 about the new found accesspoint.
551 Please see also the file README.kismet
553
556 If you installed the program it will display messages in english, ger‐
557 man, french, italian, dutch, dansk, hungarian, slovak, swedish, turkish
558 or spanish if your language is set either with LANG or LANGUAGE. LAN‐
559 GUAGE overrides all other settings. Call "locale" to see the settings
560 and call "set" if LANG or LANGUAGE is set. For german do:
561 export LANGUAGE=de
563 and then call gpsdrive in this shell.
565 You can also start it with the line LANGUAGE=de gpsdrive without set‐
567 ting the language for the shell.
568 Sometimes you have to do use LANG instead of LANGUAGE.
570 If your own language isn't available, please contact me if you want to
572 make the translations.
573
576 If you want speech output you have to install the festival speech out‐
577 put system. See http://fife.speech.cs.cmu.edu/festival for informa‐
578 tion.
579 For german output you have to get the german festival from www.ims.uni-
581 stuttgart.de/phonetik/synthesis/index.html
582 If you have a functional festival software call it as server with:
584 festival --server
586 When you start GpsDrive it will detect the server on port 1314 and puts
588 out some status information as speech. You also have an additonal but‐
589 ton (Mute) to switch off sound output.
590 GpsDrive tries to select the correct language for your locale. The -l
592 option can force the languages for speech output. At the moment eng‐
593 lish, spanish, and german are supported. GpsDrive sets festival into
594 the proper language. If the initialisation is not correct, have a look
595 into gpsdrive.c and edit following defines do your needs:
596 #define FESTIVAL_ENGLISH_INIT "(voice_ked_diphone)"
598 #define FESTIVAL_GERMAN_INIT "(voice_german_de3_os)"
600 #define FESTIVAL_SPANISH_INIT "(voice_el_diphone)"
602 For this, you need the voices ked_diphone for english, german_de3_os
604 for german (this is a MBROLA voice) and el_diphone for spanish.
605 There is now an unsupported build of festival including english, german
607 and spanish support. Download it from GpsDrive homepage mirrors and
608 extract the tar file in the directory /usr/local as root:
609 cd /usr/local
611 tar -xvzf festivalbuild.tar.gz
612 Start the server with /usr/local/festival/bin/festival --server
614
618 There is a server program, called friendsd which acts as server for the
619 position of your friends. If you enable it in the settings menu, then
620 you can see the position of all gpsdrive connected with this server.
621 You see the position of your friends as a car symbol on the map,
623 including the name, time, day of week and the speed of his last connec‐
624 tion. The blue arrow shows the last reported direction of your friend.
625 The time is transmitted as UTC, but shown on the display as your local
627 time, so it is also correct if your friend lives in another time zone.
628 The server uses port 50123 (UDP), so be sure that you open the port in
630 your firewall. The server needs no root privileges and should run as
631 normal user or a special user with no privileges. The server was NOT
632 tested for security.
633 There is a friends server running on www.gpsdrive.cc, you can try it if
635 you enable it in the settings menu.
636 You can also send messages to other mobile targets (Misc. Menu/Mes‐
638 sages)
639
643 The address for the mailing list is gpsdrive@warbase.selwerd.nl
644 Subscribing can be done by sending a mail containing subscribe gpsdrive
646 to majordomo@warbase.selwerd.nl
648
651 Please send bug reports to the author. Report version (gpsdrive -v),
652 screen size and info how to reproduce the bug. It is also a big help to
653 run gpsdrive for a minute with the -d option and send me the output.
654 If gpsdrive crashes with a segfault, I need a backtrace of the program
656 in addition. To create a backtrace do following:
657 Extract the tar file, change to gpsdrive directory and do
659 ./configure --with-debug
660 make clean
661 make
662 cd src
663 gdb ./gpsdrive
664 Inside the debugger do:
666 run (if you use arguments write it after run)
668 When you get the segfault type in:
670 bt
672 and send me this output.
674
677 Fritz Ganter
678 E-Mail: ganter@ganter.at
679 http://www.gpsdrive.cc
680
682 This program is distributed in the hope that it will be useful, but
683 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
684 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
685 Public License for more details.
686
689 Copyright (c) 2001-2004 by Fritz Ganter
690 This program is free software; you can redistribute it and/or modify it
691 under the terms of the GNU General Public License as published by the
692 Free Software Foundation; either version 2 of the License, or (at your
693 option) any later version.
694 GPSDRIVE(1)