Help

User Manual

Documentation on Suntimes can be found here. Links to these topics are also included within the app ( Online Help).

User Support

The issue tracker can be used to report bugs or request features.

Chapter 1

Configuration

Suntimes needs to be configured for best results.

Welcome

Suntimes will display a welcome screen to assist with initial configuration.

Tip

The welcome screen is automatically displayed the first time the app is launched. It can be revisited later from Suntimes -> Settings -> General -> Welcome.

Appearance

Suntimes supports light and dark themes, and can switch between them to match the system. It also includes high contrast versions of these themes.

Suntimes supports larger text sizes (while also respecting the system’s text size settings). Choose a larger text size to improve readability.

Tip

Appearance settings can be changed later from Suntimes -> Settings -> User Interface -> Appearance.

User Interface

Suntimes can be customized to show or hide information. Choose the fields that should be displayed by the main screen (and hide others).

Tip

It is also possible to show custom events that occur when the sun is at a given angle.

User Interface settings can be changed later from Suntimes -> Settings -> User Interface.

Location

Select a place. Suntimes provides a locale specific default (and includes a large list of world places).

Use Add World Places to add all defaults to the list of places, or Import to import a previously saved list.

Use Get Location to add the device’s current location to the list.

Note

The location is manually configured by default; Suntimes does not require location permissions (optional).

Time Zone

Select a time zone. Suntimes displays information using the system time zone by default.

Tip

Choose a time zone within a couple hours of local mean time for best results.

Verify the time zone if reported times seem inaccurate or don’t make sense. A mismatch between the time zone and location is a common misconfiguration.

Alarms

Use Import to restore alarms from a previous installation of Suntimes.

Extra configuration may be required for alarms to work reliably. Please follow all recommendations if you intend to use alarm features.

Select a Place

Suntimes requires location data to configure dialogs, alarms, and widgets.

It is recommended to configure the app to some user-defined location (such as a local park, intersection, or city center). Suntimes can also periodically query and update using the current location.

User-Defined Location

Suntimes is configured to a user-defined location by default. The use of location permissions is optional.

Configure the location using:

Previous place: choose a previously used place from the drop-down list.
Places list: tap to open the places list, select an item, then tap to choose that place.
Manual input: Tap to edit the displayed place. Change the place’s coordinates and label, then tap to save. The modified label will be added as a new place.
Current location: Tap to edit the displayed place, then tap to query the device’s current location. Change the place’s label, then tap to save. The modified label will be added as a new place.

Tip

You can also use a separate app to pick the location. Sharing a location with Suntimes will open the location dialog to the selected coordinates.

Tip

Suntimes supports coordinates with meter accuracy but this level of detail is optional. For best results, specify coordinates within 60 miles of your current position.

Current (last known)

Suntimes can be configured to use the current (last known) location. Location permissions are required.

When configured to current (last known), the application will periodically query the current location whenever launched or resumed, and widgets will use the last known location when updated.

Change the place settings to configure current (last known) behavior.

Select a Time Zone

Suntimes can be configured to use a given time zone (or other time standards).

System Time Zone

Suntimes displays time using the system time zone by default.

User-Defined Time Zone

Suntimes can display time using a specific time zone.

Choose user-defined, tap to sort the list, then select a time zone from the drop-down.

Tap -> Recommend Time Zone to suggest a time zone closely matching local mean time.

Note

Time zone recommendations work best for named places in the IANA time zone database and may produce inaccurate results for other places.

Tip

Choose a time zone within a couple hours of local mean time for best results.

Verify the time zone if reported times seem inaccurate or don’t make sense. A mismatch between the time zone and location is a common misconfiguration.

Tip

Suntimes will display an info icon when daylight saving (or a similar rule) is in effect.

Time Standard

Suntimes can also display time using:

Local Mean Time (LMT)
Apparent Solar Time (LTST)
Local Sidereal Time (LMST)
Greenwich Sidereal Time (GMST)
Coordinated Universal Time (UTC)

Chapter 2

App Dialogs

Use from the main screen to access app dialogs. Dialogs can also be shown by tapping different UI elements, or triggered using actions.

Main

Location

Suntimes displays the location name and coordinates in the action bar.

Tap to change the location.

