gpsdrive (1) - Linux Manuals

gpsdrive: displays GPS position on a map

Command to display gpsdrive manual in Linux: $ man 1 gpsdrive

NAME

gpsdrive - displays GPS position on a map

SYNOPSIS

gpsdrive [options]

About this manual page

This manual page explains the basic functions of GpsDrive 2.10 and additional information regarding map setup and interfacing with support software.

Within GpsDrive nearly all buttons have tooltips and there is also a HELP window describing the usage of mouse buttons and keyboard shortcuts.

For additional information concerning advanced topics consult the specialized README files, e.g. README.kismet, etc.

DESCRIPTION

GpsDrive is a car (bike, ship, plane, foot) navigation system. It will display your position on a map, record your track, and a number of other handy functions.

GpsDrive connects to a GPS receiver and displays your position on a zoomable map. The maps are auto-selected depending on your position. You can choose the preferred map scale, which the program then tries to match from the available maps. Basic worldwide maps are provided and tools are included to help you add your own localized maps.

GpsDrive will work with the vast majority of GPS receivers which output NMEA sentences to a serial device, and any USB GPS binary protocol known to the Gpsd software, which handles the back-end communication for GpsDrive. See the Gpsd website (http://gpsd.berlios.de) for an extensive list of GPS receivers known to work with that software. In most cases your GPS will "just work".

"Gpsd is a service daemon that monitors one or more GPSes attached to a host computer through serial or USB ports, making all data on the location/course/velocity of the sensors available to be queried on a TCP port of the host computer. With gpsd, multiple GPS client applications (such as navigational and wardriving software) can share access to GPSes without contention or loss of data."

You must install and launch gpsd before running GpsDrive.

DISCLAIMER

Do not use GpsDrive as a primary means of navigation!
Keep your eyes on the road and hands on the wheel.

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 (GPL) for more details.

OPTIONS

-?, --help

Displays a short help message.

-e, --embedded

Don't show the GUI; for use in external GTK apps.

-f, --force-position

Force display of position even if the GPS fix is invalid. Before a GPS has a fix it often reports its position as 0,0. And if it has lost a fix some makes of GPS will repeat the last known position together with a fix-is-bad indicator. Normally (without this flag) GpsDrive skips plotting these points. Useful for debugging.

-i, --ignore-checksum

Ignore NMEA checksum. (risky, only for broken GPS receivers)

-p, --explore-mode

Start in Explore Mode. This will let you explore around your maps independently of your GPS position (or lack thereof).

-s, --nosplash

Don't show the startup splash screen.

-t, --touchscreen

Set this special mode if you only have a single mouse button, for example when using GpsDrive on a touchscreen display.

-v, --verbose

Displays some basic debug information to the terminal as the program runs.

-x, --use-DBUS

Use DBUS for communication with gpsd; this disables socket communication.

-A, --alt-offset=<OFFSET>

Adjust the displayed altitude by adding this value.

-B, --gpsd-server=<SERVER>

Server name of the NMEA server. You can connect your GPS receiver to a remote host which is running gpsd and display the position on your local machine.

-C, --config-file=<FILE>

Set this if you wish to use an alternative configuration file.

-D, --debug=<LEVEL>

Set the debugging level. A level of 0 will show no debug information, while a level of 100 will show a lot of debugging information. If you have problems or program crashes, set this high enough to display relevant information send this output to the authors. See also the BUGS section below.

-F, --friends-server=<SERVERFILE>

Select a friends server to exchange position information with other people, e.g. friendsd.gpsdrive.de. You can also set this from the Preferences/Friends menu. You can start your own friends server with the included friendsd program. More details are in the FRIENDSD section below.

-G, --geometry=<GEOMETRY>

Specify the window geometry, e.g. 800x600.

-M, --gui-mode=[car|pda|desktop]

Set GUI mode. The default layout is 'desktop'. Car modes sets up the display in a fullscreen mode suitable for use with a small LCD touchscreen. PDA mode dedicates even more screen real-estate to the map, controls are hidden behind tabs.

-N, --nmeaout=<FILE>

Set a serial device, PTY master, or file to send NMEA sentences to. This is useful if you use GpsDrive in simulation mode to provide other GPS applications with test data.

-S, --screenshot=<PATH>

Take auto-screenshots of different GUI windows then exit. Image files will be saved to the specified path. Don't touch gpsdrive while this is running!

-T, --run-test

Run some internal unit tests and then exit.

--version

Shows the program version together with the SVN revision of the main gpsdrive.c source. If you send a bug report, also include this output.

--display=<DISPLAY>

The X-Window display to use.

CONNECTING A GPS RECEIVER

Start GPSD
This program runs as daemon in background and provides a server which sends the GPS data on port number 2947. You can download and learn more about gpsd at http://gpsd.berlios.de.

Once gpsd is running you can monitor the raw NMEA output of your GPS with telnet localhost 2947 and after the connection is made hit the R key to see the NMEA sentences. You can use the xgps program that comes with gpsd for a more comprehensive test.

If you have connected a GPS receiver, and are successfully communicating with it, you will see GpsDrive's signal strength indicator turn from red to green. By clicking on the signal strength indicator you can open the Satellite Info window which will show you information about the satellites in view.

To calculate a 2D position the GPS must have at least 3 satellites in view. To calculate altitude you need at least 4 satellites. The antenna of your GPS receiver must have free sight to the sky, so you cannot expect to use it indoors. More satellites gives you a better accuracy.

If your receiver can not see enough satellites with a usable signal, the signal level indicator is red. If your signal is ok and gives a valid position, the Satellite Info indicator is green.

You can restart the connection to gpsd in the GPS tab of the Preferences menu.

USAGE

Start GpsDrive as a normal user with: gpsdrive from your shell, if you want another language see the LOCALISATION section.

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. GpsDrive can automatically start in Simulation mode if no working GPS receiver is connected and no gpsd is running. The GPS signal level indicator is replaced with a message indicating the mode.

In simulation mode the pointer will move by itself on the map towards the target position. It may be switched permanently on or off in the Preferences menu.

Modes Of Operation

GpsDrive operates in three modes:

Normal mode:
This mode is entered if you have a GPS receiver connected. The cursor is at the position your GPS receiver sends.
Black and red arrows show your position on the map. The red arrow points to your selected target (aka "Bearing"), and the black arrow shows the direction in which you are moving (aka "Heading").
When the GPS is not sending a valid position the arrows blink.

Simulation mode
If GpsDrive does not find a GPS receiver when the program starts, it shows the last known position and the cursor will move towards the target you set. You can set the target with a right-mouse click on the map or by selecting a waypoint from the Find dialog. The target appears as a cross-hair and is available in all modes.

Explore mode
In this mode you can temporarily change the cursor position for looking around and jumping to other positions (e.g. for downloading maps). The lat/lon position shown in the dashboard is that of the current mouse position.
This mode is selected by ticking the "Explore mode" box in the Map Control window, or if you "Jump to POI" in the Find window. The Jump button simply jumps to the current target, so it is useful to move the target to a waypoint/POI first by selecting one from the list.
In this mode GpsDrive does not show your real position and the positioning arrows are replaced with a box.
You can relocate your position with a simple left-mouse click on the map or with the arrow keys (including diagonals on the keypad). Maps are automatically scrolled or load the next map when you click near the border.
To leave Explore Mode untick the "Explore mode" entry in the Map Control window, or middle or right-mouse click on the map. If a right-mouse click is used the target is reset to that position in the process.

You can change the preferred map scale with mouse wheel, or if there is no mouse wheel, with Shift-left and right mouse click. This works from any mode.

Please have a look in the Help menu in GpsDrive to learn more about available keyboard shortcuts and mouse functions.

MAPS

OpenStreetMap Maps

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

Map Download

You can easily download maps from the internet with the Download tool. This is found in the Options -> Maps menu. A preview of already downloaded maps near to the current preferred mapscale are shown as yellow rectangles drawn over the map. The area to be downloaded is drawn as a green rectangle over the map. Reposition the area to be downloaded with a left-mouse click.

There is also a program called gpsfetchmap.pl provided with GpsDrive which can be used to automatically download a series of maps covering a larger area.
Please consider the copyright information and terms of service of map providers if you want to use their maps! Do not misuse this service by downloading more maps than you need! You will risk being blocked by these servers, and possibly cause trouble for the GpsDrive project.

If you must access the internet via a proxy server, set the HTTP_PROXY or http_proxy environment variable to a value like http://proxy.provider.com:3128 where 3128 in this example is the proxy port.

About Maps

GpsDrive stores an index of your maps in a file called "map_koord.txt" in your ~/.gpsdrive/maps/ directory. You can use another directory for your maps if you like, to change this set the appropriate directory in the Preferences menu.

Here is a sample of its contents:

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 column is the filename, then comes the latitude, the longitude and the scale of the map. Typical scales for all of Europe might be 1:10,000,000, and 1:100,000 for a town. To see detailed streets in a city, choose a scale like 1:10,000 or 1:5,000.

You can figure out the exact "scale" factor by meters/pixel * 2817.947378. The 2817 number is derived from some ancient screen dpi converted into pixels/meter.

GpsDrive selects the map with the best scale for your position. So you will want to get maps of different scales. e.g. You should have maps for Europe, Austria, and Vienna if you want to drive in Vienna.

European decimal place:

While 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, exported from GIS, ...) maps. The maps must be in PNG, JPEG, GIF, TIFF, or another common file format (the format must be recognized by the gdk-pixbuf library). The lat/long coordinates you write into the "map_koord.txt" file is measured at 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/maps/ which end in "_map" or "_top". The georeferencing information (center coordinate and scale factor) for the maps in those subdirectories must be recorded in the main "map_koord.txt" file, typically stored in the ~/.gpsdrive/maps/ directory. To avoid distortion, anything more global than 1:150k to 1:500k should use "top_*".

