Überwachungsmodul "diagnostics"

Beschreibung

Aufgabe des Überwachungsmoduls "diagnostics" ist es, unterschiedliche Arten von Eingangsdaten bezüglich festgelegter Kriterien zu überwachen und die hieraus resultierenden Alarminformationen anschließend in die smartCORE Alarmdatenbank des Alarm-Managers zu schreiben.

Diese Datenbank kann zur weiteren Verarbeitung der Alarmmeldungen z.B. mit dem opticloud-Plugin an die optiCloud angebunden werden.

Zu den Arten überwachter Eingangsdaten zählen unter anderem

• Boolesche Werte, z.B. Status-Flags oder Ergbenisse berechneter Logik
• Double-Werte (Fließkomma), z.B. Messwerte oder berechnete Größen, die gegen einen festen Grenzwert verglichen werden. Eine einstellbare Hysterese ist für die Unterdrückung von Rauschen vorgesehen. Um Extremwerte nachzuverfolgen, können Aktualisierungen der Meldung aktiviert werden.
• Integer-Codes, z.B. Status- oder ENUM-Codes oder bestimmte bits oder bit-Abschnitte; dabei können einzelne Codes oder Code-Bereiche mittels eine White/Black-List gefiltert werden und jeweils dem Zustand HIGH oder LOW zugeordnet werden. Nicht passende Codes werden über einen eigenen Fehlerzustands-Alarm gemeldet bis ein gültiger Code eintrifft. Um Statuswechsel nachzuverfolgen, können Aktualisierungen der Meldung aktiviert werden.
• String-Werte (Text), z.B. Logbuch-Meldungen eines Gerätes; dabei können Textelemente über Regular Expressions (PCRE) extrahiert, als White/Black-List gefiltert und dem Zustand HIGH oder LOW zugeordnet werden. Nicht passende Texte werden über einen eigenen Fehlerzustands-Alarm gemeldet bis ein gültiger Code eintrifft.
• ErrorCode: Eine Folge von Error-Codes (<string>) in Verbindung entweder mit einem Level-Kanal oder einem Transfer-Kanal. Das Diagnostics-Modul führt intern eine Tabelle mit Fehlercodes und der zugehörigen Meldungsinstanz. Meldungen können einzelnen Codes oder als Template einem Code-Bereich (Wildcard) oder allen eingehenden Codes zugewiesen werden.

Darüberhinaus werden im Rahmen der Zusammenstellung von Alarmmeldungen aktuelle Werte von smartCORE Kanälen erfasst (sogenannte Snapshots) sowie benutzerdefinierte Metadaten integriert. Das folgende Schema gibt einen Überblick über die implementierte Funktionalität der Alarm-Logik. Je Message-Eintrag stehen die hellgelb hinterlegten Blöcke zur Verfügung:

Die Verarbeitung der Daten eines überwachten Kanals erfolgt aus Sicht des Diagnose-Plugins, d.h. es findet eine implizite Umwandlung in den erwarteten Datentyp statt. Damit spielt der Datentyp des Kanals für die Auswertung keine Rolle, sofern dieser entsprechend konvertierbar ist.

Verwendete Schnittstellen & Protokolle

• smartCORE Alarmdatenbank

JSON-Konfiguration

In den folgenden Abschnitten werden Beispielkonfigurationen aufgelistet sowie hieran beteiligte Modulparameter diskutiert.

Beispielkonfiguration (Überwachung auf Boolesche Werte)

In diesem Beispiel wird ein Kanal als Boolean gelesen auf den Wert true überwacht.

Zur Konvertierung des Datentyps gilt:

• <integer>, <unsigned integer> oder <double> ist true, wenn das Sample $\ne 0$ ist,
• <string> ist true, wenn der String nicht leer ist

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "pollingIntervalMs": 1000,
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Monitoring someBooleanChannel",
        "channel": "someBooleanChannel",
        "activation": "high"
      }
    ]
  }
}

Beispielkonfiguration (Überwachung der Überschreitung eines numerischen Werts mit Stabilisierungsverzögerungen und Hysterese)

In diesem Beispiel wird ein Kanal als Double gelesen und auf die Überschreitung des Wertes von 42.0 hin überwacht.

Zur Konvertierung des Datentyps gilt:

• <bool> werden in 0 und 1 übersetzt,
• <string> liefert als Wert die Länge des Strings

Im Beispiel ist es zur Auslösung notwendig, dass die Überschreitung mindestens 5 Sekunden lang andauert bzw. zur Deaktivierung, dass diese mindestens 10 Sekunden lang nicht vorliegt und hierfür der Wert des Kanals unterhalb des Schwellwerts minus seiner Hysterese liegt.

Es wird zudem eine Ereignis bezogene Meldung generiert, die den aktuellen Wert, das bisherige Extremum, d.h. in diesem Fall Maximum, sowie den Schwellwert beinhaltet.

Diese Meldung wird sowohl bei initialer Überschreitung als auch bei Deaktivierung aktualisiert. Außerdem wird diese Meldung bei Abweichungen des aktuellen Werts vom zuletzt gemeldeten Extremum, die größer als die Hysterese sind, ebenfalls aktualisiert.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "pollingIntervalMs": 1000,
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Monitoring measured someValueChannel",
        "messageEvent": "Some WARNING occurred (current value ${value} > ${boundary}) (maximum value ${minmax} on ${minmaxDate} at ${minmaxTime})",
        "channel": "someValueChannel",
        "threshold": 42.0,
        "hysteresis": 7.0,
        "activation": "high",
        "stabilizationSecondsRaise": 5,
        "stabilizationSecondsRelease": 10
      }
    ]
  }
}

