# LGF_AstroClock (FB / V3.0.1)

Author: Siemens Digital Industry

## Short description

This function calculates the times of sunrise and sunset based on the local time for a specific place on Earth. The exact position is transferred in the form of geographical GPS coordinates (longitude and latitude).

### Block Interface

| 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

Identifier | Data type | Default value | Description
--- | --- | --- | ---
enable | Bool | FALSE | TRUE: Activates the functionality of the FB
positionGps | LGF_typeGPS_DD | --- | GPS position to calculate the time of sunrise and sunset
offsetSunrise | Time | T#0s | Offset to sunrise (added to sunrise time, considered at `isDaytime`, negative time allowed)
offsetSunset | Time | T#0s | Offset to sunset (added to sunset time, considered at `isDaytime`, negative time allowed)

### Output parameter

Identifier | Data type | Description
--- | --- | ---
valid | Bool | TRUE: Valid set of output values available at the FB
busy | Bool | TRUE: FB is active and new output values can be expected
error | Bool | FALSE: No error / TRUE: An error occurred during the execution of the FB
status | Word | 16#0000-16#7FFF: Status of the FB / 16#8000-16#FFFF: Error identification (see following Table)
subFunctionStatus | Word | Status or return value of called FB's, FC's and system blocks
actualLocalTime | DTL | Current time (local time)
sunriseTime | DTL | Sunrise time (localtime)
sunsetTime | DTL | Sunset time (localtime)
isDaytime | Bool | TRUE: If the local time of the controller is between “sunrise” and “sunset”.

### Status & Error codes

Code / Value | Identifier / Description
--- | ---
16#0000 | STATUS_EXECUTION_FINISHED_NO_ERROR Execution finished without errors
16#7000 | STATUS_NO_CALL No job being currently processed - not `enable`
16#7001 | STATUS_IN_OPERATION Block is in Operation - Enabled
16#8204 | ERR_LATITUDE_VALUE Error: Wrong Latitude DD value
16#8205 | ERR_LONGITUDE_VALUE Error: Wrong Longitude DD value
16#8601 | ERR_RD_SYS_T Error instruction RD_SYS_T, check `subFunctionStatus` code
16#8602 | ERR_RD_LOC_T Error instruction RD_LOC_T, check `subFunctionStatus` code

## User defined datatype(s)

### LGF_typeGPS_DD (UDT)

Datatype for GPS Coordinates in decimal degrees.
For latitude and longitude.
Datatype for a whole GPS Data set.

Identifier | Data type | Default value | Description
--- | --- | --- | ---
latitude | Real | 0.0 | Degrees latitude with decimal places (Unit: degree decimal), North = positive; South = negative) valid value range [-90.00000..90.00000]
longitude | Real | 0.0 | Degrees longitude in degrees with decimal places (Unit: degree decimal), East = positive; West = negative) valid range [-180.0000..180.0000]

## Functional description

NOTE
  The status of called commands is output in `subFunctionStatus`. In this case, the output value in `status` indicates which command caused the error. In this case, refer to the TIA Portal Online Help section for information on the respective commands.

If processes must run automatically depending on the change between day and night, the function of an astronomical clock is required. Examples of this would be switching outdoor lighting on and off or opening and closing roller shutters.

If these processes are to be executed with a time delay i.e. a defined time before or after sunrise or sunset an offset is required in each case.

Note
  For precise execution of the function, it must be ensured that system time and local time of the SIMATIC controller are set correctly.

Based on the system time/local time of the SIMATIC controller and the set coordinates, the block calculates the times for sunrise and sunset. The offset times are added to the sunrise and sunset and output on the `sunrise` and `sunset` outputs. If the systems local time of the SIMATIC controller is between these values, the output `isDaytime` is set to the value `TRUE`.

Note

  Since the times for sunrise and sunset change daily, it is possible that the `isDaytime` output remains permanently on `TRUE` or `FALSE` over a longer period of time:

  - with correspondingly large offset values
  - for a place on the other side of the Arctic Circle

The input of the GPS coordinate values is checked for valid values. If there are invalid values, an appropriate error code is output to `status`.

If there is an invalid coordinate value for a formal parameter, the outputs `sunrise` and `sunset` are set to the value `DTL#1970-01-01-00:00:00`.

####### Example

The following example illustrates the block’s functionality.

Geographical coordinates for Nuremberg-Moorenbrunn, date, and system time:

Description | Value
--- | ---
Longitude: | + 11.07675°
Latitude: | + 49.45203°
Date: | 02/28/2020
Local time: | 11:22:37
Sunrise: | 07:01:23
Sunset: | 17:56:14

Figure: FB LGF_AstroClock, Observation of the block online with the parameters and the actual parameters via the Observation Table

## Change log

Version & Date | Change description
--- | ---
| 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