cilynx / sunwait

Sunwait calculates sunrise or sunset times with civil, nautical, astronomical and custom twilights, for use with Windows Task Scheduler or 'cron' on Linux.

sunwait

Sunwait calculates sunrise or sunset times with civil, nautical, astronomical and custom twilights.

It is intended for use in home automation with Windows Task Scheduler or cron. Use it to turn lights on before it gets dark! The program can wait from invocation until the event specified on the command line occurs or it can return immediately indicating if it is day or night. It's best to schedule Sunwait to run a little before the earliest opportunity for the event to occur each year - ie dusk range is 3:30pm to 10:30pm here, so it reasonable to schedule a dusk task at 3pm and allow Sunwait to pause the task for between 30mins and 7 and a half hours. If you scheduled the task for 6pm, then your lights will come on no earlier than 6pm.

The sun's position is calculated using time, and position - latitude and longitude should be specified on the command line.

Features:

• Calculates sunrise and sunset for given coordinates
• Can wait for sunrise/sunset, or return DAY or NIGHT codes
• Works with Windows Task Scheduler (or cron)
• Supports custom twilight angles
• Used to automate domestic lighting with Arduino transmitter and radio controlled sockets

History:

This project is a "reclaimed fork". I (Dan Risacher) wrote the original version around 2000, and maintained it until 2004. In 2013, Ian Craig made a version that compiled cleanly on Windows and added some useful features. In 2019, I'm moving it to GitHub as a better collaborative development platform. If you have feature requests or issues, please report them here.

help

Calculate sunrise and sunset times for the current or targetted day.
The times can be adjusted either for twilight or fixed durations.

The program can either:

• wait for sunrise or sunset (function: wait),
• or return the time (GMT or local) the event occurs (function: list),
• or report the day length and twilight timings (function: report),
• or simply report if it is DAY or NIGHT (function: poll).

You should specify the latitude and longitude of your target location.

Usage: sunwait [major options] [minor options] [twilight type] [rise|set] [offset] [latitude] [longitude]

Major options, either:

• poll Returns immediately indicating DAY or NIGHT. See 'program exit codes'. Default.
• wait Sleep until specified event occurs. Else exit immediate.
• list [X] Report twilight times for next 'X' days (inclusive). Default: 1.
• report Generate a report about the days sunrise and sunset timings.

Minor options, any of:

• [no]debug Print extra info and returns in one minute. Default: nodebug.
• [no]version Print the version number. Default: noversion.
• [no]help Print this help. Default: nohelp.
• [no]gmt Print times in GMT or local-time. Default: nogmt.

Twilight types, either:

• daylight Top of sun just below the horizon. Default.
• civil Civil Twilight. -6 degrees below horizon.
• nautical Nautical twilight. -12 degrees below horizon.
• astronomical Astronomical twilight. -18 degrees below horizon.
• angle [X.XX] User-specified twilight-angle (degrees). Default: 0.

Sunrise/sunset. Only useful with major-options: 'wait' and 'list'. Any of: (default: both)

• rise Wait for the sun to rise past specified twilight & offset.
• set Wait for the sun to set past specified twilight & offset.

Offset:

• offset [MM|HH:MM] Time interval (+ve towards noon) to adjust twilight calculation.

Target date. Only useful with major-options: 'report' or 'list'. Default: today

• d [DD] Set the target Day-of-Month to calculate for. 1 to 31.
• m [MM] Set the target Month to calculate for. 1 to 12.
• y [YYYY] Set the target Year to calculate for. 2000 to 2099.

latitude/longitude coordinates: floating-point degrees, with [NESW] appended. Default: Bingham, England.

Exit (return) codes:

• 0 OK: exit from 'wait' or 'list' only.
• 1 Error.
• 2 Exit from 'poll': it is DAY or twilight.
• 3 Exit from 'poll': it is NIGHT (after twilight).

Example 1: sunwait wait rise offset -1:15:10 51.477932N 0.000000E
Wait until 1 hour 15 minutes 10 secs before the sun rises in Greenwich, London.

Example 2: sunwait list 7 civil 55.752163N 37.617524E
List civil sunrise and sunset times for today and next 6 days. Moscow.

Example 3: sunwait poll exit angle 10 54.897786N -1.517536E
Indicate by program exit-code if is Day or Night using a custom twilight angle of 10 degrees above horizon. Washington, UK.

Example 4: sunwait list 7 gmt sunrise angle 3
List next 7 days sunrise times, custom +3 degree twilight angle, default location.
Uses GMT; as any change in daylight saving over the specified period is not considered.

Note that program uses C library functions to determine time and localtime.
Error for timings are estimated at: +/- 4 minutes.