Tide Tool Readme

This is the readme file for Tide Tool 2.2 for Palm and other handhelds running PalmOS. For changes from earlier versions, see "What's New."

This may not be the most recent version of Tide Tool. Check the Tide Tool web page. To be notified of new releases, sign up for the email list..

Tide Tool is copyrighted, licensed freeware. It is not public domain. See "License" below.

If Tide Tool doesn't work for you, please let me know so I can fix it. And if you have an unusual or interesting use for Tide Tool, please tell me.

Contents:

Requirements:

To run Tide Tool, you need a Palm handheld computer, or other handheld (such as the Handspring Visor) running the Palm OS (Operating System). If you don't have these, see the FAQ.

Installation:

To install Tide Tool on your Palm, use the Palm Install Tool on your PC to install three files:

If you are upgrading from an earlier version of Tide Tool, delete the old version from your Palm before installing the new one. (If you have Tide Tool files on an expansion card, be sure to delete these too.)

To add another set of locations, install the additional regional database file. To delete or disable a region, use the Edit menu.

Because the regional database files make the location selection process run more slowly, and take up considerable RAM, only install the files for the regions you're interested in. (Or disable some of the installed regions. See "About the Regional Databases" below.)

Program and/or database files may be installed on an expansion memory card or in main memory. For best results use the Palm Install Tool in the Palm Desktop to do this. Installing on an expansion card will make the Place screen run more slowly.

If conserving memory is important, you can install SmallArgs.pdb instead of TideArgs.pdb. This saves about 24k of memory, but will only allow tide computation from 1998 to 2014, instead of to 2031.

Tide And Current Display:

The first time you run Tide Tool, it will (after a one-time initial message) compute today's tides at the default tide location for the region you loaded.

You will also see the present time and tide displayed right under the date. This will not appear when you change to a date other than today.

If you want a prediction for a specific time, use the graphical display, and tap the graph at the time you want. The time and tide line will show the prediction. On some Palms that have a left and right direction button, it may move the prediction arrow. If displaying today's predictions, tapping the prediction text will return to the "now" status.

The phase of the moon and the state of the sun (up, down or near the horizon) are also shown. Tap the sun or moon for more details.

To see a tide or current for a different location, use the Place button (see next section).

If portions of the tide graph or the background shadings are too light to read, adjust the contrast, or use the Edit/Preferences menu command to turn off grayscale display.

How To Find And Change Locations:

The only locations for which Tide Tool can compute tides or currents are the ones in its database (see "About the Regional Databases").

To see a list of the locations in the database, hit the Place button on the main screen. This shows you a list of all the locations, in order of their approximate distance from the location that was just displayed on the main screen.