Beware if you are using an image originating from a map projection with a significant deviation between true north and the map projection's local +y direction (known as the Convergence Angle). GpsDrive assumes that true north is always directly up! i.e. the Central Meridian of the map projection is located at the map tile's center. For some map projections and areas of the country this can be a really bad assumption and your map will be significantly rotated. This effect is most visible at map scales covering a large area. This does not affect lat/lon maps.

There is an "import assistant" built in. Use it to import your non-georeferenced maps. If can be found in the menus under Options -> Maps.

WAYPOINTS AND POI

Importing waypoints

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}. The label may not exceed 80 characters or contain spaces. Use underscores (_) in place of spaces, these will automatically be converted into spaces by the program. A blank label is denoted by a single underscore.

Latitude and longitude may be in decimal degrees or in the form of DDDdMM'SS"[NSEW] or DDD:MM:SS[NSEW]. Seconds or minutes and seconds may be omitted or in decimal form. Thus the following are valid: 42d30'55"N, 75:30.6425W, -46.25. In fact the delimiters can be anything except numbers, ".", or spaces.

You may omit the waypoint type.

Following the waypoint-type are (optionally) three space separated zeros, a proximity radius (in integer meters), and a comment. Comments follow the same space/underscore rules as label names, and are limited to 255 characters.

