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).

LGF_AstroClock - Earth with 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

IdentifierData typeDefault valueDescription
enableBoolFALSETRUE: Activates the functionality of the FB
positionGpsLGF_typeGPS_DD---GPS position to calculate the time of sunrise and sunset
offsetSunriseTimeT#0sOffset to sunrise (added to sunrise time, considered at `isDaytime`, negative time allowed)
offsetSunsetTimeT#0sOffset to sunset (added to sunset time, considered at `isDaytime`, negative time allowed)

Output parameter

IdentifierData typeDescription
validBoolTRUE: Valid set of output values available at the FB
busyBoolTRUE: FB is active and new output values can be expected
errorBoolFALSE: No error / TRUE: An error occurred during the execution of the FB
statusWord16#0000-16#7FFF: Status of the FB / 16#8000-16#FFFF: Error identification (see following Table)
subFunctionStatusWordStatus or return value of called FB's, FC's and system blocks
actualLocalTimeDTLCurrent time (local time)
sunriseTimeDTLSunrise time (localtime)
sunsetTimeDTLSunset time (localtime)
isDaytimeBoolTRUE: If the local time of the controller is between “sunrise” and “sunset”.

Status & Error codes

Code / ValueIdentifier / Description
16#0000STATUS_EXECUTION_FINISHED_NO_ERROR
Execution finished without errors
16#7000STATUS_NO_CALL
No job being currently processed - not `enable`
16#7001STATUS_IN_OPERATION
Block is in Operation - Enabled
16#8204ERR_LATITUDE_VALUE
Error: Wrong Latitude DD value
16#8205ERR_LONGITUDE_VALUE
Error: Wrong Longitude DD value
16#8601ERR_RD_SYS_T
Error instruction RD_SYS_T, check `subFunctionStatus` code
16#8602ERR_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.

IdentifierData typeDefault valueDescription
latitudeReal0.0Degrees latitude with decimal places
(Unit: degree decimal), North = positive; South = negative)
valid value range [-90.00000..90.00000]
longitudeReal0.0Degrees 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:


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

LGF_AstroClock - Observation of the block online

Change log

Version & DateChange description
01.00.00Siemens Industry Online Support
19.08.2015First released version
01.00.01Siemens Industry Online Support
01.10.2015T_ADD instruction is replaced with "+"
01.00.02Siemens Industry Online Support
16.11.2015"offsetSunrise", "offsetSunset" is calculated in
"daytime"
Bug fix at "Adjust back TO UTC"
01.01.00Siemens Industry Online Support
07.06.2015Add output actSystemTime and actLocalTime
01.01.01Siemens Industry Online Support
15.06.2015Add comments
01.01.02Siemens Industry Online Support
04.01.2017Bug fix at calculation sunrise and sunset
01.01.03Siemens Industry Online Support
20.01.2017Upgrade: TIA V14 Update 1
01.01.04Siemens Industry Online Support
22.02.2017Code optimization
01.01.05Siemens Industry Online Support
09.07.2018Initialize #tempIntSunrise, #tempIntSunset,#tempDate1Jan
01.01.06Siemens Industry Online Support
17.08.2018Upgrade: TIA V15 Update 2
01.01.07Siemens Industry Online Support
23.11.2018Upgrade: TIA V15.1
01.00.08Simatic Systems Support
30.08.2019Rename 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.00Simatic Systems Support
23.04.2020Set version to V3.0.0, harmonize the version of the whole library
03.00.01Simatic Systems Support
12.11.2020Bug fix - not enabled - block still running
Insert documentation