Tap to update the current location.

Tap to show the location on a map. Visibility of the map button can be changed from Suntimes -> Settings User Interface -> Show Map Button.

Current Time

Suntimes displays the current time and time zone in the upper left.

Tap the time zone, or use : -> Set Time Zone to change the time zone.

Tip

Suntimes will display an info icon when daylight saving (or a similar rule) is in effect.

Suntimes will display a warning icon when the time zone disagrees with local mean time. This is a common misconfiguration.

Tip

Suntimes will announce the time (and other changes to the UI) when using verbose TalkBack. Suntimes -> Settings User Interface -> Verbose TalkBack.

Next Event

Suntimes tracks the time until the next event in the upper right.

Tap the event field, or swipe left or swipe right, to step through events.

Sunrise, Sunset, Twilight

Suntimes displays today’s sunrise, sunset, and twilight times.

Use : -> View date to scroll to a specific day, or swipe left or swipe right to see past and future days. Tap or to reset to today.

Tap the column headers to show the time until sunrise or sunset.

Tap noon or the lightmap to open the sun dialog.

Tip

Suntimes can also display custom events. Suntimes -> Settings User Interface -> Manage Events

Tip

Visibility of the twilight fields can be changed from the User Interface settings. Suntimes -> Settings User Interface -> Display. The lightmap can be toggled from User Interface -> Show Light Map.

Suntimes can also put emphasis on one of the fields. This can be changed from User Interface -> Emphasize Field.

Moon

Suntimes displays moonrise, moonset, phase and illumination. Tapping this info opens the moon dialog.

Tip

Visibility of the moon info can be toggled from the User Interface settings. Suntimes -> Settings User Interface -> Show Moon.

Solstice, Equinox

Suntimes displays the next solstice, equinox, or cross-quarter day. Tapping this field opens the solstice dialog.

Tip

Visibility of solstice tracking can be toggled from the User Interface settings. Suntimes -> Settings User Interface -> Show Solstice / Equinox.

Data Source

Suntimes displays the data source in the lower right. Tapping this field opens General settings.

The use elevation option can be toggled from the lower left. Altitude-based refinements will be applied when enabled.

Tip

Visibility of the data source can be changed from the User Interface settings. Suntimes -> Settings User Interface -> Show Data Source.

Sun

Current Position

Suntimes displays the sun’s current azimuth and altitude, azimuth at sunrise and sunset, and altitude at solar noon.

Light map

Suntimes can display a graph of daylight and twilight periods.

Tip

Use Suntimes -> Settings User Interface -> Show Light Map to show the light map view on the main screen.

Altitude Graph

Use : -> Altitude Graph to toggle the altitude graph, and : -> Options to change the graph’s options.

Grid
Labels
Axis
Filled Path
Show Moon

Note

Changes to the graph options are also applied to home screen widgets.

Seek Altitude

Suntimes can find the time when the sun will be at a given angle in the sky.

Use : -> Seek Altitude to specify the angle.

Tap to find the rising time, or to find the setting time.

Tip

Tapping the sunrise, noon, or sunset areas (next to the altitude field) will seek to the time of those events.

Play (animation)

Suntimes can animate the light map and altitude graphs at different rates:

5m the frames are 5 minutes apart.
1d the frames are 24 hours apart.

Tap and to step through frames one at a time.

Tap to play the animation, to pause it, and to reset to the current moment.

View Date

Use : -> View date to open other dialogs at the selected date/time.

Object Shadow

Suntimes can find the length of the shadow cast by an object with a given height.

Use : -> Object Shadow to change the height.

Tap to reduce the object’s height, and to increase it.

The object height can also be changed from Suntimes -> Settings User Interface -> Object Shadow.

Note

The length of the shadow will be ∞ when the sun is below the horizon.

Moon

Phase, Illumination, and Position

Suntimes displays the moon’s current phase, illumination, azimuth, and altitude.

Tip

Use Suntimes -> Settings User Interface -> Show Moon to show this info in the main table.

Playback

Use : -> Playback to show the controls.

Tap and to step through positions at 5 minute intervals. Tap to reset to the current time (on the selected day).

Moonrise, Moonset

Suntimes displays the time of moonrise and moonset.