To see currents instead of tides, or vice versa, use the checkboxes. This is an easy way to get the closest current to your displayed tide location, or vice versa. (For example, if you are looking at the tide display, and want to see the nearest current location to the tide location you're looking at, hit Place, then the Currents checkbox, then OK.)

(There is usually not both tide and current data available for the same location. In many parts of the world there are few or no current locations available. See "About the Regional Databases" for more information.)

To view a list of the places you have viewed recently, check Previous. Up to 32 locations are remembered. Tide and current locations are mixed in this list.

The locations that have a tiny superscript 'o' at the end of the name are offset locations. They are computed by taking fixed differences from the tides or currents at a reference station some distance away.

If you only want to see the reference stations, not the offset stations, press Menu, select Edit/Preferences, and select "Ignore secondary stations".

To pick a location near another location you see, tap it, hit Find, go to the Find screen, and use Set Position To. Or tap the location, hit OK to view that location, hit Place to return to the Place screen, and select Tides or Currents if necessary.

In what order are the locations displayed? Normally, the locations are displayed in order of their approximate distance from the location that was just displayed on the main screen. The exception is that if you go to the Find screen and select "Find place names containing:", then the locations containing the string you enter will be displayed, in alphabetical order, followed by all the other locations in alphabetical order.

On the Garmin iQue 3600 GPS only, check Use GPS Position on the Find screen to set the position to the last available GPS reading.

Other Controls:

Tide Tool displays tides for dates from January 1, 1998 through December 30, 2031.

To change the units of tide depth and current speed displayed on the screen, press Menu and select Edit/Units. The Default setting will use the default units for each location. Also use Edit/Units to choose how the time is displayed, and to suppress the display of the tide coefficient (which is only shown for French Atlantic Coast ports).

Tide Tool can indicate the times when the tide is at a level you select. Use Info/Preferences and select Tide Level Guide. In the text field on that line, enter the tide level you would like displayed, and select whether it is in feet, meters or inches. The selected level will be displayed as a line on the graph. In addition, tides at that level are listed in the tide table, but only for reference stations, not for secondary stations.

To see the time zone information for the location you are viewing, press Menu and select Info/Time Zone.

To see which regional databases are loaded, and some information about them, and to disable or delete unwanted databases, press Menu and select Edit/Regions. (See "About the Regional Databases").

For information about the location you are viewing, press Menu and select Info/Location. This will tell you the latitude and longitude of the location, which regional database it is in, whether it is computed as an offset from a reference station, and how many harmonic factors are used in the computation. Offset locations and locations with many harmonic factors take longer to compute.

To turn color or grayscale display on or off, press Menu and select Edit/ Preferences. If no color or grayscale option is shown, your device does not support them.

To beam Tide Tool to another Palm device, press Menu and select Edit/ Beam Tide Tool. Beaming from the Applications screen just sends tidetool.prc. This function will send both tidetool.prc and all the database files (except any that you have marked Disabled on the Edit/Regions menu).

Sun And Moon Functions

To see the sunrise and sunset times for the day being displayed, tap on the sun (or use the Info/Sun menu item). Also, if the graph is displayed in color or shades of gray, the graph background indicates day and night times. Sunrise and sunset times are generally accurate to within a few minutes in most latitudes, but can be off by as much as an hour or two at high latitudes when the sun is traveling nearly parallel to the horizon.

To see the moon phases for the current month, and time of moonrise and moonset, tap on the moon (or use the Info/Moon menu item). Moon phases computed by Tide Tool are generally accurate to within one day. Moonrise and moonset times are good to within a minute or so. The moon icon shows the current moon phase (one of 8 possibilities).

The sun icon shows whether the sun is up, down or on the horizon at the location being displayed, at today's date and local time. If you're displaying a location in the same time zone you're in, that's no problem.

But if you're in California and displaying Japan at 10:00 am California time, the sun icon will show the state of the sun in Japan at 10:00 am Japan time. Some day Tide Tool will use the abilities of later versions of Palm OS to determine where you really are, and this will all make more sense.

"On the horizon" means from 20 minutes before sunset to 40 minutes after. Yes, I know that there are algorithms for better computation of twilight, but I don't have one yet.

About The Regional Databases:

Tide Tool comes with about 26 regional database files (see list below) covering the entire world (except for the British Isles; see note below). Use the Edit/Regions menu command and tap an information icon to see what is in the databases you have loaded.

It is possible to load many or all the databases into your Palm, if you don't mind using up over a megabyte of memory. You can place any of the files either in main memory or in an expansion memory card. You can also load the Tide Tool program and databases into flash memory or a ROM cartridge, if you have the necessary software and hardware.

However, Tide Tool is not capable of using all or even most of the locations at one time. Loading a lot of databases may produce an error when trying to go to the Place screen, or even crash or reset your Palm. Even if no error occurs, the more locations that are available, the slower the sort process when selecting locations. Placing databases in expansion memory will slow the Place screen down even more.

To deal with this, you can temporarily disable some of the databases. Go to the Edit / Regions menu command, and use the pulldowns to set some of the databases to "Disabled". They will remain in memory, but you will not see them when searching or selecting locations until you enable them again.

The locations that you have viewed recently will still be available in the "Locations Viewed Recently" list on the Places screen (the "Previous" checkbox), even if they are in a disabled database. It is still possible to view them. They just won't show up in the list of places.

The databases are based on the harmonics files distributed with XTide 2.6, using the latest data sets as of Dec. 18, 2003. See http://www.flaterco.com/xtide. The full location list as of Dec. 18, 2003 is on the web site.

I do not add locations to Tide Tool. I only incorporate locations that are in, or have been added to, the XTide database.

If you want your location added: do not ask me. You must submit tide data for your location to the XTide database. For most locations, this would mean submitting a set of offsets from a known reference location. In some cases you would need to find or generate a set of harmonic constants.

Once the location has been added to the XTide database, it will show up in the next release of Tide Tool.

About Daylight Savings Time:

Tide Tool tries to take into account the effects of local daylight savings time. On the tide/current display, next to the date, you will see the time zone(s) that apply to the day being displayed. You can check whether daylight savings is being applied correctly (and I hope you do) by hitting the [Date] button and using the calendar to go to the day on which DST switches over. If the program is doing this correctly, you'll see something like:

To see the details for the location being displayed, hit the Menu button and select Info/Time Zone. DST can be suspended using the Edit/Units menu item.

Most areas that do not observe daylight savings time have their time zone given relative to GMT (or Greenwich Mean Time, which is now usually called UTC, but GMT has a better flavour).

Note: Spring Forward, Stumble Back: Because the Palm clock keeps local time, it is impossible to know the real (GMT) time during the hour when DST "falls back". For example, if it is 2:30 a.m. on the fourth Sunday in October in North America, there is no way for the program to know if it is 2:30 DST or 2:30 standard time. So event times that fall within that hour may be off by one hour. The correct time can be determined by tapping on the graph, which correctly displays two hours between 1 and 3 a.m.

Note On Historical Dates: Tide Tool incorporates the DST calculations available as of September 1997, as best I can figure them out. Some time zone information has been updated in response to user reports or other more recent information. Many countries have changed their DST policy in the past, but Tide Tool just assumes that the rules for dates earlier than 1997 (or later, for that matter) use the same rules.

Note On Iran: Iran, alone among the countries in the Tide Tool database, uses the Persian calendar rather than the standard calendar of the Great Satan. This makes it difficult to calculate the correct switchover date for DST. The date should be correct for 1997 through 1999, and off by no more than one day thereafter. Incidentally, the only country with worse calculations is Israel, but Tide Tool fortunately has no Israel location data.

Accuracy Of Predictions:

Before using Tide Tool's predictions, you should compare them with your local published tide tables to get a feel for how close it comes.

Tide Tool uses algorithms best suited to North America. Tide computations should generally agree with local tables in North America to within a few minutes, unless the specific locations for Tide Tool and the tables are different. In other parts of the world, the difference from local tables may be greater. In some locations in Australia, the difference can be up to an hour or two. Also note that the sunrise and sunset computation is approximate.

Predictions for offset locations (indicated by a little circle at the end of the location name) are inherently approximate. They are derived using a time and magnitude offset from a known "reference station". This can give strange results in some cases.

The event times (high tide, max ebb, etc.) for offsets should be pretty good. The graphs for offset locations are drawn using simple interpolations. Therefore, predictions between events on the graph display for offset locations are really nothing more than intelligent guesses and should not be considered reliable.

Other Limitations:

Currently, the program assumes that the local date and time in your Palm is the same as the local time and date of the tide location. So if you're displaying a location in a different time zone and it's 3:45 pm where you are, the display will say it is now 3:45 pm at the tide location, but it isn't. Of course, if you're not there, you probably don't care.

Tide Tool is based on a number of programming projects by individuals who made their work available at no charge, over the Internet. Particular thanks to:

Tide Tool is named in honor of The Software Toolworks (later called Mindscape), developer of many great software products including The Chessmaster, Mavis Beacon Teaches Typing, and The Miracle Piano Teaching System.

I started The Software Toolworks in 1980 by writing and selling software for the Heathkit H-89 computer. The H-89 featured an 8-bit Z-80 processor running at 2 MHz, 48k (not meg) of RAM, and one floppy disk drive with a capacity of 90K bytes.

Although Palm OS computers are considerably more powerful than the H-89, the community of early software developers which coalesced around the Palm OS's open software architecture was reminiscent of the cooperative energy that infused the early days of personal computer software publishing.

Source Code:

Under the terms of the GNU software license, you are entitled to a machine-readable copy of the source code of this program. The source code for version 2.1a is available on the Tide Tool web site at http://www.toolworks.com/bilofsky/tidetool/tidesource.html. Please note the cautions, especially the one about the source code being unsupported.

Please also note that the source code is subject to the terms of the GNU public license, so if you're thinking of making your fortune by selling something that uses it, please think again. Sorry.

Files:

READ THIS FIRST!.html	This file
tidetool.prc	The program file
TideArgs.pdb	Data for the tide computation algorithm
SmallArgs.pdb	A smaller substitute for TideArgs (covers years to 2014 instead of 2031)
GPL	The GNU public software license

and the following regional databases containing tide data for different regions (and current data in North America ):

Maine to Massachusetts.pdb	Massachusetts to Maine
Newport RI to Cape May NJ.pdb	Newport, R.I. to Cape May, N.J.
Cape May NJ to Virginia.pdb	Cape May, N.J. to Virginia
North Carolina to Georgia.pdb	North Carolina to Georgia
Florida East.pdb	Florida (east of Sarasota)
Gulf Coast-Florida West.pdb	Gulf Coast, and Florida (Sarasota west)
Alaska.pdb	Alaska
US West Coast.pdb	West Coast of the U.S.
SE Canada-N Atlantic.pdb	East Coast of Canada and N. Atlantic ocean (s. of 47º N)
CE Canada-N Atlantic.pdb	East Coast of Canada and N. Atlantic ocean (47º N to 53º N)
NE Canada-N Atlantic.pdb	East Coast of Canada and N. Atlantic ocean (n. of 53º N)
SW Canada.pdb	West Coast of Canada (s. of 49.5º N)
CW Canada.pdb	West Coast of Canada (49.5º N to 51º N)
NW Canada.pdb	West Coast of Canada (n. of 51 N)
Caribbean.pdb	Caribbean, Central and South America (n of the equator)
Mexico.pdb	Mexico
South America.pdb	South America (s of the equator)
Great Britain.pdb	The British Isles. (No locations in Eire are available in this release.)
Northern Europe.pdb	Europe (n. of 46.5º N) including all of Russia, but excepting the British Isles (note above)
Mediterranean.pdb	Mediterranean, including Europe (s. of 46.5º N) and Africa (n. of 31º N)
Africa-Asia Minor.pdb	Africa (including Asia Minor w. of 60º E)
Asia.pdb	Asia (e. of 60º E), excluding Japan . Includes Indonesia and the Philippines
Japan SW.pdb	Southwest half of Japan (west of 134º E)
Japan NE.pdb	Northeast half of Japan (east of 134º E)
Pacific Islands.pdb	Islands of the Pacific west of 131º E including New Zealand, Tasmania and Papua/New Guinea
Australia.pdb	Australia (except Tasmania)

Tide Tool 2.2 Instructions

Contents:

How To Find And Change Locations:

Other Controls:

Sun And Moon Functions

Tide Tool 2.2
Instructions