Mutations

Mutations are formula that can alter the value that is sent out to other plugins. The mutation is applied on the receiver of the data, not at the transmitter, which allows for emitting a single value from a receiving, and handling it differently on various receivers.

The received value is available within the formula as the variable $i$ .

Let’s take the following settings file as an example:

devices:
  - type: modbusTCP
    name: mb
    options:
      ip: 10.0.0.2

  - type: websocket
    name: ws

  - type: osc
    name: osc

mappings:
  - name: mb to ws - analog
    from: { name: mb, address: 0, type: int8 }
    to: { name: ws, address: input1, type: int16 }
    mutation: scale(i, int8, int16)

  - name: mb to osc - analog
    from: { name: mb, address: 0, type: int8 }
    to: { name: osc, address: /fader/1, type: float }
    mutation: scale(i, int8, 100)

  - name: mb to ws - digital
    from: { name: mb, address: 1, type: bool }
    to: { name: ws, address: led1, type: bool }

  - name: mb to osc - digital
    from: { name: mb, address: 1, type: bool }
    to: { name: ws, address: /led/1, type: bool }
    mutation: not(i)

The logical representation of these settings looks like this:

Variables

the only variable available in the functions is the variable $i$ which is the input value to be converted.

Constants

the following constants can be used in formula

constant	value
int8	255
int16	65535
pi	3.141592653589793
epsilon	1e-10
inf	inf

Supported Operators & Functions

the mutation math supports the following basic arithmetic operations, functions and processes:

NOTE

In the following examples we’ll use some other variable names — like $x$ — to represent numbers. Note thought that these cannot be used in the formula and must be replaced with a valid number.

Arithmetic

+ addition between $i$ and $x$ . eg:
```
i + 2
```
with $i + 2$ ⇒ $4$
arithmetic formula example
formula example
```
mutation: i + 2
```
results table

type formula input result
double i + 2 3.0 5.0
int8 i + 2 4 6
double i - 2 3.0 1.0
int8 i - 2 4 2
double i / 2 3.0 1.5
int8 i / 2 4 2
double i * 2 3.0 6.0
int8 i * 2 4 8
double i % 2 3.0 1.0
int8 i % 2 4 0
double i ^ 2 3.0 9.0
int8 i ^ 2 4 16
- subtraction between $i$ and $x$ . eg:
```
i - 2
```
with $i = 2$ ⇒ $0$
* multiplication between $i$ and $x$ . eg:
```
i * 2
```
with $i = 3$ ⇒ $6$
/ division between $i$ and $x$ . eg:
```
i / 2
```
with $i = 3$ ⇒ $1.5$
% modulus of $i$ with respect to $x$ . eg:
```
i % 2
```
with $i = 3$ ⇒ $1$
^ $i$ to the power of $x$ . eg:
```
i ^ 2
```
with $i = 3$ ⇒ $9$

type	formula	input	result
double	i + 2	3.0	5.0
int8	i + 2	4	6
double	i - 2	3.0	1.0
int8	i - 2	4	2
double	i / 2	3.0	1.5
int8	i / 2	4	2
double	i * 2	3.0	6.0
int8	i * 2	4	8
double	i % 2	3.0	1.0
int8	i % 2	4	0
double	i ^ 2	3.0	9.0
int8	i ^ 2	4	16

Assignment

:= assign the value of $x$ to $i$ . eg:
```
i := 2
```
with $i = 3$ ⇒ $2$
+= increment $i$ by the value of the expression on the right-hand side. eg:
```
i += abs(i - 4)
```
with $i = 3$ ⇒ $4$
-= decrement $i$ by the value of the expression on the right-hand side. eg:
```
i -= abs(i - 4)
```
with $i = 3$ ⇒ $2$
*= assign the multiplication of $i$ by the value of the expression on the right-hand side to $i$ . eg:
```
i *= abs(i - 5)
```
with $i = 3$ ⇒ $6$
/= assign the division of $i$ by the value of the expression on the right-hand side to $i$ . eg:
```
i /= abs(i * -2)
```
with $i = 3$ ⇒ $0.5$
%= assign $i$ modulo the value of the expression on the right-hand side to $i$ . eg:
```
i %= i / 2.5
```
with $i = 3$ ⇒ $0.6$

