# Usage

## Invocation

If you're using GPSBabel, you will need to know how to do at least two things: read data from a file, and write it to another file. There are four basic options you need to know to do those things:

Command Meaning
- `-i` format Set input format
- `-f` filename Read file
- `-o` format Set output format
- `-F` filename Write output file

Case matters. Notably `-f` (lowercase) sets the input file. `-F` (uppercase) sets the output file.

The format parameters in the above list refer to the names of formats or file types supported by GPSBabel.

`gpsbabel -?`

will always show you the supported file types. In this document, the various supported formats are listed in . The name that you would use on the command line follows the format name in parentheses.

Options are always processed in order from left to right. In practical terms, this means that things you want to read should appear in the command before things you want to write. This sometimes surprises new users as adding options to turn on debugging at the end, for example, doesn't work as the debugging is turned on after all the interesting work is done. The reason for this strict ordering becomes more apparent once you learn about mixing formats and filters.

The filename parameters specify the name of a file to be read or written.

To use GPSBabel in its simplest form, just tell it what you're reading, where to read it from, what you're writing, and what to write it to. For example:

`gpsbabel -i geo -f /tmp/geocaching.loc -o gpx -F /tmp/geocaching.gpx`

tells it to read the file `/tmp/geocaching.loc` in geocaching.com format and create a new file `/tmp/geocaching.gpx` in GPX format. It's important to note that the names have nothing to do with the formats actually used.

This command will read from a Magellan unit attached to the first serial port on a Linux system (device names will vary on other OSes; typically COMx: on Windows) and write them as a geocaching loc file.

Command showing Linux download from Magellan serial and writing to .loc file

`gpsbabel -i magellan -f /dev/ttyS0 -o geo -F mag.loc`

This second command does the same on Microsoft Windows.

Command showing Windows download from Magellan serial and writing to .loc file

`gpsbabel -i magellan -f com1 -o geo -F mag.loc`

Optionally, you may specify -s in any command line. This causes the program to ignore any "short" names that may be present in the source data format and synthesize one from the long name. This is particularly useful if you're writing to a target format that isn't the lowest common denominator but the source data was written for the lowest common denominator. This is useful for writing data from geocaching.com to a GPS so my waypoints have "real" names instead of the 'GC1234' ones that are optimized for receivers of the lowest common denominator. A geocacher using Linux with a Magellan receiver may thus find commands like this useful.

`gpsbabel -s -i geo -f geocaching.loc -o magellan -F /dev/ttyS0`

His counterpart on Windows will find this equivalent

`gpsbabel -s -i geo -f geocaching.loc -o magellan -F com1`

## Suboptions

Many of the available format options in GPSBabel can themselves take options. While we try to make all the formats do the most sensible thing possible without any extra options; this allows great power and flexibility in the operation of the program.

Suboptions are comma separated and immediately follow the option itself. The available suboptions are listed on the individual format pages. We'll make an example from :

`gpsbabel -i gpx -f file.gpx -o kml,deficon="file://myicon.png",lines=0 -F one.kml -o kml -F two.kml`

This command will read the GPX file `file.gpx` and create two KML files. `one.kml` will have the given icon and no lines between track and routepoints. `two.kml` will be created with the defaults used in the KML writer.

Suboptions for the various formats allow you to change serial speeds, pass arguments to filters, change the type of file written, override icon defaults, and lots of other things. The suboptions for each filetype are documented on the page in this document that describes the option itself.

## Advanced Usage

Argument are processed in the order they appear on the command line and are translated internally into a pipeline that data flows through when executed. Normally one would:

- read from one input
- optionally apply filters
- write into one output

but GPSBabel is flexible enough to allow more complicated operations such as reading from several files (potentially of different types), applying a filter, reading more data, then writing the merged data to multiple destinations.

The input file type remains unchanged until a new -i argument is seen. Files are read in the order they appear. So you could merge three input files into one output file with:

Merging multiple files into one

`gpsbabel -i geo -f 1.loc -f 2.loc -f 3.loc -o geo -F big.loc`

You can merge files of different types:

Merging multiple files of differing types.

`gpsbabel -i geo -f 1.loc -i gpx -f 2.gpx -i pcx 3.pcx -o gpsutil -F big.gps`

Writing the same data in multiple output formats.

You can write the same data in different output formats:

`gpsbabel -i geo -f 1.loc -o gpx -F 1.gpx -o pcx -F 1.wpt`

## Route and Track Modes

Most formats supported by GPSBabel will make a reasonable attempt to work transparently with waypoints, tracks, and routes. Some formats, like garmin require the -t flag to work with tracks and -r to work with routes. -w is for waypoints, and is the default. So if you wanted to read all data from a Magellan Meridian GPS receiver into a gpx file, you might use a command like:

`gpsbabel -t -r -w -i magellan -f com1: -o gpx -F backup.gpx`

Tracks and routes are advanced features and don't try to handle every possible hazard that can be encountered during a conversion. If you're merging or converting files of similar limitations, things work very well.

Many of those hazards can be overcome with our filters but there are often compromises to be made. For example, if you have a GPX route that contains 150 turn points but you're sending the route to a GPS receiver that supports only 30 turnpoints, something has to go. One might use our 'simplify' filter to produce a route that retained the 30 most mathematically significant turnpoints but that may not really be the route you had in mind.

Tracks and routes will sometimes be converted to a list of waypoints when necessary, One example is when writing into one of the CSV formats. The inverse operation is not supported right now, so reading the converted track back from CSV will always result in a list of waypoints, not the original track.

