diff --git a/README.md b/README.md index 024191b..c385ede 100644 --- a/README.md +++ b/README.md @@ -1,25 +1,28 @@ # SolarCalculator Library for Arduino -SolarCalculator is based on the [NOAA Solar Calculator](https://gml.noaa.gov/grad/solcalc/). +SolarCalculator is inspired by the [NOAA Solar Calculator](https://gml.noaa.gov/grad/solcalc/). -This library provides functions to calculate the times of sunrise, sunset, solar noon and twilight (civil, nautical, -astronomical dawn and dusk), solar coordinates, interpolation of coordinates, atmospheric refraction correction, Sun's -radius vector, Julian day and century, equation of time, delta T, etc. +This library provides functions to calculate the times of sunrise, sunset, solar noon and twilight (dawn and dusk), +solar coordinates, interpolation of coordinates, atmospheric refraction correction, equation of time, delta T, etc. -Most formulae are taken from the textbook Astronomical Algorithms by Jean Meeus or the NOAA Solar Calculator -[source code](https://gml.noaa.gov/grad/solcalc/main.js). Other sources are cited in the comments. +Most formulae are taken from Astronomical Algorithms by Jean Meeus and adapted for 8-bit AVR platform. + +### Version 2.0.0 + +- Unix time input support +- Optimizations ## Installation Download and copy SolarCalculator to your local Arduino/libraries directory. -### Time and Timezone +### Time Date and time inputs are assumed to be in **Universal Coordinated Time** (UTC). -Although not required, it is recommended to use SolarCalculator along with the -[Time](https://github.com/PaulStoffregen/Time) and [Timezone](https://github.com/JChristensen/Timezone) libraries. +Although not required, it is recommended to use SolarCalculator along with the +[Time](https://github.com/PaulStoffregen/Time) library (or similar). ## Usage @@ -29,58 +32,51 @@ Include SolarCalculator.h in your sketch: #include ``` -Calculate the times of sunrise, transit (solar noon) and sunset: +Calculate the times of sunrise, transit (solar noon) and sunset, in hours: ``` -int year = 2022; -int month = 2; -int day = 11; -double latitude = 45.55; -double longitude = -73.633; -int time_zone = -5; - -double sunrise, transit, sunset; +double latitude = 45.55; // Observer's latitude +double longitude = -73.633; // Observer's longitude +int time_zone = -5; // UTC offset +int year = 2022; // Calendar year (1901-2099) +int month = 1; // Calendar month (1-12) +int day = 1; // Calendar day (1-31) +double transit, sunrise, sunset; calcSunriseSunset(year, month, day, latitude, longitude, transit, sunrise, sunset); ``` -where the results are passed by reference, in hours. -Convert to local standard time: -``` -double sunrise_local = sunrise + time_zone; +Or, using the Time library: ``` -To hours and minutes: +time_t utc = now(); +calcSunriseSunset(utc, latitude, longitude, transit, sunrise, sunset); ``` -int minutes = int(round(sunrise_local * 60)); -int sunrise_local_hours = (minutes / 60) % 24; -int sunrise_local_minutes = minutes % 60; -``` -* Due to the varying effect of refraction, sunrise and sunset times should be rounded to the nearest minute. -Similarly, calculate the times of civil, nautical and astronomical dawn and dusk, in hours: +Convert to local standard time: ``` -calcCivilDawnDusk(year, month, day, latitude, longitude, transit, c_dawn, c_dusk); -calcNauticalDawnDusk(year, month, day, latitude, longitude, transit, n_dawn, n_dusk); -calcAstronomicalDawnDusk(year, month, day, latitude, longitude, transit, a_dawn, a_dusk); +double sunrise_local = sunrise + time_zone; ``` +* Refer to the example sketches for more on rounding and printing the results. -Calculate the Sun's equatorial coordinates (right ascension and declination), in degrees: +Similarly, calculate the times of civil, nautical, astronomical dawn and dusk, in hours: ``` -calcEquatorialCoordinates(year, month, day, hour, minute, second, rt_ascension, declination); +calcCivilDawnDusk(utc, latitude, longitude, transit, c_dawn, c_dusk); +calcNauticalDawnDusk(utc, latitude, longitude, transit, n_dawn, n_dusk); +calcAstronomicalDawnDusk(utc, latitude, longitude, transit, a_dawn, a_dusk); ``` -Calculate the Sun's horizontal coordinates (azimuth and elevation), in degrees: +Calculate the Sun's equatorial coordinates (right ascension, declination and radius vector), in degrees and AUs: ``` -calcHorizontalCoordinates(year, month, day, hour, minute, second, latitude, longitude, azimuth, elevation); +calcEquatorialCoordinates(utc, rt_ascension, declination, radius_vector); ``` -Calculate the Sun's radius vector (distance from the Earth), in AUs: +Calculate the Sun's horizontal coordinates (azimuth and elevation), in degrees: ``` -calcSunRadiusVector(year, month, day, hour, minute, second, radius_vector); +calcHorizontalCoordinates(utc, latitude, longitude, azimuth, elevation); ``` Calculate the equation of time, in minutes of times: ``` -calcEquationOfTime(year, month, day, hour, minute, second, eq); +calcEquationOfTime(utc, eq); ``` where the results are passed by reference. @@ -89,24 +85,19 @@ where the results are passed by reference. The following example sketches are included in this library: -* `SunriseSunset`: Calculate the times of sunrise, sunset and solar noon for a given date and location. +* `SunriseSunset`: Calculate the times of sunrise, solar noon and sunset for a given date and location. + +* `SunriseSunsetAltitude`: Calculate the rise and set times at a height above the level of the horizon. -* `SolarCalculatorTimeLib`: Calculate the times of sunrise, sunset, solar noon, and the solar coordinates for a given -location. The Arduino Time library is used for timekeeping purposes. +* `SolarCalculatorTimeLib`: Calculate the rise and set times, the equation of time and current solar coordinates. -* `SolarTrackingTimeLib`: Monitor the Sun's position in the sky for any location on Earth. +* `SolarTrackingTimeLib`: Monitor the Sun's position in the sky, corrected for atmospheric refraction. * `EquationOfTime`: Plot the equation of time for a given year. ## Notes -### Sunrise and sunset - -The algorithm for finding the times of sunrise and sunset implemented in this library is valid for all latitudes between -the Arctic and Antarctic circles (about ± 66.5°). Outside this range, a more general algorithm should be used but is not -provided at this time. - ### Accuracy Various things to consider: @@ -117,8 +108,13 @@ Therefore, sunrise and sunset times can only be accurate to the nearest minute ( * Assuming a purely elliptical motion of the Earth, solar coordinates have a "low accuracy" of 0.01° (Meeus, 1998). * Arduino's single precision floating numbers have the equivalent of `24 * log10(2)` ≈ 7.22 significant digits. -Although this is generally not sufficient for mathematical astronomy (Meeus, 1998), it is sufficient for our solar -calculations. +Although this is generally not sufficient for mathematical astronomy (Meeus, 1998), it is enough for our calculations. + +### Sunrise and sunset + +The algorithm for finding the times of sunrise and sunset implemented in this library is valid for all latitudes between +the Arctic and Antarctic circles (about ± 66.5°). Outside this range, a more general algorithm should be used but is not +provided at this time. ## References