FB_BARShadingCorrection

Function block for the shading evaluation of a window group on a facade.

This function block is valid only for the northern hemisphere. The valid function block for the southern hemisphere is FB_BARShadingCorrectionSouth.

The function block FB_BARShadingCorrection calculates whether a window group lies in the shadow of surrounding objects. The result, which is output at the output bGroupNotShaded, can be used to judge whether sun shading makes sense for this window group.
The function block thereby accesses two lists, which are to be defined:

The data of the elements (window) of the facade in which the group to be regarded is located. This list of facade elements is accessed via the IN-OUT variable arrFacadeElement, which itself is globally defined.
The parameters that describe the shading elements that are relevant to the facade on which the window group is located. This list of shading objects is likewise globally defined. The IN-OUT variable arrShadingObject accesses it directly.

On the basis of the facade orientation (lrFacadeOrientation), the direction of the sun (lrAzimuth) and the height of the sun (lrElevation), a calculation can be performed for each corner of a window to check whether this lies in a shaded area. A window group is considered to be completely shaded if all corners are shaded.

In the northern hemisphere, the following applies for the facade orientation (looking out of the window):

Line of sight	Facade orientation
North	β=0°
East	β=90°
South	β=180°
West	β=270°

The function block performs its calculations only if the sun is actually shining on the facade. If one regards the drawing presented in the introduction, then this is the case if the following is true:

Facade orientation < azimuth angle < facade orientation + 180°

In addition, a calculation is also not required, if the sun has not yet risen, i.e. the solar elevation is below 0°. In both cases the output bFacadeSunlit is set to FALSE.

VAR_INPUT

eDataSecurityType   : E_HVACDataSecurityType;
stTimeAct           : TIMESTRUCT;
lrAzimuth           : LREAL;
lrElevation         : LREAL;

eDataSecurityType: If eDataSecurityType:= eHVACDataSecurityType_Persistent, the persistent VAR_IN_OUT variables of the function block are stored in the flash of the computer if a value changes. For this to work, the function block FB_HVACPersistentDataHandling must be instanced once in the main program, which is called cyclically. Otherwise the instanced FB is not released internally.

A change of value can be initiated by the building management system, a local operating device or via a write access from TwinCAT. When the computer is restarted the saved data are automatically read back from the flash into the RAM.

Application example: example_persistent.zip

If eDataSecurityType:= eHVACDataSecurityType_Idle the persistently declared variables are not saved in a fail-safe manner.

Notice
A cyclically changing variable must never be linked with the IN_OUT variable of a function block, if eDataSecurityType:= eHVACDataSecurityType_Persistent. It would lead to early wear of the flash memory.

stTimeAct: Entry of the current time in GMT (Greenwich Mean Time).

lrAzimuth: Sun direction in degrees at the time of observation.

lrElevation: Sun elevation in degrees at the time of observation.

VAR_OUTPUT

bGroupNotShaded : BOOL;
bFacadeSunlit   : BOOL;
bError          : BOOL;
udiErrorId      : UDINT;

bGroupNotShaded: is TRUE as long as the window group is not calculated as shaded.

bFacadeSunlit: this output is set to TRUE if the sun is shining on the facade. See description above.

bError: this output is set to TRUE if an error is detected during the execution of the function block.

udiErrorId: contains the error code if the values entered should be erroneous. See Error codes.

VAR_IN_OUT

arrFacadeElement     : ARRAY[1..iColumnsPerFacade, 1..iRowsPerFacade] OF ST_BARFacadeElement;
arrShadingObject     : ARRAY[1..iShadingObjects] OF ST_BARShadingObject;
lrFacadeOrientation  : LREAL;
usiGroupID           : USINT;

In order for the registered parameters to be retained beyond a controller failure, it is necessary to declare them as In-Out variables. A reference variable is then assigned to them in the program. Each change of the value of these reference variables is persistently stored in the function block and written back to the reference variable following a controller failure and restart. If the parameters were only to be defined as input variables, they would not be able to write a reference variable.
Application example: example_persistent.zip.

arrFacadeElement: List of facade elements.

arrShadingObject: List of shading objects.

lrFacadeOrientation: Facade orientation, see illustration above.

usiGroupId: Window group regarded. The group 0 is reserved here for unused window elements, see FB_BARFacadeElementEntry. A 0-entry would lead to an error output (bError=TRUE). The function block is then not executed any further and bGroupNotShaded is set to FALSE.

Requirements

Development environment	required library	required function
TwinCAT 3.1 build 4022.16 or higher	Tc2_HVAC V3.3.1.0	TF8000 \| TC3 HVAC V1.0.0.0