Navigation Toolbox for Palm OS
Home Download Documentation Register
TheoNav Documentation
Last updated: Thursday, 24-Apr-2008 09:30:57 EDT

Table of Contents

1. Introduction
2. Disclaimer
3. Requirements
4. Installation
5. Operation
5.1. Startup
5.2. Speed, Time & Distance
5.3. Geographic Distance
5.4. Magnetic Variation
5.5. Compass Deviation
5.6. Course Vectors
5.7. Databases
6. Registration
7. Known Issues

1. Introduction

TheoNav is a PalmOS application that contains a number of (hopefully) useful tools and calculators for use in navigation. TheoNav was written primarily for sailors and other maritime navigators, but the various features can also be used for other types of navigation, such as driving, flying, or hiking.

TheoNav has five main screens, each of which has specific tools and features:

Speed, Time & Distance
This is a simple calculator for determining your speed or your travel time or the distance to a destination if you know two of those three values. Also lets you easily convert between English, metric and nautical units.
Geographic Distance
This screen lets you calculate the distance between any two points on the Earth, given their geographic coordinates. It also allows you to determine the coordinates of a location, given a distance and direction from another location. The location coordinates can be entered manually, or you can choose locations from various databases.
Magnetic Variation
This screen lets you predict the magnetic variation for any location on the Earth. Magnetic Variation is the difference between true north and magnetic north, which is pointed to by a compass.
Compass Deviation
Deviation refers to the error in your in your compass reading due to magnetic effects aboard your vessel. This screen can compute the deviation of your compass at any heading. You can enter the observed deviation at a number of different headings, and a curve-fitting algorithm is used to calculate the deviation at all headings.
Course Vectors
This screen can be used to calculate your true course and speed when travelling through a current.

2. Disclaimer

Modest efforts have been taken to ensure the accuracy of the calculations performed by TheoNav. However, there may be bugs in the software. IF YOU USE THIS SOFTWARE FOR NAVIGATION, YOU DO SO AT YOUR OWN RISK.

The U.S. Coast Guard recommends the practice of "using all available means of navigation and not relying upon any single system."

3. Requirements

TheoNav runs on Palm OS version 3.5 or later. It has been tested on the following devices:

  • Palm m500 (8MB) Palm OS 4.0
  • Fossil Abacus WristPDA (8MB) Palm OS 4.1
  • Treo "Ventura" (64MB) Palm OS 5.4.9
TheoNav has also been successfully tested on a number of different emulators and simulators, including:
  • Palm Emulator: Palm m100 (OS 3.5.1)
  • Palm Emulator: Palm IIIx (OS 4.1.2)
  • Palm Emulator: Palm V (OS 4.1.2)
  • Palm Emulator: Palm Vx (OS 4.1.2)
  • Palm Emulator: Palm IIIc (OS 4.0)
  • Palm Emulator: Palm m505 (OS 4.0)

  • Palm Simulator: Tungsten C (OS 5.2.0)
  • Palm Simulator: Tungsten E (OS 5.2.1)
  • Palm Simulator: Tungsten E2 (OS 4.1)
  • Palm Simulator: Tungsten T (OS 5.0)
  • Palm Simulator: Tungsten T3 (OS 5.2.1)
  • Palm Simulator: Zire 72 (OS 5.2.8)

  • Palm Simulator: Generic (OS 5.2)
  • Palm Simulator: Generic (OS 5.3)
  • Palm Simulator: Generic (OS 5.4)

  • Tungsten T5 (OS 5.4.8)
  • Tungsten E2 (OS 5.4.7)
  • Treo 600 (OS 5.2.1)
  • Treo 650 (OS 5.4.8)
Please note that earlier versions of TheoNav sometimes crashed on some Treo devices and some Tungsten devices running OS 5.4 or later. This problem has been fixed in version 2.0.2 of TheoNav.

TheoNav also requires MathLib. This is a library of functions for performing floating point math calculations on a Palm OS device. This library may already be present on your device (more info).

Note that Visor Handsprings come with MathLib pre-installed in ROM, and newer Palm handlhelds that use the Garnet operating system have incorporated the MathLib API into the system software, so MathLib may not be needed.

4. Installation

To get TheoNav up and running you need to:
  1. Download the TheoNav zip file (if you have not already).
  2. Unzip the files contained in the zip file.
  3. Decide which files you want to install.
  4. Install the files on your PDA device.
  5. Start TheoNav and enter the registration code (if you have purchased TheoNav, otherwise the program runs as a demo version).

