Welcome to

EclipseDroid Tutorial,

Wolfgang Strickling's Android Eclipse Page

Diese Seite auf DeutschActions list scripting tutorial | Flight mode tutorial


Screenshot Hauptfenster

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 650D.

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 O'Byrne's 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 quite easy!

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 every second.
Parallel to text output EclipseDroid can speak predefined announcements, you can select or reselect them in the "Settings" menu.Testing the
        App at the PSE 2011

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 eclipse!

ar viewA 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 File Manager". 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.

Screenshot Lokale GegebenheitenThis screen 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° south etc..
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 right side.

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:

A very important feature is

the system clock adjust screen.

screenshot clock adjustHowever, 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 correction parameter.

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 for calculation.

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 multiple files.
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

EclipseDroid is controling two cameras during TSE 2015A 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 menu.

The file will look similar like this below. Please note that media files like "/sdcard/20seconds.mp3"are not provided by EclipseDroid, nor are they 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 format

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
c2;-35;Show;Shadow Bands!
c2;-20;Show;Covers off!
c2;-10;Photo;Before Totality
c2;-3;TAKEPIC;Bailys Beads;EOS450D;1/1000;16;200;-1;MF
c2;-2;TAKEPIC;Bailys Beads;EOS450D;;;;;
c2;-1;TAKEPIC;Bailys Beads;EOS450D;0.01;8;400;-1;SN
c2;0;takepic;Bailys Beads;EOS450D;1/200;;200;;RAW
c3;35;Show;Shadow Bands!
C3;20;Show;Covers on!
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;19:35:20;SHOW;Sunrise 5:35:20
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:

#Contact (E=Emergency);Time[s];Action;Comment;Camera;speed;fStop;ISO;+-correction;Image format

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:
  1. 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.

  2. 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 4220 seconds.
    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!

  3. 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 next change.
    • PHOTO, taking a snapshot with the internal camera.  Photos are generally made with the maximum resolution and the best JPEG quality (jpeg-quality=100) by default if no other parameter is defined.
    • TAKEPIC, taking a snapshot with an USB camera.
    • IRSend, transmits an infrared remote command, for example to a DSLR camera.
      Example: C1;-1;IRSend;Canon 
      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 insensitive).
    • 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.
    • CLEAR: 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 for usage.
    • RETURN: aborts an emergency script and and returns to normal script.
      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.
  4. 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!

  5. For photos with internal cam you can enter a list of  additional camera parameters. The first (optional) parameter is always the filename, it will be extended by the date and the time. If not specified, "EclipseDroid" will be chosen by default. For devices with several cameras you can specify which camera will be used. Insert parameter camera_id=0; for the main camera, camera_id=1; will usually switch to the front camera. On the LG G5 camera_id=2; will select the wide angle camera.
    The other parameter settings are a bit tricky, so do extensive testing! Wrong parameters have no effect or can even crash the whole app!
    When a photo was taken, you will find all parameters of your camera in the CameraParameters.txt file in the .com.strickling folder on your sd card (available in EclipseDroid v. 7.1 or higher). You should have a look at this file before using custom parameters. A sample file of camera settings on my HTC Desire can be downloaded here.
    The commands are loaded one by one with the Camera.Parameters.Set method into the camera. Read the android documentation for further details.
    If coordinate acquisition is active (network or GPS), the photos will be geotagged.

  6. For USB Cameras use the command TAKEPIC. There are more parameters recommended.
    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 or similar
    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 empty.
    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.

  7. 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:
    to release the shutter and save the image to SD-card.

    Further commands for controlling Pentax cameras with FluCard:

    http://pentax/cgi-bin/host_operation?action=set-camera-config&shutter-speed=1.500&seq=00000000 sets the shutter speed to 1/500 s.
        Example values for shutter speed:  1.1000 for 1/1000 second, 4.1 for 4 seconds
    http://pentax/cgi-bin/host_operation?action=set-camera-config&f-number=8&seq=00000000  This will change the f-number (aperture) of your lens.
    http://pentax/cgi-bin/host_operation?action=set-camera-config&exposure-index=400&seq=00000000   This command sets the camera to ISO 400.
    http://pentax/cgi-bin/host_operation?action=set-camera-config&exposure-bias-compensation=2.0&seq=00000000  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).
    Read this Pentax forum thread if you need more Pentax FluCard commands.

    The network commands are sent to a task queue, which waits for the response of the previous command before sending new commands.
    There are some commands controlling the network communication. Use them 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 pipe.
      You can change the default value by using the command "timeout"  followed by the timeout time in ms instead of an "http://..." request.
      Example: set timeout to 1000 ms when starting the script: E;0;NET;TIMEOUT 1000
    • 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 longer.
      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 command.

The directive "REM DEBUG" 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:

For testing the flash mode or USB camera parameters, you can also try my free apps 'Camera Timer' and 'USB Camera Test'.

Setup of the EFlight mode

Eflight SetupEFlight setupSince 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 blue).

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 from my website: EclipseDroid.apk or from the Android Play Store. Get free Version from PlayStore.
System requirements: Android 2.0 or higher, for using USB support Android 3.1 or higher, a device supporting USB host mode and an adapter cable.
Download source code of eclipse routines here, an example actions file and the camera settings on the Desire as an example for camera settings
Small test app for checking USB capabilities of your device: Download USBCamera here  or from Google PlayStore.

Source code of the USB library PtpLib (Zipped files).

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!

Required Permissions:


Software for other computers are developed by:

last Update  2017-03-12
The original URL of this page is  http://www.strickling.net/eclipsedroid.htm