Beispielkonfiguration (Überwachung enumerierter Werte)

In diesem Beispiel wird ein Kanal als Integer-Wert gelesen und überwacht.

Zur Konvertierung des Datentyps gilt:

• <bool> werden in 0 und 1 übersetzt,
• <float> oder <double> werden ohne Nachkommastellen verwendet,
• <string> liefert als Wert die Länge des Strings

In diesem Beispiel werden die Wertebereiche 17 und 77-99 als Auslösebedingung (HIGH), die Wertebereiche 31-39, 66 und 69-71 als Deaktivierungsbedingung (LOW) sowie sämtliche anderen Bereiche als ungültige Alarmbedingung interpretiert.

{ 
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "pollingIntervalMs": 1000,
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Monitoring someEnumeratedChannel",
        "messageEvent": "Some WARNING occurred",
        "messageFailure": "INVALID error occurred",
        "channel": "someEnumeratedChannel",
        "activation": "enum",
        "valuesHigh": "17,77-99",
        "valuesLow": "31-39,66,69-71"
      }
    ]
  }
}

Beispielkonfiguration (Überwachung eines Error Streams)

In diesem Beispiel werden FehlerCodes (ErrorCode) aus einem sogenannten Error Stream überwacht. Dieser besteht aus den beiden sourceErrorCode und sourceErrorLevel Kanälen, die zeitlich synchron sein müssen. Der Fehlercode-Kanal wird als <string> gelesen, sodass fast beliebige Kanäle als Quelle verwendet weren können. Der Fehlerlevel-Kanal muss ganzzahlige <integer> Werte liefern. Die aus diesem Error Stream extrahierten Codes stehen allen ErrorCode-Messages in der Reihenfolge ihrer Definition zur Verarbeitung zur Verfügung. Ein bestimmter Code kann jeweils nur in einer ErrorCode-Message berücksichtigt werden.

Im Beispiel werden sowohl der benutzerspezifische Fehlercode "47:11", Fehlercodes, die mit "ERR:" beginnen, als auch sämtliche anderen unbekannten Fehlercodes überwacht. Wenn das Message-Objekt für verschiedene Codes verwendet werden soll, muss es als Template markiert werden.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "pollingIntervalMs": 1000,
    "sourceErrorCode": "Some.Name.Space.ErrorCodeChannel",
    "sourceErrorLevel": "Some.Name.Space.ErrorLevelChannel",
    "messages": [
      {
        "errorCode": "47:11",
        "messageLevel": "ALARM",
        "context": "Monitoring Error-Stream for 47:11",
        "messageEvent": "ALARM ${errorCode} occurred"
      },
      {
        "isTemplate": true,
        "errorCode": "ERR:*",
        "messageLevel": "ERROR",
        "context": "Monitoring for ERR-codes",
        "messageEvent": "Error ${errorCode} occurred"
      },
      {
        "isTemplate": true,
        "messageLevel": "WARNING",
        "context": "Collection unknown codes",
        "messageEvent": "Unknown code ${errorCode} occurred"
      }
    ]
  }
}

Beispielkonfiguration (Verwendung von Metadaten)

In diesem Beispiel wird ein Kanal wie in Besipiel 1 auf den Wert true überwacht. Ziel dieses Beispiels ist es, die Ergänzung von Alarmmeldungen um benutzerspezifische Metadaten zu veranschaulichen.

Es werden hierfür im Rahmen der Zusammenstellung der Alarmmeldung Metadaten in Form eines JSON-Objekts hinzugefügt, wobei immer die globalen Metadaten um die im Rahmen der Message spezifizierten Metadaten ergänzt bzw. auf oberster Ebene des JSON-Objekts ersetzt werden.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "pollingIntervalMs": 1000,
    "globalMetadata": {
      "actionToBePerformed":"some generic action",
      "consequences":[
        "consequence1",
        "consequence2"
      ]
    },
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Monitoring someBooleanChannel",
        "channel": "someBooleanChannel",
        "activation": "high",
        "metadata": {
          "actionToBePerformed":"some CRITICAL action",
          "consequences":[
            "some SEVERE consequence",
            "consequence1",
            "consequence2"
          ],
          "additionalRemarks":[
            "some REMARK"
          ]
        }
      }
    ]
  }
}

Beispielkonfiguration (Verwendung von Snapshot-Kanälen)

In diesem Beispiel wird ein Kanal wie in Besipiel 1 auf den Wert true überwacht.

Ziel dieses Beispiels ist es, die Ergänzung von Alarmmeldungen um einen benutzerspezifischen Snapshot von Kanalwerten zu veranschaulichen.

Es wird hierfür zum Zeitpunkt des initialen Auftretens der Alarmbedingung eine Momentaufnahme der aufgeführten smartCORE Kanäle angefertigt, die aus der Vereinigung aller globalen und meldungsbezogenen Snapshot-Kanälen besteht.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "pollingIntervalMs": 1000,
    "globalSnapshot": [
      "someGps.Location",
      "someOutsideTemperature"
    ],
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Monitoring someBooleanChannel",
        "channel": "someBooleanChannel",
        "activation": "high",
        "snapshot": [
          "somePressure",
          "someTemperature",
          "someQuantity",
        ]
      }
    ]
  }
}

Beispielkonfiguration (Verwendung von Snapshot-Gruppen)