Please look at our detailed Installation Instructions for details about installation.

5. Operation

TheoNav Startup Screen 5.1 Startup

Launch TheoNav as you would any other Palm application. Like most Palm applications, by default, TheoNav installs in the "Unfiled" category in the Launcher.

When you launch TheoNav you will see the Startup Screen. If you have an unregistered version of TheoNav, you will have to wait 5 seconds before proceeding (see Registration for how to register TheoNav). A pop-up "Start" menu is in the upper right corner. Use this menu to choose one of the five other screens:

TheoNav Speed/Time/Distance 5.2 Speed/Time/Distance

Speed/Time/Distance calculations are one of the basic tools a sailor uses in navigation. The (very simple) equation is:


Using this simple formula a navigator can predict the time of arrival, the speed of travel or the distance travelled along a course.

Speed can be entered in knots, statute miles per hour (mph), kilometers per hour (kph), feet per second (f/s), or meters per second (m/s). Use the popup menu to the right of the Speed field to easily convert between speed units.

Time can be entered in minutes, hours, seconds, days, or in "hh:mm:ss" format. To use "hh:mm:ss" format, enter the hours, then a colon, then 0-60 minutes, then a colon, then 0-60 seconds. Use the popup menu to the right of the Time field to easily convert between time units.

Distance can be entered in nautical miles, statute miles, kilometers, yards, or feet. Use the popup menu to the right of the Distance field to easily convert between distance units.

To calculate speed, time, or distance, enter values in two of the three fields. A "Calc" button will appear next to the third field:

  • Tap the "Calc Speed" button to determine your average speed based on the distance travelled and the time it took to get there.
  • Tap the "Calc Time" button to determine the time it will take to travel the specified distance at a given speed.
  • Tap the "Calc Dist." button to determine the distance travelled at the given speed over a known period of time.

Note: If no "Calc" buttons are displayed, then the equation is solved and all three displayed values should be correct with respect to each other.

Tap the "Clear" button to erase all of the entered values and start over.

Tap the "?" button or choose "Instructions" from the "Options" menu to get help with this screen.

TheoNav Geographic Distance Screen 5.3 Geographic Distance

This screen uses great circle calculations to determine the distance between any two points on the Earth. You can also use this screen to determine the coordinates of a location given the distance and direction from another location. The coordinates for the locations can be entered manually, or you can choose locations from a database. You can also save a location in a list of favorites for later use.

Find Distance and Bearing:

To find the distance between two locations, enter the latitude and longitude of your origin location and your destination location and click the "Calc" button next to the word "Distance". This will also calculate the direction you must initially travel to get from the origin to the destination along the shortest path.

