Wolfgang Strickling's Android Eclipse Page
EclipseDroid is an astronomic app, computing
local circumstances for solar eclipses like the contact times,
percentage coverage of the sun etc. EclipseDroid will control
cameras, take photos, launch other apps or give optical or
acoustic announcements depending on the times of your actual
position. As these times and values depend on your location, the
app can get them from your phone with GPS or network localization.
New: Version 7 has infrared remote control
capability. For documentation of the infrared setup details
see my documentation for CameraTimer.
Version 6 has
Text-to-speech functionality to speak written commands in the
script and Network ability, which can control cameras linked
by WiFi. This is tested with a Pentax FluCard.
Version 5 includes an EFlight mode for eclipse
observation from an aircraft, especially designed for the eclipse
2015-03-20. Now all timing tasks will run in a service which
prevent from being terminated by Android when running in
background. Minor improvements for newer Canon Cameras like the
Since version 4 EclipseDroid has a map screen,
new optional smart layout (see image right), a new location
selector with location database and the option to download a huge
database of eclipses from 3000 BC to 3000 AD. Thanks to Deirdre
O'Byrne for her database! Please note, that only the classic
layout (image left) will show the actions list, so I recommend
setting EclipseDroid to classic layout for observing the eclipse..
Most interesting are the so called contact times,
i. e. the beginning (1st contact, C1) and the end of
the eclipse (4th contact, C4), and the start (second
contact, C2) and end (3rd contact, C3) of a total or
annular eclipse. For partial eclipses, C2 and C3 are not defined,
you only obtain C1 and C4 and the maximum of eclipse.
The eclipse algorithms came from Deirdre
Java Script Eclipse Calculator, thanks to Deirdre!
BTW: Deirdre's Java Script eclipse calculator will work also
on your phone off-line! Download
source code here
Languages: English, German and Italian. Thanks to Alessandro
Veronesi for his Italian translation!
If you like to translate EclipseDroid into other languages, please
send an email to me ( dr.strickling <at> gmx.de ), it is
The Main Screen
On the main screen (see image left) you see the
date of the eclipse, whether it is partial, total or annular.
Below this, the actual location (may be GPS or network based, can
also choose a custom defined location) is shown. To choose another
location, click the Menu button and select "Location". You may
select GPS localization, let Google search a place by its address
or enter coordinates manually.
If chosen GPS or network localization, EclipseDroid
updates your location every 50 meters or 10 seconds and calculates
new times if necessary.
Below your coordinates in the second field
there are shown the four contact times and the time of mid of
eclipse. You see the absolute times and a countdown. Recent events
are displayed in grey, future events in green, except those ones
in the next five minutes. They are shown in red colour.
In the third field, the next event and its
countdown is displayed in a large line. Below this, the current
time, the selected time zone and the actual coverage (eclipse
magnitude) of the sun. The eclipse magnitude is the amount of the
covered solar diameter by the moon.
The main screen updates the countdown timers
Parallel to text output EclipseDroid can speak predefined
announcements, you can select or reselect them in the "Settings"
Below are shown a number of user defined event
and action times, like photos or text announcements. These events
need a configuration file, the "Actions File", see
documentation below. In case of cloudiness, you can check
"clouds" to prevent taking photos. If there occurs a sudden
opening in the cloud cover, press "Load emergency list". Photos in
emergency mode are taken, regardless "clouds" are checked or not.
After executing the emergency list, the regular list is loaded
again. The emergency button is only visible, if such a list is
stored on your SD card.
It is highly recommended to test extensive observation
programs carefully! Please do not expect perfect running like
a clockwork if you start your tests one week before the
click on "simulation" starts an eclipse simulation for training
and testing purposes. By default, the simulation starts 65 seconds
before C2. You can change this value in the settings menu. You can
also start a simulation at a free selectable date and time via the
settings menu, selecting "Date Simulation".
Photo events, location coordinates or brightness
sensor values can be logged in the log file
"sdcard/EclipseDroidLog.txt". Check the appropriate options in the
settings screen. Remember that the brightness sensor only gives
very rough data.
There is also an augmented reality view
available. By clicking on "sky" in the home screen you get a life
camera picture with the positions of first and last contact and
mid of eclipse in yellow, the rising and setting points. the
ecliptic in blue, a compass scale and the positions of the bright
planets. The menu button offers some fine adjustment options for
the AR screen.
Now with version 5 all timing tasks will run in a service in
background. This is indicated by a small eclipse symbol in your
Android status bar in the upper left of your screen. Thy
notification symbol will prevents EclipseDroid from being
terminated by Android when running in background. You can switch
off the notification via the settings screen, but this will also
remove the protection against termination in background, so I do
not recommend this!
The Settings screen
Pressing the Menu button of your device will pop up the settings
screen. Try EclipseDroid running with different settings according
to your requirements. To improve files and folder selection, I
recommend installing "OI
". EclipseDroid can use the browsing
capabilities of the OI File manager.
The button "local circumstances" at the bottom of
the screen starts
the local circumstances form.
displays all local parameters of the eclipse, starting again with
the location, showing some more details like the assumed value of
delta T and the altitude above sea level.
The following lines present the contact times, the altitude and
azimuth angle of the event. Azimuth 0° is north, 90° is east, 180°
The position angle to celestial north is given also, as well as
the position angle to local zenith, given in an o'clock value.
12 o'clock is upward direction zenith, 3 o'clock right. If
C1 has an o'clock position of 3, this means, that the moon will
start the eclipse by touching the solar limb exactly from the
Below are several other parameters, like rise and set times and
general parameters of the eclipse, like duration, angle of shadow bands
(only for total
eclipses), the maximal eclipse magnitude, the umbral depth (100%
is in th mid of path of totality)
At the bottom of the page you see a table at which time a certain
magnitude (coverage of solar diameter) occurs, possibly
interesting for photographers. This feature can be deselected via
the settings menu in the main screen.
Clicking your phone's menu button enables to copy the text
to the clipboard, e.g.. for saving or sending by email. You can
also select to show a NASA map of the eclipse in your web browser.
Other menu options are only available in the main screen.
You can select by pressing the menu button:
- another eclipse
- the location setup
- adjust the system clock
- simulate the eclipse
- change the program settings
- edit the actions file
- showing a global NASA-Map of the eclipse in your web browser
- displaying an info text with program version
- control the volume of speech output
- selecting the language
- visiting this web page
- Adding the eclipse to your Android calendar (only in menu of
the main form). Respect, that all times are given in the time
zone you selected in EclipseDroid, while the times in your
calendar depend on the time zone of the android device!
A very important feature is
the system clock adjust screen.
However, this app
can not change the system clock itself, as android protects system
settings against change by apps.
EclipseDroid stores and applies internally the offset as a
In this screen you can select the offset (i. e. the error) of
the system clock and the time zone.
If GPS is active, you can also force a synchronization with GPS
time. However, my desire has an average delay of about 1 second.
The entered value of GPS delay is added to the displayed GPS time.
If you have a mobile network connection, i recommend setting
"Automatic" date and time in your phone's "Date & time" menu.
It seems to be quite precise.
If you do not have a network connection, you can force a
continuous synchronization of EclipseDroid's time to GPS time. For
unstable GPS connections, deselect it and load a measured GPS
offset into the offset input field.
Selection location, date for simulation and selecting an eclipse
There are special screens from the menu, where you can select the
location, the date for simulation and select an eclipse.
With the map screen you will see the global progress of the eclipse.
By clicking you can take any position from the map as new position
Since EclipseDroid version 6.2.0 EclipseDroid offers the option to
use OpenStreetMap (OSM) geodata. with the OSM module you can use a
map tile cache or save maps for offline use. Offline maps can be
created with Mobile Atlas
Creator (MOBAC). Create an Osmdroid zip file and place it in
the osmdroid folder on your sd-card, which will be created by
EclipseDroid after the first OSM map call. Make sure, that the
folder inside the zip file has the same name as the map folder in
the osmdroid/tiles folder on your sd-card, otherwise EclipseDroid
will not fine the offline maps! Depending you your device's
performance, it my be a good advice to divide larger zip files into
In the OSM screen there will be shown the eclipse magnitude and, for
central eclipses, the central duration of the location at the map
center, indicated by a crosshair.
In this screen you can select to show the lines of magnitude in 10%
steps. However this may slow down scrolling and zooming on small
devices, so this option is not selected by default.
Setting up the actions file
A central item of EclipseDroid
is the ability to use scripts, launching user defined actions
depending on the actual contact times of your location.
To show user defined events, announcements or to take snapshots
automatically you must select the "actions file" in the settings
menu. This is a kind of CSV file with data rows and semicolon
separated columns. Each actions file line consists of several
rows, the first row is the contact you refer to, the second the
time relative to the contact (minus sign "-" means before a
contact, no sign or "+" means after a contact), the third row
denotes the kind of action and the fourth specifies details or
parameters of the action. For special actions like DSLR photos
there may follow optional parameter rows. Once you have selected
the file, you can edit it either using your favourite Computer or
Android text editor or using EclipseDroid's simple text editor in
The file will look similar like this
below. Please note that media files like
"/sdcard/20seconds.mp3"are not provided by EclipseDroid, nor are
the installed by default on your SD-card. It is just an example
how to access audio files.
#Contact;Time;Action;Parameter/for TAKEPIC: Comment;Camera;speed;fStop;ISO;+-correction;Image
E;0;LOG;*** Loading EclipseDroid.csv ****
C3;-20;SPEAK;20 seconds left;EN
c2;-45;Photo;45 mins before C2;picture-size=640x480;jpeg-quality=50
C3;120;Show;Game over, serve Champaign
A;12:00:00;show;Noon @UTC, let's have lunch
A;17:00:00;show;Noon in New York
A;2017-08-14 12:00:00;SHOW;Your flight NY -> Seattle one week before the US eclipse
REM this is a remark
# This is also a remark
// This is also a remark
You may define an emergency script. Although this is not necessary
for your observation, it may be useful in the case of clouds. If an
opening in the cloud cover appears, you can launch the emergency
script to capture the most important shots you would like to get. If
there is an emergency list present, it may look like this:
E;0;LOG;*** Loading EclipseDroidEmergency.csv ****
E;3;LOG;Emergency script finished
Do not finish the emergency script with a long
time exposure, as the regular list will be loaded after execution!
Each line consists of a minimum of four rows, separated by a
semicolon. The meaning of those entries are:
- First row: The contact.
Can be C1, C2, C3, C4 or Mid or MAX, relative to the
calculated eclipse events, spelling is case insensitive. You
may also write C0 instead of MID or MAX.
There is also the possibility to select absolute times,
indicated by the letter "A". A-times are UTC, not local time!!
For the emergency list or logging entries you may choose the
letter "E" like Emergency. These times are counted and logged
from the moment when the list has been loaded.
- Second row: The time.
For relative events (MID, C1-C4) it is the time in seconds
before ("-" sign) or after (no sign or "+") the contact. You
may also use HH:MM:SS or MM:SS format.
01:10:20 in HH:MM:SS format is the same as 70:20 in MM:SS or
Absolute timings ("A" in the first row) are given in
HH:MM:SS format in UTC (date = eclipse day),
you may also enter other dates in the format YYYY-MM-DD
HH:MM:SS in UTC.
Do not enter local time zones!
- Third row: The action.
Actions can be:
- SHOW (displaying a text on
the main screen in classic layout).
As the actions list will only be displayed in the classic
menu, I recommend setting EclipseDroid in to classic
layout just before your eclipse observation. Go to the
preferences and select "Classic layout"
- LOG will write a text into
the EclipseDroid log file, for example indicating certain
phases of your observation program or to protocol loading
a script. Example: E;0;LOG;Loading EclipseDroidEmergency.csv
- PLAY playing an audio file with
Android's media player.
- SPEAK will speak a
written text, using the text-to-speech (TTS) engine of
Android. You can specify a desired language by adding a
language code parameter.
Examples: C1;-1;Speak;1;en will
say "one", C1;-2;Speak;2;IT
will say "duo". The selected language is kept until the
- PHOTO, taking a snapshot with the
internal camera. Photos are generally made with the
maximum resolution and the best JPEG quality (jpeg-quality=100)
- TAKEPIC, taking a snapshot with an
- IRSend, transmits an infrared
remote command, for example to a DSLR camera.
Use as device names the same the same names as
specified in the .com.strickling/ircommands.csv
file on your sd-card.
For a documentation of the infrared setup details see
my documentation for CameraTimer.
- FLASH, to release the camera
flash, e. g. for launching external cameras like a DSLR.
The following number is the flash duration in ms, try
something in the range from 100 to 300 ms. My EOS 450D
accepts 100 ms. You will find a description of an optical
interface cable to use the flash light of your phone for
releasing a camera in my description of the Android App CameraTimer.
- LAUNCH, launching an external app.
It searches first for the application label (case
sensitive), then makes case insensitive search, if not
found yet it searches for class name (sub string, case
- Still experimental: The USBCOMM Command.
Accepts at present LifeViewOff and LifeViewOn,
for some CANON cameras. It switches to LifeView mode,
though does not display an image. But this works like the
mirror lockup avoiding camera shake by the mirror.
- NET: communication via WiFi
network, especially for controlling Pentax cameras with FluCard.
deletes all events related to a special contact,
example: C3;-20;CLEAR;C2 will
delete all commands starting with "C2" twenty
seconds before C3. See tips below
aborts an emergency script and and returns to normal
Useful to avoid that a late launched totality emergency
script extends into Baily's beads phase. Include something
like "C3;-5;RETURN" in your emergency
script to hand over to your normal actions file just in
time before C3.
- fourth row: The parameter.
For SHOW it is the message to be displayed on the screen,
otherwise the file to be played or to be launched.
For internal photos you can select a file for storage. If
nothing selected, the file name will be "EclipseDroid". The
date and time will be added in every case. Chose the desired
photo directory in the settings menu of the main screen!
- For photos with internal cam you can enter a list of
additional camera parameters. These settings are a bit
tricky, so make extensive tests! Wrong parameters have no
effect or can even crash the whole app!
The commands are loaded one by one with the Camera.Parameters.Set
method into the camera. Read the android
documentation for further details. A sample file of
camera settings on my HTC Desire can be downloaded here.
If coordinate acquisition is active (network or GPS), the
photos will be geotagged.
- For USB Cameras with command TAKEPIC there are more
The first parameter is a comment;
second parameter the camera model as displayed on
connect (at present it may be left empty, for future planned
multi camera support required);
third parameter: shutter speed in seconds. Examples:
2, 0.01, 1/100; Use standard values and avoid interim values
1.3 or similar!
fourth parameter: fStop, like 8.0, 5.6; Usage of
standard values is recommended, avoid interim values like 7.1
fifth parameter: ISO speed, valid parameters: "a" for
automatic, 100; 200 etc. Avoid non standard values like ISO
160 or similar!
sixth parameter: +- exposure correction;
seventh parameter: Image format. Valid values: "S",
"M", "L", "R", "RAW", "R+L", "SF", "SmallFine", "SNormal",
"Medium Fine", "MF", "S1", "S2", "S3"
If no parameter change is desired, leave one or more fields
Keep in mind, that your camera has to be in the correct mode.
For instance, shutter speed selection is usually not possible
in full automatic mode, in full manual mode +- exposure
correction will have no effect!
For using USB functionality please set "USB Debugging" to On
in Android Settings, Developer Settings, otherwise the app
might crash on certain devices.
- A new option in Version 6 is the Network capability,
using the http protocol, especially to control Pentax cameras
equipped with the WiFi
FluCard and connected to your device.
Syntax is like this:
C2;+20;NET;http://pentax/cgi-bin/host_operation?action=shutter&af=0&seq=00000000 to release the shutter and
save the image to SD-card.
Further commands for controlling Pentax cameras with
sets the shutter speed to 1/500 s.
Example values for shutter speed:
1.1000 for 1/1000 second, 4.1
for 4 seconds
This will change the f-number (aperture) of your lens.
This command sets the camera to ISO 400.
This is the +- correction.
Exposure bias (+/- correction) values range
from -5.0 to 5.0. Examples: -1.0,
-0.7, -0.3, 0, 0.3, 0.7, 1.0 and so on.
This will set the auto correct exposure (same
effect as pressing the Pentax GREEN Button).
Pentax forum thread if you need more Pentax FluCard
The network commands are sent to a task queue, which waits for
the response of the previous command before sending new
There are some commands controlling the network communication.
instead of an "http://..." request:
- To clear the network queue send "CLEAR".
It is recommended to call when loading an (emergency)
script, Example: E;0;NET;CLEAR
- The default network timeout is set to 2000 ms. After
this time EclipseDroid will not longer wait for a missing
response and will execute the next command in the network
You can change the default value by using the command "timeout"
followed by the timeout time in ms instead of an "http://..."
Example: set timeout to 1000 ms when starting the script:
- EclipseDroid will wait 100 ms between receiving a
response and sending a new command to the network
device. You can change this waiting time by sending
the WAIT command
example: E;0;NET;WAIT 50 will set the
value to 50 ms, if you send E;0;NET;WAIT 0
EclipseDroid will not wait any
The waiting time is needed, because sometimes the
FluCard connection produces an EOF (End Of File)
error, if the app does not wait until the next
The directive "REM
" in an actions or emergency script forces
EclipseDroid to create a text file with the calculated times of
your script for script debugging. It is located in the same folder
like your actions file, its file name ends with "_Debug.txt".
It is highly recommended to test extensive observation
programs carefully! Please do not expect that everything is
perfect running like a clockwork if you start your tests just
one week before the eclipse!
Tips & tricks for your scripting:
- Eclipsedroid ignores upper case or lower case typography the
scripts as well as the "+" sign in times: "MID;+20;LOG;"
is the same as "mid;20;log;" will do the
- You may write relative timings in several formats: 01:10:20
in HH:MM:SS format is the same as 70:20 in MM:SS or 4220
- I recommend writing the times around second and third
contact as well as for totality as relative to C2
Although for a 2 minutes eclipse "C2;0;"
is the same as "MID;-60;" a possible
necessary location change may spoil your script. If you will
get a shorter totality time at your location, "MID;-60;"
will be in the partial phase whereas the
times relative to C2 or C3 are corrected automatically for
your location. Use C0 or MID only for events which are
absolutely tied to the mid of the eclipse!
For the same reason I introduced the CLEAR
command. Imagine you wrote your script for a 2 minutes
eclipse, but you have to change your location, so that
there will be only one minute of totality left. Now
times like C2;+90 will be after C3! to avoid this,
insert something like
C3;-20;CLEAR;C2 to delete all
surplus commands tied to C2.
- You may plan a gap in your totality photographic
program to pick up possible shortening of totality time,
if you have to change your location. You may fill this gap
easily by launching an emergency script.
- For sequences of the partial phases I recommend
using times relative to C1 for the first half of the first
partial phase, and times relative to C2 (with "-"
sign) for the second half of
the first partial phase.
This will also buffer changes in the timing in case of
location changes. The same applies for the second partial
- I do not recommend starting scripts for early partial phases
with fixed exposure times. It is better to try the correct
exposure manually according to atmospheric transparency.
- Test your scripts, use the debug option, rehearse your
observation program and simulate the eclipse with the
For testing the flash mode or USB camera parameters, you can also
try my free apps 'Camera Timer'
Setup of the EFlight mode
Since version 5
EclipseDroid supports an EFlight mode. During a flight, your
position will change and with this your contact times will change
as well. There will be different locations for each contact event
and in higher altitudes above sea level there will be a noticeable
shift of the centreline.
A classic eclipse observing flight will usually happen like this,
see the map at the left:
The flight will start from a departure location at a given time
and return to a destination location. Usually but not necessarily
this will be the same airport. From the departure location the
aircraft will cruise more or less directly to the centreline. In
between, the first contact will occur. Once the centreline is
reached, the aircraft will turn and fly more or less parallel to
the centreline in the same direction as the Moon's shadow
movement. This will provide a longer totality duration than an
observer on the ground will observe.
The aircraft will keep this course for the whole totality and
several minutes after totality, trying to give a good and stable
view on the eclipse from one window side. This section of the
flight is called the totality run
Several minutes after totality the aircraft will turn to a course
back to the destination airport. On this way, there will happen
the fourth contact.
As you see on the map, the centreline in the stratosphere (short
grey line) is not the same than the centreline at sea level (in
In EclipseDroid you have the choice to enter the contact times
either manually, if you get them from the flight operator, or to
calculate them dynamically on the estimated locations and times
for departure, start and end of totality run and arrival. You can
also use GPS to calculate the actual times.
There is a special setup screen for entering your EFlight parameters
available, see screen shot on the right:
After entering the estimated positions and times of departure,
arrival at totality run and arrival at destination airport
EclipseDroid calculates contact timings. For calculation of the
totality run you have to enter its start location, time, speed and
bearing. The totality run usually ends a few minutes after totality.
You have to enter the time from mid eclipse to the end of totality
run, an often used value are 5 or 6 minutes.
If "Use GPS position" is checked, the current flight phase is
dynamically calculated from your actual location, speed and bearing.
If the aircraft is already cruising on the centreline, check
"Totality Run in progress" to force totality run calculation for
your actual coordinates.
For more details on planning EFlights see Glenn
Schneider's special website.
Download here the old
4 without EFlight or the old
Version 2 without USB support.
Small test app for checking USB capabilities of
your device: Download USBCamera here
or from Google
Source code of the USB library PtpLib (Zipped
This app is also available in the Android market.
For manual download you need an Apk_Installer
(see QR-Code in the right) or the Astro File Explorer. On
your phone you have to allow installation of applications from
non-Market sources. Activate in your phone's menu in "Settings",
"Applications" the check box "unknown sources", otherwise you will
not be able to install my applications!
- Hardware controls: Camera.
Required for AR. May cause compatibility refusal for devices
without front camera. Try installation from my website!
- Exact location: For
site-specific calculations of the contact times.
- Internet Access and network
communication: Online selection and network based
localization of an observation site.
- SD card access:
Storing settings, event lists, logs and locations coordinates
for offline search.
- System tools: prevent phone from sleeping in hot phase
of the eclipse
- Your Accounts: for actual Google maps required.
Software for other computers are developed by:
last Update 2016-09-03
The original URL of this page is http://www.strickling.net/eclipsedroid.htm