Swipe left or right to scroll to past or upcoming days, or tap to reset to today.

Tip

The month views will scroll automatically to show dates around the selected day.

Show Lunar Noon

Suntimes can also display the time of lunar noon and lunar midnight.

Use : -> Show Lunar Noon to toggle this option.

Synodic Month

Suntimes displays the time/date of the moon’s major phases (synodic month), and labels the “Super Moons”.

Swipe left or right to scroll to future or past months, or tap to reset the view.

Columns (phases)

Use : -> Columns (phases) to change the number of columns displayed.

Anomalistic Month

Suntimes displays the time/date of the moon’s apogee and perigee (anomalistic month), and the moon’s current distance.

Swipe left or right to scroll to future or past months, or tap to reset the view.

More Options

Tap on a field to show the context menu button.

Use : -> Set Alarm to set an alarm for the selected event.

Use : -> View Date to open other dialogs at the selected date/time.

Use : -> Share to copy text to clipboard.

Solstice, Equinox

Solstices, Equinoxes (tracking)

Suntimes displays the solstices and equinoxes, and can track the number of days until or since those events.

Use : -> Track to change tracking to the recent, nearest, or upcoming event.

This option can also be changed from the User Interface settings. Suntimes -> Settings User Interface -> Solstice Tracking.

Tip

Tracking can be enabled in the main view using Suntimes -> Settings User Interface -> Show Solstice / Equinox.

Cross-Quarter Days

Suntimes can display the midpoints between each solstice and equinox (the cross-quarter days).

Use : -> Cross-Quarter Days to toggle this setting.

This option can also be changed from the User Interface settings. Suntimes -> Settings User Interface -> Cross-Quarter Days.

Note

Changes to the Cross-Quarter Days setting are also applied to home screen widgets.

Tropical Year

Suntimes displays the length of the tropical year.

More Options

Tap on a row to select it and reveal the context menu button.

Use : -> Set Alarm to set an alarm for the selected event.

Use : -> View Date to open other dialogs at the selected date/time.

Use : -> Share to copy text to clipboard.

World Map

Maps

Basic
Blue Marble
Polar (North)
Polar (South)
Azimuthal Equidistant (Phoenix)

Map Options

Use : -> Options to change the map’s options.

Sunlight (shadow)
Moonlight
Location (dot)
Graticule (minor grid lines)
Major Lines (equator, tropics, arctic circle)

Note

The map options are also applied to home screen widgets.

Play (animation)

Suntimes can animate the world map at different rates.

15m the frames are 15 minutes apart.
1d the frames are 24 hours apart.

Tap and to step through frames one at a time.

Tap to play the animation, to pause it, and to reset to the current moment.

Tip

Long pressing the map will also play the animation, and tapping it again will pause.

Suntimes can share individual frames, or record all frames in an animation.

Use : -> Share to share the current map view.

To share an animation, long press to start recording. When finished, tap (where the play button was previously) to share the frames (as .zip).

View Date

Use : -> View date to open other dialogs at the selected date/time.

Set Background

Suntimes can be configured to display a custom world map background.

Use : -> Center -> Set Background to change the map’s background image.

Download Backgrounds

To use backgrounds… Store full-sized images somewhere on your device, then open with Set background. Suntimes uses URI permissions to access images stored on the SD card.

Projection	Map Backgrounds (click for full-size image)
Equidistant Rectangular
Equidistant Azimuthal

Made with Natural Earth. https://www.naturalearthdata.com/about/terms-of-use/

NASA Earth Observatory. Blue Marble: Next Generation. https://visibleearth.nasa.gov/view_cat.php?categoryID=1484

Advanced

Creating Backgrounds

The background image should be a png or jpeg, with recommended dimensions 1024 x 512 or 1024 x 1024 or greater (will be scaled to fit the screen).
The default maps use vector data from Natural Earth, and raster data from Blue Marble: Next Generation.
The default maps use a white foreground (landmasses), and transparent background (ocean). The final coloring is determined by the app’s theme.
The graticule and other markings are drawn behind the background image (requires transparency).
The background image must have the appropriate map projection, center, and aspect ratio to align correctly.

