Function blocks
Basic structure of the function blocks
All function blocks of the library Tc3_Filter are based on the same basic structure. This simplifies the engineering process when changing from one filter type to another.
Syntax
FUNCTION_BLOCK FB_FTR_<type>
VAR_INPUT
stConfig : ST_FTR_<type>;
END_VAR
VAR_OUTPUT
bError : BOOL;
bConfigured : BOOL;
ipResultMessage : I_TCMessage;
END_VAR
Inputs
To configure the filter, a configuration structure of type ST_FTR_<type> is transferred to the function blocks during instantiation. The configuration structure can be assigned in the declaration or via the Configure() method at runtime.
See also: Data types > Configuration structures
Sample of configuration in the declaration:
(* define configure structure – exemplary for IIRSpec *)
stParams : ST_FTR_IIRSpec := (
eFilterName := E_FTR_Name.eButterworth,
eFilterType = E_FTR_Type.eLowPass,
nFilterOrder := nFilterOrder,
fSamplingRate := fSampleRate,
fCutoff := fCutoff,
nOversamples := cOversamples,
nChannels := cChannels);
(* create filter instance with configure structure *)
fbFilter : FB_FTR_IIRSpec := (stConfig := stParams);
Outputs
All function blocks have an error flag bError and a flag bConfigured of type BOOL as output parameters. These indicate whether an error has occurred and whether the corresponding function block instance has been successfully configured. The output ipResultMessage of type I_TcMessage provides various properties for explaining the cause of an event and methods for processing the message (event list).
See also: I_TcEventBase und I_TcMessage
Methods
All function blocks of the library Tc3_Filter have three methods. They return a positive value if they were executed without errors.
Configure()
This method can be used at runtime to initially configure the instance of a filter function block (if it was not already configured in the declaration) or to reconfigure it.
METHOD Configure : BOOL
VAR_INPUT
stConfig : ST_FTR_<type>;
END_VAR
Call()
The method calculates a manipulated output signal from an input signal that is transferred in the form of a pointer.
METHOD Call : BOOL
VAR_INPUT
pIn : POINTER TO LREAL; (*address of input array*)
nSizeIn : UDINT; (*size of input array*)
pOut : POINTER TO LREAL; (*address of output array*)
nSizeOut : UDINT; (*size of output array*)
END_VAR
Reset()
The method resets the internal status of a filter. The influence of the past values on the current output value is eliminated.
METHOD Reset : BOOL
Properties
The library Tc3_Filter references the TwinCAT 3 EventLogger and thus ensures that information (events) is provided via the standardized interface I_TcMessage.
Each function block has the properties eTraceLevel of type TcEventSeverity and eTraceLevelDefault of type BOOL.
The trace level determines the severity of an event (verbose, info, warning, error, critical) and is set using the eTraceLevel property.
(* Sample of setting fbFilter to trace level info *)
fbFilter.eTraceLevel := TcEventSeverity.Info;
The property eTraceLevelDefault can be used to reset the trace level to the default value (TcEventSeverity.Critical). The property can be read and written, i.e. the property eTraceLevelDefault can be used to query whether the default value is set.
The properties can also be set in Online view.
Dealing with oversampling and multiple channels
All function blocks are oversampling- and multi-channel-capable. They can be used in different ways. The declaration of the filter function block instance fbFilter is always the same.
Multi-channel with two-dimensional signal arrays
The definition of a two-dimensional array has the advantage that it is universally valid, and the parameter cChannels can also be set to 1 in other projects. The channels in TwinCAT 3 Scope can also be selected individually, so that all channels can be viewed independently of each other.
Display of the multidimensional array in the "Target Browser":
Sample:
VAR CONSTANT
cChannels : UINT := 2;
cOversamples : UINT := 10;
END_VAR
VAR
aInput : ARRAY [1..cChannels] OF ARRAY [1..cOversamples] OF LREAL;
aOutput : ARRAY [1..cChannels] OF ARRAY [1..cOversamples] OF LREAL;
END_VAR
bSucceed := fbFilter.Call(ADR(aInput), SIZEOF(aInput), ADR(aOutput), SIZEOF(aOutput));
Multi-channel with one-dimensional signal arrays
Alternatively, the sampling values of the different channels can be stored in a one-dimensional array. However, in this case recording the individual channels with TwinCAT 3 Scope is more difficult.
Sample:
VAR CONSTANT
cChannels : UINT := 2;
cOversamples : UINT := 10;
END_VAR
VAR
aInput : ARRAY [1..cChannels*cOversamples] OF LREAL;
aOutput : ARRAY [1..cChannels*cOversamples] OF LREAL;
END_VAR
bSucceed := fbFilter.Call(ADR(aInput), SIZEOF(aInput), ADR(aOutput), SIZEOF(aOutput));
One-channel application with oversamples
If only a single channel is considered, the input and output arrays can be declared as one-dimensional quantities.
VAR CONSTANT
cChannels : UINT := 1;
cOversamples : UINT := 10;
END_VAR
VAR
aInput : ARRAY [1..cOversamples] OF LREAL;
aOutput : ARRAY [1..cOversamples] OF LREAL;
END_VAR
bSucceed := fbFilter.Call(ADR(aInput), SIZEOF(aInput), ADR(aOutput), SIZEOF(aOutput));
One-channel application without oversamples
If only a single channel is considered and no oversampling is applied, the input and output variables can be declared as LREAL.
VAR CONSTANT
cChannels : UINT := 1;
cOversamples : UINT := 1;
END_VAR
VAR
fInput : LREAL;
fOutput : LREAL;
END_VAR
bSucceed := fbFilter.Call(ADR(fInput), SIZEOF(fInput), ADR(fOutput), SIZEOF(fOutput));