SEAL Functions

Overview

All of the following functions are available from SEAL code.

Naming convention used in this document:

• Sensor value – name of a SEAL sensor, including user-defined sensors.
• Scalar value – a predefined constant, a variable, or an integer literal.

Calling the functions

Functions can be called from SEAL code by specifying the name of the function, followed by arguments enclosed in brackets.

Some of the functions have synomyns. The they can be called from either of those names.

Optional arguments can be skipped; then they take default values. In contrast, some arguments can be 'repeated one or more times. The description of the functions mention which arguments are optional, and which can be repeated.

Functions parameters can also be named. For example, to call contrast function on 20 samples of light sensor readings, using the weight coefficient 2.0 you can write contrast(Light, numSamples 20, weight 2.0) .

The meaning is the same as for contrast(Light, 20, 2.0), but the former approach leads to self-documenting code.

If named, the parameetrs can also be written in mixed order, for example, contrast(numSamples 20, weight 2.0, value Light).

Arithmetic functions

sum(value, ...)

Sum of one or more values.

Argument: a sensor value or a scalar.

Argument can be repeated zero to many times.

Aggregate function (i.e. can have take() as parameter).

Example syntax:

1. sum(Light, Humidity, -12) – calculates sum of last light sensor reading with last humidity sensor reading and -12 (i.e. subtracts 12).
2. sum(take(Light, 10)) – calculates sum of last 10 light sensor readings

plus(value1, value2)

Addition.

Arguments: sensor values or scalars.

Synonym: add

Example syntax: plus(Light, Humidity) – calculates sum of light and humidity sensor readings

minus(value1, value2)

Subtraction.

Arguments: sensor values or scalars.

Synonym: subtract

Example syntax: minus(Light, Humidity) – calculates value of the expression: light sensor value minus humidity sensor value.

times(value1, value2)

Multiplication.

Arguments: sensor values or scalars.

Synonym: multiply

Example syntax: times(Light, 3) – calculates the value of light sensor reading multiplied by three.

divide(value1, value2)

Division.

Arguments: sensor values or scalars.

Example syntax: divide(Light, 3) – calculates the value of light sensor reading divided by three and rounded down to the nearest integer.

modulo(value1, value2)

The remainder in division.

Arguments: sensor values or scalars.

Example syntax: modulo(Random, 3) – calculates the remainder of a random number value divided by three.

difference(value1, value2)

Symmetrical difference.

Argument: sensor values or scalars.

Example syntax: difference(13, 14) calculates the absolute value of the difference between two values 13 and 14. Same as abs(minus(13, 14)).

abs(value)

Absolute value.

Argument: a sensor value or a scalar.

Example syntax: abs(Temperature) – calculate the absolute valute of temperature sensor reading

neg(value)

Negation.

Argument: a sensor value or a scalar.

Example syntax: neg(Humidity) – calculate the negation valute of humidity sensor reading

invert(value)

Return the Boolean inverse of the value passed: True if the value is zero, False otherwise.

Argument: a sensor value or a scalar.

Example syntax: invert(Random) – evaluates to true if the last random number is zero.

square(value)

Calculate square (second power) of a value.

Argument: a sensor value or a scalar.

Example syntax: square(Random) – calculate the square of the last random number.

sqrt(value)

Calculate square root of a value.

Argument: a sensor value or a scalar.

Example syntax: sqrt(Random) – calculates the square root of the last random number rounded to the nearest integer. Depending on the implmentation, approximate values may be returned!

power(base, exponent)

Exponentiation.

Arguments: base is a sensor value or a scalar, exponent must be scalar.

Example syntax: power(Random, 3) – calculate the cube of the last random number.

Data aggregation functions

min(value, ...)

Minimal value.

Argument: a sensor value or a scalar

Argument can be repeated one to many times.

Aggregate function (i.e. can have take() as parameter).

Example syntax:

1. min(Light, 10) – calculate the minimum of light sensor reading and the number 10;
2. min(take(Light, 100)) – calculate the minimum of the last 100 light sensor readings.

