1GPSDRIVE(1) General Commands Manual GPSDRIVE(1)
2
6 gpsdrive - displays GPS position on a map
7
9 gpsdrive [options]
10
13 This manual page explains the basic functions of GpsDrive 2.11 and
14 additional information regarding map setup and interfacing with support
15 software.
16 Within GpsDrive nearly all buttons have tooltips and there is also a
18 HELP window describing the usage of mouse buttons and keyboard short‐
19 cuts.
20 For additional information concerning advanced topics consult the spe‐
22 cialized README files, e.g. README.kismet, etc.
23
27 GpsDrive is a car (bike, ship, plane, foot) navigation system. It will
28 display your position on a map, record your track, and a number of
29 other handy functions.
30 GpsDrive connects to a GPS receiver and displays your position on a
32 zoomable map. The maps are auto-selected depending on your position.
33 You can choose the preferred map scale, which the program then tries to
34 match from the available maps. Basic worldwide maps are provided and
35 tools are included to help you add your own localized maps.
36 GpsDrive will work with the vast majority of GPS receivers which output
38 NMEA sentences to a serial device, and any USB GPS binary protocol
39 known to the Gpsd software, which handles the back-end communication
40 for GpsDrive. See the Gpsd website (http://gpsd.berlios.de) for an
41 extensive list of GPS receivers known to work with that software. In
42 most cases your GPS will "just work".
43 "Gpsd is a service daemon that monitors one or more GPSes attached to a
45 host computer through serial or USB ports, making all data on the loca‐
46 tion/course/velocity of the sensors available to be queried on a TCP
47 port of the host computer. With gpsd, multiple GPS client applications
48 (such as navigational and wardriving software) can share access to
49 GPSes without contention or loss of data."
50 You must install and launch gpsd before running GpsDrive.
52
56 Do not use GpsDrive as a primary means of navigation!
57 Keep your eyes on the road and hands on the wheel.
58 This program is distributed in the hope that it will be useful, but
60 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
61 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
62 Public License (GPL) for more details.
63
67 -?, --help
68 Displays a short help message.
69 -e, --embedded
71 Don't show the GUI; for use in external GTK apps.
72 -f, --force-position
74 Force display of position even if the GPS fix is invalid. Before
75 a GPS has a fix it often reports its position as 0,0. And if it
76 has lost a fix some makes of GPS will repeat the last known
77 position together with a fix-is-bad indicator. Normally (with‐
78 out this flag) GpsDrive skips plotting these points. Useful for
79 debugging.
80 -i, --ignore-checksum
82 Ignore NMEA checksum. (risky, only for broken GPS receivers)
83 -p, --explore-mode
85 Start in Explore Mode. This will let you explore around your
86 maps independently of your GPS position (or lack thereof).
87 -s, --nosplash
89 Don't show the startup splash screen.
90 -t, --touchscreen
92 Set this special mode if you only have a single mouse button,
93 for example when using GpsDrive on a touchscreen display.
94 -v, --verbose
96 Displays some basic debug information to the terminal as the
97 program runs.
98 -x, --use-DBUS
100 Use DBUS for communication with gpsd; this disables socket com‐
101 munication.
102 -A, --alt-offset=<OFFSET>
104 Adjust the displayed altitude by adding this value.
105 -B, --gpsd-server=<SERVER>
107 Server name of the NMEA server. You can connect your GPS
108 receiver to a remote host which is running gpsd and display the
109 position on your local machine.
110 -C, --config-file=<FILE>
112 Set this if you wish to use an alternative configuration file.
113 -D, --debug=<LEVEL>
115 Set the debugging level. A level of 0 will show no debug infor‐
116 mation, while a level of 100 will show a lot of debugging infor‐
117 mation. If you have problems or program crashes, set this high
118 enough to display relevant information send this output to the
119 authors. See also the BUGS section below.
120 -F, --friends-server=<SERVERFILE>
122 Select a friends server to exchange position information with
123 other people, e.g. friendsd.gpsdrive.de. You can also set this
124 from the Preferences/Friends menu. You can start your own
125 friends server with the included friendsd program. More details
126 are in the FRIENDSD section below.
127 -G, --geometry=<GEOMETRY>
129 Specify the window geometry, e.g. 800x600.
130 -M, --gui-mode=[car|pda|desktop]
132 Set GUI mode. The default layout is 'desktop'. Car modes sets up
133 the display in a fullscreen mode suitable for use with a small
134 LCD touchscreen. PDA mode dedicates even more screen real-estate
135 to the map, controls are hidden behind tabs.
136 -N, --nmeaout=<FILE>
138 Set a serial device, PTY master, or file to send NMEA sentences
139 to. This is useful if you use GpsDrive in simulation mode to
140 provide other GPS applications with test data.
141 -S, --screenshot=<PATH>
143 Take auto-screenshots of different GUI windows then exit. Image
144 files will be saved to the specified path. Don't touch gpsdrive
145 while this is running!
146 -T, --run-test
148 Run some internal unit tests and then exit.
149 --version
151 Shows the program version together with the SVN revision of the
152 main gpsdrive.c source. If you send a bug report, also include
153 this output.
154 --display=<DISPLAY>
156 The X-Window display to use.
157
161 Start GPSD
162 This program runs as daemon in background and provides a server which
163 sends the GPS data on port number 2947. You can download and learn more
164 about gpsd at http://gpsd.berlios.de.
165 Once gpsd is running you can monitor the raw NMEA output of your GPS
167 with telnet localhost 2947 and after the connection is made hit the R
168 key to see the NMEA sentences. You can use the xgps program that comes
169 with gpsd for a more comprehensive test.
170 If you have connected a GPS receiver, and are successfully communicat‐
172 ing with it, you will see GpsDrive's signal strength indicator turn
173 from red to green. By clicking on the signal strength indicator you can
174 open the Satellite Info window which will show you information about
175 the satellites in view.
176 To calculate a 2D position the GPS must have at least 3 satellites in
178 view. To calculate altitude you need at least 4 satellites. The
179 antenna of your GPS receiver must have free sight to the sky, so you
180 cannot expect to use it indoors. More satellites gives you a better
181 accuracy.
182 If your receiver can not see enough satellites with a usable signal,
184 the signal level indicator is red. If your signal is ok and gives a
185 valid position, the Satellite Info indicator is green.
186 You can restart the connection to gpsd in the GPS tab of the Prefer‐
188 ences menu.
189
193 Start GpsDrive as a normal user with: gpsdrive from your shell, if you
194 want another language see the LOCALISATION section.
195 On some distributions you may find a "GpsDrive" entry in your Gnome or
197 KDE menu.
198 It is important that you have installed GpsDrive as root, so it can
200 find the necessary files. Don't start GpsDrive as root!
201 You can use GpsDrive without a GPS device connected. GpsDrive can
203 automatically start in Simulation mode if no working GPS receiver is
204 connected and no gpsd is running. The GPS signal level indicator is
205 replaced with a message indicating the mode.
206 In simulation mode the pointer will move by itself on the map towards
208 the target position. It may be switched permanently on or off in the
209 Preferences menu.
210 Modes Of Operation
214 GpsDrive operates in three modes:
215 Normal mode:
217 This mode is entered if you have a GPS receiver connected. The cursor
218 is at the position your GPS receiver sends.
219 Black and red arrows show your position on the map. The red arrow
220 points to your selected target (aka "Bearing"), and the black arrow
221 shows the direction in which you are moving (aka "Heading").
222 When the GPS is not sending a valid position the arrows blink.
223 Simulation mode
225 If GpsDrive does not find a GPS receiver when the program starts, it
226 shows the last known position and the cursor will move towards the tar‐
227 get you set. You can set the target with a right-mouse click on the map
228 or by selecting a waypoint from the Find dialog. The target appears as
229 a cross-hair and is available in all modes.
230 Explore mode
232 In this mode you can temporarily change the cursor position for looking
233 around and jumping to other positions (e.g. for downloading maps). The
234 lat/lon position shown in the dashboard is that of the current mouse
235 position.
236 This mode is selected by ticking the "Explore mode" box in the Map Con‐
237 trol window, or if you "Jump to POI" in the Find window. The Jump but‐
238 ton simply jumps to the current target, so it is useful to move the
239 target to a waypoint/POI first by selecting one from the list.
240 In this mode GpsDrive does not show your real position and the posi‐
241 tioning arrows are replaced with a box.
242 You can relocate your position with a simple left-mouse click on the
243 map or with the arrow keys (including diagonals on the keypad). Maps
244 are automatically scrolled or load the next map when you click near the
245 border.
246 To leave Explore Mode untick the "Explore mode" entry in the Map Con‐
247 trol window, or middle or right-mouse click on the map. If a right-
248 mouse click is used the target is reset to that position in the
249 process.
250 You can change the preferred map scale with mouse wheel, or if there is
253 no mouse wheel, with Shift-left and right mouse click. This works from
254 any mode.
255 Please have a look in the Help menu in GpsDrive to learn more about
257 available keyboard shortcuts and mouse functions.
258
262 OpenStreetMap Maps
263 GpsDrive now supports OSM maps with the help of the Mapnik renderer.
264 To activate this mode you have to build GpsDrive with the Mapnik option
265 enabled.
266 Map Download
270 You can easily download maps from the internet with the Download tool.
271 This is found in the Options -> Maps menu. A preview of already down‐
272 loaded maps near to the current preferred mapscale are shown as yellow
273 rectangles drawn over the map. The area to be downloaded is drawn as a
274 green rectangle over the map. Reposition the area to be downloaded with
275 a left-mouse click. Map scales given in the GUI for OpenStreetMap tiles
276 are only approximate, the true scale at the selected latitude will be
277 calculated when the map is downloaded - this can vary by up to 50% at
278 high latitudes and is a limitation of the popular Web Tile method.
279 LANDSAT maps use a WMS server and will match the requested scale
280 exactly.
281 If you have Mapnik set up you can also use the gpsdrive_mapnik_gentiles
283 utility to pre-render maps of varying scale directly from your PostGIS
284 database. There is also a program called gpsfetchmap.pl provided with
285 GpsDrive which can be used to automatically download a series of maps
286 covering a larger area from a number of online map servers.
287 Please consider the copyright information and terms of service of map
288 providers if you want to use their maps! Do not misuse this service by
289 downloading more maps than you need! You will risk being blocked by
290 these servers, and possibly cause trouble for the GpsDrive project.
291 If you must access the internet via a proxy server, set the HTTP_PROXY
293 or http_proxy environment variable to a value like
294 http://proxy.provider.com:3128 where 3128 in this example is the proxy
295 port.
296 About Maps
300 GpsDrive stores an index of your maps in a file called "map_koord.txt"
301 in your ~/.gpsdrive/maps/ directory. You can use another directory for
302 your maps if you like, to change this set the appropriate directory in
303 the Preferences menu.
304 Here is a sample of its contents:
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 column is the filename, then comes the latitude, the longi‐
315 tude and the scale of the map. Typical scales for all of Europe might
316 be 1:10,000,000, and 1:100,000 for a town. To see detailed streets in a
317 city, choose a scale like 1:10,000 or 1:5,000.
318 You can figure out the exact "scale" factor by meters/pixel *
320 2817.947378. The 2817 number is derived from some ancient screen dpi
321 converted into pixels/meter.
322 GpsDrive selects the map with the best scale for your position. So you
324 will want to get maps of different scales. e.g. You should have maps
325 for Europe, Austria, and Vienna if you want to drive in Vienna.
326 European decimal place:
329 While the decimal points in way.txt must always be a dot ('.'), in
330 map_koord.txt '.' or ',' are possible. If you download maps from within
331 the program, GpsDrive writes the map_koord.txt respecting your
332 LC_NUMERIC setting.
333 Can I use other maps?
337 You can also use your own (self drawn, scanned, exported from GIS, ...)
338 maps. The maps must be in PNG, JPEG, GIF, TIFF, or another common file
339 format (the format must be recognized by the gdk-pixbuf library). The
340 lat/long coordinates you write into the "map_koord.txt" file is mea‐
341 sured at the center of the map. The map must have a size of 1280x1024
342 pixels!
343 Important! The maps must be named "map_*" for UTM-like projections
345 (lat:lon = 1:cos(lat)) and "top_*" for lat/lon Plate carrée projection
346 (lat:lon = 1:1). The prefix is given so that gpsdrive knows how to
347 scale the maps correctly. Alternatively the maps can be stored without
348 prefix in subdirectories of $HOME/.gpsdrive/maps/ which end in "_map"
349 or "_top". The georeferencing information (center coordinate and scale
350 factor) for the maps in those subdirectories must be recorded in the
351 main "map_koord.txt" file, typically stored in the ~/.gpsdrive/maps/
352 directory. To avoid distortion, anything more global than 1:150k to
353 1:500k should use "top_*".
354 Beware if you are using an image originating from a map projection with
356 a significant deviation between true north and the map projection's
357 local +y direction (known as the Convergence Angle). GpsDrive assumes
358 that true north is always directly up! i.e. the Central Meridian of the
359 map projection is located at the map tile's center. For some map pro‐
360 jections and areas of the country this can be a really bad assumption
361 and your map will be significantly rotated. This effect is most visible
362 at map scales covering a large area. This does not affect lat/lon maps.
363 There is an "import assistant" built in. Use it to import your non-geo‐
365 referenced maps. If can be found in the menus under Options -> Maps.
366
370 Importing waypoints
371 The manual way:
372 You may create a file "way.txt" in your ~/.gpsdrive directory which
374 looks like:
375 DFN-Cert 53.577694 9.991263 FRITZ
377 Finkenwerder 53.541765 9.842541 AIRPORT
378 Fritz_Wohnung 53.582700 9.971390 FRITZ
379 The rows are: {label latitude longitude waypoint-type}. The label may
381 not exceed 80 characters or contain spaces. Use underscores (_) in
382 place of spaces, these will automatically be converted into spaces by
383 the program. A blank label is denoted by a single underscore.
384 Latitude and longitude may be in decimal degrees or in the form of
386 DDDdMM'SS"[NSEW] or DDD:MM:SS[NSEW]. Seconds or minutes and seconds may
387 be omitted or in decimal form. Thus the following are valid:
388 42d30'55"N, 75:30.6425W, -46.25. In fact the delimiters can be any‐
389 thing except numbers, ".", or spaces.
390 You may omit the waypoint type.
392 Following the waypoint-type are (optionally) three space separated
394 zeros, a proximity radius (in integer meters), and a comment. Comments
395 follow the same space/underscore rules as label names, and are limited
396 to 255 characters.
397 You can create any number of way-*.txt files and chose between them
399 from the Preferences menu.
400 There is no need to create the way.txt file yourself, you can add the
402 waypoints with GpsDrive using the "x" key. See the Help menu.
403 Add new waypoints
407 Waypoints created by GpsDrive will be stored in a SQLite database file
408 locacted at ~/.gpsdrive/waypoints.db.
409 You can add new waypoints in two simple ways:
411 o To add a waypoint at the current (GPS) position simply press CTRL and
413 RIGHT-mouse-click. You can also press the x key for this.
414 o To add a waypoint at the mouse position, simply press CTRL and LEFT-
416 mouse-click. You can also press the y key for this.
417 In the popup window give the waypoint a name (spaces will be converted
419 to underscores) and choose a waypoint type (see below for predefined
420 waypoint types).
421 Waypoint icons
425 At the moment there a three different icon themes available, but not
426 all have distinct icons for every type. You can choose the themes in
427 the Preferences menu. The possible themes are: "square.big",
428 "square.small" and "classic".
429 SQL support
433 For managing a larger number of waypoints SQL support is essential.
434 Don't be afraid, SQLite doesn't need much in the way of resources, is
435 very fast, and makes the management (including selection of waypoint
436 types) of the waypoints much easier. In SQL mode you can select the
437 waypoints to display in the Preferences menu.
438
442 A route is a list of waypoints. GpsDrive guides you from one waypoint
443 to the next on the route.
444 You can add waypoints to a route using the Find waypoint (select tar‐
446 get) window. Find some POIs, then open the Route Listing window with
447 the Edit Route button in the Find window or from the button on the main
448 window. When you click on waypoints in the the Find window's Results
449 list they will be added to the Route List. Click "Start Route" when you
450 are ready to begin your journey. It is also possible to import a com‐
451 plete route from a GPX file.
452 You can add comments to a waypoint which will be spoken by the speech
454 system and also be shown in the map window as scrolling text.
455 Comments for routes
458 To add comments create a file with the same name as the waypoint file,
459 but change the suffix to .dsc, i.e way-trip.txt and way-trip.dsc, then
460 enter comments in the way-*.dsc file in the manner of:
461 $waypoint_name Text which is displayed and spoken
463 $next_waypoint_name Some more text
465 Example:
467 $Fritz_Wohnung Hier wohnt Fritz, der Autor von diesem Programm. Er
469 freut sich auf Besuch und eine Einladung zu einem saftigen Steak.
470 $Hubertus Hier wohnt Hubertus, ein Freund von Fritz.
472 There is no limit of the length of the comment. It is important is to
474 start the line with '$name' and the comment on the following line.
475 Route planning
479 There is no shortest-path route planning feature at the moment. We are
480 keenly watching developments over at the OpenStreetMap project for uti‐
481 lizing software such as pgRouting and DGLib.
482
486 GpsDrive supports kismet. Kismet is a 802.11b wireless network (WLAN)
487 sniffer. If you have kismet running, gpsdrive will detect it when the
488 program starts and show new WLAN access points in real-time on the map.
489 It is necessary to use SQL mode when using GpsDrive with Kismet. WLAN
490 access points which are already stored in the SQL database from prior
491 war-drivings are ignored. If you have enabled GpsDrive's voice output,
492 you will hear information about the newly found access point.
493 For more details have a look at the README.kismet file.
495
499 The program will display messages in English, German, French, Italian,
500 Dutch, Dansk, Hungarian, Slovak, Swedish, Turkish or Spanish if your
501 language is set either with LANG or LANGUAGE. LANGUAGE overrides all
502 other settings. Call "locale" to see the settings and call "set" if
503 LANG or LANGUAGE is set. For German do:
504 export LANGUAGE=de
506 and then call gpsdrive in this shell.
507 You can also start it with the line LANGUAGE=de gpsdrive without set‐
509 ting the language for the shell.
510 Sometimes it is necessary use LANG instead of LANGUAGE.
512 If your own language isn't available, please contact the GpsDrive
514 Development Team if you want to make the translation. No programming
515 experience is necessary!
516
520 If you want speech output you have to install speech dispatcher and at
521 least one of the supported speech synthesizers (festival, espeak, ...).
522 See http://www.freebsoft.org/speechd for information.
523 For German output you can use espeak or the German festival from
525 http://www.ims.uni-stuttgart.de/phonetik/synthesis/index.html
526 If you have a functional festival software call it as server with:
528 festival --server
530 When you start GpsDrive it will detect a running speechd and speak some
532 status information. When speech output is enabled an additional Mute
533 button is available to switch off sound output.
534 GpsDrive tries to use the correct language for your locale. If the
536 voice used is not correct, you can choose another one in the Prefer‐
537 ences, if installed.
538
542 A server program called friendsd comes with GpsDrive. It acts as a
543 server for coordinating the position of your friends. After enabling it
544 in the Preferences menu you can see the position of all GpsDrivers con‐
545 nected to this server.
546 You will see the position of your friends as a car symbol on the map,
548 including the name, time, day of week and the speed of their last con‐
549 nection. The blue arrow shows the last reported direction of your
550 friend.
551 The time is transmitted as UTC, but shown on the display in your local
553 time, so it is also correct if your friend lives in another time zone.
554 The server uses port 50123 (UDP), so be sure that you open the port in
556 your firewall. The server needs no root privileges and should run as a
557 normal user or a special user with no privileges. The server has NOT
558 been tested for security.
559 There is a friends server running on friendsd.gpsdrive.de, you can try
561 it if you enable it in the settings menu.
562 You can also send messages to other mobile targets (Options/Send Mes‐
564 sage)
565
569 The primary means of support and coordination of program development
570 happens on the GpsDrive mailing list.
571 Information about subscription and a searchable archive can be found at
573 http://www.gpsdrive.de/support.shtml.
574
578 Please send bug reports to the development team! If we don't know about
579 them we can't fix them and then they remain unfixed.
580 File bug reports in our tracker at http://bugzilla.gpsdrive.de/. You
582 will need to create yourself a SourceForge account at that site, it is
583 rather painless and only takes a minute. This ensures you get feedback
584 about the bug and we can communicate with you if we need further infor‐
585 mation.
586 Please report the version (gpsdrive --version), screen size, platform,
588 and as much specific information about how to reproduce the bug as pos‐
589 sible. Whenever possible cut and paste exact error messages and take
590 screenshots. It is helpful to run gpsdrive for a minute with the -D
591 debug level option set high and send us the output.
592 If GpsDrive crashes with a SegFault, we will need a backtrace of the
594 program as well. Assuming GpsDrive was built with debugging symbols and
595 the binaries were not stripped of them, create a backtrace by running
596 the GpsDrive the GNU debugging software as follows:
597 gdb `which gpsdrive`
599 Inside the debugger do:
601 run (if you use command line arguments place these after the word
603 run)
604 When you get the SegFault type in:
606 bt full
608 and send us this output. This gives us an indication of exactly what
610 the program was doing when it broke.
611
615 GpsDrive was originally written by Fritz Ganter. Today it is maintained
616 and improved by a worldwide team of volunteer developers centered
617 around the http://www.gpsdrive.de website. The source code repository,
618 bug tracker, and collaborative wiki help site are hosted at http://gps‐
619 drive.sourceforge.net. A partial list of contributing authors can be
620 found in the Help->About menu within the program.
621
625 This program is distributed in the hope that it will be useful, but
626 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
627 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
628 Public License for more details.
629
633 Copyright (c) 2001-2004 by Fritz Ganter
634 Copyright (c) 2005-2009 by the members of the GpsDrive Development Team
635 This program is free software; you can redistribute it and/or modify it
637 under the terms of the GNU General Public License as published by the
638 Free Software Foundation; either version 2 of the License, or (at your
639 option) any later version. Indeed, you are encouraged to do so!
640 This document last modified
643 $Date: 2010-05-20 11:04:34 +0200 (Thu, 20 May 2010) $
644 GPSDRIVE(1)