World Map	Aspect	Projection	Center	proj4
Basic	`2:1`	Equidistant Rectangular	`[0,0]`	`+proj=eqc +lat_ts=0 +lat_0=0 +lon_0=0 +x_0=0 +y_0=0 +a=6371007 +b=6371007 +units=m +no_defs`
Polar [north]	`1:1`	Equidistant Azimuthal	`[90,0]`	`+proj=aeqd +lat_0=90 +lon_0=0 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs"`
Polar [south]	`1:1`	Equidistant Azimuthal	`[-90,0]`	`+proj=aeqd +lat_0=-90 +lon_0=0 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs"`
Azimuthal Equidistant	`1:1`	Equidistant Azimuthal	`[LAT,LON]`	`+proj=aeqd +lat_0=LAT +lon_0=LON +x_0=0 +y_0=0 +a=6371000 +b=6371000 +units=m +no_defs"` where `LAT` and `LON` define the center of the projection.

A GIS application (e.g. QGIS) can be used to create new map backgrounds. The map data needs to be re-projected or warped (see proj4 definitions), and exported to an image with the appropriate aspect ratio. The final image should be optimized to reduce its size (e.g. pngquant).

Chapter 3

Alarms

Suntimes Alarms is a sunlight aware alarm clock with support for daily repeating alarms and notifications.

Set Alarm

Alarm Types

Suntimes supports multiple alarm types. Tap to choose the type.

Alarms will sound until they are dismissed or snoozed.
Notifications remain in the tray until they are dismissed.
Quick Notifications are shown for a brief moment.

Tip

Quick Notifications are automatically dismissed after 30s (changed from Suntimes -> Settings -> Alarms -> Auto-dismiss after). Regular notifications will remain the tray until they are dismissed.

Schedule by Time

Tap the Time tab to schedule alarms by time.

Use the picker to select a time, then tap to accept and edit the alarm.

Suntimes can also schedule alarms using solar time. Tap to change the time standard:

System Time Zone (default)
Apparent Solar Time
Local Mean Time

Suntimes can schedule an alarm on a specific date. Tap to open the date picker. Choose a date, then tap to accept.

Schedule by Event

Tap the Event tab to schedule alarms by event.

Select an event from the drop-down list, then tap to accept and edit the alarm.

Tap to select a custom event (or an event provided by an add-on).

Tap to change the alarm’s location.

Show Alarm Time

The alarm time is displayed at the bottom of the dialog.

The icon is displayed if the time will be adjusted by a before/after offset. Tap the icon to momentarily display the combined alarm + offset. The alarm offset can be configured when editing the alarm.

Edit Alarm

Tap to cancel without making changes.

Tap to save, or to save and enable.

Tap to save and disable.

Tap to cancel and delete.

Type

Tap to change the alarm type:

Alarm
Notification
Quick Notification

Tip

Quick Notifications are automatically dismissed after 30s. Suntimes -> Settings -> Alarms -> Auto-dismiss after to change this setting.

Label

Tap Label to change the alarm label.

Note

Tap to change the alarm note.

Tip

The note is displayed with the label, and supports limited %substitutions.

Event (or time)

Tap to change the alarm’s event or time.

Repeat

Suntimes supports daily repeating alarms, and will automatically reschedule alarms as event times change throughout the year.

Tap to change repeat options.

Offset (before/after)

Suntimes can schedule alarms before or after an event or specified time.

Tap at to change the offset options.

Tip

Tap the alarm time preview to see the combined event + offset alarm time.

Location

Suntimes can schedule alarms for events occurring in different locations.

Tap to change the location.

Reminder

Suntimes can show a reminder several hours before an alarm triggers, and perform an additional action at that time.

Tap to toggle the reminder.

Tip

The reminder notification allows alarms to be dismissed early. Dismissing a repeating alarm will automatically reschedule it for the next day.

Sound

Suntimes can play a ringtone or audio file when an alarm sounds.

Tap to change the alert sound, or select No Sound for a silent alarm.

Tip

Enable Suntimes -> Settings -> Alarms -> Show all ringtones to allow selection of all system sounds regardless of their intended use.

Vibration

Suntimes can cause the device to vibrate when an alarm triggers.

Tap to enable vibration.

On Alert Action

Suntimes can perform an action when an alarm triggers.

Tap On Alert to change the alert action.

On Dismiss Action

