FB_CMA_DiscreteClassification

Klassifikation von mehrkanaligen Daten anhand konfigurierbarer Schwellwerte

Der Baustein ordnet die einzelnen Kanäle eines mehrkanaligen Signals anhand konfigurierbarer Schwellwerte einer festen Zahl von diskreten Kategorien zu. Die Zahl der Kanäle und die Anzahl der Kategorien werden bei der Instanziierung festgelegt. Der Baustein lässt sich zur Laufzeit konfigurieren, indem für jeden Kanal und jede Schwellwert-Kategorie die Größe des Schwellwerts angegeben wird.

In der Operationsphase wird für jeden Zeitschritt ein Eingangsvektor angenommen und die Nummer der zutreffenden Kategorie für jeden Kanal berechnet. Rückgabewert ist ein eindimensionales Array, das für jeden Eingangskanal einen vorzeichenbehafteten Integer-Wert enthält, den Index der zugeordneten Kategorie.

Wenn der Eingangswert kleiner ist als der Schwellwert der ersten Kategorie, wird für diesen Kanal der Wert -1 zurückgegeben. Wenn ein Eingangswert größer gleich dem Schwellwert für eine Kategorie ist, wird der null-basierte Index dieser Kategorie zurückgegeben. Falls mehrere Schwellwerte gleich konfiguriert sind, wird der Wert mit dem größten Index genommen.

Konfiguration

Der Funktionsbaustein muss mittels Parameter wie der Anzahl der Klassifikationsklassen konfiguriert werden. Die Klassifikationsschwellwerte jedes Kanals können individuell vergeben werden. Diese Schwellwerte müssen monoton steigend (aber nicht streng monoton) sein. Dementsprechend darf kein Schwellwert kleiner als der vorhergehende Wert sein.

Gedächtniseigenschaften

Der Baustein berücksichtigt nur die bei Konfiguration und Training gespeicherten Werte. Die während der Klassifikation übergebenen Werte haben keinen Einfluss auf spätere Aufrufe.

NaN Vorkommnis

Bei einem Eingangswert von NaN ist das Ergebnis -2. Am Ausgang sind keine NaN Werte zu erwarten.

Verhalten bei der Verarbeitung mehrkanaliger Eingangsdaten

Bei der Verarbeitung mehrerer Kanäle (nChannels > 1) besteht die Möglichkeit unterschiedlicher Rückgabewerte je Kanal. In diesem Fall können gesonderte Rückgabewerte am Funktionsbaustein abgefragt werden. Sind die Ergebnisse von einem oder mehreren Kanälen unzulässig, jedoch nicht alle Kanäle, dann entspricht der Wert am Baustein eCM_InfRTime_AmbiguousChannelResults. Sind die Ergebnisse aller Kanäle unzulässig, dann entspricht der Wert am Baustein eCM_ErrRTime_ErrornousChannelResults.

Die Abfrage einer Liste der Rückgabewerte aller Kanäle kann über die Methode GetChannelErrors()erfolgen.

Bei der Verarbeitung mehrerer Unterkanäle (nSubChannels > 0) ist die Formatierung der Eingangs- und Ausgangsdaten gesondert zu beachten. Bestehen die Eingangsdaten aus einem mehrkanaligen Ergebnis eines vorangestellten Funktionsbausteins, muss der Wert von nChannels übernommen werden, eine weitere Konfiguration erfolgt in diesem Fall über den Parameter nSubChannels.

Beispiel: Bei der statistischen Betrachtung (z.B. durch FB_CMA_Quantiles) der Frequenzkanäle eines mehrkanaligen Spektrums (z.B. FB_CMA_MagnitudeSpectrum) ist der Wert von nChannels identisch zur Anzahl der Eingangssignale zu wählen, die Anzahl der Unterkanäle nSubChannels entspricht der Länge des Spektrums.

Beispielimplementierung

