FB_CMA_CrestFactor

Calculates the crest factor for each channel for single and multi-channel time series.

This is defined as the ratio between the peak value of a signal and the RMS value.

FB_CMA_CrestFactor 1:

The crest factor is calculated in the logarithmic unit decibel. A sine wave, for example, has a crest factor of 3.01 dB (=1,414). It allows, for example, conclusions to be drawn about the condition of roller bearings. In general the crest factor increases at the start of damage to a roller bearing and can decrease again as the damage progresses.

To avoid value range errors, each calculated value is compared to a minimum value before the logarithm is applied and, if it is less than that, replaced by that minimum value.

Since the crest factor is defined by the ratio between peak value and RMS value, this means that the result is strongly influenced by the individual maxima, which can lead to unexpected results.

Memory properties

For the calculation of the RMS value, nBufferLength values of the time series are stored internally per channel/subchannel. In a call with smaller input buffer size, fewer values can be transferred. In this case the buffer content is shifted, and the signal length is filled with the corresponding number of newly transferred values. If the input buffer is larger than the internal buffer, the latter is filled with the latest values for the calculation.

NaN occurrence

If the input vector contains one or more NaN (Not a Number) values, the entire output sector is filled with NaN. See separate section for further information on NaN values.

The output vector is filled with NaN until the internal buffer has been completely filled with new, valid values.

FB_CMA_CrestFactor 2:

Handling of NaN values

If the situations described above, which lead to NaN values, cannot be ruled out or safely neglected, the application program must be able to handle these error values.

Behavior when processing multi-channel input data

When processing several channels (nChannels > 1), there is a possibility of each channel having different return values. In this case, return values can be queried separately on the function block. If the results from one or more channels are impermissible, but not all channels, the value on the function block corresponds to eCM_InfRTime_AmbiguousChannelResults. If the results of all channels are impermissible, then the value on the function block corresponds to eCM_ErrRTime_ErrornousChannelResults.

A list of return values of all channels can be queried using the method GetChannelErrors().

When processing several subchannels (nSubChannels > 0), particular attention must be paid to the formatting of the input and output data. If the input data consist of a multi-channel result of an upstream function block, the value of nChannels must be adopted; further configuration takes place in this case via the parameter nSubChannels.

Sample: In the statistical consideration (e.g. by FB_CMA_Quantiles) of the frequency channels of a multi-channel spectrum (e.g. FB_CMA_MagnitudeSpectrum), the value of nChannels must be identical to the number of input signals; the number of subchannels nSubChannels corresponds to the length of the spectrum.

Sample implementation

A sample implementation is available under the following link: Crest factor.

Inputs and outputs

The input and output buffers correspond to one of the following definitions (input / output shape). The variable parameters are part of the function block input stInitPars.

Versions

Input buffer (MultiArray input stream)
Element type, number of dimensions, dimension sizes

Output buffer (MultiArray output stream)
Element type, number of dimensions, dimension sizes

Standard version for several data sets
(nSubChannels = 0)

LREAL, 2,
nChannels not specified*

LREAL, 1,
nChannels

Multi-channel version for several data sets
(nSubChannels > 0)

LREAL, 3,
nChannels x nSubChannels x not specified*

LREAL, 2,
nChannels x nSubChannels

*: The length of this dimension can be selected as desired and can thus adapt itself to the application or to the output buffer of the preceding algorithm.

VAR_INPUT
    stInitPars       : ST_CM_CrestFactor_InitPars;      // init parameter
    nOwnID           : UDINT;                           // ID for this FB instance
    aDestIDs         : ARRAY[1..cCMA_MaxDest] OF UDINT; // IDs of destinations for output
    nResultBuffers   : UDINT := 4;                      // number of MultiArrays which should be initialized for results (0 for no initialization)
    tTransferTimeout : LTIME := LTIME#500US;            // timeout checking off during access to inter-task FIFOs
END_VAR

Input parameters

The input parameters of this function block represent initialization parameters and must already be assigned in the declaration of the FB instance! (Alternatively: Init() method). They may only be assigned once. A change at runtime is not possible.

  • stInitPars: Function-block-specific structure with initialization parameters of the type ST_CM_CrestFactor_InitPars. The parameters must correlate to the above definition of the input and output buffers.

Output parameters

VAR_OUTPUT
    bError         : BOOL;                           // TRUE if an error occurs. Reset by next method call.
    hrErrorCode    : HRESULT;                        // '< 0' = error; '> 0' = info; '0' = no error/info
    ipErrorMessage : I_TcMessage := fbErrorMessage;  // Shows detailed information about occurred errors, warnings and more.
    nCntResults    : ULINT;                          // Counts outgoing results (MultiArrays were calculated and sent to transfer tray).
