Hilfsfunktionen

Systemfunktionen

Funktion	Beschreibung
time()	Liefert den Auswertezeitpunkt des Moduls in Sekunden UTC

Eigenschaften eines Kanals oder Wertes

Funktion	Beschreibung
deltaT(x)	Liefert den zeitlichen Abstand der letzten zwei Auswertezeitpunkte des Terms x in Sekunden
deltaY(x)	Liefert die Wertedifferenz der letzten zwei Samples des Terms x, ist positiv bei ansteigendem Signalverlauf
time(x)	Liefert den Zeitpunkt des letzten, geänderten Datensamples des Terms x
sgn(x)	Vorzeichen des Wertes x $-1: x < 0$ $+1: x > 0$ $\enspace0:sonst$
sgn(x,eps)	Vorzeichen des Wertes x mit Toleranz $\epsilon$ (eps) $-1: x < -\epsilon$ $+1: x > \epsilon$ $\enspace0:sonst$
abs(x)	Absolutbetrag vom skalaren Wert x, Für die Länge eines Vektors siehe Length(V)
isConnected(x)	SmartCORE Verbindung abfragen
isEmpty(x)	Status der Datenquelle abfragen
isTimeout(x)	Datenlücke abfragen
isDefault(x)	Kanal auf Ersatzwert abfragen
isError(x)	Fehlerzustand eines Ergebnisses abfragen
typeOf(x)	Datentyp abfragen
value(x, ...)	Werte eines Kanals zeitlos abfragen
shiftT(x,dT)	Zeitliche Verschiebung von Kanaldaten

SmartCORE Verbindung abfragen "isConnected" ¹

Die Funktion liefert true, wenn der Kanal als Eingang mit einem smartCORE-Kanal erfolgreich verbunden wurde.

Wenn beim Start des smartCORE und des Math Modul kein smartCORE Kanal gefunden werden kann, wird dies nicht nur im Log-File ausgegeben, sondern auch über diesen Status signalisiert (false).

In diesem Fall wird der default Wert als Konstante in die Variable geschrieben, sodass Rechnungen ausgeführt werden können. Dieser ist zunächst false, kann aber über das #property-Macro mittels default=<variant> auf jeden beliebigen, konstanten Wert und Typ eingestellt werden. Siehe auch isDefault().

Die Abfrage liefert den Status für das laufende Batch-Intervall.

s1 = isConnected(x);
s2 = isConnected($'other.y');

important

Das Argument der Funktion muss unmittelbar eine Eingangsvariable sein.

Status der Datenquelle abfragen "isEmpty" ¹

Die Funktion liefert true, wenn beim Start des smartCORE und des Math Modul noch keine Daten in den smartCORE Eingangskanal produziert wurden. Dies kann passieren, wenn andere Datenquellen erst nach einer Initialisierungsphase oder einem länger andauernden Aufbau einer Datenverbindung Daten produzieren können.

Tritt bei anhaltend leerem Kanal zusätzlich die Timeout-Bedingung bezogen auf den Startzeitpunkt des Math Moduls auf und ist ein expliziter Default-Wert über das #property-Macro mit der Option default=<val> gesetzt, wird dieser vorübergehend bis zum Eintreffen des ersten Datensamples als Ersatzwert verwendet. Siehe auch isDefault().

Die Abfrage liefert den Status für das laufende Batch-Intervall und ist unabhängig von den Dateninhalten und Zeitstempeln des Kanals.

s1 = isEmpty(x);
s2 = isEmpty($'other.y');

important

Das Argument der Funktion muss unmittelbar eine Eingangsvariable sein.

Datenlücke abfragen "isTimeout" ¹

Die Funktion liefert true, wenn das jüngste Sample im smartCORE Eingangssignal älter als ist als ein einstellbares Timeout-Intervall und damit wahrscheinlich keine neuen Daten auf dem smartCORE Eingangssignal produziert wurden. Dies kann verschiedene Ursachen haben, wie z.B. das Ausbleiben einer CANbus-Botschaft, ein fehlendes GPS Signal oder eine fehlende Internet-Verbindung zur Abfrage von Steuerinformationen. Sobald neue Daten eintreffen, fällt der Status auf false zurück.

