Earth&Sun Program for the PalmPilot

Earth&Sun Program for the PalmPilot
Version 1.2^*

Description

Earth&Sun is a program for the PalmPilot to show the Sun Illuminated area of the Earth.
It will also display:

The latitude and longitude of an Earth location.
The time zone at that location, based on only longitude not civil boundaries.
The current time at that location based on the above time zone.
The sunrise, sunset times, and day length at that location.
The great circle distance between to locations on the earth.

Earth&Sun can be used as a realtime clock if you have a Palm V or use a PalmPilot simulator on your computer.

Because of time zone irregularities some will consider Earth&Sun to fall into the category of "fun and games".
We hope you find Earth&Sun useful and enjoy it.

About This Documentation

Earth&Sun is intuitive and easy to use. This documentation probably seems large, but you really should read it to fully understand all of the features. For a Quick Start read Installation. Then after trying it out please return to this documentation to learn all of the features. Sections:

Installation (Must Read)
Using the Program
- Time Mode
- Distance Mode
Prefs.. Menu and RealTime Clock
More Details
Version Changes

Installation

earth12.prc: The executable file
mathlib.prc: The required mathematics library
earth&sun.html: This file
esDisp1.gif, esDisp2.gif, esMenu1.gif, esMenu2.gif, esPref1.gif, esPref2.gif: Images for Earth&Sun.html

If you have Earth&Sun V1.1 installed, installation of this V1.2 will replace the V1.1.
If you have Earth&Sun V1.0 installed in your PalmPilot after installation of Earth&Sun V1.2 you will have the older V1.0 still installed. Simply delete the V1.0. (The older Earth&Sun is titled "Earth&Sun", the new version is titled "Earth & Sun", for your convenience).

Use the Pilot installer to install earth12.prc. Earth&Sun requires mathlib.prc^*. If you already have mathlib.prc already installed just install earth12.prc. Otherwise install both earth12.prc and mathlib.prc.

Note: If your PalmPilot is using OS3.5 be aware that there is a bug in OS3.5 such that it will not remember the category of any re-installed application. Thus for both new or re-installation will have to move Earth&Sun out of 'unfiled'.

Using the Program

The map display should be obvious. The shaded area is that part of the world that is dark at the current time. The location where the Sun is directly overhead is shown by a little icon which is a + sign outlined in reverse 'color'. It is not too obvious in the screen shots shown here. You can find it located over Ecuador.

Hopefully program usage is pretty much self evident once you have followed these instructions. Earth&Sun has two modes of operation: Time Mode, and Distance Mode. Initially it is in the Time Mode.

Upon first use you will be greeted with a message requesting you to tell Earth&Sun the time zone to which the PalmPilot's clock is set. This is an offset from GMT (Greenwich Mean Time). If you do not set this the display will always be incorrect!
First just set the PalmPilot's Clock Time Zone and check DayLight Savings if applicable.
(See GMT offset time zone table if you do not know what to enter.)

The "Done" button will set the value and return to the main screen.
Below is a discussion on the other two items in the Prefs.. menus. Ignore them at first.

Time Mode

To understand the following instructions first tap the pen on an earth location.
Look at the first and second rows of the text output display area from left to right.
For the tapped location:

Time is its current time. This is based solely on the time zone displayed next.
Zone is its time zone based solely on its longitude, not on civil boundaries.
Lat is its latitude.
Rise is its sunrise time. See discussion on sunrise/set time values.
Set is its sunset time. For latitudes near the poles, it is possible that the Sun does not rise or set. In that case the rise/set output will be displayed as: N/A.
Length is the length of the day.

Looking at the third row of the output display from left to right:

Clock is the PalmPilot clock's time zone which you set when Earth&Sun started up. If you did not set it do it now using the Commands -- Prefs.. menu. Failure to do so makes the entire display of Earth&Sun invalid.
Longitude is tapped location's longitude.
(S) is the Standard/Daylight Savings Time button. Pressing this button switches any tapped location from standard to daylight time, or vise versa, for all locations.
(N) is the Normal/Freeze button. See discussion on freezing time zones.

Looking at the forth row of the output display from left to right:

1X Button is a button to toggle the map between 1X and 2X magnification. In the 2X mode use the pen to drag the map.
Date Selector allows selection of a different date.
Time Selector allows selection of a clock time different than the PalmPilot's clock.
Now Button resets the time to the current PalmPilot clock time, but does not change the date.

Hardware Scroll Buttons
The Up/Down hardware scroll buttons in the lower center of the PalmPilot allow you to simulate time changes in increments of: 1, 3 and 6 hours. Pressing the Up bottom advance time and the Down button decreases time. You can change the time increment/decrement value using the Time Incr menu. Wrapping time around for 24 hours does not change the date.

Distance Mode

You switch between the Time and Distance Modes with the Commands menu, or simply by tapping the word "Time" ("Loc") on the first line below the map.

In the Distance mode the text output display area changes as shown on the right.
Tap a location on the map. For the tapped location:

Loc is 1 because the "1" button on the third line was highlighted.
Lat is the latitude of the location you tapped.
Long is its latitude.
Mi is the distance in miles from location 1 to location 2
NMi is the distance in nautical miles.
Km is the distance in kilometers.

Next tap the "2" button on the third line and it will become highlighted. Then tapping the map will fill in the data for Loc 2 and change the distance to reflect the new location. "Br:" is the great circle bearing from Loc 1 to Loc 2.