Zwei exemplarische Implementierungen sind unter folgenden Links verfügbar: Schwellwertbetrachtung gemittelte Betragsspektren sowie Condition Monitoring mit Frequenzanalyse.

Ein- und Ausgänge

Die Ein- und Ausgangspuffer entsprechen einer der folgenden Definitionen (input / output shape). Die variablen Parameter sind Teil des Bausteineingangs stInitPars.

Varianten

Eingangspuffer (MultiArray input stream)
Elementtyp, Dimensionsanzahl, Dimensionsgrößen

Ausgangspuffer (MultiArray output stream)
Elementtyp, Dimensionsanzahl, Dimensionsgrößen

Standardvariante
(nSubChannels = 0)

LREAL, 1,
nChannels

DINT (32bit), 1,
nChannels

Mehrkanalige Variante
(nSubChannels > 0)

LREAL, 2,
nChannels x nSubChannels

DINT (32bit), 2,
nChannels x nSubChannels

Eingangsparameter

Die Eingangsparameter dieses Bausteins repräsentieren Initialisierungsparameter und müssen bereits bei der Deklaration der FB Instanz zugewiesen werden! (Alternativ: Init()-Methode). Sie dürfen nur einmalig zugewiesen werden. Eine Änderung zur Laufzeit ist nicht möglich.

VAR_INPUT
    stInitPars       : ST_CM_DiscreteClassification_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

Ausgangsparameter

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: Der Ausgang ist TRUE, falls ein Fehler auftritt.
  • hrErrorCode: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert.
  • ipErrorMessage: Beinhaltet nähere Informationen zum aktuellen Rückgabewert. Siehe hierzu den Abschnitt Fehlerbeschreibung und Information. Für diesen speziellen Schnittstellenzeiger ist intern sichergestellt, dass er immer gültig/zugewiesen ist.

Methoden

Call():

Die Methode wird jeden Zyklus aufgerufen, um den Algorithmus auf die aktuellen Eingangsdaten anzuwenden. Der Baustein wartet auf Eingangsdaten, sofern die Methode weder neue Ergebnisse noch einen Fehler angibt. Dies ist ein reguläres Verhalten im Ablauf der Analysekette.

  • Rückgabewert: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert.
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: Der Ausgang ist TRUE, falls ein Fehler auftritt.
  • hrErrorCode: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert. Dieser Ausgang ist identisch zum Rückgabewert der Methode.
FB_CMA_DiscreteClassification 1:

Falls ein Timeout eintritt oder kein MultiArray Puffer für das Ergebnis verfügbar ist, so gehen weder die Eingangsdaten noch die Ergebnisdaten verloren. Sie werden beim nächsten Aufruf weitergeleitet.

Configure():

Mit dem Aufruf dieser Methode müssen die Klassifikationsargumente zu Beginn konfiguriert werden. Das entsprechende SPS Array muss wie folgt definiert sein. Für eine erneute Konfiguration mit einem anderen Satz an Argumenten kann die Configure() Methode ebenfalls genutzt werden.

  • Rückgabewert: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert.
METHOD Configure : HRESULT
VAR_INPUT
    pArg     : POINTER TO LREAL; // pointer to array (LREAL) of arguments
    nArgSize : UDINT;            // size of arguments buffer in bytes 
END_VAR

Die Eingangspuffer entsprechen einer der folgenden Definitionen (input shape). Die variablen Parameter sind Teil des Bausteineingangs stInitPars.

Varianten

Eingangspuffer (MultiArray input stream)
Elementtyp, Dimensionsanzahl, Dimensionsgrößen

Identische Konfiguration aller Kanäle und Unterkanäle

LREAL, 1,
nMaxClasses

Kanalspezifische Konfiguration
(nSubChannels = 0)

LREAL, 2,
nChannels x nMaxClasses

Unterkanalspezifische Konfiguration
(nSubChannels > 0)