Equalities & Inequalities

= == true only if $i$ is strictly equal to $x$ . eg:
```
x == 3
```
with $i = 3$ ⇒ $1$

with $i = 2$ ⇒ $0$
<> != True only if $i$ does not equal $x$ . eg:
```
i != 3
```
with $i = 3$ ⇒ $0$

with $i = 2$ ⇒ $1$
< True only if $i$ is less than $x$ . eg:
```
i < 3
```
with $i = 2$ ⇒ $1$

with $i = 3$ ⇒ $0$

with $i = 4$ ⇒ $0$
<= True only if $i$ is less than or equal to $x$ . eg:
```
i <= 3
```
with $i = 2$ ⇒ $1$

with $i = 3$ ⇒ $1$

with $i = 4$ ⇒ $0$
> True only if $i$ is greater than $x$ . eg:
```
i > 3
```
with $i = 2$ ⇒ $0$

with $i = 3$ ⇒ $0$

with $i = 4$ ⇒ $1$
>= True only if $i$ greater than or equal to $x$ . eg:
```
i >= 3
```
with $i = 2$ ⇒ $0$

with $i = 3$ ⇒ $1$

with $i = 4$ ⇒ $1$

Logic Operators

and & Logical AND, true only if $i$ and $x$ are both true. eg:
```
i and 2
```
with $i = 3$ ⇒ $1$

with $i = 0$ ⇒ $0$

and truth table

Input A Input B Output
$i$ $x$ $i$ and $x$
0 0 0
0 1 0
1 0 0
1 1 1
mand Multi-input logical AND, true only if all inputs are true. Left to right short-circuiting of expressions. eg:
```
mand(i > 2, i < 4)
```
with $i = 3$ ⇒ $1$

with $i = 4$ ⇒ $0$
or | Logical OR, True if either $i$ or $x$ is true. eg:
```
(i == 2) or (i == 4)
```
with $i = 2$ ⇒ $1$

with $i = 3$ ⇒ $0$

with $i = 4$ ⇒ $1$

or truth table

Input A Input B Output
$i$ $x$ $i$ or $x$
0 0 0
0 1 1
1 0 1
1 1 1
mor Multi-input logical OR, true if at least one of the inputs are true. Left to right short-circuiting of expressions. eg:
```
mor(i > 3, i < -3)
```
with $i = 3$ ⇒ $0$

with $i = 4$ ⇒ $1$
nand Logical NAND, True only if either $i$ or $x$ is false. eg:
```
i nand 3
```
with $i = 0$ ⇒ $1$

with $i = 1$ ⇒ $0$

nand truth table

Input A Input B Output
$i$ $x$ $i$ nand $x$
0 0 1
0 1 1
1 0 1
1 1 0
nor Logical NOR, True only if the result of $i$ or $x$ is false eg:
```
i nor 0
```
with $i = 0$ ⇒ $1$

with $i = 1$ ⇒ $0$

nor truth table

Input A Input B Output
$i$ $x$ $i$ nor $x$
0 0 1
0 1 0
1 0 0
1 1 0
not Logical NOT, negate the logical sense of the input. eg:
```
not(i)
```
with $i = 0$ ⇒ $1$

with $i = 1$ ⇒ $0$

not truth table

Input Output
$i$ not $i$
0 1
1 0
Invert / Not formula example
The not(i) function converts the input $i$ to a boolean, converts back to the input type and returns it. + When using any number type it will always return either $0$ or $1$ .
formula example
```
mutation: not(i)
```
results table

Type Formula Input Result
int8 not(i) 1 0
int8 not(i) 0 1
int8 not(i) 4 0
int16 not(i) 1 0
int16 not(i) 0 1
double not(i) 1.0 0.0
double not(i) 0.0 1.0
bool not(i) true false
bool not(i) false true
xnor Logical XNOR, True if the biconditional of $i$ and $x$ is satisfied. eg:
```
i xnor 0
```
with $i = 0$ ⇒ $1$