In diesem Beispiel wird ein Kanal wie in Besipiel 1 auf den Wert true überwacht.

Dieses Beispiel veranschaulicht zusätzlich die Verwendung sogenannter Snapshot-Gruppen.

{
  "module": "diagnostics",
  "factory": "diagnostics",
  "config": {
    "pollingIntervalMs": 1000,
    "snapshotGroups": [
      {
        "name": "gpsInfoChannels",
        "channels": [
          "GPS.Location",
          "GPS.Altitude",
          "GPS.SatCount"
        ]
      },
      {
        "name": "EngineOilPTQChannels",
        "channels": [
          "Engine.Oil.Pressure",
          "Engine.Oil.Temperature",
          "Engine.Oil.Quantity"
        ]
      }
    ],
    "globalSnapshot": [
      "gpsInfoChannels",
      "someOutsideTemperature"
    ],
    "messages": [
      {
        "messageLevel": "WARNING",
        "context": "Monitoring someBooleanChannel",
        "channel": "someBooleanChannel",
        "activation": "high",
        "snapshot": [
          "Engine.Revs",
          "EngineOilPTQChannels"
        ]
      }
    ]
  }
}

Globale Modulparameter

Im folgenden Abschnitt werden sämtliche Parameter des Moduls diskutiert.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
pollingIntervalMs	Nein	INT	1 -	1000 (1 s)	Verarbeitungsintervall [ms]
minLogEvents1	Nein	STRING	none, info, action, service, warning, alarm, error, fatal	warning	Schweregrad, ab dem ein überwachtes Ereignis zusätzlich in die Logdatei geschrieben wird. none schaltet die Protokollierung ab
logReleased1	Nein	BOOLEAN	false, true	false	Protokolliert auch das Ende eines Alarms, nicht nur sein Auftreten
debugMask1	Nein	INTEGER | STRING	Bitmaske	0	Schaltet einzelne Diagnoseausgaben des Moduls frei. Nur für Entwicklung und Fehlersuche
globalMetadata	Nein	JSON Object		EMPTY JSON Object	JSON Objekt mit beliebigen benutzerspezifizierten Metadaten
globalSnapshot	Nein	JSON Array of STRING		EMPTY JSON Array	JSON Array, welches eine globale Liste mit Kanälen beinhaltet, deren Werte zum Zeitpunkt der Alarmierung punktuell erfasst werden sollen
snapshotGroups	Nein	JSON Array of JSON Object		EMPTY JSON Array	siehe unten
activationMode2	(veraltet)				Siehe Beschreibung der Messages
messages	JA	JSON Array of JSON Object		KEIN Default-Wert	siehe unten
					für Error-Stream oder Error-Table
sourceErrorCode	Nein/Ja3 4	STRING		KEIN Default-Wert	smartCORE Kanal, gelesen als <string>, der einen zeitlich variablen Fehlercode beinhaltet
sourceErrorLevel	Nein/Ja3	STRING		KEIN Default-Wert	smartCORE Kanal, gelesen als <integer> der ein hierzu synchrones Fehlerlevel beinhaltet
neutralErrorLevel neutraErrorCode5	Nein3 (veraltet)	INTEGER		0	Neutraler Fehlerlevel, bei dem KEIN Alarm ausgelöst wird
sourceBufferTransfer	Nein/Ja4	STRING		KEIN Default-Wert	smartCORE Kanal, gelesen als <bool>, der das Framing für die Übertragung der Fehlertabelle steuert
timeoutBufferTransfer	Nein/Ja4	DOUBLE		0	Minimale Pause zwischen der Übertragung der Fehlertabellen in Sekunden

Globale Snapshot Gruppen "snapshotGroups"

Mehrere im Rahmen eines Snapshots zu erfassende Kanäle können in Form einer Snapshot-Gruppe als JSON-Objekt konfiguriert werden, deren Name dann im weiteren Verlauf der Konfiguration in Gruppen und Signallisten wie ein Kanalname verwendet werden kann. Sinnvollerweise sollten diese Gruppen so benannt werden, dass keine Überschreibung mit existierenden Kanalnamen erfolgt, da ein Name in einer Signalliste bei der Interpretation zuerst als Gruppenname geprüft wird.

Sind Kanalnamen in verschiedenen Gruppen oder Signallisten enthalten und damit vervielfacht, werden sie beim Zusammenstellen des Snapshot nur einmal in diesen aufgenommen.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
name	JA	STRING			Name bzw. Alias der Snapshot-Gruppe
channels	JA	JSON Array of STRING			Liste aller Kanalnamen oder bereits definierten Gruppen

Protokollierung überwachter Ereignisse

Ein ausgelöstes Ereignis wird immer in die Alarmdatenbank geschrieben. Unabhängig davon kann es zusätzlich in der Logdatei des Geräts erscheinen. Das ist die einzige Spur, die ohne Zugriff auf die Alarmdatenbank auswertbar bleibt — bei einem Gerät im Feld oft die einzige, die überhaupt zur Verfügung steht.

Zwei globale Parameter steuern diese Protokollierung:

• minLogEvents bestimmt, ab welchem messageLevel ein Ereignis protokolliert wird. Verglichen wird entlang der Rangfolge info $\lt$ action $\lt$ service $\lt$ warning $\lt$ alarm $\lt$ error $\lt$ fatal. Der Wert none schaltet die Protokollierung vollständig ab. Groß-/Kleinschreibung ist gleichgültig, critical wird als Synonym für error akzeptiert.
• logReleased entscheidet, ob auch das Ende eines Alarms protokolliert wird. Mit false (Default) erscheint nur sein Auftreten.