Für jeden Eingangskanal kann über das #property-Macro mit der Option timeout=<val> ein individueller Timeout-Wert zugewiesen werden. Dieser überschreibt für den Kanal die globale Einstellung mittels inputTimeoutS, die mit $15 s$ vorbelegt ist.

Tritt bei anhaltend leerem Kanal die Timeout-Bedingung bezogen auf den Startzeitpunkt des Math Moduls auf und ist ein expliziter Default-Wert über das #property-Macro mit der Option default=<val> gesetzt, wird dieser vorübergehend bis zum Eintreffen des ersten Datensamples als Ersatzwert verwendet. Siehe auch isDefault().

Sind bereits Datensamples im Kanal vorhanden, wird im timeout-Status der jüngste Wert der Variable in seiner Gültigkeit verlängert. Er läuft dann um das eingestelte Timeout-Intervall der aktuellen Ausführungszeit des Math Modul hinterher. Abhängige Berechnungen können dann bis zu diesem Zeitpunkt fortgeführt werden.

hinweis

Dieser Zeitversatz ist nur dort zu sehen, wo Daten ohne Zeitstempel visualisiert oder verwendet werden, also z.B. in den MQTT Live-Daten, nicht aber in den OSF-Datein.

Die Abfrage liefert den Status für das laufende Batch-Intervall und ist unabhängig von den Dateninhalten und Zeitstempeln des Kanals.

s1 = isTimeout(x);
s2 = isTimeout($'other.y');

important

Das Argument der Funktion muss unmittelbar eine Eingangsvariable sein.

Kanal auf Ersatzwert abfragen "isDefault" ²

Die Funktion liefert true, wenn der Kanal dauerhaft oder temporär auf einen Default-Ersatzwert gesetzt ist.

Für jeden Eingangskanal kann über das #property-Macro mit der Option default=<val> ein individueller, konstanter Default-Wert zugewiesen werden. Falls dieser nicht gesetzt ist, wird false (<bool> => 0, 0.0, "false") verwendet.

Der Default-Wert wird als konstanter Ersatzwert verwendet, wenn der Kanal nicht mit einem smartCORE Kanal verbunden werden konnte.

Der Default-Wert wird als vorrübergehender Ersatzwert verwendet, wenn

• der Kanal verbunden wurde isConnected()
• und der Kanal noch leer ist isEmpty()
• und der Kanal in den Timeout gelaufen ist isTimeout()
• und
  • explizit der Default-Wert über das #property-Macro gesetzt wurde
  • oder der Kanal als #timeless markiert wurde.

Die Abfrage liefert den Status für das laufende Batch-Intervall und ist unabhängig von den Dateninhalten und Zeitstempeln des Kanals.

s1 = isDefault(x);
s2 = isDefault($'other.y');

important

Das Argument der Funktion muss unmittelbar eine Eingangsvariable sein.

Fehlerzustand eines Ergebnisses abfragen "isError" ¹

Die Funktion liefert true, wenn die Auswertung eines Terms einen Laufzeitfehler erzeugt hat. Die Fehlermeldung wird bei der Ausgabe der Variablen an den smartCORE auch im Log-File abgelegt oder kann als String im Math Modul weiter verwendet werden.

res = ...;                                // some expression
use     = isError(res) ? 12.34 : res;   // use alternate value on error
errCode = isError(res) ? int(res) : 0;
errMsg  = isError(res) ? str(res) : 'ok';

hinweis

Die Verwendung einer (lokalen) Variable, um das Ergebnis wiederzuverwenden, ist empfehlenswert.

Datentyp abfragen "typeOf" ¹

Die Funktion typeOf liefert den Datentyp des übergebenen Wertes als ENUM Wert:

t = typeOf(x);

Der Werte haben folgende Entsprechung:

Wert	Datentyp
0	void
1	<bool>
2	<uint>
3	<int>
4	<dbl>
5	<cxFlt>
6	<str>
> 0x80000000	(Reserviert)
0x8000B10B	BLOB - Binäres Objekt, z.B. einer transition()
0x8000EBAD	ERROR - Laufzeitfehler eines Terms