Prefs.. Menu and RealTime Clock

Reference Location
The Reference Location is for you to enter a location for which you would frequently like to find the sunrise and sunset, your home for example, you may enter that location into the Reference Location of the Prefs.. menu. Then when you tap to the right of "Sun Illuminated Earth" it will fill in the data for that location. You may also tap the data line that shows time/rise/set, or use the 'Ref. Info.' menu item. This works in either the Time or Distance modes.
If you do not enter a location the data will always be for the equator.

RealTime Clock
If you have a PalmPilot which is plugged into external power (such as Palm V or a computer Palm simulator) you may use Earth&Sun as a real time clock. Simply check the "RealTime Clock (Palm V)" checkbox.
When that box is checked and the PalmPilot is plugged into external power, the Time Selector box will be in synchronism with the PalmPilot clock and the map will be updated every 5 minutes. Five minutes is the smallest time which can show a Sun shadow change. When the external power is removed the updating will stop.

More Details

Sunrise/set Time Values
You will find that the sunrise and sunset times may be different in the 1X and 2X modes. The reason is that the calculated values are for different longitudes in the two modes:

In the 1X mode the sunrise and sunset times are for the longitude at the center of the displayed time zone.
In the 2X mode the sunrise and sunset times are for the displayed longitude.

The reason for two different calculation is a matter of accuracy of pen positioning. On the 1X display it is difficult to locate a particular latitude/longitude, so it was found that giving the sunrise/set times for the center of the time zone would give more consistent results. This means that the sunrise/set times are the same for all time zones at a given latitude! Thinking about that for a moment you may conclude that it is a useful feature.

In the 2X mode the sunrise/set times are accurate for the displayed latitude/longitude. See for discussion on the Normal/Freeze Button which follows. This gives an example of different times at different longitudes.

Back to the second row discussion.

Normal/Freeze Button
Since the time zone is based solely on longitude the Normal/Freeze button allows you to freeze a time zone so that in the 2X mode you can find sunrise/set times for locations which do not follow normal time zone rules. For example: Alaska which extends over 4 time zones, Russia and China which extend over 3 times zones. Also there are locations like western Texas where the time zone boundary is very much west of where it should be

To use this feature, in the 2X and Normal mode, put the pen down on a location which is in the desired time zone. For example: Alaska time is 9W, so tap the map on eastern Alaska and verify that the time zone is 9W. Then observe the sunrise/set times. Next tap the (N) button. It will change to (F) -- Freeze. Then tap the western part of Alaska and the sunrise/set time should be about 2 hours later. Now tap the far western Aleutians Islands and see the sunrise/set advance another hour. Note that the time zone still reads 9W.

With a frozen time zone it is possible that the sunset could occur in the next morning. In this case the time might be, e.g. 24:10. The same is true for sunrise except it might occur the previous night, with a sunrise e.g. of 23:45. Note: In these cases the Date Selector does not change.

Back to the third row discussion.

Contact Info

The Bray PalmPilot Page can be found at: http://www.40-below.com/palm/

Registering

Earth&Sun is freeware no registration is required. We hope you enjoy using it.

This archive may be freely redistributed, provided it is made available only in its complete, unmodified form with no additional files and for noncommercial purposes only. Any other use must have prior written authorization from David W. Bray at bray@clarkson.edu.

Unauthorized commercial use includes, but is not limited to:

Earth&Sun itself as a product for sale.
Accompanying a product for sale.
Accompanying a magazine, book or other publication for sale.
Distribution with 'Media', 'Copying' or other incidental costs.
Available for download with access or download fees.

Disclaimer

This program is provided without warranty and the user accepts full responsibility for any damages, consequential or otherwise, resulting from its use.

Foot Notes

^* - Many thanks to Rick Huebner, the author of MathLib, for his excellent routines and making them freely available.

GMT Time Zone Offset is the number of hours the PalmPilot's local clocks differ from that of Greenwich Observatory in England. Set the Time Zone menu to correspond to the following table according to your location.

United States		Around the World
Time Zones	Offset	Time Zones	Offset
Eastern	5 West	British Isles	0 East
Central	6 West	Western Europe	1 East
Mountain	7 West	Eastern Europe	2 East
Pacific	8 West	So. Africa	2 East
Alaska	9 West	Russia	3 East
Hawaii	10 West	Japan	9 East
		Eastern Australia	10 East

Back to "Using the Program"

^*Program Changes in Version 1.2

Earth&Sun Version 1.2 differs from earlier versions in:

Distance Mode is added. (V1.1)
Reference Location for quick data update entry added. (V1.1)
Palm V RealTime Clock mode added. (V1.1)
East/West/North/South letter indicators changed from uppercase (E/W/N/S) to lowercase (e/w/n/s). The S looked too much like a 5. (V1.1)
Map display shows terminator line by one dot in reverse 'color'. (V1.1)
Improved display for all time values when the timezone Freeze mode is in effect (See Normal/Freeze button above.) (V1.1)
Removed Reference Timezone rounding to make it exact for both 1X & 2X. (V1.2)
Changed title to be left justified and added tap of data line for Reference Info. (For OS3.5). (V1.2)
Added a menu entry 'Ref. Info.' had Ref. Info. be displayed at application start-up. (V1.2)