Installation

CacheMate requires Palm OS 3.0 or later.

Follow these steps to get started with CacheMate:

1. Run the Install Tool from your Palm™ Desktop directory.
2. Click Add, and add the CacheMate.prc file to your HotSync® list.
3. Add the MathLib.prc file as well, if you want to use the "nearest caches" and waypoint calculation features.
4. HotSync your Palm OS handheld.
5. Tap the CacheMate icon on your handheld to start the program.
6. Tap the New button to begin adding items to the database.

Record List View

The list view provides a categorized list of waypoints/caches stored in the database. This list may be sorted by the name or waypoint fields of each record. Tapping the New button will switch to an empty record view to allow creation of a new database record.

Extra information may be displayed on each line, depending on the presence of that information and settings made in the Preferences dialog. The waypoint name or terrain/difficulty of a cache may be displayed, as well as an indicator for travel bugs. The travel bug indicator is displayed if it is enabled (as a double-arrow on the left of the list), and a line in the description begins with "Bugs: ", which is how travel bug names are placed in the cache record. If the waypoint name is selected for display, and the list is sorted by waypoint, the waypoint name will be on the left.

The record list may be scrolled using the hardware up/down buttons. If your device has a supported jog wheel or switch (currently Sony, HandEra, Handspring Treo, and the Garmin iQue 3600), it may also be used to navigate the record list. Moving the wheel up or down selects records, and pressing it switches to the record view for the selected record. On Sony devices, pressing and rotating the jog wheel scrolls the list.

The list may also be searched by entering characters, using either Graffiti or a keyboard. Up to 20 characters may be entered to search for record names beginning with those characters. Records are searched according to the selected sort order (if sorting by waypoint, waypoint names are searched, otherwise record names are searched).

Depending on the plugins that are installed, a button labeled "Ex" may appear at the bottom. Tapping this button will allow selection of a plugin to run for multiple-waypoint export of all records in the current category.

Record Menu

Delete Records - Delete all records in current category

Beam Category - Beam all records in selected category to another device

Move Records - Move all records in current category to another database/category

Record Count - Display number of records in current category

Mark Recs As Found - Marks "found" checkboxes for all records in current category

Import Record - Import Memo Pad record

Export Logs - Export logs of records in current category to Memo Pad

Mark Waypoint - Mark current location as new waypoint record

Search (Srch) Menu

Nearest Caches - Run "nearest caches" search, retrieving last saved coordinates

Last Search - Repeat the last successful "nearest caches" search

Bookmarks - Display list of bookmarked records

Clear Bookmarks - Clear bookmarks in current category

Calc Menu

Calc Plugins - Select and launch a calculation plugin

Option Menu

Edit Cache Types - Edit list of cache types for records

Font - Select font for list view

Preferences - Display Preferences dialog

List Options - Display List Options dialog

Select DB - Select, create, rename or delete item databases

Buttons - Assign functions to hardware buttons

Rescan Mem Card - Resets stored information on memory card files

About CacheMate - Displays version and support information

Register - Display prompt for registration code

Help - Display help text for list view

Record View

This view displays and allows editing of information for a record, using one of five selectable views. The only thing that is currently read-only are any cache logs imported from Groundspeak GPX files. Records may also be bookmarked from this form, for easy recall later. Tapping the Done button will return to the list view.

The sixth view (Overview) is a scrollable color text display, which is kept in sync with the editable fields in the record. It supports high-res screens and natively supports FontHack-compatible fonts. Font selection and other options related to this display are in the Option menu.

The hardware up/down buttons may be used to scroll the currently visible multi-line field, if any. One of the other four hardware buttons may be selected to cycle through the various views of a record. If your device has a supported jog wheel or switch, it may be used here for navigation. Moving the wheel up or down will mimic the functionality of the hardware up/down buttons, and pressing it will perform the view cycling function described above.

In the record view, pressing the jog wheel switches between different views of a record (general, description, hints and log). Scrolling with the jog wheel affects views with multi-line fields, scrolling those fields similar to the way that the up and down buttons perform.

Depending on the plugins that are installed, one to three buttons may appear at the bottom of the list view, labeled "Map", "Nav" and "Ex". These are for mapping, navigation, and general export plugins, respectively. If there is only one mapping or navigation plugin installed, those buttons will automatically launch it. Otherwise, a selection dialog will appear. The dialog will appear regardless for general export plugins.