with $i = 1$ ⇒ $0$

xnor truth table

Input A Input B Output
$i$ $x$ $i$ xnor $x$
0 0 1
0 1 0
1 0 0
1 1 1
xor Logical XOR, True only if the logical states of $i$ and $x$ differ. eg:
```
i xor 0
```
with $i = 0$ ⇒ $0$

with $i = 1$ ⇒ $1$

xor truth table

Input A Input B Output
$i$ $x$ $i$ xor $x$
0 0 0
0 1 1
1 0 1
1 1 0
true True state or any value other than zero (typically 1). eg:
```
true
```
with $true$ ⇒ $1$
false False state, value of exactly zero. eg:
```
false
```
with $false$ ⇒ $0$

Input A	Input B	Output
$i$	$x$	$i$ and $x$
0	0	0
0	1	0
1	0	0
1	1	1

Input A	Input B	Output
$i$	$x$	$i$ or $x$
0	0	0
0	1	1
1	0	1
1	1	1

Input A	Input B	Output
$i$	$x$	$i$ nand $x$
0	0	1
0	1	1
1	0	1
1	1	0

Input A	Input B	Output
$i$	$x$	$i$ nor $x$
0	0	1
0	1	0
1	0	0
1	1	0

Input	Output
$i$	not $i$
0	1
1	0

Type	Formula	Input	Result
int8	not(i)	1	0
int8	not(i)	0	1
int8	not(i)	4	0
int16	not(i)	1	0
int16	not(i)	0	1
double	not(i)	1.0	0.0
double	not(i)	0.0	1.0
bool	not(i)	true	false
bool	not(i)	false	true

Input A	Input B	Output
$i$	$x$	$i$ xnor $x$
0	0	1
0	1	0
1	0	0
1	1	1

Input A	Input B	Output
$i$	$x$	$i$ xor $x$
0	0	0
0	1	1
1	0	1
1	1	0

Functions

map map a value $i$ from range $f0, f1$ to range $t0, t1$ where $f0 < i < f1$ eg:
```
map(i, 50, 100, 100, 200)
```
with $i = 75$ ⇒ $150$
Map formula example
The map function scales a given input value from one value range $a$ (specified with a lower and upper bound) to another value range $b$ (again, specified with a lower and upper bound). eg:
formula example
```
mutation: map(i, in_min, in_max, out_min, out_max)
```
results table

Type Formula Input Result
int8 map(i, 10, 80, 0, 100) 0 0
int8 map(i, 10, 80, 0, 100) 25 21
int8 map(i, 10, 80, 0, 100) 75 92

Type	Formula	Input	Result
int8	map(i, 10, 80, 0, 100)	0	0
int8	map(i, 10, 80, 0, 100)	25	21
int8	map(i, 10, 80, 0, 100)	75	92

scale scale a value $i$ from range $0, f1$ to range $0, f2$ where $0 < i < f1$ . eg:

scale(i, 100, 200)

with $i = 50$ ⇒ $100$

Scale formula example

The scale function is similar to the map function, but assumes that the in_min and out_min values are both 0. + This function is useful to scale between let’s say a percentage and a number range (be it the int8 number range 0 - 255, the int16 number range 0 - 65535, or any custom range starting at 0).

formula example

mutation: scale(i, in_max, out_max)

results table

Type	Formula	Input	Result
int8	scale(i, 255, 65535)	0	0
int8	scale(i, 255, 65535)	127	255
int8	scale(i, 255, 65535)	255	255
int16	scale(i, 65535, 255)	0	0
int16	scale(i, 65535, 255)	32639	127
int16	scale(i, 65535, 255)	65535	255
bool	scale(i, 1, 255)	false	false
bool	scale(i, 1, 255)	true	true
int8	scale(i, 1, 255)	0	0
int8	scale(i, 1, 255)	1	255
int8	scale(i, 1, 255)	4	255

abs Absolute value of $i$ . eg:
```
abs(i)
```
with $i = 2$ ⇒ $2$

