Subsections of More

Settings

Suntimes -> Settings to change application settings.

General

Suntimes -> Settings -> General to change general settings.

Alarms

Suntimes -> Settings -> Alarms to change alarm settings.

Language

Suntimes -> Settings -> Language to change language settings.

Places

Suntimes -> Settings -> Places to change place settings.

User Interface

Suntimes -> Settings -> User Interface to change user interface settings.

Widgets

Suntimes -> Settings -> Widgets to reconfigure widgets, or configure widget themes, or widget actions.

Subsections of Settings

General

Suntimes -> Settings -> General to change general settings.

Welcome Screen

Starts the first launch configuration wizard. This guided configuration is also shown the first time the app is launched.

Time Format

  • System format (default)
  • 12-hour
  • 24-hour

Units of Length

  • Metric (kilometers, meters)
  • Imperial (miles, feet)

The default value will depend on your specific locale.

Localize to Hemisphere

Apply hemisphere based localization. This setting will swap labels and icons (seasons, moon phases, etc) when configured to locations in the southern hemisphere.

Show Seconds

Include seconds when displaying twilight times. Do not expect precision better than minutes. This option is disabled by default.

Use Elevation

Apply altitude based refinements when calculating data (times may differ up to 10 minutes).

Data Source

Select the data source for sun or moon based calculations (Advanced). The default is time4j-4a.

Language

Suntimes -> Settings -> Language to change language settings.

Mode

  • System to use the system locale (default).
  • User Defined to override the system locale.
Note

It is recommended to change System settings instead of overriding the locale. In some cases User Defined may fail to work as expected (partial translation).

Language

Suntimes has been translated into the following languages:

  • Arabic
  • Basque
  • Catalan
  • Czech
  • Dutch
  • Esperanto
  • French
  • German
  • Hungarian
  • Italian
  • Norwegian
  • Polish
  • Portuguese
  • Russian
  • Simplified Chinese
  • Spanish
  • Traditional Chinese
Note

All translations are volunteer contributions! On occasion a translation may be incomplete or may contain minor errors. See the contribution guidelines if you would like to help update or improve a translation.

User Interface

Suntimes -> Settings -> User Interface to change user interface settings.

Appearance

  • Light always shows light theme.
  • Dark always shows dark dark.
  • System default follows the system theme, and will automatically switch between light and dark themes.
Light Theme
  • Default (Light)
  • High Contrast (Light)

Default (light) Default (light) Contrast (light) Contrast (light)

Dark Theme
  • Default (Dark)
  • High Contrast (Dark)

Default (dark) Default (dark) Contrast (dark) Contrast (dark)

Text Size

  • Small (12)
  • Normal (14)
  • Large (16)
  • Extra Large (18)
Tip

The text size setting also respects the system settings.

Adjust system text size first, then override the size in Suntimes for readability if necessary.

Small text Small text Large text Large text

Display (Default Events)

Tap options to toggle the visibility of default fields on the main screen.

  • Astronomical Twilight
  • Nautical Twilight
  • Blue Hour
  • Civil Twilight
  • Actual Time (sunrise, sunset)
  • Solar Noon
  • Golden Hour
Emphasize Field

The emphasized field is displayed with increased text size (defaults to actual time).

Display (Custom Events)

Tap Manage Events to add or remove custom events.

Display (Other)

Twilight

  • Header Icon. Show column header icons.
  • Header Text. Show column header text. [None, Labels, Azimuth]
  • Light Map. Show a stacked bar chart of day, night, and twilight periods.

Moon

  • Moon. Show moon rise and set times, phase, and illumination.
  • Lunar Noon. Show lunar noon and lunar midnight as part of the moon dialog.

Solstice / Equinox

  • Solstice / Equinox. Show time until next solstice or equinox.
  • Cross-Quarter Days. Include midpoints between solstices and equinoxes.
  • Solstice Tracking. Track the [Recent, Nearest, Upcoming] event.

Object Shadow. Display the length of a shadow cast by an object with a given height (defaults to 1.83 meters).

Miscellaneous

  • Show Map Button. Show an action bar button that opens the default map app.
  • Show Data Source. Show a label indicating the current configuration.
  • Show Warnings. Show configuration warning messages.
  • Verbose TalkBack. Announce automated changes to the UI.

More options:

  • Show Weeks. Divide time spans greater than 7 days into weeks (e.g. 15d becomes 2w 1d).
  • Show Hours. Include hours and minutes in time spans greater than a day.
  • Show Time (with dates). Include the time when displaying dates.

Tap Actions

The main screen can be customized to perform specific actions when parts of the UI are tapped.

The default tap actions are:

  • On Clock Tap, show next upcoming event.
  • On Date Tap, swap cards (today/tomorrow).
  • On Date Long Press, open the calendar.
  • On Note Tap, show the next note.

Tap on each setting to pick from suggested actions, or tap the icon to select from all actions.

Events