max(value, ...)

Maximal value.

Argument: a sensor value or a scalar

Argument can be repeated one to many times.

Aggregate function (i.e. can have take() as parameter).

Example syntax:

1. max(Light, 10) – calculate the maximum of the light sensor reading and the number 10;
2. max(take(Light, 100)) – calculate the maximum of the last 100 light sensor readings.

average(value)

Average value (the mean).

Argument: a sensor value or a scalar

Aggregate function (i.e. can have take() as parameter).

Synonym: avg

Example syntax:

1. average(Light) – calculate the average of light sensor readings during program's execution;
2. average(take(Light, 100)) – calculate the average of the last 100 light sensor readings.

stdev(value)

Standard deviation.

Argument: a sensor value or a scalar

Aggregate function (i.e. can have take() as parameter).

Synonym: std

Example syntax:

1. stdev(Light) – calculate the standard deviation of light sensor readings during program's execution;
2. stdev(take(Light, 100)) – calculate the standard deviation of the last 100 light sensor readings.

variance(value)

Signal variance.

Argument: a sensor value or a scalar

Aggregate function (i.e. can have take() as parameter).

Example syntax:

1. variance(Light) – calculate the variance of light sensor readings during program's execution;
2. variance(take(Light, 100)) – calculate the variance of the last 100 light sensor readings.

ewma(value, alpha)

Exponential moving average with coefficient alpha.

Arguments: 'value' is a sensor value or a scalar, 'alpha' is a scalar (including floating point) value.

Example syntax:

1. ewma(Light, 0.5) – calculate the exponential moving average of light sensor readings during program's execution with coefficient 0.5;
2. ewma(take(Light, 100), 0.5) – calculate the same, but for the last 100 light sensor readings.

changed(value)

Calculate a Boolean value that describes whether the value has changed.

Argument: a sensor value or a scalar

Example syntax:

1. changed(Light) – true if light sensor reading have changed during program's execution.
2. changed(take(Light, 100)) – true if light sensor reading have changed during last 100 readings.
3. changed(13) – always false, because the value is constant.

Signal processing functions

map(value, fromRangeLow, fromRangeHigh, toRangeLow, toRangeHigh)

Do mapping.

Arguments: 'value' is a sensor value or a scalar. The arguments 'fromRangeLow' and 'fromRangeHigh' are scalars that define the lower and upper bound of the range from which to map; the arguments 'toRangeLow' and 'toRangeHigh' are scalars that define the range to which to map.

Example syntax: map(Light, 0, 1023, 0, 255) – map light sensor reading from range [0..1023] (10 bit range, e.g. ADC) to range [0..255] (eight bit range, e.g. for a variable of char type).

sharpen(value, numSamples, weight)

Add contrast.

Arguments: 'value' is a sensor value or a scalar. 'numSamples' (optional, default value 3) – a scalar value that describes the number of samples to take. 'weight' (optional, default value 1) – a scalar value (can be florating point) that describes the amplitude of the sharpening.

Synonym: contrast

Example syntax: sharpen(Light) – add contrast to light sensor readings using the default values.

smoothen(value, numSamples, weight)

Remove contrast.

Arguments: 'value' is a sensor value or a scalar. 'numSamples' (optional, default value 3) – a scalar value that describes the number of samples to take. 'weight' (optional, default value 1) – a scalar value (can be florating point) that describes the amplitude of the bluring.

Synonym: blur

Example syntax: smoothen(Light) – add blur to light sensor readings using the default values.

Filtering functions

match(value, pattern)

Match sensor readings against a predefined patter.

Arguments: 'value' is a sensor value or a scalar. 'pattern' is the name of a predefined pattern in the source file.

Example syntax: pattern P (0, 0, 0, 0); ...; match(Light, pattern) – compare last four light sensor reading with four consecutive zeros and evaluate to True in case of match, False otherwise.

filterRange(value, thresholdMin, thresholdMin)