with $i = -2$ ⇒ $2$
avg Average of all the inputs. eg:
```
avg(i, 2)
```
with $i = 2$ ⇒ $2$

with $i = 6$ ⇒ $4$
ceil Smallest integer that is greater than or equal to $i$ . eg:
```
ceil(i)
```
with $i = 3.2$ ⇒ $4$
floor Largest integer that is less than or equal to $i$ . eg:
```
floor(i)
```
with $i = 1.7$ ⇒ $1$
clamp Clamp $i$ in range between $r0$ and $r1$ , where $r0 < r1$ . eg:
```
clamp(0, i, 10)
```
with $i = -2$ ⇒ $0$

with $i = 2$ ⇒ $2$

with $i = 20$ ⇒ $10$
Clamp formula example
formula example
```
mutation: clamp(limit_low, i, limit_high)
```
results table

Type Formula Input Result
double clamp(20, i, 80) 3.0 20.0
int8 clamp(20, i, 80) 4 20
int8 clamp(20, i, 80) 25 25
int8 clamp(20, i, 80) 125 80
iclamp Inverse-clamp $i$ outside the range $r0$ and $r1$ . Where $r0 < r1$ . If $i$ is within the range it will snap to the closest bound. eg:
```
iclamp(10, i, 20)
```
with $i = 2$ ⇒ $2$

with $i = 12$ ⇒ $10$

with $i = 18$ ⇒ $20$
round Round $i$ to the nearest integer. eg:
```
round(x)
```
with $i = 2.3$ ⇒ $2$

with $i = 2.49$ ⇒ $2$

with $i = 2.5$ ⇒ $3$
roundn Round $i$ to $n$ decimal places (eg: $roundn(i, 3)]$ where $n > 0$ and is an integer. eg:
```
roundn(i, 4)
```
with $i = 1.2345678$ ⇒ $1.2346$
equal Equality test between $i$ and $x$ using normalised epsilon. eg:
```
equal(i, 2.3)
```
with $i = 2$ ⇒ $0$

with $i = 2.3$ ⇒ $1$
pow $i$ to the power of $x$ . eg:
```
pow(i, 3)
```
with $i = 2$ ⇒ $8$
Pow formula example
formula example
```
mutation: pow(i, power)
```
results table

Type Formula Input Result
double pow(i, 2) 3.0 9.0
int8 pow(i, 2) 4 16
exp $e$ to the power of $i$ . eg:
```
exp(i)
```
with $i = 2$ ⇒ $8$
expm1 $e$ to the power of $i$ minus 1, where $i$ is very small. eg:
```
expm1(i)
```
with $i = 0.1$ ⇒ $0.105171$
sqrt Square root of $i$ , where $i$ >= 0. eg:
```
sqrt(i)
```
with $i = 100$ ⇒ $10$
root Nth-Root of $i$ . where $n$ is a positive integer. eg:
```
root(i, 3)
```
with $i = 8$ ⇒ $2$
log Natural logarithm (a logarithm to the base of $e$ ) of $i$ . eg:
```
log(i)
```
with $i = 100$ ⇒ $4.60517$
log10 Base 10 logarithm of $i$ . eg:
```
log10(i)
```
with $i = 100$ ⇒ $2$
log2 Base 2 logarithm of $i$ . eg:
```
log2(i)
```
with $i = 16$ ⇒ $4$
log1p Natural logarithm of 1 + $i$ , where $i$ is very small. eg:
```
log1p(i)
```
with $i = 0.1$ ⇒ $0.0953102$
logn Base N logarithm of $i$ . where $n$ is a positive integer. eg:
```
logn(i, 8)
```
with $i = 64$ ⇒ $2$
trunc Integer portion of $i$ . eg:
```
trunc(i)
```
with $i = 1.7$ ⇒ $1$
frac Fractional portion of $i$ . eg:
```
frac(i)
```
with $i = 1.7$ ⇒ $0.7$
hypot Hypotenuse of $i$ and $x$ eg:
```
hypot(i, 4)
```
with $i = 3$ ⇒ $5$
inrange In-range returns true when $i$ is within the range $r0$ and $r1$ . Where $r0 < r1$ . eg:
```
inrange(10, i, 20)
```
with $i = 2$ ⇒ $0$

