# LGF_AstroClock (FB / V3.0.1)

Autor: Siemens Digital Industry

## Kurzbeschreibung

Diese Funktion berechnet die Zeiten des Sonnenauf- und Sonnenuntergangs basierent auf der Lokalzeit für einen bestimmten Ort auf der Erde. Die genaue Position wird in Form von geographischen GPS Koordinaten (Längen- und Breitengrad / Longitude und Latitude) übergeben.

### Baustein Schnittstelle

| LGF_AstroClock (FB) |
--- | --- | ---
Bool |  |  | enable |  | valid |  |  | Bool
LGF_typeGPS_DD |  |  | positionGps |  | busy |  |  | Bool
Time |  |  | offsetSunrise |  | error |  |  | Bool
Time |  |  | offsetSunset |  | status |  |  | Word
|  |  |  |  | subFunctionStatus |  |  | Word
|  |  |  |  | actualLocalTime |  |  | DTL
|  |  |  |  | sunriseTime |  |  | DTL
|  |  |  |  | sunsetTime |  |  | DTL
|  |  |  |  | isDaytime |  |  | Bool

### Input Parameter

Bezeichner | Datentyp | Default Wert | Beschreibung
--- | --- | --- | ---
enable | Bool | FALSE | TRUE: Aktiviert die Funktionalität des FB
positionGps | LGF_typeGPS_DD | --- | GPS-Position zur Berechnung der Sonnenaufgangs- und Sonnenuntergangszeit
offsetSunrise | Time | T#0s | Offset zum Sonnenaufgang (wird zur Sonnenaufgangszeit addiert, wird bei `isDaytime` berücksichtigt, negative Zeit ist erlaubt)
offsetSunset | Time | T#0s | Offset zum Sonnenuntergang (addiert zur Sonnenuntergangszeit, berücksichtigt bei `isDaytime`, negative Zeit erlaubt)

### Output Parameter

Bezeichner | Datentyp | Beschreibung
--- | --- | ---
valid | Bool | TRUE: Ausgabewerte am FB gültig
busy | Bool | TRUE: FB ist aktive und neue Ausgabewerte können erwartet werden.
error | Bool | FALSE: Kein Fehler / TRUE: Während der Ausführung des FB ist ein Fehler aufgetreten
status | Word | 16#0000-16#7FFF: Status des FB / 16#8000-16#FFFF: Fehleridentifikation (siehe folgende Tabelle)
subFunctionStatus | Word | Status oder Rückgabewert von aufgerufenen FB's / FC's und Systemfunktionen
actualLocalTime | DTL | Aktuelle Zeit (Lokalzeit)
sunriseTime | DTL | Sonnenaufgangszeit (Lokalzeit)
sunsetTime | DTL | Sonnenuntergangzeit (Lokalzeit)
isDaytime | Bool | TRUE: Wenn die Lokalzeit der Steuerung zwischen "sunrise" und "sunset" liegt.

### Status & Error Meldungen

Code / Wert | Bezeichner / Beschreibung
--- | ---
16#0000 | STATUS_EXECUTION_FINISHED_NO_ERROR Abarbeitung ohne Fehler beendet
16#7000 | STATUS_NO_CALL Block ist nicht in Bearbeitung - not `enable`
16#7001 | STATUS_IN_OPERATION Block ist in Abarbeitung - Enabled
16#8204 | ERR_LATITUDE_VALUE Fehler: Falscher Latitude DD Wert (Breitengrad)
16#8205 | ERR_LONGITUDE_VALUE Fehler: Falscher Longitude DD Wert (Längengrad)
16#8601 | ERR_RD_SYS_T Fehler in Funktion RD_SYS_T: Lese System Zeit - weitere infos in `subFunctionStatus`
16#8602 | ERR_RD_LOC_T Fehler in Funktion RD_LOC_T: Lese Lokal Zeit - weitere infos in `subFunctionStatus`

## Benutzer definierte Datentypen

### LGF_typeGPS_DD (UDT)

Datentyp für GPS-Koordinaten im Format Dezimalgrad.
Für Breitengrad (Latitude) und Längengrad (Longitude).
Datentyp für einen gesamten GPS Datensatz.

Bezeichner | Datentyp | Default Wert | Beschreibung
--- | --- | --- | ---
latitude | Real | 0.0 | Breitengrad (Latitude) in Grad mit Nachkommastellen (Einheit: Grad dezimal), Norden = positiv; Süden = negativ) gültiger Wertebereich [-90.00000..90.00000]
longitude | Real | 0.0 | Längengrad (Longitude) in Grad mit Nachkommastellen (Einheit: Grad dezimal), Osten = positiv; Westen = negativ) gültiger Wertebereich [-180.0000..180.0000]

## Funktionsbeschreibung