Threshold sensor readings against predefined lower and upper bounds.

Arguments: 'value' is a sensor value or a scalar. 'thresholdMin' and 'thresholdMin' are scalars that define the range [thresholdMin..thresholdMin].

Example syntax: filterRange(Light, 1000, 2000) – read only those light sensor values that are between 1000 and 2000, inclusive, and ignore the rest.

filterEqual(value, threshold)

Arguments: 'value' is a sensor value or a scalar. 'threshold' is a scalar.

Example syntax: filterEqual(Light, 1000) – read only those light sensor values that are equal to 1000, and ignore the rest.

filterNotEqual(value, threshold)

Argument: 'value' is a sensor value or a scalar. 'threshold' is a scalar.

Example syntax: filterNotEqual(Light, 1000) – read only those light sensor values that are not equal to 1000, and ignore the rest.

filterLess(value, threshold)

Argument: 'value' is a sensor value or a scalar. 'threshold' is a scalar.

Example syntax: filterLess(Light, 1000) – read only those light sensor values that are less than 1000, and ignore the rest.

filterLessOrEqual(value, threshold)

Argument: 'value' is a sensor value or a scalar. 'threshold' is a scalar.

Example syntax: filterLessOrEqual(Light, 1000) – read only those light sensor values that are less than or equal to 1000, and ignore the rest.

filterMore(value, threshold)

Argument: 'value' is a sensor value or a scalar. 'threshold' is a scalar.

Example syntax: filterMore(Light, 1000) – read only those light sensor values that more than to 1000, and ignore the rest.

filterMoreOrEqual(value, threshold)

Argument: 'value' is a sensor value or a scalar. 'threshold' is a scalar.

Example syntax: filterMoreOrEqual(Light, 1000) – read only those light sensor values that are more than or equal to 1000, and ignore the rest.

invertFilter(value)

Invert the effect of any previosly applied filters, or filter out the value if there were none.

Argument: 'value' is a sensor value or a scalar

Example syntax: invertFilter(filterRange(Light, 1000, 2000)) – read only those light sensor values that are NOT bewteen 1000 and 2000, inclusive, and ignore those that are.

Subset selection & special purpose functions

if(conditionValue, ifValue, elseValue)

Logical IF function. If conditionValue is true (nonzero), then ifValue is returned. Else elseValue is returned.

elseValue is optional, and has default value of zero.

Arguments: sensor values.

Example syntax:

• if(True, Temperature, Humidity) – if 'True' is true, then read light and humidity values.
• when Light < 100: set ConditionValue True; end;

    define BoundedLight if(ConditionValue, Light, 100); – this is a more practical example that uses states (the ConditionValue variable) to achieve conditional behaviour. If Light sensor reads less than 100, then reading BoundedLight will return light value, else it will return the number 100.

take(value, numberToTake, timeToTake)

Take one or more sensor value. The values are read one at time, but the enclosing function is evaluated on all of them. At the start of program, the values that are not read yet are treated as zero.

take can only be used in context of specific enclosing functions – those that are marked as aggregate.

Arguments: 'value' is a sensor value. 'numberToTake' is a scalar value that describes the number of sensor values to read. 'timeToTake' (optional, default value is not specified) is the time period in which to limit the values.

Example syntax:

1. sum(take(Random, 100)) – calculate sum of 100 random numbers.
2. sum(take(Light, 600, 1h)) – calculate sum of light sensor readings sampled in the last hour, and limit their count to six hundred (600).

tuple(value, ...)

Read multiple, heterogenous sensor values.

tuple can only be used in context of specific enclosing functions – those that are marked as aggregate.

Argument: sensor values.

Example syntax: tuple(Light, Temperature, Humidity) – read a tuple of light, temperature, and humidity sensor values.

sync(value, ...)

Synchronize reading of multiple sensors.

Arguments: sensor values.

Example syntax: sync(Light, Temperature, Humidity) – synchronize light, temperature, and humidity sensor reading.