with $i = 12$ ⇒ $1$

with $i = 22$ ⇒ $0$
max Largest value of all the inputs. eg:
```
max(i, 2, 5)
```
with $i = 1$ ⇒ $5$

with $i = 10$ ⇒ $10$
min Smallest value of all the inputs. eg:
```
min(i, 2, 5)
```
with $i = 1$ ⇒ $1$

with $i = 10$ ⇒ $2$
sum Sum of all the inputs. eg:
```
sum(i, 2, 3)
```
with $i = 1$ ⇒ $6$
mul Product of all the inputs. eg:
```
mul(i, 2, 3)
```
with $i = 1$ ⇒ $6$

with $i = 2$ ⇒ $12$
ncdf Normal cumulative distribution function. eg:
```
ncdf(i)
```
sgn Sign of $i$ , -1 where $i$ < 0, +1 where $i$ > 0, else zero. eg:
```
sgn(x)
```
with $i = -4$ ⇒ $-1$

with $i = 4$ ⇒ $1$

with $i = 0$ ⇒ $0$

Type	Formula	Input	Result
double	clamp(20, i, 80)	3.0	20.0
int8	clamp(20, i, 80)	4	20
int8	clamp(20, i, 80)	25	25
int8	clamp(20, i, 80)	125	80

Type	Formula	Input	Result
double	pow(i, 2)	3.0	9.0
int8	pow(i, 2)	4	16

Trigonometry

sin Sine of $i$ . eg:
```
sin(i)
```
with $i = 2$ ⇒ $0.909297$
cos Cosine of $i$ . eg:
```
cos(i)
```
with $i = 2$ ⇒ $-0.41647$
tan Tangent of $i$ . eg:
```
tan(i)
```
with $i = 2$ ⇒ $-2.18504$
sinh Hyperbolic sine of $i$ . eg:
```
sinh(i)
```
with $i = 2$ ⇒ $3.62686$
cosh Hyperbolic cosine of $i$ . eg:
```
cosh(i)
```
with $i = 2$ ⇒ $3.7622$
tanh Hyperbolic tangent of $i$ . eg:
```
tanh(i)
```
with $i = 2$ ⇒ $0.964028$
asin Arc sine of $i$ expressed in radians. Interval $[-1, +1]$ . eg:
```
asin(i)
```
with $i = 0.5$ ⇒ $0.523599$
acos Arc cosine of $i$ expressed in radians. Interval $[-1, +1]$ . eg:
```
acos(i)
```
with $i = 0.5$ ⇒ $1.0472$
atan Arc tangent of $i$ expressed in radians. Interval $[-1, +1]$ . eg:
```
atan(i)
```
with $i = 0.5$ ⇒ $0.463648$
asinh Inverse hyperbolic sine of $i$ expressed in radians. eg:
```
asinh(i)
```
with $i = 2$ ⇒ $1.44364$
acosh Inverse hyperbolic cosine of $i$ expressed in radians. eg:
```
acosh(i)
```
with $i = 2$ ⇒ $1.31696$
atanh Inverse hyperbolic tangent of $i$ expressed in radians. eg:
```
atanh(i)
```
with $i = 0.5$ ⇒ $0.549306$
sinc Sine cardinal of $i$ . eg:
```
sinc(i)
```
with $i = 2$ ⇒ $0.454649$
cot Cotangent of $i$ . eg:
```
cot(i)
```
with $i = 2$ ⇒ $-0.457658$
csc Cosecant of $i$ . eg:
```
csc(i)
```
with $i = 2$ ⇒ $1.09975$
sec Secant of $i$ . eg:
```
sec(i)
```
with $i = 2$ ⇒ $-2.403$
atan2 Arc tangent of $(i / x)$ expressed in radians. $[-pi, +pi]$ . eg:
```
atan2(i, 1)
```
with $i = 2$ ⇒ $1.10715$
rad2deg Convert $i$ from radians to degrees. eg:
```
rad2deg(i)
```
with $i = 2$ ⇒ $114.592$
deg2rad Convert $i$ from degrees to radians. eg:
```
deg2rad(i)
```
with $i = 114$ ⇒ $1.98968$
grad2deg Convert $i$ from gradians to degrees. eg:
```
grad2deg(i)
```
with $i = 2$ ⇒ $0.9$
deg2grad Convert $i$ from degrees to gradians. eg:
```
deg2grad(i)
```
with $i = 0.9$ ⇒ $2$