The presence of -s on the command line tends to create havoc on tracks and routes since many of these formats rely on internal linkages between such points and renaming them may break those linkages. In general, don't use -s when tracks or routes are present.

## Working with predefined options

GPSBabel can read a file on startup to set defaults for options. All module and filter options may be set this way.

The format of the file is identical to the inifile-format often seen on Windows. Here is an example:

- [Common format settings]
- snupper=Y
- snlen=10
- [gpx]
- gpxver=1.1
- [magellan]
- baud=115200
- [tiger]
- [Garmin categories]
- ; any # from 1 to 16
- 1=fixed waypoints
- 2=temporary waypoints

Each section of the file starts with a '[section]' header followed by any number of lines formatted option=value. Leading and trailing whitespace will be automatically removed from header, option and value items. Lines starting with '#' or ';' will be treated as comments and ignored.

There are three optional sections.

- Common format settings.

  Any option from any of the formats listed here will be used by GPSBabel unless explicitly provided on the command line.

- Common filter settings.

  As above, but for filters.

- Garmin categories

  This allows you to give readable names to the numeric categories used internally in some Garmin devices and the Mapsource formats such as GDB and MPS. This is information is also used by our GPX and garmin_txt formats as well.

By default, GPSBabel tries at startup to load the file named `gpsbabel.ini` from the following locations:

- current working directory

- Windows: all paths "APPDATA", "WINDIR", "SYSTEMROOT" declared in environment.

- Unix like OS'ses: `${HOME}/.gpsbabel/` , `/usr/local/etc/` and `/etc/`

If the `-p` option is specified, the above locations are not searched. Only the filename specified by that option will be used.

There may be situations where predefined values are not usable (i.e. wrapper applications using GPSBabel in the background). The inifile mechanism can be disabled with an empty filename.

`gpsbabel -p "" -i gpx -f something.gpx -o tiger -F -`

## Realtime tracking

Introduced in GPSBabel 1.3.1, we now have an experimental feature for realtime tracking via the new `-T` option. This reads position reports from selected formats and writes an output file when a position report is received.

As of this writing, Garmin's PVT protocol and NMEA are supported inputs. KML, NMEA, and the various XCSV formats are supported on output. Additional formats may be added by interested parties later.

Read realtime positioning from Garmin USB, write to Keyhole Markup

`gpsbabel -T -i garmin -f usb: -o kml -F example.kml`

Will read the USB-connected Garmin and rewrite 'example.kml' atomically, suitable for a self-refreshing network link in Google Earth.

Read realtime positioning from Wintec WBT-201 via Bluetooth on Mac, write to Keyhole Markup

`gpsbabel -T -i nmea -f /dev/cu.G-Rays2-SPPslave-1 -o kml -F example.kml`

Will read the Wintec WBT-201 via Bluetooth, using the name that the Mac assigned it, and rewrite 'example.kml' atomically, suitable for a self-refreshing network link in Google Earth.

Be sure to substitute an device name appropriate for your device and OS, such as `/dev/cu.usbserial` or `/dev/cu.BT-GPS-37A695-BT-GPSCOM-1` for Mac, `COM23:` for Windows, or `usb:` for Garmin USB . These names (except the "usb:" parlance for Garmin USB) are assigned by your operating system.

## Batch mode (command files)

In addition to reading arguments from the command line, GPSBabel can read directions from batch (or command) files via the `-b` option.

These files are ideal for holding long command lines, long file lists, complex filters and so on. You can use all GPSBabel options and combinations when writing such files. Nesting batch files by using the `-b` option within a batch file is supported.

Here is an example demonstrating segmenting a large command line by placing the input and filtering directives in a file called 'all_my_files'.

`gpsbabel -b all_my_files -o gdb -F all_my_tracks.gdb`

'all_my_files' could look like this:

- -i gpx
- -f saxony_in_summer_2004.gpx -f austria_2005.gpx
- -i gdb
- -f croatia_2006.gdb
- -x nuketypes,waypoints,routes
- -x track,pack,split,title="LOG # %Y%m%d"

## List of Options

The complete list of available options to GPSBabel can be obtained by running `gpsbabel -h` . While there are a number of options, most people will not use most of them, so don't be intimidated.

`-p` Read preferences file. On startup, GPSBabel will look for a file named `gpsbabel.ini` containing preferences you have provided. This option lets you pick a different files. See for more info.

`-s` Write "smart" names. This option influences some - but not all - of our writers to try to build "smart" waypoint names. For example, in modules that know about geocaching, it may replace "GC1234" with the actual name of the geocache.

`-r` Work on routes. This option has a subtly different meaning in different cases. As the very first formats in GPSBabel were for serial GPSes and routes and tracks were large and thus time-consuming to transfer, the default was waypoints only with this option to turn on the extra data. Some of our file formats use this option to mean "work only on routes, even if you have tracks/waypoints", but we're trying to discourage that behavior and in most cases, consider it a bug.

`-t` Work on tracks. See `-r` for usage.

`-w` Work on waypoints. This is the default.

`-T` Enable Realtime tracking. This option isn't supported by the majority of our file formats, but repeatedly reads location from a GPS and writes it to a file as described in

`-b` Process batch file. In addition to reading arguments from the command line, we can read them from files containing lists of commands as described in

`-x` filter Run filter. This option lets use use one of of our many data filters. Position of this in the command line does matter - remember, we process left to right.

`-D` Enable debugging. Not all formats support this. It's typically better supported by the various protocol modules because they just plain need more debugging. This option may be followed by a number. Zero means no debugging. Larger numbers mean more debugging.

`-h`, `-?` Print help.

`-V` Print version number.