====== Sonnenstands-Funktionen  ======

LoxBerry XL implementiert Funktionen, um die Sonnenzeiten sowie den Sonnenstand (Winkel) auszugeben. Dafür gibt es die Funktion **''%%$sun%%''**.

Die Sonnenstandsfunktion muss zu Beginn mit den GPS-Koordinaten und der gewünschten Zeit initialisiert werden. Danach können verschiedene Zeiten und die Sonnenstandswinkel abgerufen werden. Deine GPS-Koordinaten werden nicht an LoxBerry gesendet. 

Die Berechnungen basieren auf die Bibliothek https://github.com/gregseth/suncalc-php, wobei LoxBerry XL die Daten für uns aufbereitet.

<code php>
<?php
require_once "loxberry_XL.php";

// Die Zeit kann, wie bei allen Funktionen, in verschiedenen Formaten übergeben werden. Mit time() wird die aktuelle Zeit übergeben.
$sun->gps( time(), 38.268660, -85.521844 );

// Es kann voreingestellt werden, ob die Rückgabe einer Zeit als Minuten des Tages ('minofday'=Standard), als Zeit HH:mm ('time') oder epoch ('epoch') zurückgegeben werden soll.
$sun->format('time');

// Nun fragen wir einige Werte der Sonne ab:
echo "Sonnenaufgang um " . $sun->sunTimes('sunrise') . "\n";
echo "Sonnenhöchststand um " . $sun->sunTimes('solarNoon') . "\n";
echo "Sonnenuntergang um " . $sun->sunTimes('sunset') . "\n";
echo "Abenddämmerung um " . $sun->sunTimes('dusk') . "\n";
echo "Morgendämmerung um " . $sun->sunTimes('dawn') . "\n";

// Sonnenwinkel (Angaben in Grad, Nordazimut)
echo "Himmelsrichtung: " . $sun->sunPosition('azimuth');
echo "Sonnenhöhe: " . $sun->sunPosition('altitude');

// Um Berechnungen mehrerer Zeiten oder Tage durchzuführen, kann man die Zeit jederzeit, ohne wieder die GPS-Koordinaten angeben zu müssen:
$sun->gps( '24.03.2020 12:00' );
echo "Himmelsrichtung: " . $sun->sunPosition('azimuth');
$sun->gps( '24.03.2020 13:00' );
echo "Himmelsrichtung: " . $sun->sunPosition('azimuth');
</code>


==== $sun->format( $format ) ====

Damit kann die Ausgabe von Zeiten voreingestellt werden.

Parameter:

  * 'minofday' → Die Minuten seit Mitternacht
  * 'time' → Ausgabe im Format 'HH:mm', z.B. 13:50
  * 'epoch' → Unix Timestamp

==== $sun->sunTimes( $typeoftime ) $sun->sunTimes( $typeoftime, $format ) ====

Dies liefert die Zeiten für den aktuellen Tag. Das Format kann optional direkt mitgegeben werden und hat dann Vorrang gegenüber dem voreingestellten Format.

^Property             ^Description                                                             ^
|''%%sunrise%%''      |sunrise (top edge of the sun appears on the horizon)                    |
|''%%sunriseEnd%%''   |sunrise ends (bottom edge of the sun touches the horizon)               |
|''%%goldenHourEnd%%''|morning golden hour (soft light, best time for photography) ends        |
|''%%solarNoon%%''    |solar noon (sun is in the highest position)                             |
|''%%goldenHour%%''   |evening golden hour starts                                              |
|''%%sunsetStart%%''  |sunset starts (bottom edge of the sun touches the horizon)              |
|''%%sunset%%''       |sunset (sun disappears below the horizon, evening civil twilight starts)|
|''%%dusk%%''         |dusk (evening nautical twilight starts)                                 |
|''%%nauticalDusk%%'' |nautical dusk (evening astronomical twilight starts)                    |
|''%%night%%''        |night starts (dark enough for astronomical observations)                |
|''%%nadir%%''        |nadir (darkest moment of the night, sun is in the lowest position)      |
|''%%nightEnd%%''     |night ends (morning astronomical twilight starts)                       |
|''%%nauticalDawn%%'' |nautical dawn (morning nautical twilight starts)                        |
|''%%dawn%%''         |dawn (morning nautical twilight ends, morning civil twilight starts)    |


==== $sun->sunPosition($sunpostype) ====

Die Sonnenhöhe und der Sonnenwinkel.

Parameter sunpostype:

  * 'azimuth' → Die Himmelsrichtung der Sonne (Nordazimut). 0° ist Norden, 180° ist Süden.
  * 'altitude' → Die Sonnenhöhe. 90° bedeutet, die Sonne steht direkt über uns. 0° bedeutet, die Sonne steht auf einer Horizontale mit uns.

==== $sun->gps( $time, $lat, $lng ) $sun->gps( $time  ) ====

Damit muss initial die Position und Zeit/Datum gesetzt werden. Nachdem einmal die Koordinaten gesetzt wurden, ist die Angabe optional.

Parameter time kann sein:

  * null → die aktuelle Zeit
  * $epoch → Ein epoch Zeitstempel
  * 'tt.mm.yyyy hh:mm' → Die Angabe eines Datums und der Zeit im gezeigten Format

Für die sunTimes ist die Uhrzeit nicht relevant, sondern nur das Datum. Für die sunPosition ist natürlich beides relevant.