Suntimes displays astronomical event times in dialogs and widgets. It can also use events to schedule repeating alarms.

Default Events

  • sunrise, sunset, & solar noon
  • civil, nautical, & astronomical twilight times
  • blue hour, & golden hour
  • moonrise, moonset, lunar noon, & lunar midnight
  • major moon phases
  • solstices, equinoxes, & cross-quarter days

Custom Events

Suntimes allows defining events with a user-defined angle. Similar to defaults, these custom events can be displayed in the app, in widgets, and used to schedule alarms.

Suntimes -> Settings -> User Interface -> Manage Events to configure custom events.

Custom Events Custom Events

Add, Edit

Tap to add an event. To edit an existing event, select an item, then tap edit. The edit dialog will be shown.

Custom Events Custom Events

Enter a label, angle, and (optional) color, then tap to save the event.

The button toggles visibility of the event on the main screen.

Delete, Clear

To remove an event, select an item, then tap delete.

Use : -> Clear to clear all events.

Note

When removing custom events, any alarms, notifications, or widgets using that event may no longer work and will need to be reconfigured.

Export, Import

Custom Events (menu) Custom Events (menu)

Use : -> Export to export events to file, and : -> Import to import events from a previous export.

Tip

It is also possible to export or import events by creating or restoring a backup.

Add-on Events

Suntimes supports additional events through add-ons.

For example, Interval Midpoints can be used to schedule alarms between events (at calculated midpoints), and the Natural Hour app can be used to schedule alarms using roman time.

Interval Midpoints Interval Midpoints Natural Hour Natural Hour

Subsections of Places

Manage Places

Places List

Suntimes -> Settings -> Places -> Manage Places to open the places list.

The places list can also be reached by tapping when selecting a place.

Places List (menu) Places List (menu)

Add World Places

Suntimes includes coordinates for over 200 cities located around the globe.

Use : -> Add World Places to add world places to the list.

Tap to search the list of places.

Add Place

To add a place, tap to show the add place dialog.

Add Place Add Place

Tap to query the device’s current location, or manually input coordinates.

Finally, tap to save the place.

Permissions

Getting the current location requires location permissions. When prompted, grant permissions and enable device location to use this feature.

Copy, Edit, Remove

To copy a place, select it, then tap : -> Copy.

To remove a place, select it, then tap : -> Delete.

Select Place Select Place Select Place Select Place

To edit a place, select it, then tap edit. Modify the label or coordinates, then tap to save changes.

Edit Place Edit Place

Share Place

To share a place, select it, then tap share.

Place coordinates can be displayed on a map, or by other applications that support location sharing.

Tip

The currently configured place can be shared from the main screen using the map button.

Import, Export

Use : -> Export to export the list of places to file.

Use : -> Import to import a previously exported list.

Tip

It is also possible to export or import places by creating or restoring a backup.

Clear Places

Use : -> Clear to clear the list of places.

Tip

Changes made to the place list will not affect existing configurations. It is safe to clear the list at any time. Places will be automatically added to the list when (re)configuring widgets or alarms.

Place Settings

Suntimes can query the device’s current location using the GPS or Network providers.

To configure this behavior, use Suntimes -> Settings -> Places to access the place settings.

Location Settings Location Settings

Permissions

Getting the current location requires location permissions. When prompted, grant permissions and enable device location.

Location time limit

When requesting the current location, Suntimes will actively wait for a location update until the time limit expires.

The default location time limit is 1 minute.

Note

Location requests may time out if GPS or Network location providers are unavailable (and the current location is older than the max age).

Location recent max age

When requesting the current location, Suntimes will trigger a location update if the current location is older than the max age.

The default location max age is 5 minutes.

Passive Location

Suntimes can use the passive location provider to determine the device’s location. A separate app is required to make active update requests.

Actions

Suntimes can perform user-defined actions when a widget is clicked, or when an alarm or notification is shown or dismissed.

widget action widget action alarm action alarm action

Subsections of Actions

Add Actions

To add an action… create an Intent by declaring:

Intent (leave fields empty for an implicit intent)
Action An action string. e.g. android.intent.action.ACTION_VIEW
Class A fully qualified class name (case-sensitive). This must be a complete definition that includes both the package and class name.
The class is required for explicit intents - leave it blank to allow the system to decide which class to launch.
e.g net.osmand.plus.activities.MapActivity
Data A URI that contains or points to attached data. e.g. geo:30,31. Limited %substitutions are supported. e.g. geo:%lat,%lon
Mime The mime type of attached data (if applicable). Leave blank for most types of data.
Extras An & delimited string containing key-value pairs. Values may be Strings, int, long, double, float, or boolean. Limited %substitutions are supported.
e.g. key1="some string" & key2=1 & key3=1L & key4=1D & key5=1F & key6=true & key7=%dm

An app that displays package info is useful for discovering Activities, which can then be launched with an explicit intent.

Subsections of Data

Data Substitutions