Suntimes can perform an action when dismissing an alarm.

Tap On Dismiss to change the dismiss action.

On Dismiss Challenge

Suntimes can require passing a challenge before dismissing a sounding alarm.

Tap On Dismiss to change the dismiss challenge.

None
Easy Math (single digit math problems)

Tip

Add-ons can provide additional challenges; e.g. Suntimes NFC can be used to dismiss alarms using NFC tags.

Alarm List

The alarm list can be shown from Suntimes -> Set Alarm, or by tapping Suntimes Alarms from the app launcher.

Tip

Suntimes -> Settings -> Alarms -> Launcher Icon to enable the Suntimes Alarms icon in the app launcher.

Select, Deselect

Tap an item in the list to select it. Selected items display the alarm note and additional controls.

Tap on the lower left of the screen, or press back to clear the selection.

Add Alarm

Tap to set an alarm. The alarm event dialog will be shown.

Edit Alarm

Tap an item in the list to select it. Tap the item again to edit the alarm.

Delete, Clear

Tap an item in the list to select it, then tap the button to remove the alarm.

Use : -> Clear to remove all alarms.

Snooze, Dismiss

Tap an item in the list to select it. Sounding alarms will display additional buttons.

Tap snooze or dismiss, or tap the item again to display the fullscreen notification.

Sort Alarms

Use : -> Sort to sort the alarm list by

Alarm Time
Creation Date

Use Enabled first to move enabled items to the top of the list.

Use Show Offsets to show before/after offsets separately from the alarm time.

Export, Import

Use : -> Export to export the alarm list to file.

Use : -> Import to import alarms from a previous export.

Tip

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

Alarm Settings

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

Alarms

Dismiss Challenge

None (default)
Easy Math. Solve single digit math problems to dismiss alarms.

Reminder within

Show a reminder notification within 12 hours of each alarm.

Snooze for

Snooze alarms for up to 120 minutes.

Snooze limit

Change the snooze limit to limit the number of times snooze can be used.

Timeout after

Alarms will timeout after sounding for too long without user intervention.

Quick Notification

Quick Notifications are displayed for less than a minute and then automatically dismissed (defaults to 30s).

Sounds

Volumes

Tap to opens system volume settings.

Gradually increase volume

Gradually increase the alarm volume over time (defaults to 10s).

Show all ringtones

Show all system sounds during selection (ignore ringtone type).

Miscellaneous

Launcher Icon

Show alarm clock icon in the app tray.

Import Warning

Imported alarms might revert some settings to defaults.

Do not show this warning again.

Boot Completed

Alarms are automatically rescheduled a few minutes after reboot. This setting displays the last time alarms were rescheduled and the total amount of time that was consumed.

Tap this setting to trigger the boot completed routine manually.

Experimental

Power Off Alarm

Wake the device from the power off state.

This feature is hardware dependent. Supported devices will display the name of the package responsible for implementing this feature. Unsupported devices will display null.

For supported devices, tapping this setting will request power off alarm permissions.

Note

This feature is incomplete and has been reported as non-functional. If you have supporting hardware, please considering testing and creating a detailed report.

Alarm Recommendations

Battery Optimization

Suntimes must be not optimized for alarms to work reliably.

Settings -> Apps -> Suntimes -> Battery -> Unrestricted

Note

On most devices the optimized setting may delay alarms up to 15 minutes. Other devices may restrict alarms without special configuration.

The following devices are affected: Asus, Blackview, Huawei, LENOVO, Meizu, OnePlus, OPPO, realme, Samsung, Sony, Unihertz, Vivo, WIKO, and Xiaomi. Check https://dontkillmyapp.com/ for solutions.

Notification Settings

Notifications must be enabled for alarms to display correctly.

Settings -> Apps -> Suntimes -> Notifications -> Show Notifications

Autostart Permission

Suntimes must be granted autostart permissions or alarms may fail to work after a reboot (Xiaomi devices only).

Security app > Permissions > Auto-start

Chapter 4

Widgets

Suntimes includes a variety of home screen widgets.

Time & Date

Sun

Moon

Solstice, Equinox

Manage Widgets

Add

To add a widget, navigate to the home screen, long-press to show the widget menu, then hold and drag the widget to a position on the screen.