Werte eines Kanals zeitlos abfragen "value" ²

Diese Funktion ermöglicht, an einer bestimmten Stelle der Berechnung die Zeitabhängigkeit eines Berechnungspfades ähnlich dem #timeless aufzulösen.

Dazu wird der letzte vor dem Batch-Intervall (evaluationTimeMs) verfügbare Wert als Startwert für das Intervall verwendet, dann alle Samples mit Zeitstempeln im Batch-Intervall kopiert und zum Schluss der letzte Wert bis zum Ende des Intervalls ausgedehnt. Falls als Argument ein leerer Kanal verwendet wird, kann explizit ein Ersatzwert angegeben werden.

Die Abfrage liefert Werte für das laufende Batch-Intervall und ist unabhängig von den Dateninhalten und Zeitstempeln des Kanals.

v1 = value(x);
v2 = value(x, def);      // use def, if isEmpty(x)

Typischerweise führt eine zirkuläre Referenz im Math Module zum Wechsel auf ein diskretes Abtastintervall (discreteSampleTimeMs) für den betroffenen Kanal, der dann auch mit einem explizitem Startwert (@0-Syntax) versehen sein muss:

zv@0 = 0;                      // startvalue for discrete calculation
zv   = a * zv + (1 - a) * x;   // example for circular use of 'zv'

tipp

Im Kontext von logischen Steuerungen, Statemachines, Grenzwertüberwachungen, etc. kann es sinnvoll sein, die Berechnungen zeitrichtig auszuführen und dennoch eine Rückführung eines Berechnungsergebnisses auf den Anfang der Berechnung zu nutzen. Die Funktion value() stellt genau die Stelle dar, an der die Rückführung lokal im Sinne von #timeless aufgebrochen wird.

vorsicht

Das Auflösen der Zeitabhängigkeiten führt an der entsprechenden Stelle zu einem Verhalten, das nicht mehr 100%ig vorhersehbar und definiert ist. Kurzzeitige Signaländerungen auf dem Eingangs-Term können übersehen werden oder Änderungen erst in einem späteren Batch-Intervall sichtbar werden. Die Auswirkungen der Funktion müssen vor einem produktiven Einsatz sorgfältig geprüft werden!

Zeitliche Verschiebung von Kanaldaten "shiftT" ²

Um einen Daten eines Kanals um eine bestimmtes ZeitinvervalldT zu verschieben, kann die Funktion shiftT() eingesetzt werden. Da eine Verschiebung und nachfolgend zeitrichtige Verrechnung mit anderen Daten immer zu einer Pufferung führt, sollte die Verschiebung auf wenige Sekunden begrenzt bleiben.

Zu allen Zeitstempeln der Daten des x-Terms wird das Zeitintervall dT in Sekunden addiert. Eine Verschiebung mit dT > 0.0 verschiebt die Daten in die Zukunft, dT < 0.0 in die Vergangenheit.

xs = shiftT(x, dT); 

tipp

Mit dieser Funktion können bekannte Zeitverzögerungen durch die Datenübertragung vom tatsächlichen Erfassungssystem (AD-Wandler, MicroController) eines analogen Signals bis zum Empfang und der Zeitstempelung der Daten im smartCORE ausgeglichen werden. Dies kann zum Ausgleich von Phasenverschiebungen insbesondere bei sehr hochfrequent abgetasteten Signalen sinnvoll sein.

Kenngrößen mehrerer Werte

Funktion	Beschreibung
abs(x1, ..., xN)	l2-Norm der Einzelwerte (x1, ..., xN), $= \sqrt{\sum_{i=1}^N x_i^2}$
min(x1, ..., xN)	Minimum der Einzelwerte (x1, ..., xN)
max(x1, ..., xN)	Maximum der Einzelwerte (x1, ..., xN)
mean(x1, ..., xN)	Arithmetischer Mittelwert der Einzelwerte (x1, ..., xN) $= \frac{1}{N} \sum_{i=1}^N x_i$
rms(x1, ..., xN)	Quadratwurzel des arithmetischen Mittelwerts der quadrierten Einzelwerte (x1, ..., xN) $= \sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}$

Begrenzen und Runden