You can create any number of way-*.txt files and chose between them from the Preferences menu.

There is no need to create the way.txt file yourself, you can add the waypoints with GpsDrive using the "x" key. See the Help menu.

Add new waypoints

Waypoints created by GpsDrive will be stored in a SQLite database file locacted at ~/.gpsdrive/waypoints.db.

You can add new waypoints in two simple 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 for this.

o To add a waypoint at the mouse position, simply press CTRL and LEFT-mouse-click. You can also press the y key for this.

In the popup window give the waypoint a name (spaces will be converted to underscores) and choose a waypoint type (see below for predefined waypoint types).

Waypoint icons

At the moment there a three different icon themes available, but not all have distinct icons for every type. You can choose the themes in the Preferences menu. The possible themes are: "square.big", "square.small" and "classic".

SQL support

For managing a larger number of waypoints SQL support is essential. Don't be afraid, SQLite doesn't need much in the way of 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 Preferences menu.

ROUTES

A route is a list of waypoints. GpsDrive guides you from one waypoint to the next on the route.

You can add waypoints to a route using the Find waypoint (select target) window. Find some POIs, then open the Route Listing window with the Edit Route button in the Find window or from the button on the main window. When you click on waypoints in the the Find window's Results list they will be added to the Route List. Click "Start Route" when you are ready to begin your journey. It is also possible to import a complete route from a GPX file.

