Hilfsfunktionen

Systemfunktionen

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

Verbingsstatus 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.

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 auf einen beliebigen Wert und Typ eingestellt werden.

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

important

Das Argument der Funktion muss unmittelbar eine Eingangsvariable sein.

Verbingsstatus 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.

Wenn der #timeless-Mode aktiviert ist, wird der "empty" Zustand sofort zum Startzeitpunkt signalisiert. Im Übrigen tritt er erst nach Ablauf der Timeout-Phase inputTimeoutS mit entsprechendem Zeitversatz auf.

Mit Signalisierung des empty-Zustands wird der default-Wert als Startwert in die Variable des Math Modul geschrieben und verlängert, bis die ersten Datensätze im smartCORE-Kanal produziert werden. Dadurch können von der Variable abhängige Rechnungen bereits ausgeführt werden. Der default-Wert ist zunächst false, kann aber über das #property-Macro auf einen beliebigen Wert und Typ eingestellt werden.

s1 = isEmpty(x);
s2 = isEmpty($'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.

Datenlücke abfragen "isTimeout" ¹

Die Funktion liefert true, wenn das jüngste Sample im smartCORE Eingangssignal älter als inputTimeoutS ist 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.

Solange der timeout-Status besteht, wird der jüngste Wert der Variable in seiner Gültigkeit verlängert. Er läuft dann um inputTimeoutS 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 Zeitstemepl visualisiert oder verwendet werden, also z.B. in den MQTT Live-Daten, nicht aber in den OSF-Datein.

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

important

Das Argument der Funktion muss unmittelbar eine Eingangsvariable sein.

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

Zeitumwandlung "decodeTime"

Die Funktion decodeTime() nimmt einen skalaren Zeitstempel t in UTC und wandelt ihn mit dem optionalen Offset tzDif zur lokalen Uhrzeit in die zugehörige Datum und Zeitdarstellung um. Verschiedene Interpretationen und Ausgabeformate können eingestellt werden.

TM1 = decodeTime(t);
TM2 = decodeTime(t, tzDif);
// Optionale Konfiguration
TMx = decodeTime(..., { scale: <enum>
                      , epoch: unix|<date>
                      , tzDif: <int>
                      , format: <str> 
                      });

Eigenschaft	Wert	Beschreibung
scale	<enum>	Bestimmt, was der ganzzahlige Anteil des Zeitstempels beschreibt: auto: Größenordnung des Zeitstempels bestimmen die Auflösung (def.), oder der ganzzahlige Teil von t zählt... d: ... Tage s: ... Sekunden ms: ... Millisekunden us: ... Microsekunden ns: ... Nanosekunden
epoch	unix/<date>	Der Startzeitpunkt der Zählung wird auf das gegebene UTC Datum festgelegt, Format: 'yyyy-mm-dd', optional mit Zeitangabe 'yyyy-mm-dd  HH:MM' (def.: unix 1970-01-01)
tzDif	<int>	Zeitversatz in Minuten zur Ausgabe der lokalen Zeit, Beispiel MEZ: +60, MESZ: +120, EST: -300
format	<str>	Statt eines Vektors wird ein formatierter Datum/Zeit-String ausgegeben. Die Funktion verwendet intern die c++ Funktion strftime(). Die Formatierung der Ausgabe ist hier beschrieben. Zusätzlich können folgende Platzhalter verwendet werden: %FMS: 3-Ziffern milli-Sekunden %FUS: 6-Ziffern micro-Sekunden %FNS: 9-Ziffern nano-Sekunden jeweils mit führenden Nullen

Sofern nicht mit der Eigenschaft format die Ausgabe eines formatierten Datum-Zeit-Textes angefordert wird, ist das Ergebnis ein Vektor mit folgenden <uint> Werten:

// Rückgabe der Datums-Zeit-Information als Vektor entsprechend
// folgendem Inhalt:
TM = [ year, month, day
     , hour, minute, second, nanoseconds
     , weekday                  // 0..6, 0 := Sunday
     , yearday];

Eigenschaften eines 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)

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. ↩ ↩² ↩³ ↩⁴ ↩⁵