The configuration screen will be shown. Tap to add the widget.

Remove

To remove a widget, long press on it, then hold and drag it to the zone at the top of the screen.

Resize

To resize a widget, long press on it to reveal the control frame, then hold and drag the controls.

Tip

Widgets can be configured to swap layouts, or scale text and icons, to use all available space.

Widgets can also be aligned to an edge or corner when there is extra space.

Reconfigure

Suntimes -> Settings -> Widgets to show the widget list.

Tap on a widget in the list to configure it.

Tap to configure widget actions.

Tap to configure widget themes.

Create Backup

Suntimes -> Settings -> Widgets to show the widget list, then : -> Create Backup to save widgets (and other settings) to file.

Restore Backup

Suntimes -> Settings -> Widgets to show the widget list, then : -> Restore Backup to import settings from file.

After selecting a backup file you will be prompted to select an import method:

Restore Backup. Imported settings will be cached for now and restored later when requested by the launcher. The launcher must support this option.
Best Guess. Imported settings will be applied to existing widgets by type.
Direct Import. Imported settings will be applied directly. This only works correctly if the widget ids are unchanged.

Configure Widgets

Layout

Suntimes groups widgets by type of data (sun, moon, etc). Each widget type offers a selection of different layouts. Change the layout settings to choose the widget that will be displayed at a given size.

Swap layouts to fill available space

Suntimes can swap between widget layouts when resized to take advantage of available space.

Enabled :: The widget will switch between layouts depending on available space.
Disabled :: The widget maintains its initial layout when resized. Use this with “scale text and icons” for extra large widgets.

Appearance

Theme

Suntimes can customize the appearance of widgets with themes.

Scale text and icons

Suntimes can scale widget text and icons to fill all available space.

Disabled :: Text and icons are displayed at normal size.
Enabled :: Text and icons will be scaled to fill available space.

Align base

Suntimes can align widgets to an edge or corner when there is extra space.


Top-Left	Top	Top-Right
Left	Center	Right
Bottom-Left	Bottom	Bottom-Right

General

Show Title

Widgets can be configured to show a title in the top left corner.

Tip

Title text supports limited % substitutions.

Show Labels

Some widgets can be configured to show optional labels.

Time Format

Widgets can be configured to display time in 12 or 24 hour format.

System Format (follows system settings)
12-hour
24-hour
Suntimes (follows app settings)

Data Source

Widgets can be configured to use a specific data source.

Time Zone

System Time Zone

The widget is configured to the current system time zone. [default]

User Defined

The widget is configured to a given user-defined time zone.

Tap to sort the list, then select a time zone from the drop-down.

Time Standard

Widgets can be configured to display:

Local Mean Time (LMT)
Apparent Solar Time (LTST)
Local Sidereal Time (LMST)
Greenwich Sidereal Time (GMST)
Coordinated Universal Time (UTC)

Use App Time Zone

The widget will use the same time zone as the main app; changes to the app setting will be reflected by widgets.

Location

User Defined

The widget is configured to a given set of user-defined coordinates. [default]

Select a place from the drop-down list, or tap to open the places list.

Tap to change the coordinates or label (then tap to save changes, or to cancel). If the label was changed then the coordinates will be saved as a new place.

Current (last known)

The widget will use the “last known” location. The home screen widgets use the passive location provider, so a separate app is required to query the location.

Use App Location

The widget will use the same location as the main app; changes to the app setting will be reflected by widgets.

Action

Suntimes can perform an action whenever a widget is tapped.

Do Nothing
Update Widget
Reconfigure Widget [default]
Perform Action
Update All Widgets

Suntimes can customize the appearance of widgets using widget themes.

Defaults

Manage Themes

To access the theme list Suntimes -> Settings -> Widgets -> Themes

Add, Edit, Copy, Remove

To add, edit, copy, or remove themes, navigate to the theme list.

To add a theme, tap add.

To copy a theme, select it, then tap copy to create a new theme with the same values.

To edit a theme, select it, then tap edit.

To remove a theme, select it, then tap delete.

Note

The default themes cannot be modified; the edit and remove actions will not be shown.

From the theme list, select a theme, then tap to share the theme as a file.

Use : -> Export to export all themes to file.