Hinweis
  In `subFunctionStatus` wird der Status von aufgerufenen Anweisungen ausge-geben. Der Ausgangswert in `status` gibt in diesem Fall an, welche Anweisung den Fehler verursacht hat. Holen Sie sich in diesem Fall die Informationen aus der TIA Portal Online Hilfe zu den jeweiligen Anweisungen.

Wenn Prozesse in Abhängigkeit vom Wechsel zwischen Tag und Nacht automa-tisiert ablaufen sollen, wird die Funktion einer astronomischen Uhr benötigt. Beispiele dafür wären das Ein- und Ausschalten einer Außenbeleuchtung oder das Öffnen und Schließen von Rollläden.

Sollen diese Prozesse zeitversetzt, also eine definierte Zeit vor oder nach Sonnen-auf- oder Sonnenuntergang, ausgeführt werden, wird jeweils noch ein Offset benötigt.

Hinweis
  Für eine exakte Ausführung der Funktion, muss gewährleistet sein, dass die Systemzeit und Lokalzeit der SIMATIC Steuerung richtig eingestellt ist.

Basierend auf der Systemzeit/Lokalzeit der SIMATIC Steuerung und den ein-gestellten Koordinaten berechnet der Baustein die Zeiten für Sonnenauf- und Sonnenuntergang. Die Offset-Zeiten werden zum Sonnenauf- und Sonnenuntergang hinzugerechnet und an den Ausgängen `sunrise` und `sunset` ausgegeben. Liegt die System Lokalzeit der SIMATIC Steuerung zwischen diesen Werten, wird der Ausgang `isDaytime` auf den Wert `TRUE` gesetzt.

Hinweis

  Da sich die Zeiten für Sonnenauf- und Sonnenuntergang täglich verändern, kann es sein, dass der Ausgang `isDaytime` über einen längeren Zeitraum dauerhaft auf `TRUE` oder `FALSE` "stehen bleibt":

  - bei entsprechend großen Offsetwerten
  - bei einem Ort jenseits des Polarkreises

Die Eingabe der GPS- Koordinatenwerte wird auf gültige Werte geprüft. Bei ungül-tigen Werten wird ein entsprechender Fehlercode an `status` ausgegeben.

Liegt an einem Formalparameter ein ungültiger Koordinatenwert vor, werden die Ausgänge `sunrise` und `sunset` auf den Wert `DTL#1970-01-01-00:00:00` gesetzt.

####### Beispiel

Das folgende Beispiel verdeutlicht die Funktionsweise des Bausteins.

Geografische Koordinaten für Nürnberg-Moorenbrunn, Datum und Systemzeit:

Beschreibung | Wert
--- | ---
Längengrad: | + 11.07675°
Breitengrad: | + 49.45203°
Datum: | 28.02.2020
Lokalzeit: | 11:22:37
Sonnenaufgang | 07:01:23
Sonnenuntergang | 17:56:14

Abbildung: FB LGF_AstroClock, Beobachtung des Bausteins online mit den Parametern sowie den Aktualparametern über die Beobachtungstabelle

## Änderungshistorie

Version & Datum | Änderungsbeschreibung
--- | ---
| 01.00.00 | Siemens Industry Online Support
| 19.08.2015 | First released version
| 01.00.01 | Siemens Industry Online Support
| 01.10.2015 | T_ADD instruction is replaced with "+"
| 01.00.02 | Siemens Industry Online Support
| 16.11.2015 | "offsetSunrise", "offsetSunset" is calculated in "daytime" Bug fix at "Adjust back TO UTC"
| 01.01.00 | Siemens Industry Online Support
| 07.06.2015 | Add output actSystemTime and actLocalTime
| 01.01.01 | Siemens Industry Online Support
| 15.06.2015 | Add comments
| 01.01.02 | Siemens Industry Online Support
| 04.01.2017 | Bug fix at calculation sunrise and sunset
| 01.01.03 | Siemens Industry Online Support
| 20.01.2017 | Upgrade: TIA V14 Update 1
| 01.01.04 | Siemens Industry Online Support
| 22.02.2017 | Code optimization
| 01.01.05 | Siemens Industry Online Support
| 09.07.2018 | Initialize #tempIntSunrise, #tempIntSunset,#tempDate1Jan
| 01.01.06 | Siemens Industry Online Support
| 17.08.2018 | Upgrade: TIA V15 Update 2
| 01.01.07 | Siemens Industry Online Support
| 23.11.2018 | Upgrade: TIA V15.1
| 01.00.08 | Simatic Systems Support
| 30.08.2019 | Rename from Astro to AstroClock Update Type name to positionGps - "LGF_typeGPS_DD" - GPS position as decimal degree Refactoring of interface - one input type for GPS data - refactored for better usability - refactoring of whole block to "ENABLE" behavior
| 03.00.00 | Simatic Systems Support
| 23.04.2020 | Set version to V3.0.0, harmonize the version of the whole library
| 03.00.01 | Simatic Systems Support
| 12.11.2020 | Bug fix - not enabled - block still running Insert documentation