Math Expressions

iViewer embeds a powerful and versatile math expression engine. Math expressions can be inserted in commands and feedback items. The Math expression parser features:

• Standard math operators
• Parenthesis grouping
• Logical (boolean) operators
• Standard math functions
• Conditional logic using the if() function (like if / then /else statements)
• Local variables
• Multiple math expressions in the same command
• Flexible result output

Basic math expressions can be written in a standard way using numbers and operators. You can use tokens which are dynamically replaced by their actual value before the math evaluation begins. Multiple expressions can be separated by a comma. You will use this feature to declare local variables and reuse them in the other expressions. When multiple expressions are present, the final result is the value of the last expression.

Within commands, math expressions must be enclosed in double curly braces, the result of the math evaluation is converted to a string (and can be optionally formatted the way you need it). Math expression can also be used in the transform field of 'capture group' feedback items (where the incoming data type is set to Analog), in which case you won't use the double curly braces to enclose the expression.

Simple addition:       {{ 1 + [currentValue] }}

Math functions:        {{ round(1.5 * [currentValue]) }}

Multiple expressions:  {{ a=100, b=2*[inputValue], max(a, b) }}

Conditions:            {{ a=[currentValue]+[delta], if(a<5, a=0, a) }}

Boolean logic:         {{ above=([currentValue] > 100), below=([currentValue]  < 0), if (above or below, 0, [currentValue]) }}

When using a math expression, you can specify an output format prefixed by a colon before the closing accolades. If you omit the format, the result will be formatted as an integer.

 {{math expression}} -> will output an integer without any decimal points

 {{math expression:}} -> will output a double with full decimal points

 {{math expression:N}} -> will output double with N decimals (can be 0, in this case this amounts to outputing an int)

 {{math expression::printf format}} -> will output a string using a full printf format string, with one argument (the math expression double result).

For more info on the printf format, see here: Printf Format on Wikipedia

Math expressions can also be used in feedback 'capture group' items, within the transform field. This works same as above, but you don't have to wrap the expression in curly braces.

With transforms, one predefined constant is set (“value”) which is the value extracted from the capture group, and can be used in the math computation.

In addition to the various number formatting options shown above, math expression can generate a hexadecimal ASCII string, or even raw bytes that you can use to send to a remote system. The options should be appended to the math expression, separated by a colon, just before the closing curly braces.

 :h         Convert the result to an unsigned long value (4 bytes) then output as few raw bytes as possible to
            represent this number. Bytes are output in network order (big endian).
            Examples:
            {{12+1:h}}   -> result=0x0000000d, output = "\x0d" (1 byte)
            {{1005*2:h}} -> result=0x000007da, output="\x07\xda" (2 bytes)

 
 :h<count>  Convert the result to an unsigned long value (4 bytes) the output the requested number of bytes,
            regardless of the result value. count should be 1 to 4 inclusive.
            Examples:
            {{12+1:h3}} -> result=0x0000000d, output = "\x00\x00\x0d" (3 bytes)
            

 :hs        Convert the result to an unsigned long value (4 bytes) then output an ASCII representation, using as few
            characters as possible to represent the value, using lowercase letters when needed.

            {{12+1:hs}} -> result=0x0000000d, output = "0d" (2 characters)
            {{1005*2:hs}} -> result=0x000007da, output="07da" (4 characters)
 
 :hs<count> Convert the result to an unsigned long value (4 bytes) then output an ASCII representation,
            showing the <count> least significant bytes of the result, using lowercase letters when needed.

            {{12+1:hs3}} -> result=0x0000000d, output = "00000d" (6 characters)
            {{1005*2:hs4}} -> result=0x000007da, output="000007da" (8 characters)

 
 :Hs        Same as :hs but text is output using uppercase characters:

            {{12+1:Hs}} -> result=0x0000000d, output = "0D" (2 characters)
            {{1005*2:Hs}} -> result=0x000007da, output="07DA" (4 characters)

 
 :Hs<count> Same as :hs<count> but text is output using uppercase characters.

            {{12+1:Hs3}} -> result=0x0000000d, output = "00000D" (6 characters)
            {{1005*2:Hs4}} -> result=0x000007da, output="000007DA" (8 characters)

Finally, an additional 's' specifier asks the engine to output as few characters as possible by stripping the leading nibble (half-byte) if its value is 0:

 :hss       Same as :hs, stripping the leading nibble is possible:

            {{12+1:hss}} -> result=0x0000000d, output = "d" (2 characters)
            {{1005*2:hss}} -> result=0x000007da, output="7da" (4 characters)

 
 :Hss       Same as :Hs, stripping the leading nibble is possible:

            {{12+1:hss}} -> result=0x0000000d, output = "D" (2 characters)
            {{1005*2:hss}} -> result=0x000007da, output="7DA" (4 characters)