Funktion	Beschreibung
range(x, ...)	Begrenzt den Eingangswert auf einen bestimmten Wertebereich. Siehe nachfolgende Beschreibung.
ceil(x)	kleinster ganzzahliger Wert $i >= x$ (datentyperhaltend)
ceil2i(x)	kleinster ganzzahliger Wert $i >= x$ (Rückgabetyp int)
floor(x)	größter ganzzahliger Wert $i <= x$ (datentyperhaltend)
floor2i(x)	größter ganzzahliger Wert $i <= x$ (Rückgabetyp int)
trunc(x)	falls $x >= 0$ dann größter ganzzahliger Wert $i <= x$, sonst kleinster ganzzahliger Wert $i >= x$
round(x)	ganzzahliger Wert $i$, so dass $x - 0.5 < i <= x + 0.5$ (datentyperhaltend)
round2i(x)	ganzzahliger Wert $i$, so dass $x - 0.5 < i <= x + 0.5$ (Rückgabetyp int)
nonZero(x, ...)	Folgt x, sofern $\|x-x_{crit}\| \ge \epsilon$, sonst wenn $x \ge x_{crit}$ wird $x_{crit}+\epsilon$ gesetzt, im Übrigen $x_{crit}-\epsilon$ Siehe nachfolgende Beschreibung.

Wertebereich "range"

Die Funktion schränkt den Wertebereich für ein gegebenes Eingangssignal x (Skalar oder Vektor) auf einen Bereich $[min, max]$ ein und bietet über die optionale Konfiguration vielfältige Varianten.

r1  = range(x);
r2  = range(x, [min, max]);        // bessere Lesbarkeit
r3  = range(x, min, max);          // nicht mehr verwenden
// Optionale Konfiguration für alle Varianten
rx  = range(..., { min: off|<val>
                 , max: off|<val>
                 , lower: off|<val>|erase
                 , upper: off|<val>|erase
                 , mode: <enum>
                 , defXY: [<dbl>, <dbl>]
                 , limVar: <str>
                 });

Eigenschaft	Wert	Beschreibung
min	off/<val>	Deaktivierung oder feste Konfiguration einer unteren (skalaren) Grenze. Wird der Funktionsparameter min genutzt, ist diese Eigenschaft ohne Funktion.
max	off/<val>	Deaktivierung oder feste Konfiguration einer oberen (skalaren) Grenze. Wird der Funktionsparameter max genutzt, ist diese Eigenschaft ohne Funktion.
lower	off/<val>/erase	Falls aktiviert, wird der Ersatzwert beim Überschreiten der unteren Grenze (x < min) ausgegeben oder das Sample entfernt
upper	off/<val>/erase	Falls aktiviert, wird der Ersatzwert beim Überschreiten der oberen Grenze (x > max) ausgegeben oder das Sample entfernt
mode	<enum>	Falls x ein Vektor ist, werden in Abhängigkeit von mode - box: alle Koordinaten einzeln… - length: die Länge des Vektors ( >= 0.0 )... - azimuth: der Winkel des Vektors in der XY-Ebene... - elevation: der Winkel des Vektors aus der XY-Ebene zur Z-Achse… ...auf den eingestellten Bereich $[min, max]$ limitiert
defXY	[<dbl>, <dbl>]	Im elevation-Mode ist defXY ist die Standardrichtung, wenn der Vektor aus der senkrechten zurückgeschwenkt werden muss (def.: [1, 0, 0]).
limVar	<str>	limVar definiert optional den Namen einer lokalen <bool>-Variable, um die aktive Limitierung zu signalisieren

Nicht-Null "nonZero"

Die Funktion sorgt dafür, dass ein kritischer Wert (def.: 0.0) niemals ausgegeben wird. Statt dessen wird der Wertebereich mittels eine Größe $\epsilon$ (def.: 1e-6) um die kritische Größe ausgespart. Die Anwendung der Funktion ist z.B. für Divisionen optimiert, bei denen eine Division durch Null möglich wäre und ausgeschlossen werden muss.

xnz1 = nonZero(x);                // eps := 1e-6, x_crit := 0.0
xnz2 = nonZero(x, eps);           // x_crit := 0.0
xnz3 = nonZero(x, eps, x_crit);