Record Menu

New Record - Save current record and empty form for new record

Delete Record - Delete the current record

Beam Record - Beam the current record to another device

Move Record - Move current record to another database/category

Nearest Caches - Run "nearest caches" search, using coordinates from current record

Last Search - Repeat the last successful "nearest caches" search

Bookmarks - Display list of bookmarked records

Mark Waypoint - Mark current location as new waypoint record

Took/Left Notes - Place template for items taken/left and travel bugs in log notes

Export Record - Export record information to MemoPad record(s)

Export Log - Export cache log to MemoPad record

Calc Menu

Project Waypoint - Project waypoint from the current record

Calc Plugins - Select and launch a calculation plugin

Edit Menu

Undo - Undo last edit in selected text field

Cut - Move selected text to clipboard

Copy - Copy selected text to clipboard

Paste - Copy text in clipboard (if any) to current field

Select All - Select all text in current field

Keyboard - Display on-screen keyboard dialog

Graffifi Help - Display built-in Graffiti Help dialog

Option Menu

Preferences - Display Preferences dialog

View Options - Display Record View options dialog

Display Font - Select font to use for Overview display

Buttons - Assign functions to hardware buttons

Help - Display help text for record view

Preferences

Distance units
Selects distance units for the "nearest caches" search, between metric, nautical and statute.

Delete memo after importing
Controls the automatic deletion of MemoPad records after they are imported into CacheMate.

Add time to log memo title
Adds a timestamp to exported log memos. When those memos are sorted alphabetically, they will be listed in order of the hunt end date/time set in the record.

Merge import file records
Controls merging of LOC/GPX records during import with those already in the database, according to waypoint names. Log/bookmark information is taken from the old record, and the other information is replaced with the new one. This option does not apply to records imported from memory card files.

Preserve old item category
When import file record merging is enabled, with the above option, this option causes the category setting of any existing records that are merged to be preserved in the new record. This option does not apply to records imported from memory card files.

GPS Setup
Displays the GPS connection settings dialog box (see below).

GPS Preferences

Baud Rate
Sets the baud rate for a normal serial connection to a GPS receiver.

Port
Selects the serial port to use for communcating with a GPS receiver. If Bluetooth is selected, handshaking and baud rate settings are ignored.

Enable RTS/CTS handshaking
Enables hardware handshaking with the GPS receiver, to ensure stable communications. If the baud rate is set higher than 19200, this setting is ignored and handshaking is automatically enabled.

Enable location averaging
Enables location averaging, in GPS location query plugins that support this option.

Set BT Device
Allows discovery and storage of a Bluetooth device address for the GPS receiver, so the Bluetooth discovery process may be avoided when the GPS receiver is actually used.

Record View Options

When marked as found
These options allow for automatic actions, setting the record category and/or the hunt end date/time, when the Found checkbox is checked and the record is saved.

Page select with pushbuttons
Replaces the popup trigger that selects the different views of a record with a series of pushbuttons. If this is changed while currently viewing a record, it will take effect the next time a record is viewed.

Show logs in overview
Causes past logs to be included in the Overview display. This is optional, because the text formatting takes some time on older hardware. This option does not automatically cause a rebuild of the Overview display... it will take effect the next time that that happens (via opening the record or changing its text).

Show overview by default
Makes the Overview display the default view when opening an existing record.

Allow search from overview
Allow nearest cache searches from the Overview display. This option is turned off by default, as some users have reported stability issues when attempting that.

List Options

Extra info
Selects whether the waypoint name or terrain/difficulty information for a record is displayed in the list view.

Show travel bugs
Controls display of the list view travel bug indicator. This option has no effect with records stored on memory cards.

Display waypoint as name
Causes the list view to display the waypoint name of a record as the record name. Sorting and character-based searching will still use the true record name, if the sort order is by name.

...When sorted by category
Performs the same function as the previous option, but only when the list is sorted by waypoint.

Show status/type columns
Causes a pair of columns to appear to the left of cache names in the list. The first shows the first character of the record/cache type, and the second shows bookmarked (-) and found (+) records. A combination of both symbols is used to indicate that both boxes are checked.