END_VAR
  • bError: The output is TRUE if an error occurs.
  • hrErrorCode: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes.
  • ipErrorMessage: Contains more detailed information on the current return value. Refer here to the section Error description and information. This special interface pointer is internally secured so that it is always valid/assigned.

Methods

METHOD Init : HRESULT
VAR_INPUT
    stInitPars     : ST_CM_CrestFactor_InitPars;      // init parameter
    nOwnID         : UDINT;                           // ID for this FB instance
    aDestIDs       : ARRAY[1..cCMA_MaxDest] OF UDINT; // IDs of destinations for output
    nResultBuffers : UDINT := 4;                      // number of MultiArrays which should be initialized for results (0 for no initialization)
END_VAR

Call():

The method is called each cycle in order to apply the algorithm to the current input data. The function block waits for input data if the method indicates neither new results nor an error. This is a regular behavior in the process of the analysis chain.

  • Return value: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes.
METHOD Call : HRESULT
VAR_OUTPUT
    bNewResult   : BOOL;       // TRUE every time when outgoing MultiArray was calculated and sent to transfer tray.
    bError       : BOOL;       // TRUE if an error occurs.
    hrErrorCode  : HRESULT;    // '< 0' = error; '> 0' = info; '0' = no error/info
END_VAR
  • bError: The output is TRUE if an error occurs.
  • hrErrorCode: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes. This output is identical to the return value of the method.
FB_CMA_CrestFactor 3:

If a timeout occurs or no MultiArray buffer is available for the result, then neither the input data nor the result data are lost. They are forwarded on the next call.

Init():

This method is not usually necessary in a Condition Monitoring application. It offers an alternative to the function block initialization. The Init() method may only be called during the initialization phase of the PLC. It cannot be used at runtime. You are referred to the use of an FB_init method or the attribute 'call_after_init' (see TwinCAT PLC reference). In addition, this facilitates the function block encapsulation.

The input parameters of the function block instance may not be assigned in the declaration if the initialization is to take place using the Init() method.

  • Return value: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes.
  • stInitPars: Function-block-specific structure with initialization parameters of the type ST_CM_CrestFactor_InitPars. The parameters must correlate to the above definition of the input and output buffers.

ResetData():

The method deletes all data records that have already been added, see Memory property of the function block. If the Call() method is called again after a ResetData(), the internal memory must be replenished in order to calculate a valid result.

  • Return value: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes.
METHOD ResetData : HRESULT
VAR_INPUT
END_VAR

PassInputs():

As long as an FB_CMA_Source instance is called and signal data are thus transferred to a target block, all further function blocks of the analysis chain have to be called cyclically as explained in the API PLC Reference.
Sometimes it is useful not to execute an algorithm for a certain time. For example, some algorithms should be executed only after prior training or configuration. The function block must be called cyclically, but it is sufficient for the data arriving at the function block to be forwarded in the communication ring. This is done using the PassInputs() method in place of the Call() method. The algorithm itself is not called here, and accordingly no result is calculated and no output buffer generated.

  • Return value: If an error occurs, a corresponding error code of the type HRESULT is output. Possible values are described in the List of error codes.
METHOD PassInputs : HRESULT
VAR_INPUT
END_VAR

GetChannelErrors():

The method enables the querying of a list of the channel-specific return values when processing several channels (nChannels > 1). A call is useful in the case that the return value of the function block corresponds to one of the values eCM_InfRTime_AmbiguousChannelResults or eCM_ErrRTime_ErrornousChannelResults.

  • Return value: Information on the reading process of the list of error codes. The value is set to TRUE if the query was successful, otherwise to FALSE.

    METHOD GetChannelErrors : BOOL
VAR_IN_OUT
    aChannelErrors : ARRAY[*] OF HRESULT;
END_VAR
  • aChannelErrors: Error list of the type HRESULT of the length nChannels.

Similar function blocks

The FB_CMA_HistArray function block calculates the histograms of input value distributions.

The FB_CMA_Quantiles block calculates the quantiles of an empirical distribution, which enable the frequency of outliers to be assessed.

The FB_CMA_MomentCoefficients block provides the kurtosis as an alternative measure for the peakiness of a signal that is less sensitive to outliers.

Requirements

Development environment

Target platform

PLC libraries to include

TwinCAT v3.1.4022.25

PC or CX (x86, x64)

Tc3_CM, Tc3_CM_Base

FB_CMA_CrestFactor 4:

Limited functional scope already available with CM 3.1. See section Compatibility.