$$\rm{nonZero}(x) = \left\{ {\begin{array}{ll} {x:}&{\left| {x - {x_{crit}}} \right| \ge \varepsilon }\\ {{x_{crit}} + \varepsilon :}&{x \in [{x_{crit}},{x_{crit}} + \varepsilon [}\\ {{x_{crit}} - \varepsilon :}&{x \in ]{x_{crit}} - \varepsilon ,{x_{crit}}[} \end{array}} \right..$$

Ein Beispiel ist die sichere Umrechnung von Krafstoff-Volumenstrom in $l/h$ und Geschwindigkeit in $km/h$ in einen Verbrauch in $l/100km$:

consumption = volFlow / nonZero(speed, 0.1) * 100;

Schaltschwelle mit Hysterese "threshold"

Diese Funktion erzeugt ein Schaltsignal aus dem Vergleich eines Signals gegen einen festen Schwellenwert threshold. Mittels einer Hysterese hysteresis und Verzögerungszeiten delayOn, delayOff können Störungen auf dem Signalverlauf unterdrückt werden.

Die Funktion kann in verschiedenen Anwendungsformen verwendet werden:

trig1 = threshold(x);
trig2 = threshold(x, t);
trig3 = threshold(x, t, h);
// Optionale Konfiguration für alle Varianten
trigX = threshold(..., { threshold: <dbl>
                       , hysteresis: <dbl>
                       , delayOn: <dbl>
                       , delayOff: <dbl> 
                       , logic: <enum>
                       , startup: inf|<bool>
                       });

Eigenschaft	Wert	Bedeutung
threshold	<dbl>	Auslöseschwelle, def.: 0.55 Wird mit Argument t überschrieben
hysteresis	<dbl>	Breite der Hysteresezone, wird auf den threshold für den zweiten Grenzwert addiert, def.: -0.10 Wird mit Argument h überschrieben
delayOn	<dbl>	optionale Filterzeit in Sekunden für den Einschaltvorgang
delayOff	<dbl>	optionale Filterzeit in Sekunden für den Ausschaltvorgang
logic	<enum>	- auto: Funktion wird durch das Vorzeichen der Hysterese bestimmt - above: Auslösung oberhalb der Hysterese-Zone - below: Auslösung unterhalb der Hysterese-Zone
startup	inf|<bool>	Startverhalten: inf: Die Lage des ersten Samples bestimmt bezüglich des Thresholds den Ausgangswert (def.). <bool>: Es wird angenommen, dass dieser Ausgangswert vor dem ersten Sample ausgegeben wurde.

• Die Funktion liefert true für den Zeitpunkt, wo das Signal x die definierte Auslöseschwelle überschreitet und false für den Zeitpunkt, wo das Signal x in die Rückstellung fällt.

Werden die Verzögerungszeiten eingestellt, muss das Signal x kontinuierlich für das angegebene Intervall in der Auslösung oder Rückstellung verbleiben, bevor die Umschaltung realisiert wird. Die Umschaltung ist dadurch gegenüber dem Überschreiten des jeweiligen Grenzwertes verzögert.

In der Betriebsart auto (default) erfolgt die Auslösung in Abhängigkeit vom Vorzeichen der Hysterese:

Hysterese	Auslösung (true)	Rückstellung (false)
$hysterese < 0$	$x > threshold$	$x < threshold + hysteresis$
$hysterese > 0$	$x < threshold$	$x > threshold + hysteresis$

In den Betriebsarten above und below definieren threshold und hysteresis zwei Grenzen einer Hysterese-Zone:

$$g_{low} = min(threshold, threshold + hysteresis)$$ $$g_{high} = max(threshold, threshold + hysteresis)$$ $$zone = [g_{low}, g_{high}]$$

Betriebsart	Auslösung (true)	Rückstellung (false)
above	$x > g_{high}$	$x < g_{low}$
below	$x < g_{low}$	$x > g_{high}$

Footnotes

1. Ab Katalog Version 10 verfügbar. ↩ ↩² ↩³ ↩⁴ ↩⁵

2. Ab Katalog Version 11 verfügbar. ↩ ↩² ↩³