Eine protokollierte Zeile hat diese Form:

Message[ "Pumpe.Druck" , "Hydraulik" ] ALARM RAISED, ts: 1759395881.400, uuid: ab6ffc2f-…: Druck zu hoch: 214 bar

Sie nennt den überwachten Kanal, den context der Meldung, den Schweregrad, die Richtung (RAISED oder RELEASED), den Ereigniszeitpunkt und — sofern die Meldung in der Alarmdatenbank angelegt werden konnte — deren UUID. Über diese UUID lässt sich die Logzeile der Meldung in der Datenbank und in der Cloud eindeutig zuordnen. Danach folgt der fertig ausgefüllte Meldungstext.

Der Schweregrad der Logzeile folgt dem Schweregrad der Meldung: alarm, error und fatal erscheinen als ERROR, warning als WARNING, alle übrigen als INFO. Das Ende eines Alarms wird immer als INFO protokolliert — eine Entwarnung ist keine Warnung, wie laut der Alarm selbst auch war.

hinweis

Ein bereits anstehender und erneut bestätigter Alarm wird nicht noch einmal protokolliert. Andernfalls würde eine einzige dauerhaft anstehende Bedingung die Logdatei mit jedem Verarbeitungsintervall um eine Zeile verlängern.

vorsicht

Mit logReleased: false ist in der Logdatei nicht zu erkennen, ob ein Alarm noch ansteht. Eine zwischen Auftreten und Ende pendelnde Bedingung sieht dann aus wie eine Folge immer neuer Alarme. Für die Beurteilung eines schwingenden Signals gehört logReleased auf true.

Diagnoseausgabe des Moduls "debugMask"

Der globale Parameter debugMask schaltet einzelne Diagnoseausgaben des Moduls frei. Jedes Bit steht für eine Art von Ausgabe, so dass sich eine Frage stellen lässt, ohne dass die Antwort in den übrigen zwölf untergeht. Default ist 0: das Modul gibt nichts aus, was es nicht ohnehin zu beanstanden hat.

Bit	Ausgabe
0x00000001	Welche Überwachung auf welchem Quellkanal liegt, mit dessen Datentyp und Einheit
0x00000002	Die aus globalen und lokalen Angaben zusammengeführten Metadaten je Überwachung
0x00000004	Der Verarbeitungszyklus: Zeitstempel und bediente Überwachungen
0x00000008	Der Weg einer Alarmmeldung durch das Modul, verfolgbar an ihrer internen Id
0x00000100	Snapshot: die aufgelösten Gruppen und die globale Kanalliste
0x00000200	Snapshot: je Meldung der Index, die beteiligten Kanäle und das Zeitfenster
0x00000400	Snapshot: die erfassten Werte selbst
0x00000800	Snapshot: Kanäle ohne Daten im Zeitfenster sowie das Überschreiten der Wartezeit
0x00010000	ErrorCode: jeder eingehende Fehlercode mit seinem Zeitstempel
0x00020000	ErrorCode: die Einstufung eines Codes — Level und resultierender Zustand
0x00040000	ErrorCode: welche Meldung welche Codes abgeholt hat und wieviele unverarbeitet bleiben
0x00080000	ErrorCode: Codes, die von keiner Meldung abgeholt wurden
0x00100000	Error-Table: der Zustand des Transferkanals und seine Zeitüberschreitung

Die Maske wird als JSON-Zahl oder als Zeichenkette entgegengenommen. Als Zeichenkette ist jede im smartCORE übliche Schreibweise zulässig, auch mit ' als Tausendertrenner:

"debugMask": 66048
"debugMask": "0x00010200"
"debugMask": "0b0000'0001'0000'0010'0000'0000"
"debugMask": "10200h"
"debugMask": "~0"

Negative Werte, Nachkommastellen und zu breite Werte werden abgewiesen; die Maske bleibt dann auf 0 und das Modul schreibt eine Warnung in die Logdatei.

warnung

Die Diagnoseausgabe ist für Entwicklung und Fehlersuche gedacht und ausschließlich für den kurzzeitigen Betrieb unter Aufsicht.

Mehrere der Bits schreiben eine Zeile je Abtastwert oder je Verarbeitungszyklus. Auf einem schnellen Kanal wächst die Logdatei damit um ein Vielfaches ihres gewohnten Umfangs — auf einem Gerät mit SD-Karte ist das nicht nur eine Frage des Platzes, sondern auch der Lebensdauer des Speichermediums. Die Ausgaben erscheinen als DEBUG-Zeilen.

Die Maske gehört deshalb gezielt gesetzt — nur die Bits, die zur offenen Frage gehören — und nach der Messung wieder entfernt. In einer Konfiguration, die dauerhaft im Feld läuft, hat debugMask nichts zu suchen.

Konfiguration der Alarmmeldungen "messages"

Die Alarmmeldungen "messages" werden in Form von JSON Objekten und je nach Art der Überwachung unterschiedlich konfiguriert.

important

Über die Auswahl der Parameter wird bestimmt, welche Art der Überwachung ausgeführt wird. Die folgende Tabelle fasst dies zusammen. Sobald ein genannter Parameter verwendet wird, wird die entsprechende Funktion aktiviert:

Überwachung als...	Parameter zur Aktivierung	Erforderlich	Weitere empfohlene Parameter	Bemerkung
ErrorCode	isTemplate errorCode	Nein Nein		Ignoriert channelName, da Datenquelle Error-Stream/-Table, activation := HIGH Keine Filterfunktion
Double	threshold boundary6 hysteresis	Ja (veraltet) Ja	channel activation stabilizationSecondsRaise stabilizationSecondsRelease	Hysteresis ist immer $\gt 0.0$
Integer	startBit numberOfBits valuesWhite valuesBlack valuesHigh valuesLow	Nein Nein Nein Nein Empfohlen Empfohlen	channel activation stabilizationSecondsRaise stabilizationSecondsRelease	Mit numberOfBits == 1 wird das ausgewählte Bit wie im Mode Boolean behandelt.
String	regxWhite regxBlack regxHigh regxLow	Nein Nein Empfohlen Empfohlen	channel activation stabilizationSecondsRaise stabilizationSecondsRelease	Wenn regxWhite Subexpressions definiert, werden diese für alle nachfolgenden Tests extrahiert und mit ';' verbunden.
Boolean			channel activation stabilizationSecondsRaise stabilizationSecondsRelease

Gemeinsame Konfigurationsparameter

Unabhängig vom Typ der Überwachung sind folgende Parameter für Messages definiert:

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
messageLevel	JA	STRING	info, action, service, warning, alarm, error, fatal	KEIN Default-Wert	Schweregrad der Alarmmeldung
context	JA	STRING			Kontext der Alarmmeldung Statischer Text zur Identifiaktion einer Meldung
channel	JA/Nein7	STRING			Name des überwachten smartCORE Kanals
activation	JA	STRING	low, high, minimum, maximum, positiveEdge, negativeEdge, enumCode	high	Art der Alarmaktivierung.
messageEvent	Nein	STRING			Alarmmeldung, wenn Alarm ausgelöst wird. Es können Platzhalter für dynmische Meldungsinhalte verwendet werden.
needAcknowledge	Nein	BOOLEAN	false, true	false	ist eine Quittierung auf Cloud-Seite erforderlich
keepAcknowledgedStatus	Nein	BOOLEAN	false, true	false	soll quittierter Status beibehalten werden
metadata	Nein	JSON Object		EMPTY JSON Object	Benutzerdefinierte Metadaten, die die globalen Metadaten potentiell überschreiben können
snapshot	Nein	JSON Array of STRING		EMPTY JSON Array	während des initialen Auftretens der Alarmbedingung zu erfassende Kanäle. Es wird der globale Snapshot "globalSnapshot" mit den hier spezifizierten und aufgelösten Snapshot-Gruppen (aus "snapshotGroups") sowie hier individuell spezifizierten Kanälen vereinigt.
debugMask1	Nein	INTEGER | STRING	Bitmaske	0	Schaltet einzelne Diagnoseausgaben dieser einen Überwachung frei. Nur für Entwicklung und Fehlersuche
					Sofern die Filterfunktion verfügbar ist:
stabilizationSecondsRaise	Nein	INTEGER	1 -	0	Stabilisierungsverzögerung, nach der der Alarm ausgelöst werden soll (es wird der initiale Zeitpunkt des ersten Auftretens der Alarmbedingung gemeldet)
stabilizationSecondsRelease	Nein	INTEGER	1 -	0	Stabilisierungsverzögerung, nach der der Alarm deaktiviert werden soll (es wird der initiale Zeitpunkt des ersten Auftretens der Deaktivierungsbedingung gemeldet)
					Sofern ein Fehlerereignis ausgelöst werden kann:
messageFailure	Nein	STRING			Alarmmeldung, wenn Alarmierungsbedingung ungültig ist. Es können Platzhalter für dynmische Meldungsinhalte verwendet werden.

Konfiguration der Aktivierung: activation

Folgende Werte sind für die Alarmaktivierung wählbar:

Enum-Wert	Aliase	Bedeutung	Bemerkung
low		Auslösung solange Quelle LOW liefert	Mode Double überwacht auf Minimum
high, (Default)		Auslösung solange Quelle HIGH liefert	Mode Double überwacht auf Maximum
minimum	min	Auslösung solange Quelle LOW liefert mit Updates	Mode Double überwacht auf Minimum mit Aktualisierung
maximum	max	Auslösung solange Quelle HIGH liefert mit Updates	Mode Double überwacht auf Maximum mit Aktualisierung
negativeEdge	negEdge	Wechsel von HIGH->LOW löst aus	Meldung als zustandsloses Ereignis8
positiveEdge	posEdge	Wechsel von LOW->HIGH löst aus	Meldung als zustandsloses Ereignis8
enumCode	enum	Auslösung solange Quelle HIGH liefert mit Updates	Modes Integer/String aktualisieren jeweils für den neuen Fehlercode

Platzhalter für Meldungstexte

In den Meldungstexten messageEvent, messageFailure können folgende Platzhalter verwendet werden, um dynamisch den Text mit jedem Event oder jeder Aktualisierung durch aktuelle Werte zu ergänzen. Im Falle von templated-Errorcode-Messages können bestimmte Platzhalter auch in context ersetzt werden, wenn der Fehlercode zum ersten Mal registreiert wird.

