Help functions

System functions

Function	Description
time()	Returns the evaluation time of the module in seconds UTC

Query connection status "isConnected" ¹

The function returns true if the channel has been successfully connected as an input to a smartCORE channel.

If no smartCORE channel can be found when the smartCORE and Math Module are started, this is not only output in the log file, but also signaled via this status.

In this case, the default value is written to the variable as a constant so that calculations can be performed. This is initially false, but can be set to any value and type using the #property macro.

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

important

The argument of the function must be an input variable.

Query verb status "isEmpty" ¹

The function returns true if no data has been produced in the smartCORE input channel when the smartCORE and Math Module are started. This can happen if other data sources can only produce data after an initialization phase or a lengthy process of establishing a data connection.

If the #timeless mode is activated, the "empty" state is signaled immediately at startup. Otherwise, it only occurs after the timeout phase inputTimeoutS has expired with the corresponding time delay.

When the empty state is signaled, the default value is written to the Math module variable as the start value and extended until the first data records are produced in the smartCORE channel. This allows calculations dependent on the variable to be executed already. The default value is initially false, but can be set to any value and type using the #property macro.

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

important

The argument of the function must be an input variable.

Query the error status of a result "isError" ¹

The function returns true if the evaluation of a term has generated a runtime error. The error message is also stored in the log file when the variable is output to the smartCORE, or can be used as a string in the Math module.

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';

note

Using a (local) variable to reuse the result is recommended.

Query data gap "isTimeout" ¹

The function returns true if the most recent sample in the smartCORE input signal is older than inputTimeoutS and therefore no new data has likely been produced on the smartCORE input signal. This can have various causes, such as the absence of a CANbus message, a missing GPS signal, or a missing Internet connection for querying control information. As soon as new data arrives, the status reverts to false.

As long as the timeout status persists, the validity of the most recent value of the variable is extended. It then lags behind the current execution time of the Math module by inputTimeoutS. Dependent calculations can then be continued until this point in time.

note

This time offset can only be seen where data without a timestamp is visualized or used, e.g., in the MQTT live data, but not in the OSF files.

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

important

The argument of the function must be an input variable.

Query data type "typeOf" ¹

The typeOf function returns the data type of the passed value as an ENUM value:

t = typeOf(x);

The values have the following equivalents:

Value	Data type
0	void
1	<bool>
2	<uint>
3	<int>
4	<dbl>
5	<cxFlt>
6	<str>
> 0x80000000	(Reserved)
0x8000B10B	BLOB - Binary object, e.g., a transition()
0x8000EBAD	ERROR - Runtime error of a term

Time conversion "decodeTime"

The function decodeTime() takes a scalar timestamp t in UTC and converts it to the corresponding date and time representation using the optional offset tzDif to the local time. Various interpretations and output formats can be set.

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

Property	Value	Description
scale	<enum>	Determines what the integer part of the timestamp describes: auto: The order of magnitude of the timestamp determines the resolution (def.), or the integer part of t counts... d: ... days s: ... seconds ms: ... milliseconds us: ... microseconds ns: ... nanoseconds
epoch	unix/<date>	The start time of the count is set to the given UTC date, Format: 'yyyy-mm-dd', optionally with time specification 'yyyy-mm-dd HH:MM' (def.: unix 1970-01-01)
tzDif	<int>	Time offset in minutes for outputting local time, example CET: +60, CEST: +120, EST: -300
format	<str>	Instead of a vector, a formatted date/time string is output. The function uses the C++ function strftime() internally. The formatting of the output is described here. The following placeholders can also be used: %FMS: 3 digits milli-seconds %FUS: 6 digits micro-seconds %FNS: 9 digits nano-seconds each with leading zeros

Unless the output of a formatted date-time text is requested with the format property, the result is a vector with the following <uint> values:

// Return of the date-time information as a vector corresponding to
// the following content:
TM = [ year, month, day
     , hour, minute, second, nanoseconds
     , weekday                  // 0..6, 0 := Sunday
     , yearday];

Properties of a value

Function	Description
deltaT(x)	Returns the time interval between the last two evaluation points of term x in seconds
deltaY(x)	Returns the difference in value between the last two samples of term x; is positive for an increasing signal curve
time(x)	Returns the time of the last changed data sample of term x
sgn(x)	Sign of the value x $-1: x < 0$ $+1: x > 0$ $\enspace0:otherwise$
sgn(x,eps)	Sign of the value x with tolerance $\epsilon$ (eps) $-1: x < -\epsilon$ $+1: x > \epsilon$ $\enspace0:otherwise$
abs(x)	Absolute value of the scalar value x, For the length of a vector, see Length(V)

Parameters of multiple values

Function	Description
abs(x1, ..., xN)	l2-norm of the individual values (x1, ..., xN), $= \sqrt{\sum_{i=1}^N x_i^2}$
min(x1, ..., xN)	Minimum of the individual values (x1, ..., xN)
max(x1, ..., xN)	Maximum of the individual values (x1, ..., xN)
mean(x1, ..., xN)	Arithmetic mean of the individual values (x1, ..., xN) $= \frac{1}{N} \sum_{i=1}^N x_i$
rms(x1, ..., xN)	Square root of the arithmetic mean of the squared individual values (x1, ..., xN) $= \sqrt{\frac{1}{N}\sum_{i=1}^N x_i^2}$