LREAL, 2,
nSubChannels x nMaxClasses

Kanal- und unterspezifische Konfiguration
(nSubChannels > 0)

LREAL, 3,
nChannels x nSubChannels x nMaxClasses

Init():

Üblicherweise ist diese Methode in einer Condition Monitoring Applikation nicht notwendig. Sie bietet eine Alternative zur Bausteininitialisierung. Die Init() Methode darf nur während der Initialisierungsphase der SPS aufgerufen werden. Sie kann nicht während der Laufzeit verwendet werden. Es sei auf die Verwendung von einer FB_init Methode oder dem Attribut 'call_after_init' hingewiesen (siehe TwinCAT SPS Referenz). Hiermit wird zudem die Bausteinkapselung erleichtert.

Die Eingangsparameter der Bausteininstanz dürfen nicht bei der Deklaration zugewiesen werden, falls die Initialisierung mit der Init() Methode erfolgen soll.

  • Rückgabewert: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert.
METHOD Init : HRESULT
VAR_INPUT
    stInitPars     : ST_CM_DiscreteClassification_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

PassInputs():

Solange eine FB_CMA_Source Instanz aufgerufen wird und somit Signaldaten zu einem Zielblock übertragen werden, müssen wie in der API SPS Referenz erläutert alle weiteren Blöcke der Analysekette zyklisch aufgerufen werden.
Manchmal ist es sinnvoll, einen Algorithmus für eine bestimmte Zeit nicht auszuführen. Beispielsweise sollten manche Algorithmen nur nach vorherigem Training bzw. Konfiguration ausgeführt werden. Zwar muss der Funktionsbaustein dennoch zyklisch aufgerufen werden, aber es ist ausreichend, wenn die am Baustein ankommenden Daten im Kommunikationsring weitergeleitet werden. Dies geschieht mittels der Methode PassInputs() anstelle der Methode Call(). Hierbei wird der Algorithmus selbst nicht aufgerufen und entsprechend kein Ergebnis berechnet sowie kein Ausgangspuffer generiert.

  • Rückgabewert: Falls ein Fehler auftritt, wird ein entsprechender Fehlercode vom Typ HRESULT ausgegeben. Mögliche Werte sind in der Liste der Fehlercodes erläutert.
METHOD PassInputs : HRESULT
VAR_INPUT
END_VAR

GetChannelErrors():

Die Methode ermöglicht die Abfrage einer Liste der kanalspezifischen Rückgabewerte bei der Verarbeitung mehrerer Kanäle (nChannels > 1). Ein Aufruf ist sinnvoll für den Fall, dass der Rückgabewert des Bausteins einem der Werte eCM_InfRTime_AmbiguousChannelResults oder eCM_ErrRTime_ErrornousChannelResults entspricht.

  • Rückgabewert: Information über den Ausleseprozess der Liste der Fehlercodes. Der Wert wird auf TRUE gesetzt, falls die Abfrage erfolgreich war, FALSE anderenfalls.

    METHOD GetChannelErrors : BOOL
VAR_IN_OUT
    aChannelErrors : ARRAY[*] OF HRESULT;
END_VAR
  • aChannelErrors: Fehlerliste vom Typ HRESULT der Länge nChannels.

Ähnliche Funktionsbausteine

Der Baustein FB_CMA_WatchUpperThresholds berechnet die höchste Kategorie mehrkanaliger Eingangsdaten und gibt diese, sowie die Nummer des zugehörigen Kanals zurück.

Voraussetzungen

Entwicklungsumgebung

Zielplattform

Einzubindende SPS-Bibliotheken

TwinCAT v3.1.4022.25

PC or CX (x86, x64)

Tc3_CM, Tc3_CM_Base

FB_CMA_DiscreteClassification 2:

Eingeschränkter Funktionsumfang bereits mit CM 3.1 verfügbar. Siehe Abschnitt Kompatibilität.