Platzhalter	ersetzt durch	Beispiel
${channel}	Kanalname der Message	someChannelName
${unit}	Physikalische Einheit des Kanals	°C
${value}9	Der aktuelle Datenwert des Kanals	3.14159
${date}	Das Datum des Ereignisses, YYYY-MM-DD	2026-12-31
${time}	Die Uhrzeit des Ereignisses, hh:mm:ss	18:05:27
${errorCode}10	Der auslösende Fehlercode	ERR:243:881
${errorLevel}10	Der auslösende Fehler-Level	8
${boundary}11 ${raiseBoundary}11	Eingestellter Grenzwert zur Aktivierung threshold	10.0
${releaseBoundary}11	Grenzwert zur Deaktivierung threshold $\pm$ hysteresis	8.5
${minmax}11	Letzter Extremwert seit Ereignis oder falls nicht ermittelt:	17.9 (n.a.)
${minmaxDate}11	Datum des Extremwerts oder falls nicht zugewiesen:	2026-12-31 (n.a.)
${minmaxTime}11	Uhrzeit des Extremwerts oder falls nicht zugewiesen:	18:12:35 (n.a.)

Alle anderen und eventuell nicht verfügabre Platzhalter ${...} werden durch "(n.d.)" ersetzt.

Diagnoseausgabe einer Überwachung "debugMask"

Die globale debugMask beantwortet die Frage, was das Modul tut. Die gleichnamige Maske in einem Eintrag von messages beantwortet die Frage, was eine einzelne Überwachung tut — die Spur eines Verdächtigen, ohne dass die übrigen zwanzig mitschreiben. Die beiden Masken sind voneinander unabhängig und haben eigene Bits; Default ist auch hier 0.

Bit	Ausgabe
0x00000001	Jeder verarbeitete Abtastwert mit Zeitstempel, Aktivierungszustand und Aktualisierungskennzeichen
0x00000002	Das Ergebnis der Aktivierungsauswertung
0x00000004	Die Zustandswechsel des Stabilisierungsfilters
0x00000008	Der Filterzyklus ohne neue Daten — die Stabilisierung läuft auch ohne Abtastwerte weiter
0x00000010	Die Entscheidung, eine erneut auftretende Bedingung als Fortbestehen zu werten
0x00000020	Der Fehlerzustand einer Überwachung und dessen automatische Rücknahme
0x00000040	Ob die Meldung mit oder ohne gespeicherten Zustand geführt wird
0x00000080	Der fertige Meldungstext nach dem Einsetzen der Platzhalter
0x00000100	Die Ausgangswarteschlange der Meldungen: eingestellt, entnommen, Länge
0x00000200	Der Snapshot dieser Meldung: angeforderter Index und Rückgabe
0x00010000	Der Quellkanal: jeder Lesevorgang des Kanalzugriffs
0x00020000	Der Quellkanal: Prüfung der Zeitstempel auf stetiges Fortschreiten

Die Maske akzeptiert dieselben Schreibweisen wie die globale Maske.

hinweis

Die beiden letzten Bits werden nicht von der Überwachung selbst ausgewertet, sondern an den Kanalzugriff ihres Quellkanals weitergereicht. Dieser Zugriff wird von allen Überwachungen desselben Kanals gemeinsam genutzt — die beiden Bits sprechen also für den Kanal, nicht für die einzelne Meldung.

warnung

Es gilt dieselbe Einschränkung wie für die globale Maske: Diagnoseausgabe nur kurzzeitig und unter Aufsicht. Bit 0x00000001 schreibt eine Zeile je Abtastwert — auf einem Kanal mit 1 kHz sind das 3,6 Millionen Zeilen pro Stunde. Für die Frage, was gemeldet wurde, ist Bit 0x00000080 die richtige Wahl: es schreibt einmal je Ereignis statt einmal je Abtastwert.

Kanalwertüberwachung als Boolean

Die Überwachung als Boolean-Wert wird eingerichtet, wenn keine individuellen Parameter in dem Messages-Objekt hinzugefügt werden. Der Kanal liefert direkt die Werte true (HIGH) und false (LOW). Der Parameter activation bestimmt, mit welchem Pegel oder mit welcher Flanke die Meldung ausgelöst wird.

Kanalwertüberwachung als Double

Im Rahmen der numerischen Wertüberwachung eines smartCORE Kanals wird das Konfigurationsobjekt in messages durch die Parameter threshold oder hysteresis ergänzt. Der Parameter activation bestimmt, ob die Grenze threshold als Minimum oder Maximum zu lesen ist und demnach die hysteresis als Rückschaltung in den unkritischen Bereich unterhalb oder oberhalb der Grenze liegen muss.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
threshold boundary6	JA	FLOAT		0	Schwellwert, dessen Überschreitung bzw. Unterschreitung zur initialen Erfüllung der Alarmbedingung führt
hysteresis	JA	FLOAT	low, high, minimum, maximum	0.5	Zone unterhalb/oberhalb des Grenzwerts, in der der letzte Zustand beibehalten wird.
activation	JA	STRING	low, high, minimum, maximum	HIGH	Legt fest, ob der Grenzwert als Minimum oder Maximum gelesen werden soll und ob ein Tracking des Extremwerts mit erneuter Signalisierung erfolgen soll.

Kanalwertüberwachung als Integer