The math expression parser recognizes the following operators. They are listed in inverse priority order (lowest priority ones come first).

 =    assignment (creates or updates a local variable)

 and  logical AND
 or   logical OR
 xor  logical XOR
 <=   less than or equal
 >=   greater than or equal
 !=   not equal
 ==   equal
 >    greater than
 <    less than

 +    addition
 -    subtraction
 *    multiplication
 /    division
 %    modulo
 ^    power (raise x to the power of y)

The math parser provides several built-in functions. Let us know if the function you need is missing from this list! Trigonometric functions take an angle expressed in radians, use the dtor() and rtod() functions to convert between degrees and radians.

 dtor(a)  convert angle from degrees to radians
 rtod(a)  convert angle from radians to degrees
 sin(a)   sine function
 cos(a)   cosine function
 tan(a)   tangent function
 asin(a)  arc sine function
 acos(a)  arc cosine function
 atan(a)  arc tangent function
 sinh(a)  hyperbolic sine function
 cosh(a)  hyperbolic cosine function
 tanh(a)  hyperbolic tangent function
 asinh(a) hyperbolic arc sine function
 acosh(a) hyperbolic arc cosine function
 atanh(a) hyperbolic arc tangent function

 log(n)   natural logarithm
 log2(n)  logarithm to base 2
 log10(n) logarithm to base 10
 ln(n)    logarithm to base e (2.71828...)
 exp(n)   e raised to the power of x
 sqrt(n)  square root
 abs(n)   absolute value
 trunc(n) truncate to integral value
 rint(n)  round to integral value
 near(n)  same as rint(n)
 round(n) round to integral value, regardless of rounding direction
 ceil(n)  round to smallest integral value not less than n
 floor(n) round to largest integral value not greater than n
 sign(n)  sign function: -1 if n<0, 0 if n=0, 1 if n>0

 min(n1,n2,...) smallest of all arguments. Use as many arguments as needed.
 max(n1,n2,...) largest of all arguments. Use as many arguments as needed.
 sum(n1,n2,...) sum of all arguments. Use as many arguments as needed.
 avg(n1,n2,...) mean value of all arguments. Use as many arguments as needed.

 if(t,a,b) if t is > 0 then result is a, otherwise result is b.

Assuming the captured value of the feedback group = 125.266335454

 "value / 100:" -> "1.25266335454"

 "value / 100" -> "1"

 "value / 100:0" -> "1"

 "value / 100:3" -> "1.252"

 "value / 100::%03.1f" -> "001.2"

 "value / 100::your value is %.2f. Isn't it cool?" -> "your value is 1.25. Isn't it cool?"

Token names can be used anywhere in the math expression, and will be replaced with their value before the math expression is evaluated.

For example, if you had a global token named [level] defined with a value of 125.266335454, you could create the following examples:

 "[level] / 100:" -> "1.25266335454"

 "[level] / 100" -> "1"

 "[level] / 100:0" -> "1"

 "[level] / 100:3" -> "1.252"

 "[level] / 100::%03.1f" -> "001.2"

 "[level] / 100::your value is %.2f. Isn't it cool?" -> "your value is 1.25. Isn't it cool?"

Within feedback group transform expressions, you can also reference the value of any other capture group defined in the same feedback item.

To reference a group, it must first be given a name, and must also be listed above the current group in the feedback processing order.

Reference the group by surrounding the name of the group in dollar signs. So if we had another capture group named [temp], which captured the value 1.25266335454 we could reference it like so:

 "$[temp]$ / 100:3" -> "1.252"

 "$[temp]$ / 100::%03.1f" -> "001.2"

 "$[temp]$ / 100::your temp value before transform is $[temp]$ and after transform is %.2f. Isn't it cool?" -> "your value before transform is 1.25266335454 and after transform is 1.25. Isn't it

Commands (and commands within macros), string join assignments and token assignments are being run through the math parser which looks for any math expression(s) enclosed in double curly braces within the text. Text can include multiple math blocks, each enclosed in double curly braces. When processing the text, all math local variables are reset at beginning, then kept accross multiple math blocks. This means that you can perfectly send text with intertwined math result values, and that each calculation can reuse local variables from the previous step. Here is an example:

 "Going from [currentValue] to {{a=min(1,max(100, [currentValue]+[delta]))}}. Final delta is {{abs(a - [currentValue])}} (was [delta])."

In the case above, we compute a new value from a current value and a delta, cap it to a minimum of 1 and a maximum of 100, and output text showing the new value, as well as the delta between the capped new value and the current value. Assuming that [currentValue] is 17 and [delta] is 100, the output text will be:

 "Going from 17 to 100. Final delta is 83 (was 100)."