GPXView - Geocaching with Maemo

Till Harbaum <till@harbaum.org>

GPXView is a geocaching application. Its main purpose is to work with pocket queries in GPX format (hence the name GPXView). GPXView allows you to conveniently read the information stored in these files and navigates you to geocaches using your devices built-in GPS. GPXView features many advanced features including full HTML rendered cache descriptions, GPS based voice navigation and a built-in map viewer.

Did you know?

GPXView supports online download of geocaches using geotoad. This even works without a premium account!

GPXView can guide you by voice so you can concentrate on your search while the device sits in your pocket.

The latest Maemo5 release supports copy'n paste. Very handy when working with typical multi cache descriptions.

Obtaining GPXView

GPXView is available for three different plattforms: The latest N810/N800 version is available from the Nokia repositories.

GPXView on N810
The N900 version is available from the extras repository and can be installed from the Navigation section in the Application Manager on that device. However, since there's a review process involved in getting software into the respective repositories and since the review process for the N900 is rather slow, it may take some time for the latest version to show up on your device.

GPXView on N900
There is no pre-packaged version for the Linux desktop. In order to install GPXView on a desktop PC you'll have to download the source code and compile and install it yourself.

GPXView on Ubuntu Linux

Getting started

GPXView comes ready-to-run and even includes some little "welcome" demo file. You can use this to learn about the basic usage of GPXView and check out the various program features.

First start of GPXView
However, to start hunting geocaches near your location you need to get the appropriate pocket queries in GPX or LOC format either from geocaching.com where you have to be a paying member to be allowed to download them. Or you check free services. Sources known to work with GPXView are:

Installing GPX files

Once you got your GPX files you might install them anywhere on your device like e.g. the memory card on your N900. Files being downloaded in ZIP format from geocaching.com can be left compressed. GPXView will uncompress them automatically.

You can copy the files onto the device via USB. But you might as well just receive the files via Email directly on the device without any PC involved.

Finally you might use geotoad to download cache data directly.

The GPX list view

To import such files into GPXView you need to start GPXView and and select "Import file" from the main menu. The GPX file will then be included into the main screens list of GPX files. The following session has two active GPX files and a closed one installed.

GPX list
You can adjust details of this list and enable and disable selected columns in the settings dialog.

These GPX list will be loaded whenever you restart GPXView. Since these files may contain plenty caches, loading them may take a few seconds. While loading you'll see a progress bar.

Loading ...
You may wish to temporarily disable certain GPX files from this list in order to speed up loading. In order to do so, just click the icon (on N800/N810 and desktop use the Import->Close in the menu instead). A dialog will pop up to ask you whether you want to remove that entry completely from the list or whether you only want to close it.

Close or Remove?
If you choose to close the file it will be displayed in "disabled" style as visible in the GPX list screenshot above. These files will not be opened at startup and thus don't affect the startup time of GPXView. The containing cache files are not imported and are e.g. not found when using the Search function and are not displayed on the map. To reenable a closed entry just select it.

Importing entire directories

GPX files derived from pocket queries usually contain many geocaches and it makes sense to maintain them as one big object in the main view. But some GPX files only contain a single geocache and you might have many of those seperate files stored on your device. To cope with such a collection of single GPX files, GPXView provides the "Import directory" feature. This collects all GPX files from a given directory and treats them like one big GPX file.

The cache list view

When you select a GPX file in the GPX list view, you'll be forwarded to the cache list view. This view lists all geocaches of the selected GPX file sorted by distance from your current GPS coordinate.

The cache list view
You can adjust details of this list and enable and disable selected columns in the settings dialog.

Little markers at the cache icon will give you additional info about the cache:

The cache list also tells you how far in which direction a cache is. This of course changes when your position changes. GPXView can thus update the cachelist periodically. This can be adjusted in the settings.

The cache view

Selecting a cache in the cache list will forward you to the main screen of the cache view.

If the map window is open at the time you select a cache, then the map switches into navigation mode and e.g. a compass rose will be displayed for the selected cache.

Cache main view

The main view gives you a quick overview of the most important aspects of a geocache. Among this information is the difficulty and the terrain rating and of course the main coordinate.

Cache main view
This coordinate is displayed striked out if it was overridden on the goto page. You'll also find various informantion placed on buttons which are linked to the internet browser. The waypoint id button will e.g. open the caches description in the web browser.

Cache description view

The cache description usually contains the main part of the cache. It's the important part when solving multi caches or mystery caches. This description often comes in HTML format as it may contain all kind of text formatting, tables, images etc ...