String Processing

NOTE

Note that the input type of mapping can be of type string, but the returned value of the mutation formula must be a number (a number will be converted to a boolean or string if required). It is currently not possible to mutate a string to a different string. The input string is available as the variable $i$ , any other string must be enclosed in quotes.

= == != <> \<= >= < > All common equality / inequality operators are applicable to strings and are applied in a case-sensitive manner. eg:
```
i == 'test'
```
with $i = "test"$ ⇒ $1$

with $i = "testing"$ ⇒ $0$
in True only if $i$ is a substring of $x$ . eg:
```
i in 'testing'
```
with $i = "test"$ ⇒ $1$

with $i = "hello"$ ⇒ $0$
like True only if the string $i$ matches the pattern $x$ . Available wildcard characters are * and ? denoting zero or more and zero or one matches respectively. eg:
```
i like 'te?t*'
```
with $i = "test"$ ⇒ $1$

with $i = "testing"$ ⇒ $1$

with $i = "texting"$ ⇒ $1$

with $i = "taste"$ ⇒ $0$
ilike True only if the string $i$ matches the pattern $x$ in a case-insensitive manner. Available wildcard characters are ’*’ and ’?’ denoting zero or more and zero or one matches respectively. eg:
```
i ilike 'te?t*'
```
with $i = "Test"$ ⇒ $1$

with $i = "teSting"$ ⇒ $1$

with $i = "textinG"$ ⇒ $1$

with $i = "taste"$ ⇒ $0$
[r0:r1] Substring of $i$ starting at character index $r0$ up to and including $r1$ . Both $r0$ and $r1$ are assumed to be integers, where $r0 <= r1$ . They may also be the result of an expression; in the event they have a fractional component they will be truncated (eg: $1.67 -> 1$ ). eg:

with $i = 'abcdefgh'$ :
- i[1:4] == 'bcde'
- i[:10 / 2] == 'abcdef'
- i[3:] =='defgh'
- i[:] == 'abcdefgh'
- i[2:5] == 'cdef'
[] The string size operator returns the size of the string being actioned. eg:
```
i[]
```
with $i = "test"$ ⇒ $4$

Control Structures

if If $i$ is true then return $x$ else return $y$ . eg:
```
if (i, 100, 200)
```
with $i = 1$ ⇒ $100$

with $i = 0$ ⇒ $200$
if-else The if-else/else-if statement. Subject to the condition branch the statement will return either the value of the consequent or the alternative branch. eg:
```
if (i > 100) 1; else 2;
```
with $i = 1$ ⇒ $2$

with $i = 101$ ⇒ $1$
switch The first true case condition that is encountered will determine the result of the switch. If none of the case conditions resolve true, the default action is assumed as the final return value. eg:
```
switch
{
    case i == 'connected' : 1;
    case i == 'disconnected' : 0;
    default : -1;
}
```
with $i = "error"$ ⇒ $-1$

with $i = "connected"$ ⇒ $1$

with $i = "disconnected"$ ⇒ $0$
?: Ternary conditional statement, similar to that of the above denoted if-statement. eg:
```
i > 100 ? 1 : 2
```
with $i = 1$ ⇒ $2$

with $i = 101$ ⇒ $1$

Mutations

Mutations

Variables

Constants

Supported Operators & Functions

Arithmetic

formula example

results table

Assignment

Equalities & Inequalities

Logic Operators

and truth table

or truth table

nand truth table

nor truth table

not truth table

formula example

results table

xnor truth table

xor truth table

Functions

formula example

results table

formula example

results table

formula example

results table

formula example

results table

Trigonometry

String Processing

Control Structures