Suntimes supports limited %substitutions, a set of tags that are replaced with values from the data set.

Substitutions may be used within widget titles, alarm notes, or within action data or extras.

widget title widget title action data action data

Examples

%loc, %M, or %t can be used to include the location name, event name, or time zone as part of a widget’s title.

%dm and %em@<event> can be used to pass time (milliseconds) as part of an action; e.g. URI content://com.android.calendar/time/%dm opens the calendar app.

%lat and %lon can be used to pass the location as part of an action; e.g. URI geo:%lat,%lon opens the map app.

Subsections of Data Substitutions

Available Substitutions

Date/Time:

  • %t for time zone (id) (e.g. US/Arizona)
  • %d for formatted date (e.g. February 12)
  • %dd for day (short) (e.g. Mon)
  • %dD for day (long) (e.g. Monday)
  • %dY for year (e.g. 2018)
  • %dt for formatted time (of last update)
  • %dT for formatted time with seconds (of last update)
  • %dm for time in milliseconds (of last update)
  • %eot for formatted ’equation of time’ (of last update)
  • %eot_m for ’equation of time’ milliseconds (of last update)

Location:

  • %loc for label (e.g. Phoenix)
  • %lat for latitude
  • %lon for longitude
  • %lel for elevation (e.g. 385 meters)

Misc:

  • %s for data source (e.g. sunrisesunsetlib)
  • %id for appWidgetID

Sun Widgets:

  • %m for mode (short) (e.g. Civil)
  • %M for mode (long) (e.g. Civil Twilight)
  • %o for order (e.g. Last/Next, Today)
  • %em@<event> event milliseconds
  • %et@<event> event formatted time
  • %eT@<event> event formatted time (with seconds)
  • %eA@<event> event altitude
  • %eZ@<event> event azimuth
  • %eD@<event> event declination
  • %eR@<event> event right ascension

where <event> is:

Sun WidgetsSun Position Widgets
<event>
rising sr
setting ss
noon sn
rising setting
civil twilight cr cs
nautical twilight nr ns
astronomical twilight ar as
blue hour 4deg b4r b4s
blue hour 8deg b8r b8s
golden hour gr gs

Moon Widgets:

  • %i for moon illumination (e.g. 25%)
  • %M for moon phase (e.g. Waxing Crescent)
  • %o for order (e.g. Last/Next, Today)

Solstice Widgets:

  • %m for mode (short) (e.g. Solstice)
  • %M for mode (long) (e.g. Winter Solstice)
  • %o for order (e.g. Closest Event, Upcoming Event)

Data Sources

Suntimes uses third-party libraries to perform astronomical calculations.

The data source settings allow for choosing between different libraries (or choosing between different algorithms offered by those libraries).

Suntimes -> Settings -> General -> Advanced

Data source settings Data source settings

These are advanced settings that affect the speed and accuracy of calculations, and may limit which features are available.

Subsections of Data Sources

Available Data Sources

Library Description
sunrisesunsetlib Not Recommended Somewhat inaccurate and sometimes buggy. Does not support altitude, seconds-based calculation, solstice, equinox, or sun position. Based on “Almanac for Computers” by the USNO. github.com/mikereedell/sunrisesunsetlib-java
ca.rmen.sunrisesunset Partially Recommended Similar to sunrisesunsetlib but with reasonable precision. Does not support altitude, solstice, equinox, or sun position. Based on the algorithms published by NOAA. github.com/caarmen/SunriseSunset
time4a-simple Not Recommended Somewhat inaccurate. Does not support altitude. Based on “Almanac for Computers” by the USNO.
time4a-noaa Partially Recommended Same algorithm used by ca.rmen.sunrisesunset with reasonable precision. Does not support altitude. Based on the algorithms published by NOAA.
time4a-cc Recommended Good precision taking the altitude of locations into account. Based on “Calendrical Calculations” by Dershowitz/Reingold. Supports all features.
time4a-time4j Recommended Default Best precision taking the altitude of locations, the elliptic shape of the earth and typical weather conditions into account. Based on “Astronomical Algorithm” by Jean Meeus. Supports all features. github.com/MenoData/Time4A

A few important details:

  • Do not expect precision better than minutes. The app hides seconds by default (but this can be enabled).
  • The precision of the USNO and NOAA algorithms tends to be very inaccurate in polar regions.
  • The time4j and cc algorithms may differ substantially (up to 10 minutes) from algorithms that do not account for altitude.
  • One difference between the time4j and cc algorithms is that cc only assumes the altitude of the observer by an approximated geodetic model, while time4j does it using a spheroid (WGS84) and the assumption of a standard atmosphere (for refraction).
  • None of these algorithms are able to account for local topology (a mountain directly in front of you), or deviating local weather conditions.

Adding Data Sources

The app can be extended to add additional data sources by implementing the Suntimes Calculator interface.

Data Provider

Suntimes can provide data to plugins or add-on apps through a content-provider.