Color highlighting
Shows bookmarked and found records as red and grey, respectively. Other records remain the default black color. This option only has any effect if the display supports color.

Memo Pad Import/Export

From the cache list view, you may import information from a specially-formatted MemoPad record by selecting Import Record from the list view Record menu. A list of visible memo records will be displayed for selection. Memo import is currently disabled for Palm OS Cobalt devices, due to compatibility issues.

The memo format for importing consists of the cache name, waypont name, and coordinates on the first 3 lines, followed by sections for the cache description and hints. The description and hints sections are both optional, and must be preceded by lines reading "Desc:" and "Hints:", respectively. Between the first 3 lines and the description/hints sections, terrain and difficulty ratings may be optionally included, on lines starting with "Terr: " and "Diff: ", respectively. A template demonstrating this format is in the included file MemoTemplate.txt.

There is an option in the Preferences dialog for automatically deleting memos that are imported. If this option is not enabled, memo records that are imported are left in the Memopad database.

Cache information and logs are exported separately, using the Export Record and Export Log options in the record view Record menu. The exported information is in the same format used for importing, but the description and hint text will be in separate memo records if they are both specified. Exported logs contain all of the information displayed in the Log section of the record view.

From the list view, cache logs for all records in the current category may be exported using the Export Logs option of the Record menu. Caches for which there is no hunt date set will be skipped.

GPX/LOC File Import

EasyGPS GPX/LOC XML file importing is also possible with CacheMate. Groundspeak-specific extensions to the GPX file format are supported.

Unregistered copies of CacheMate will only import up to a 10 record limit for the database, and will truncate descriptions to 2 kilobytes. Once the program is registered, you will need to re-import the records that were imported before, to get the full description text.

To import a LOC or GPX file into CacheMate, you need to use a PC-based tool to convert the XML file into a PDB file that can be used with your Palm OS device. A Windows version of this tool is included in the CacheMate distribution. A version for Unix variants is available here.

The file converters accept a LOC or GPX formatted XML file as input, and output a file that can be installed on the Palm OS device. When this file is installed and CacheMate is launched, a prompt for database and category will be displayed, and its contents will automatically be merged with the main CacheMate database once selections are made. If the database name matches a category name in the target database, the category will be selected automatically.

There is an option in the Preferences dialog to merge imported LOC/GPX records with what already exists in the CacheMate database, based on the waypoint name. Cache log information is taken from the existing record, while all other information is taken from the import record.

Both versions of the file converter allow for selecting of waypoints to convert. The Unix version has an option for listing the waypoints in the input file, and allows specifying of waypoints to convert on the command line. The Windows version presents a GUI for waypoint selection, and also allows converting of waypoints from multiple input files into a single output file.

Bookmarks

Record bookmarking allows for quick switching between records, even though they may be far apart from each other in the list view. To set a bookmark, navigate to the Info page of a record and check the Bookmarked checkbox. To view and navigate between bookmarked records, choose Bookmarks from the Record menu, either in the record or list views.

If any plugins are installed that support multiple-waypoint exporting, an Export button will appear under the bookmark list. Tapping this button will export all bookmarked entries using the selected plugin. The Move button allows moving all bookmarked records to a selected category.

"Nearest Caches" Search

If the MathLib library is installed, you may generate a list of the caches in the database, sorted by distance from the selected cache or a specified set of coordinates.

In the Record menu is a Nearest Caches option that begins the search. When this option is selected, a dialog box will appear, allowing for input of coordinates. If a cache is selected, its coordinates will be displayed, otherwise the coordinates of the last search will be displayed. The following coordinate formats are supported:

• hddd.ddddd
• hddd mm.mmm
• hddd mm ss.s
• DDD.ddddd (decimal degrees)
• DDD mm.mmm

Punctuation (such as symbols for degrees, minutes and seconds) are ignored, and therefore not required.

A Search Filters dialog will then appear, allowing setting filters on caches listed using either category name or general direction from the point the search is made from. It is also possible to specify a maximum distance and number of records. If either of those are zero or not specified, they will not be applied. Tapping the Reset button will reset the filter controls back to their default state (all categories, all directions).