Latitude and Longitude Coordinates can be entered in one of three formats:

  • d.dd - Decimal degrees (e.g. 40.74836°)
  • - Degrees and decimal minutes (e.g. 40° 44.902')
  • - Degrees, minutes, and seconds (e.g. 40° 44' 54.1")
Use the pop-up menu to the right, above the coordinates, to easily convert between coordinate formats.

Use the pushbuttons to the right of the coordinates to specify north or south for latitude, and east or west for longitude.

Find Destination Coordinates:

To calculate the destination coordinates, enter the origin coordinates, the distance between the two points, and the bearing from the origin to the destination. Then tap the "Calc" button under the word "Destination".

Distance can be entered in nautical miles, statute miles, kilometers, yards, or feet. Use the popup menu to the right of the Distance field to easily convert between distance units.

Bearing can be entered in degrees relative to true north, or relative to magnetic north (Note: if a valid magnetic model database is not available, then the bearing can only be expressed relative to true north). Use the popup menu to the right of the Bearing field to easily convert between true and magnetic bearings.

TheoNav Choose a Location Screen Choose a Location from a Database

Instead of manually entering the latitude and longitude of a location, you can choose a location from one of several location databases that are supplied with TheoNav.

Tap the "Choose a Location" box underneath the origin or destination coordinate fields. Then choose a database from the pop-up menu at the top of the "Choose a Location" dialog box.

You can scroll through the list of locations with the scroll bar or with the up/down keys on your device. Tap the name of the location to select it and to see the latitude and longitude of the location. Tap the "Aye" button to use that location's coordinates, or tap "Cancel" to return to the previous screen.

To search quickly through a large list of locations, enter the first few letters of the location name. The list will skip ahead to the first location that matches the entered letters. Tap the ("+") button to skip to the next location that matches the entered letters.

Note: Version 2 location databases are alphabetical and indexed to speed up searching. If the database you are using are indexed, then the "Fast Search" icon will appear next to the search field. If the database is not indexed, then the regular search icon will appear, and searching by location name might be slow if the database is very large.

See the chapter on Databases for more information about TheoNav databases.

Save a Favorite Location

After entering the coordinates for a location, you can save it to a list of favorites. This list will be available as a database named "Favorite Locations". This way, you can use this location later for other distance calculations, or for determining your magnetic variation.

Unregistered users can save up to ten locations in their list of favorites. Regstered users can save up to 32,000 favorite locations (see Registration for how to register TheoNav).

TheoNav Magnetic Variation Screen 5.4 Magnetic Variation

This screen can be used to predict the magnetic variation at any location on the Earth.

Magnetic variation is the navigation term used to describe the difference in direction between true north and magnetic north (this value is often referred to as magnetic declination outside the context of navigation). Variation is expressed in terms of degrees east or west and indicates how far east or west of true north a compass needle should point.

Magnetic variation differs from one location on the Earth to another. It also changes slightly over time. TheoNav uses the World Magnetic Model to predict the magnetic variation at the location you specify using the current time and date. You must have a valid World Magnetic Model database on your device to be able to calculate the variation.

To calculate the variation at a location, enter the latitude and longitude of a location, then tap the "Calculate Variation" button. See the instructions under Geographic Distance above for how to enter latitude and longitude coordinates.

Alternatively, you can choose a location from a database by tapping the "Choose a Location" box. See the instructions under Geographic Distance above for how to choose a location from a database. When you choose from a database, the variation will automatically be calculated for that location.

WARNING! TheoNav uses a global model to predict magnetic variation. Local anomalies can cause errors of several degrees or more. Always consult a current navigation chart for accurate magnetic variation values for an area.

TheoNav Compass Deviation Screen 5.5 Compass Deviation

This screen can be used to create a compass deviation table, based on the compass deviation values you have observed at various headings.

Deviation is the error induced in a compass by local magnetic fields, which can be caused by nearby metallic objects or electrical equipment aboard your vessel. Deviation is expressed as degrees east or west of magnetic north and represents the difference between the direction your compass points and the actual direction of magnetic north.

Compass deviation will be different in each direction. A compass deviation table will list the expected deviation for every heading and will allow you to accurately determine your heading from your compass reading.

Note: The technical details of how to "Swing a Compass" and take deviation measurements are beyond the scope of this document. We recommend the following books as useful guides for how to measure compass deviation values:

TheoNav uses a "least-squares" curve-fitting technique to generate a compass table based on the deviation measurements that you make. The more deviation measurements you make, the more accurate your compass table will be. You will need at least three deviation measurements for a first-order curve fit, but preferably you will have five or more measurements for a second-order curve fit.

TheoNav Edit Compass Data Enter Compass Deviation Data

Tap the "Choose Vessel" pop-up menu at the top of the screen and select "New..." to enter data for a new compass table. Enter a name for your compass table (such as the name of your vessel), and tap the "Aye" button to proceed to the Compass Data Entry screen.

Tap the "Add Value" button to add a new compass deviation value to the list. Enter the observed deviation in the "Dev." column, and enter the magnetic heading at which that deviation was observed in the "Mag." column. Tap the "E" or "W" button to specify that the deviation is east or west. After entering the data, the "Comp." column will show the compass heading based on the entered magnetic heading and deviation.

For example, if you know your vessel has a heading of 10 degrees relative to magnetic north and your compass reads a heading of "009", then your deviation at that heading is "1 degree east". In this case, enter "10" in the "Mag." column, "1" in the "Dev." column, and toggle the east/west indicator to read "E".

TheoNav Edit Compass Data

Alternatively, you can click the "Comp." pushbutton at the top of the compass column to enter a compass value directly. In the above example, you would enter "10" in the "Mag." column as before, and enter "9" in the "Comp." column. The deviation of 1° E will automatically be calculated.

You can also enter your heading for each data point with respect to true north, but you must first set your magnetic variation. Tap the "Var." box at the lower right to automatically determine the magnetic variation for your location, or if you already know the variation at your location (from a chart, for example), you can enter the variation manually. See the chapter on Magnetic Variation for more details about how to determine your variation.

When the variation has been set for this screen, it will appear in the "Var." box at the lower right. Now you can tap on the "True" pushbutton at the top of the "True" column to enter your heading relative to true north.

Tap the "Add Value" button to add the data for all the headings at which you measured the deviation, even if the deviation was zero. To delete a row of data, tap the [X] box under the trash can icon for that row. Once you have entered at least 3 values (preferably five) you can tap the "Graph" button to see a graph of the deviation curve for all headings. You can also tap the "Sort" button to re-sort the entered values in ascending order.

TheoNav Compass Deviation Screen

Once all the data has been entered, tap "Done" to build a compass deviation table. This table lets you convert between your compass heading, your magnetic heading, and your true heading.

To accurately show the difference between true and magnetic headings, click the "Var." box at the lower left to specify the magnetic variation at your location. You will be taken to the Magnetic Variation screen where you can calculate the magnetic variation at a specific location, or you can enter the variation manually. See the section on Magnetic Variation for more information on how to use the magnetic variation screen.

You can click the "True", "Mag" or "Comp" buttons at the top of the respective columns to sort and display the values by true, magnetic or compass headings. You can also change how many rows to display in the table by changing the "step" value at the bottom of the screen.

TheoNav Course Vectors Screen 5.6 Course Vectors

To calculate your Course Over Ground (COG) and Speed Over Ground (SOG) through a current, enter your vessel's heading and speed (through the water) and the set and drift of the current and tap "Calc Actual".

Alternatively, if you know your vessel's COG and SOG, you can calculate the current based on your vessel's heading and speed by tapping "Calc Current".

Thirdly, if you know the set and drift of the current and want to determine the heading to which to steer your vessel to acheive an intended COG and SOG, tap "Calc Vessel."

Similarly, if you know your vessel's speed through the water and want to know the heading to which to steer to acheive an intended COG through a current, tap "Calc Heading/SOG".

The Leeway field allows you to enter a the angle between the direction your sailboat is pointing and the direction it is travelling through the water due to sideways slippage downwind.

You can also calculate the leeway angle by entering all the other values and tapping the "Calc Leeway" button.

Tap the "Show Vectors" button to see a graphic representation of the vector sum of your vessel's speed and heading and the set and drift of the current.

TheoNav Heading vs. Speed Table Heading vs. Speed Table

The "Table" button can be used to calculate the heading to which you must steer your vessel to acheive an intended COG through a current at a variety of different speeds through the water.

The course that you are trying to achieve (COG) is shown at the top, along with the set and drift of the current that you entered on the previous screen.

The left column of the table is your vessel's speed through the water and the Heading column shows the heading to which you must steer to achieve the intended COG. The right column shows your actual speed over ground (SOG). If "n/a" appears in the Heading or SOG column, then it is impossible to achieve the intended course at that speed.

Be default, the heading and SOG are only calculated for vessel speeds from 1 to 10 knots. To calculate values at higher speeds, choose a maximum speed from the "max" popup menu at the bottom left. You can also choose a different speed step value from the "step" popup menu at the bottom.

TheoNav Vector Display Terms used in Vector Calculations:

Heading:   The direction towards which your vessel is pointing. This is indicated by your compass, after correcting for compass deviation and magnetic variation.

Speed:   The speed of your vessel relative to the water. This is the speed indicated by your vessel's knot log.

Set:   The direction towards which the current is flowing.

Drift:   The speed that the current is flowing.

COG:   'Course Over Ground' - The actual direction that your vessel is travelling, relative to the earth. This is the direction that would be indicated by a GPS. It is also the course used in dead reckoning calculations.

SOG:   'Speed Over Ground' - The actual speed of your vessel relative to the earth. This is the speed that would be indicated by a GPS. It is also the speed that would be used in dead reckoning calculations.

Leeway:   On sailboats, this is the angle that the vessel travels through the water, relative to the heading, due to sideways slippage through the water. On a port tack, this angle is added to the heading to determine your vessel's true course through the water. On a starboard tack, it is subtracted from the heading. Power boats usually have no leeway.

TheoNav Database Management Screen 5.7 Databases

TheoNav uses three types of databases:

  • Compass Deviations - Used to store compass deviation data. This is the data that you enter on the "Compass Deviation" screen.
  • Geographic Locations - Used to store names, latitudes and longitudes of geographic locations for distance calculations, and for determining magnetic variation.
  • Magnetic Models - Contains data that is used to calculate the magnetic variation at any location on the Earth.
These databases can be managed in TheoNav by selecting the "Databases" option from the "Options" menu from any of the main screens. From this screen, you can delete, rename, or beam databases to other devices.

Choose a database type from the popup menu at the top of the screen. The names of the databases of that type will be shown in the table below. The version number and size of each database will also be displayed.

A version number of 2 or higher for location databases indicates that the database is indexed and searching for a location name may be much faster for large databases. The version number for magnetic models is the "epoch", which is the first year that the model is valid. The version number is not currently used for compass deviation databases.

Notes on TheoNav databases:

A variety of geographic location databases are available for download from If you have older versions of location databases on your device, you may wish to upgrade to the newer versions for increased speed.

When you save a location as a "Favorite", it is stored in a special location database named "Favorite Locations". If you beam your "Favorite Locations" database to a friend's device, you may wish to rename it first. Otherwise it will overwrite your friend's list of favorites.

The name of each compass deviation database is the name you entered when you created a "New" vessel on the Compass Deviation screen.

Each magnetic model is valid for 5 years. The magnetic model is loaded when TheoNav starts up. If you have more than one magnetic model on your device, TheoNav tries to choose the best model, based on the current date on your PalmOS device. If you delete a magnetic model, it will not affect operation until you restart TheoNav. You cannot rename a magnetic model database.

6. Registration

TheoNav is Shareware. It's my philosophy that shareware should be useful software, even for unregistered users. As such, almost all of the features of TheoNav are available in the unregistered version. Navigators who enjoy using TheoNav on a regular basis are encouraged to register. As more features are added to TheoNav, some of them will be available to all users, and some will only be available for registered users.

You are welcome to download TheoNav for free and use it for evaluation purposes. If you like TheoNav, please register at The cost is only $10.00 (US).

Please try out the free version of TheoNav before you buy it! TheoNav has not been tested on all types of Palm OS devices. You should check that it works on your device before buying the registration key.

Benefits of Registration: (for version 2.0 and later)

  • No 5-second countdown when you launch TheoNav
  • Compass deviation data can be saved for more than one vessel
  • More than 10 locations can be saved in your list of Favorites
  • Databases can be renamed
  • You'll feel better about using TheoNav when you know you've given something back to the author
  • Future versions of TheoNav may have additional features only available to registered users

How to Register:

To aquire a registration key for TheoNav, please visit, add TheoNav to your cart, and follow the instructions for purchasing the software.

When you purchase TheoNav, you will be given a registration key for your username. You must give Handango the username that you use on your Palm device (the name that is used when you sync your handheld device).

When you get your registration key, you can enter it by clicking the "Registration" button on the startup screen, or by choosing "Register" under the "Options" menu.

7. Known Issues

  1. The graphic representation of course vectors in a current needs some improvement.

  2. TheoNav has been tested on devices with color and high-resolution screens. This version of TheoNav, however, does not fully take advantages of these features.

  3. Geographic distances are calculated assuming a spherical Earth with a circumference of 21,600 nautical miles. Greater accuracy could be acheived with calcuations using an ellipsoid model of the Earth.

  4. There are no user preferences (such as preferred types of units, default locations, etc).

  5. On devices with high-resolution screens, the white "dots" that indicate the entered compass deviation values when displaying the graph of the compass deviation curve do not display properly. FIXED in ver. 2.0.3!

  6. The following problem occurs in the Palm Emulator when emulating an m100 with Palm OS 3.5.1: when initially displaying the Compass Deviation screen when no vessels have been selected, the instruction message is partially obscured by an empty table. Once a vessel's compass data is loaded, this problem is no longer relevant. This will be fixed in the next version. FIXED in ver. 2.0.3!

  7. Vessels with long names may obscure the "Edit" and "Del" buttons on the Compass Deviation screen. FIXED in ver. 2.0.5!

  8. Non-ASCII characters cause problems when searching through location databases. FIXED in ver. 2.0.7!

  9. Use of copy and paste, or the popup keyboard are not fully tested. TheoNav may not function properly when using these methods of entering information in TheoNav.FIXED in ver. 2.0.7!