Update README.md

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 <SolarCalculator.h>
 ```
 
-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