Cache description view
Images are usually not part of the GPS file itself. Instead the description text is in HTML format and contains references to the actual images stored somewhere on the internet. When being asked to display such a description, GPXView downloads the images and stores them internally for further usage. So once you had a working internet connection while reading a cache description and the images successfully got loaded everything is stored on device. And the images are available to you afterwards in the field even without internet connection.

Cache hint view

The hint is displayed in the typical encrypted form. Just click the encrypt and decrypt buttons to toggle between the encrypted and decrypted display,

Cache hint view
In some cases (e.g. in GPX files from opencaching.com) the hints are tagged as html text or actually are encoded in html. In this case GPXView is unable to encrypt the text. The hint tab will then just display the decoded plain text.

Cache log view

Pocket query in GPX format usually contains the last 5 logs. If you have found this cache and logged it, your log is included regardless how recent it is. GPXView uses this fact to determine whether you found a cache. In order to make this feature work, your username must be specified in the settings.

Cache log view
If the geocaching id of the cache is known, GPXView is able to create a browser button on top of the log view. Clicking this button will open the browser with the appropriate log page for convenient logging.

Cache waypoints view

Some caches contain additional waypoints. These are only included in GPX files if they actually contain a valid coordinate (unlike e.g. the stages of a multi cache which don't come with valid coordinates as you are supposed to determine the coordinates yourself).

Cache waypoints view
When the selected cache has waypoints, these are also displayed on the map.

Cache travelbug view

Travelbug or geocoin information stored in the GPX file is also parsed.

Cache travelbug view
If GPXView is able to create a valid internet link for a travelbug or goicoin the id will be displayed on a button. Clicking that button will open the browser with the travelbugs homepage.

Cache notes view

The notes view is special in a way that it does not display informantion from the GPX file. Instead it's meant to store information that you enter manually. You might e.g. use the notes page to solve a mystery cache or store your findings while solving a multi cache.

Cache notes view
The cache notes page contains a coordinate tool. An alternative ("new") coordinate entered here (e.g. a solved mystery position or a multi cache state). This can be used to overwrite the original one if the "override" checkbox is enabled. This overridden coordinate will then always be used instead of the original one.Icons derived from the overridden cache position are overlayed by the marker.

You can also mark the cache as "found" here. Found caches can then be found in the search dialog or exported in the garmin field notes or garmin waypoints.

A common use case for the notes page is to copy equations from the description page and fill them with the correct values while on the go. Since PR1.2 Maemo5 supports this with copy'n paste. Press and hold shift while viewing the description and then drag the desired text marks it. The selelected text can then be copied to the clipboard using CTRL-C and pasted to the notes pages using CTRL-V.

All user generated content on this page is stored permanently on the device. This data is not stored inside the GPX files. You may at any time update or replace GPX files without affecting the contents of the notes pages.

Cache goto view

The goto view helps you navigating to a geocache. It contains a compass rose that is adjusted to your walking direction (the compass damping may need adjustment in the settings). Furthermore the compass needle always points to the geocache.

Cache goto view
Due to a lack of a real magnetic compass, GPXView needs to use the GPS signal to determine your heading. This only works while you are moving. And it works better if you are miving fast and in a straight line. These conditions are usually not given when approaching the cache on the last few meters. Once you are moving too slow for the heading detection to work reliably, you can lock the compass in place by tapping it. You'll then need some other means to determine where north it. As long as you still know this, you can adjust the device accordingly and the compass needle will still point to the geocache.

Another advanced feature is the voice navigation. The small speaker icon allows you to enable an accoustic distance announcement. This way you don't need to look at the device all the time and the device will keep you informed about the distance to the cache.

Coordinate tool

Whenever GPXView deals with coordinates it will use the coordinate tool. This tool consists of two buttons displaying the coordinates (on N810, N800 and desktop linux these are text entry fields) and one or two additional buttons with icons.

The coordinate tool
You can change the coordinate directly by clicking the coordinate buttons. On N810, N810 and desktop linux you can use the text entry fields to enter a new coordinate. On the N900 the coordinate picker will show up once you click one of the coordinate buttons.

The coordinate picker
The coordinate picker is designed for finger friendlyness and allows you to enter coordinates without using a keyboard.

You can also import one of the various coordinates GPXView already knows. In order to do this you just habe to click the coordinate import button . A picker with then show up allowing you to select a coordinate source.

Import a coordinate
The number of sources available depends on the state GPXView is in. Possible sources include: In some occasions also a export button is present. This button opens the coordinate export tool.

Export a coordinate
Up to three choices may be present here: Similar pickers also exist for distances

The distance picker
 and directions (angles).

The direction picker

Main Menu

The main menu can be reached from the main screen (and e.g. not from the map screen). It exact contents vary with the state of the main screen and e.g. some menu entries may only be visible if the main screen is in "GPX list" mode.

The main menu

About

The first thing selectable from the menu is the about dialog. The main about screen will tell you version and comppile time. This is the way to check whether you have the latest version of GPSView running.

Main about view
GPXView comes free of charge. You can install it on any device you want. If you think you want to show your appreciation, you are welcome to make a little donation via paypal.

Donations are appreciated
You may also actively contribute to the project by reporting bugs or filing feature requests.

You can contribute

Settings

The settings dialog contains various global settings. Any change made here is permanent.

The settings

Enable GPS

This settings controls GPS globally. The major reason for disabling GPS is to save energy. Since geocaching without precise location information is not possible, you usually want to have the GPS enables. However, if GPS is disabled, an alternatice coordinate is being used instead. As a default only a home coordinate is stored. You might add an unlimited number of additional locations (like your workplace or other places you often use). Just hit the add or edit buttons while GPS is disabled to maintain this list. If GPS is disabled, all coordinate calculation (e.g. in order to display the distance of a cache) is then based on the selected alternative coordinate in the list. In the example above the "Home" coordinate is the active one.

Manually edit a location
The alternate positions are also useful while having GPS as they can easily be reached via the coordinate tool.

Imperial Units

This settings changes the display between imperial (mi, in, ft) and metric units (km, m). These only affect the display. Any input accepts both formats at any time. So you may enter inches while in metric mode and meters while in imperial mode. However, these are immediately converted into display units while being processed.

Username

This is your geocaching.com user name. It's used to determine if a geocache has been placed by you or has been found by you. The caches are then marked using the appropriate icons as finds and owned .

Furthermore the username is being used when using the geotoad feature.

Visible GPX list items

This setting allows you to enable and disable columns in the GPX list view. The original file name (as opposed to the GPX name stored in that file), the date of creation and the number of caches stored in that GPX files can be toggled independently.

Visible cache list items

This setting allows you to enable and disable columns in the cache list view. The waypoint name, the cache size and the caches rating can be toggled.

Cache list screensaver

The screensaver can be disabled while the cache list is being displayed. This is useful when e.g. driving with the cache list view active. Since the cache list may optionally be sorted by distance, the nearest cache is always the first one on screen.

Cache list refresh

As pointed out before, the cache list can be refreshed automatically every 30 seconds. Since this feature consumes CPU power (and thus battery), it can be disabled.

Cache compass damping

The compass in the caches goto view uses track information from the GPS signal to determine the heading in order to re-create the functionality of a magnetic compass. Depending on the precision of the GPS receiver and the signal quality of the GPS signal the tracking information may be rather inaccurate. Especially when you are moving slowly the compass tends to jitter. If you have this problem you might want to increase damping. This makes the compass a little less responsive but it increases stability of the compass display.

Use GCVote service

GPXView can retrieve cache quality ratings from the GCVote service. If GCvote is enabled, an additional line of stars is shown in the caches main view describing the quality of a cache like difficulty and terrain are already displayed by default.

Disable screen saver in goto view

Since the goto view can be used to navigate to the cache, it may be handy to keep the screen on all the time. Be aware that this may drain your battery if you leave the device for a longer period in this mode with the goto view active.

Export

GPXView can export data for use with other devices or applications.
Export
The export submenu lets you select the application you want to export data to.

Export to Maemo Mapper POI
Maemo Mapper is a popular mapping solution for maemo. GPXView can export geocache locations as points of interest (POI) directly into a database as use by Maemo Mapper. Selecting this database in Maemo Mapper will make it display geocaches locations in its map. Since the database export is rather slow, you might limit the radius around your current GPS position, You can also prevent caches to be exported that you already found or that are disabled or archived to further reduce the number of exported caches.

Export garmin field notes
GPXView is able to export so-called Garmin field notes. These are files containing information about all caches you have marked as found. Also the text from the notes page of each found cache is included. You can upload the resulting file via the upload page at geocaching.com. Afterwards you can conveniently log all the caches.

Export Garmin waypoints
GPXView can export waypoints of overridden coordinates into a file suitable for use on garmin handheld gps devices (tested with Garmin Colorado and Garmin Oregon devices). This way you can transfer the coordintes of solved mystery caches or stages of a multi cache to those Garmin handhelds.

Search

The number of geocaches stored on your device may grow very fast. The search feature allows you to search through all of the currently active GPX files and to search for particular text fragements in the caches name, description etc.

The search dialog
You can also search for caches that you found within the last few days. This may be handy when logging at home and is meant to help you remember which geocaches you've found recently.

Tools Submenu

The tools submenu is reached via the main menu. It can be used to invoke various geocaching related tools. The tools act as if they were seperate programs but are tightly integrated into GPXView and typically import or export data to or from GPXView.

The tools submenu

Geomath

The geomath tool allows very basic geocoordinate calculations. Two coordinates can be entered as well as a distance and a direction.

The Geomath tool
Clicking the "Calculate" button calculates the distance between the two given coordinates and projects the first coordinate (on the screens left) by the given distance and direction. The resulting projected coordinate is then be displayed in the bottom row.

The resulting coordinate can be used within GPXView from the coordinate selector tool using the geocalc icon . This icon also shows up in the map if a valid geomath result is present.

Usage example: "Go 120m in 65°" from the given start coordinate
The cache description tells you to walk a certain distance into a certain direction from a given coordinate. First you select the caches main position from the coordinate selector tool . The start coordinate should then be displayed in the left column. Now enter the requested distance and direction into the appropriate fields (on Maemo5 using the picker tools). When done just click "Calculate" and the "projection" row will contain your target coordinate. This coordinate can now be selected in the caches "goto" view and is also being shown in the map. You can even re-select the projected coordinate in the Geomath dialog for further processing and to e.g. walk another distance in another direction.

Geotext

The geotext tool allows two simple text operations often required to solve a geocache. Many geocaches ask you to calculate the letter sum of a certain text or word.

The Geotext tool
Just enter this word into geotext and the character sum is being displayed while you type. Another common operation is the "shift" letters. If you shift the letter "a" by one you get the next letter "b" (and "z" becomes "a" again). If you shift by two "a" becomes "c" and so on. This is the so-called cesar encryption. A special case is a shift by 13. This encryption of shifting letters by 13 is named rot13 and is for example used on the geocaching.com website to encrypt hints and spoilers.

Precise Position

The Precise Position is more for the hider than for the seeker. It is supposed to be used when standing still. It allows you to average the current position over some longer period of time.

The Precise Position tool
The tool will also show you graphically how far all the positions received so far are apart to give you an impression how precise the position really is. The more coordinates you get and the smaller the radius of the circle containing them all is the more precise is the resulting coordinate. You can then copy the resulting coordinate to the clipboard for further processing in other applications.

GeoToad

GeoToad is not part of GPXView itself but has to be installed seperately. GeoToad is written in the ruby language and as of this writing has to be installed together with the ruby interpreter from the extras-devel repository when using Maemo5.

GeoToad allows you to download geocache information directly from the geocaching.com website. In order to comply with the terms of that site, GeoToad intentionally runs rather slow (about one cache request per second) to prevent to overload that site with automated requests.

To use GeoToad you first have to enter your account information (you don't need a premioum account!), the location you want to get geocache information from and the size of the area you are interested in. Please, start with an area of ~1km (0.6 mi) radius. Otherwise the download may take rather long. You also have to select a place to store the resulting file. You can choose any location, but it's preferred to use a memory card to save precious root file system space on a mobile device like the N900.

Setup of GeoToad
GeoToad is then invoked using the parameters you just entered.

Running GeoToad
After a few seconds the first information should be returned and GeoToad starts reporting what it receives from geocaching.com.

Search results are coming in
Once geotoad is done it reports some statistics about its work and GPXView tells you that the GeoToad job is done.

GeoToad download is done
You can now close the window and return to the main screen. You'll find that the download has been added to the list of GPX files.

The resulting file
You can now use this file like any other GPX file you might have downloaded from geocaching.com or similar sites.

Caches downloaded by GeoToad

The Map

GPXView comes with a built-in map. This map is downloaded on demand, but all data being downloaded is caches locally. Once you've visited a certain area on the map, the data will even be accessible without internet connection.

The map
The map is tightly integrated into GPXView and always displays all active caches with little icons. You can click these icons and get detailed information of the cache in a "balloon". Clicking this balloon will cause the main GPXView application to switch to that particular cache.

The map data can be taken from several sources. Clicking the little arrow on the right screen side will extent a menu allowing you to select a different map source.

Selecting the map source
The map always displays your current GPS position using a blue marker surrounded by a circular gray area. This area displays your current GPS precision. In the example below the precision of ~5km is extremely low indicating that the position is likely not derived from the GPS signal but of location information derived from the cell network or a wlan position. Furthermore a small blue arrow on the GPS indicator displays your current tracking.

Navigating to a cache
When there's a geocache selected in GPXViews main view, then all caches except the selected one a displayed semi-transparent. Furthermore a info display on the left side of the screen helps navigating to the cache. Clicking on the coordinate in that info display will center the map in that position. Clicking the compass will toggle between GPS mode (blue compass arrow) and map center mode (black compass arrow). In GPS mode, the distance and heading info is displayed relative to the current GPS position. In map center mode the distance and heading info is displayed relative to the map center.

Finally, the current map position can be used as coordinate input in the coordinate tool.