When the list appears, cache names will be listed. When a cache is selected, its waypoint name, distance and bearing from the search coordinates are displayed. When you have selected a cache, tap Go To to switch to that cache record, or Close to close the dialog box. Hardware up/down buttons and supported jog wheel hardware are also supported for scrolling the list. If any plugins are installed that support multiple-waypoint exporting, an Export button will appear under the list. Tapping this button will export all listed entries using the selected plugin. The Move button allows moving all bookmarked records to a selected category.

To run a search using the previous search coordinates and filters, use the Last Search option in the Record menu. This option is available in both the list and record views.

Reading coordinates from a connected GPS receiver is also supported, through an appropriate plugin. If you have a plugin installed that supports GPS location query, tap the From GPS button to use it. If multiple installed plugins have that support, a prompt will appear to select which one to use.

Waypoint Projection

To project a waypoint from the currently selected record, select the Project Waypoint option from the Calc menu. A prompt will appear for bearing and distance of the projection. The projected waypoint will be assigned an 6-character waypoint name starting with X, and its description will be the source waypoint, distance and bearing. Both the source and projected waypoints are automatically bookmarked.

Plugin Support

CacheMate contains support for various types of plugins, mostly for hooking into external mapping or navigation software, but can be used for other purposes as well. Plugins install just like normal applications but, when CacheMate is started, it will identify installed plugins and alter its user interface to allow for their use.

Currently, the supported plugin types are mapping, navigation, general waypoint export, calculation and GPS query. The first three types display buttons in the record view if any of those types are installed, and calculation plugins are supported through a choice in the Calc menu, visible in both the list and record views. General export plugins that support multiple waypoints in batch will cause a button to display on the list view, for exporting all records in the selected category.

A few plugins are included in the CacheMate download package. Others are available here.

Memory Card Support

CacheMate has support for standard memory cards on Palm OS versions 4.0 and later. To use this support, install import files created by CMConvert to one of the following directories on a memory card instead of on the PDA as normal:

• /CacheMate
• /PALM/Launcher
• /PALM/Programs/MSFiles
• /PALM/Programs/MSFiles/CacheMate

When CacheMate is started and a memory card is detected, those 4 directories are scanned for CacheMate import files, and entries are created in CacheMate's main database, with minimal information copied from the files on the card. The remaining information (description and past log text) remains on the memory card, and is referenced by those new database entries. If records exist in the main database are found with waypoint names matching those from memory card files, those records will be converted to records referencing data on the memory card.

When files are found on the memory card and processed, information on those files is cached to prevent the memory card scan from being done every time CacheMate starts, to keep the startup delay low most of the time. Whenever an existing file is deleted, renamed, or updated with a newer copy, the memory card is again scanned for files on the next startup. A Rescan Mem Card option exists in the list view's Option menu to force a rescan for new files, if necessary.

The main CacheMate database will not work if copied to the memory card, due to the limits of Palm OS support for databases on memory cards and the desire to keep most of the functionality available. The bulk of the information, though, is left on the memory card, affording a roughly 90% savings in main memory space on average.

As with the normal record import process, if the file name matches a category in the target database, that will be the default category for new records.

The following limits apply to records from memory cards:

• When beamed, these records will be missing text stored on the memory card
• Full-text searching will not include the description or past logs
• The description and waypoint fields are read-only
• The travel bug indicator does not work

Multiple Databases

CacheMate supports multiple waypoint databases which, in some cases, can allow much greater flexibility than the Palm OS limit of 15 categories will allow. You can create, rename, delete and switch between databases, as well as choose which to import new records into when those are detected.

The main GUI element for multiple database support is the database selection popup, which can be accessed from the Select DB option in the list view's Option menu. From there, the following are possible:

Select database
To select a different database, choose one from the list and tap Done. The list view and category selection will update and the chosen database resorted to match the current sort order.

Create new database
To create a new waypoint database, enter the name in the field below the database list and tap New. If the database is successfully created, it will appear in the list.

Rename database
To rename a database, select a database from the list, edit its name in the field as desired, and tap Ren. If the rename operation is successful, the list will be updated to reflect the new name.

Delete database
To delete an existing database, select it from the list and tap Del.

Clear database
To delete all records from an existing database, select it from the list and tap Clr.