Limiting and rounding

Function	Description
range(x, ...)	Limits the input value to a specific range of values. See description below.
ceil(x)	Smallest integer value $i >= x$ (preserving data type)
ceil2i(x)	smallest integer value $i >= x$ (return type int)
floor(x)	largest integer value $i <= x$ (data type preserved)
floor2i(x)	largest integer value $i <= x$ (return type int)
trunc(x)	if $x >= 0$, then largest integer value $i <= x$, otherwise smallest integer value $i >= x$
round(x)	integer value $i$ such that $x - 0.5 < i <= x + 0.5$ (preserving data type)
round2i(x)	integer value $i$ such that $x - 0.5 < i <= x + 0.5$ (return type int)
nonZero(x, ...)	Follows x if $\|x-x_{crit}\| \ge \epsilon$, otherwise if $x \ge x_{crit}$, $x_{crit}+\epsilon$ is set, otherwise $x_{crit}-\epsilon$ See description below.

Value range "range"

This function limits the value range for a given input signal x (scalar or vector) to a range $[min, max]$ and offers a wide range of options via optional configuration.

r1  = range(x);
r2  = range(x, [min, max]);        // better readability
r3  = range(x, min, max);          // no longer used
// Optional configuration for all variants
rx  = range(..., { min: off|<val>
                 , max: off|<val>
                 , lower: off|<val>|erase
                 , upper: off|<val|erase
                 , mode: <enum>
                 , defXY: [<dbl>, <dbl>]
                 , limVar: <str>
                 });

Property	Value	Description
min	off/<val>	Deactivation or fixed configuration of a lower (scalar) limit. If the function parameter min is used, this property has no function.
max	off/<val>	Deactivation or fixed configuration of an upper (scalar) limit. If the function parameter max is used, this property has no function.
lower	off/<val>/erase	If activated, the replacement value is output when the lower limit is exceeded (x < min) or the sample is removed.
upper	off/<val>/erase	If activated, the replacement value is output when the upper limit (x > max) is exceeded, or the sample is removed.
mode	<enum>	If x is a vector, depending on mode - box: all coordinates individually... - length: the length of the vector ( >= 0.0 )... - azimuth: the angle of the vector in the XY plane... - elevation: the angle of the vector from the XY plane to the Z axis… ...limited to the set range $[min, max]$
defXY	[<dbl>, <dbl>]	In elevation mode, defXY is the default direction when the vector must be swung back from the vertical (def.: [1, 0, 0]).
limVar	<str>	limVar optionally defines the name of a local <bool> variable to signal the active limitation

Non-zero "nonZero"

This function ensures that a critical value (def.: 0.0) is never output. Instead, the value range is omitted by a factor of $\epsilon$ (def.: 1e-6) around the critical value. The application of the function is optimized, for example, for divisions where division by zero would be possible and must be excluded.

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

One example is the safe conversion of fuel flow rate in $l/h$ and speed in $km/h$ into fuel consumption in $l/100km$:

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

Switching threshold with hysteresis "threshold"

This function generates a switching signal by comparing a signal against a fixed threshold value threshold. Disturbances in the signal curve can be suppressed using hysteresis hysteresis and delay times delayOn, delayOff.

The function can be used in various applications:

trig1 = threshold(x);
trig2 = threshold(x, t);
trig3 = threshold(x, t, h);
// Optional configuration for all variants
trigX = threshold(..., { threshold: <dbl>
                       , hysteresis: <dbl>
                       , delayOn: <dbl>
                       , delayOff: <dbl> 
                       , logic: <enum>
                       , startup: inf|<bool>
                       });

Property	Value	Meaning
threshold	<dbl>	Trigger threshold, def.: 0.55 Overwritten with argument t
hysteresis	<dbl>	Width of the hysteresis zone, added to the threshold for the second limit value, def.: -0.10 Overwritten with argument h
delayOn	<dbl>	Optional filter time in seconds for the switch-on process
delayOff	<dbl>	Optional filter time in seconds for the switch-off process
logic	<enum>	- auto: Function is determined by the sign of the hysteresis - above: Triggering above the hysteresis zone - below: Triggering below the hysteresis zone
startup	inf|<bool>	Start behavior: inf: The position of the first sample determines the output value (def.) with respect to the threshold. <bool>: It is assumed that this output value was output before the first sample.

• The function returns true for the point in time when the signal x exceeds the defined trigger threshold and false for the point in time when the signal x falls back into the reset state.

If the delay times are set, the signal x must remain continuously in the trigger or reset state for the specified interval before the switchover is implemented. The switchover is therefore delayed relative to the respective threshold value being exceeded.

In auto mode (default), triggering depends on the sign of the hysteresis:

Hysteresis	Triggering (true)	Reset (false)
$hysteresis < 0$	$x > threshold$	$x < threshold + hysteresis$
$hysteresis > 0$	$x < threshold$	$x > threshold + hysteresis$

In the above and below operating modes, threshold and hysteresis define two limits of a hysteresis zone:

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

Operating mode	Trigger (true)	Reset (false)
above	$x > g_{high}$	$x < g_{low}$
below	$x < g_{low}$	$x > g_{high}$

Footnotes

1. Available from catalog version 10 onwards. ↩ ↩² ↩³ ↩⁴ ↩⁵