Use : -> Import to import previously shared or exported themes.

Edit Themes

TODO

Chapter 5

Tiles

Suntimes can display information in the system tray as a quick settings tile.

Available Tiles

Clock Tile shows the current time in a given time zone or time standard.
Next Event Tile shows the time of the next twilight event.

Tile Dialog

From the system tray, tap on a tile to open the tile dialog to display more information.

Tile Action

From the tile dialog, tap the action button (bottom right). The default action is to open the main screen.

Tip

The action can be assigned from the tile configuration screen.

Manage Tiles

Add, Remove Tiles

Pull down from the top of the screen to open the system tray, then tap to edit.

To add a tile, hold and drag the tile to the top of the tray.

To remove a tile, hold and drag the tile to the bottom of the tray (unused area).

Configure Tiles

From the system tray, tap a tile to open the tile dialog, then tap Settings (bottom left). The configuration screen will be shown.

Tip

Tile settings can be included in backups and restored with other widget settings.

Chapter 6

Add-ons

Suntimes Calendars
An add-on that supplies events to the Calendar app.

Solunar Periods
A hunting and fishing add-on app.

Natural Hour
A 24-hour clock & roman timekeeping add-on app.

Suntimes NFC
An NFC Add-on for Suntimes Alarms; dismiss alarms with an NFC tag.

Interval Midpoints
A midpoint calculator add-on for Suntimes Alarms; schedule alarms for event midpoints.

Advanced

Interfaces

Add-ons are separate applications that integrate with or extend Suntimes through the use of public interfaces. Add-ons may start intents, use content-providers, or implement content-provider contracts.

Add-ons must declare the READ_CALCULATOR permission. This permission is granted during installation.

See https://github.com/forrestguice/SuntimesWidget/wiki/Interfaces for a list of interfaces available to add-ons (and other applications).

Chapter 7

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.

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)

Dark Theme

Default (Dark)
High Contrast (Dark)

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.

Add, Edit

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

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

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.

Places

Suntimes is configured using location data and maintains a private collection 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.

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.

Search

Tap to search the list of places.

Add Place

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

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.

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

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.

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.

Add Actions

Advanced

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.

Data

Suntimes performs all calculations locally on the device.

This data is displayed by dialogs in the app, by home screen widgets, and can used to schedule alarms and notifications. Data is also available to plugins and add-ons apps through a provider.

Data Substitutions

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

Available Substitutions

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

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.

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 Widgets Sun 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)

Advanced

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

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

Advanced

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.

Advanced

Adding Data Sources

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

Advanced

Data Provider

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

Documentation

This user manual (and other documentation) is maintained at https://github.com/forrestguice/Suntimes/issues.

You can help improve it by reporting typos, dead links, and other errors.

Mirrors

This user manual is published to:

Versions

v0.1.0 (latest), 2024-05-01, written for Suntimes v0.15.14.

Help

User Manual

User Support

Subsections of Help

Configuration

Subsections of Configuration

Welcome

Appearance

User Interface

Location

Time Zone

Alarms

Select a Place

User-Defined Location

Current (last known)

Select a Time Zone

System Time Zone

User-Defined Time Zone

Time Standard

App Dialogs

Subsections of App Dialogs

Main

Location

Current Time

Next Event

Sunrise, Sunset, Twilight

Moon

Solstice, Equinox

Data Source

Sun

Current Position

Light map

Altitude Graph

Seek Altitude

Play (animation)

View Date

Object Shadow

Moon

Phase, Illumination, and Position

Playback

Moonrise, Moonset

Show Lunar Noon

Synodic Month

Columns (phases)

Anomalistic Month

More Options

Solstice, Equinox

Solstices, Equinoxes (tracking)

Cross-Quarter Days

Tropical Year

More Options

World Map

Maps

Map Options

Play (animation)

Share (Record)

View Date

Set Background

Subsections of World Map

Download Backgrounds

Creating Backgrounds

Alarms

Subsections of Alarms

Set Alarm

Alarm Types

Schedule by Time

Schedule by Event

Show Alarm Time

Edit Alarm

Type

Label

Note

Event (or time)

Repeat

Offset (before/after)

Location

Reminder

Sound

Vibration

On Alert Action