Wird das Konfigurationsobjekt in messages durch mindestens einen der folgenden individuellen Parameter ergänzt, wird der zu überwachende Kanal als <integer> gelesen. Optional kann aus diesem Wert eine Bitgruppe mit einstellbarer Länge zur weiteren Verarbeitung extrahiert werden. Dieser Wert wird als Statuscode oder ENUM-Wert gefiltert und interpretiert:

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
startBit	Nein	INTEGER	0..63	0	Definiert eine Rechtsverschiebung des Integer-Werts vor der Analyse.
numberOfBits	Nein	INTEGER	1..64 0: keine Maskierung	0	Maskiert entsprechend viele Bits aus dem Statuswort für die Analyse. Der maskierte Wert ist für numberOfBits $\lt 64$ vorzeichenlos. Falls numberOfBits == 1, erfolgt die weitere Verarbeitung des Bits als Boolean.
valuesWhite	Nein	STRING12		(leer)	Zulässige Wertebereiche für die Analyse, nicht enthaltene Werte werden ignoriert.
valuesBlack	Nein	STRING12		(leer)	Nicht zulässige Wertebereiche für die Analyse, enthaltene Werte werden ignoriert.
valuesLow	WAHLWEISE	STRING12		(leer)	Spezifikation der Wertebereiche, die einer deaktivierten Alarmbedingung korrespondieren
valuesHigh	WAHLWEISE	STRING12		(leer)	Spezifikation der Wertebereiche, die einer ausgelösten Alarmbedingung korrespondieren
activation	JA	STRING	high enum	HIGH	Art der Alarmaktivierung

Bevor die Werte des Kanals einer Auswertung zugeführt werden, können sie optional über die White- bzw. Black-Liste gefiltert werden. Es werden nur Werte verarbeitet, die in der valuesWhite Liste enthalten sind. Es werden alle Werte ingnoriert, die in der valuesBlack Liste ausgeschlossen werden.

Es können wahlweise eine bzw. beide der o.g. Wertebereichsspezifikationen valuesLow bzw. valuesHigh verwendet werden. Wird lediglich eine Spezifikation verwendet, z.B. valuesHigh, werden alle anderen Werte automatisch dem Gegenteil zugeordnet, hier z.B. LOW. Werden hingegen beide Spezifikationen verwendet, so entsprechen die nicht abgedeckten Wertebereiche einer ungültigen Alarmbedingung. Hierfür kann eine ungültige Alarmmeldung mit dem Text messageFailure spezifiziert werden.

Kanalwertüberwachung als String

Wird das Konfigurationsobjekt in messages durch mindestens einen der folgenden individuellen Parameter ergänzt, wird der zu überwachende Kanal als <string> (Text), z.B. als Logbucheintrag eines Subsystems, interpretiert:

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
regxWhite	Nein	STRING13		(leer)	Regulärer Ausdruck der zulässige Texte und Formatierungen prüft.
regxBlack	Nein	STRING13		(leer)	Regulärer Ausdruck, der zu ignorierende Texte bestimmt.
regxLow	WAHLWEISE	STRING13		(leer)	Regulärer Ausdruck, der den Zustand LOW beschreibt
regxHigh	WAHLWEISE	STRING13		(leer)	Regulärer Ausdruck, der den Zustand HIGH beschreibt
activation	JA	STRING	high enum	HIGH	Art der Alarmaktivierung

Bevor die Werte des Kanals einer Auswertung zugeführt werden, können sie optional über die White- bzw. Black-Ausdrücke gefiltert werden. Es werden nur Texte verarbeitet, die dem regxWhite Ausdruck entsprechen. Es werden alle Werte ingnoriert, die dem regxBlack Ausdruck entsprechen.

Wenn regxWhite Unterausdrücke (Terme in (...)) enthält, werden diese bei Übereinstimmung extrahiert und für alle nachfolgenden Analysen durch ';' miteinander verbunden. Dies vereinfacht die weitere Interpretation, da die Kern-Elemente bereits aus dem oft komplexen Kontext herausgelöst sind.

Beispiel:

"regxWhite": "Level:([A-Z]+),\\s+(.*)$"
"regxHigh" : "(ERROR|WARNING);"

Extrahiert aus einer Logbuch-Zeile:

2345987.3256346, abcDevice, Level:ERROR, Here some message!

die Elemente "ERROR" und "Here some message!". Die weitere Prüfung erfolgt für den Text "ERROR;Here some message!". regxHigh kann nun einfach auf die zwei zulässigen Fehlercodes prüfen.

Es können wahlweise eine bzw. beide der o.g. Ausdrücke regxLow bzw. regxHigh verwendet werden. Wird lediglich ein Ausdruck verwendet, z.B. regxHigh, werden alle anderen Werte automatisch dem Gegenteil zugeordnet, hier z.B. LOW. Werden hingegen beide Ausdrücke verwendet, so entsprechen die nicht abgedeckten Muster einer ungültigen Alarmbedingung. Hierfür kann eine ungültige Alarmmeldung mit dem Text messageFailure spezifiziert werden.

Überwachung von Fehlercodes: ErrorCode

Geräte, die Anlagen oder Anlagenteile steuern, können ihre Fehlerzustände in verschiedenen Formen nach außen kommunizieren:

1. In Form von einzelnen Codes die jeweils mit dem Status "Kommt" oder "Geht" kombiniert sind

2. In Form vollständig übertragener Fehler-Code-Tabellen (Fehlerspeicher) der noch anstehenden Codes. Hier ist durch Beobachtung zu ermitteln, welche einzelnen Codes "kommen" (neu hinzugekommen sind) oder "gehen" (nicht mehr enthalten sind). Die Übertragung der Tabelle wird durch ein Steuersignal angezeigt oder durch einen Timeout nach dem letzten Fehlercode abgeschlossen.

Das Beispiel im folgenden Diagramm zeigt dies für die Fehlercodes 17, 42, B7 und E8. Für maximal mögliche Flexibilität werden die Codes auf dem Kanal sourceErrorCodes immer als <string> gelesen und verarbeitet.