You can 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 comments in the way-*.dsc file in the manner of:

$waypoint_name Text which is displayed and spoken

$next_waypoint_name Some more text

Example:

$Fritz_Wohnung Hier wohnt Fritz, der Autor von diesem Programm. Er freut sich auf Besuch und eine Einladung zu einem saftigen Steak.
$Hubertus Hier wohnt Hubertus, ein Freund von Fritz.

There is no limit of the length of the comment. It is important is to start the line with '$name' and the comment on the following line.

Route planning

There is no shortest-path route planning feature at the moment. We are keenly watching developments over at the OpenStreetMap project for utilizing software such as pgRouting and DGLib.

KISMET support

GpsDrive supports kismet. Kismet is a 802.11b wireless network (WLAN) sniffer. If you have kismet running, gpsdrive will detect it when the program starts and show new WLAN access points in real-time on the map. It is necessary to use SQL mode when using GpsDrive with Kismet. WLAN access points which are already stored in the SQL database from prior war-drivings are ignored. If you have enabled GpsDrive's voice output, you will hear information about the newly found access point.

For more details have a look at the README.kismet file.

LOCALISATION

The program 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 it is necessary use LANG instead of LANGUAGE.

If your own language isn't available, please contact the GpsDrive Development Team if you want to make the translation. No programming experience is necessary!

SPEECH OUTPUT

If you want speech output you have to install speech dispatcher and at least one of the supported speech synthesizers (festival, espeak, ...).
See http://www.freebsoft.org/speechd for information.

For German output you can use espeak or the German festival from
http://www.ims.uni-stuttgart.de/phonetik/synthesis/index.html

If you have a functional festival software call it as server with:

festival --server

When you start GpsDrive it will detect a running speechd and speak some status information. When speech output is enabled an additional Mute button is available to switch off sound output.

GpsDrive tries to use the correct language for your locale. If the voice used is not correct, you can choose another one in the Preferences, if installed.

FRIENDSD server

A server program called friendsd comes with GpsDrive. It acts as a server for coordinating the position of your friends. After enabling it in the Preferences menu you can see the position of all GpsDrivers connected to 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 their last connection. The blue arrow shows the last reported direction of your friend.

The time is transmitted as UTC, but shown on the display in 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 a normal user or a special user with no privileges. The server has NOT been tested for security.

There is a friends server running on friendsd.gpsdrive.de, you can try it if you enable it in the settings menu.

You can also send messages to other mobile targets (Options/Send Message)

MAILING LIST

The primary means of support and coordination of program development happens on the GpsDrive mailing list.

Information about subscription and a searchable archive can be found at http://www.gpsdrive.de/support.shtml.

BUGS

Please send bug reports to the development team! If we don't know about them we can't fix them and then they remain unfixed.

File bug reports in our tracker at http://bugzilla.gpsdrive.de/. You will need to create yourself a SourceForge account at that site, it is rather painless and only takes a minute. This ensures you get feedback about the bug and we can communicate with you if we need further information.

Please report the version (gpsdrive --version), screen size, platform, and as much specific information about how to reproduce the bug as possible. Whenever possible cut and paste exact error messages and take screenshots. It is helpful to run gpsdrive for a minute with the -D debug level option set high and send us the output.

If GpsDrive crashes with a SegFault, we will need a backtrace of the program as well. Assuming GpsDrive was built with debugging symbols and the binaries were not stripped of them, create a backtrace by running the GpsDrive the GNU debugging software as follows:

gdb `which gpsdrive`

Inside the debugger do:

run (if you use command line arguments place these after the word run)

When you get the SegFault type in:

bt full

and send us this output. This gives us an indication of exactly what the program was doing when it broke.

AUTHORS

GpsDrive was originally written by Fritz Ganter. Today it is maintained and improved by a worldwide team of volunteer developers centered around the http://www.gpsdrive.de website. The source code repository, bug tracker, and collaborative wiki help site are hosted at http://gpsdrive.sourceforge.net. A partial list of contributing authors can be found in the Help->About menu within the program.

WARRANTY

COPYRIGHT

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. Indeed, you are encouraged to do so!

This document last modified

$Date: 2009-06-13 00:14:17 +0200 (Sat, 13 Jun 2009) $