Das Diagnostics-Modul liest zentral die Kanäle

1. sourceErrorCode und sourceErrorLevel, um einen Error-Stream zu interpretieren oder

2. sourceErrorCode und sourceBufferTransfer, um die Übertragung von Fehler-Code-Tabellen zu verfolgen.

important

Für diese Kanäle dürfen keine Datenreduktions-Filter an der Quelle konfiguriert werden. Die Zeitstempel spielen zur Lokalisierung und Synchronisation der Daten eine entscheidende Rolle!

Grundsätzlich ist der Zeitstempel des Fehler-Codes im Kanal sourceErrorCode für die Interpretation ausschlaggebend. Der Kanal sourceErrorLevel muss mit exakt identischen Zeitstempeln den zugehörenden Level liefern. Er wird als <integer> gelesen und gegen den neutralErrorLevel ("geht") verglichen, um den Aktivierungszustand zu bestimmen.

Der Pegel des Kanals sourceBufferTransfer muss spätestens mit dem ersten Fehler-Code einer Tabelle auf true wechseln und muss nach dem letzten Code der Tabelle wieder auf false zurück fallen. Die Übertragungsrate oder Reihenfolge der Fehler-Codes spielt keine Rolle. Alternativ zum Steuerkanal kann auch ein Zeitintervall timeoutBufferTransfer verwendet werden. Die die Übertragung der Tabelle wird als vollständig angesehen, wenn in diesem Intervall nach dem vermeintlich letzten ErrorCode keine weiteren ErrorCodes eintreffen.

Wird das Konfigurationsobjekt in messages durch mindestens einen der folgenden individuellen Parameter ergänzt, greifen die entsprechenden "messages" auf diese Fehlercodes in der Reihenfolge der Definition zu. Dabei kann ein bestimmter Fehler-Code beobachtet und gemeldet werden oder als Template eine Gruppe von Codes oder schlicht sämtliche (verbleibende) Codes. Für jeden individuellen Code wird automatisch eine eigene Alarm-Meldung angelegt, die den Kommt/Geht-Zustand nachführt. Text-Bausteine können verwendet werden, um den Kontext initial und Meldungstexte dynamisch zu konfigurieren.

Parametername	Erforderlich	Datentyp	sinnvoller Wertebereich	Default-Wert	Beschreibung
errorCode	WAHLWEISE	STRING		(leer)	Fehlercode, der von dieser Überwachungseinheit überwacht wird, ggf. als WildMask-Text, falls isTemplate gesetzt ist. (leer) entspricht "*"
isTemplate	WAHLWEISE	BOOLEAN	false, true	false	Wird gesetzt, wenn dieser Message-Eintrag automatisch für passende Error-Codes dynamisch Meldungseinträge generieren soll.

Modul-Informationen

Information	Wert
Autoren	optiMEAS GmbH
seit smartCORE	2.6
Modultyp	Consumer
Abhängigkeiten	KEINE

Footnotes

1. Ab smartCORE 2.12 verfügbar. ↩ ↩² ↩³ ↩⁴

2. Vor smartCORE 2.10.1 wurde activationMode verwendet, um zwischen Kanalüberwachung und Error-Stream-Betriebsart umzuschalten. Dies ist ab 2.10.1 nicht mehr notwendig, der Parameter wird ignoriert. ↩

3. Um die Error-Stream Funktion zu nutzen, sind diese Parameter zwingend anzugeben. ↩ ↩² ↩³

4. Um die Error-Table Funktion zu nutzen, sind diese Parameter zwingend anzugeben. ↩ ↩² ↩³

5. Vor smartCORE 2.10.1 wurde neutraErrorCode verwendet, obwohl sich der Wert auf den ErrorLevel-Kanal bezieht. Der Parameter wird zwar noch eingelesen, sollte aber nicht mehr verwendet werden. ↩

6. An vielen Stellen wird "threshold" als Grenzwert verwendet, so jetzt auch hier. Der Parameter boundary wird für threshold noch eingelesen, sollte aber nicht mehr verwendet werden. ↩ ↩²

7. Wenn die Message in der Betriebsart Error-Stream oder Error-Table konfiguriert wird, wird die interne Datenquelle im Diagnostics Modul verwendet und der Kanal ignoriert. ↩

8. Es wird eine Alarm-Meldung generiert, die nur den Ereigniszeitpunkt enthält - kein "Kommt"/"Geht". ↩ ↩²

9. Im Falle von Integer-Meldungen ist dies ggf. der aus dem eigentlichen Kanalwert extrahierte bit-Bereich. Im Falle von String ist dies ggf. der zusammengestze Text aus Unterausdrücken. ↩

10. nur in Verbindung mit ErrorCode ↩ ↩²

11. nur in Verbindung mit Double ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

12. Enthält als String eine durch Komma separierte Liste von einzelnen <integer>-Werten oder Wertebereiche der Form <integer> - <integer>. Leerzeichen werden ignoriert, Vorzeichen sind zulässig. Beispiel: "-100, -20 - -5, 12 - 34,47,55-57" ↩ ↩² ↩³ ↩⁴

13. Hier wird ein Regular Expression (PCRE) erwartet, dessen Steuerzeichen korrekt escaped werden müssen. Die Ausdrücke werden ohne Unterscheidung von Groß-/Kleinschreibung angewendet (case insensitive). ↩ ↩² ↩³ ↩⁴