Expression Builder

An expression allows you to scale and operate on an input value or variable using Expression Monitor widgets and also in Data Logs.

Basic Concepts

Values read by the ioBridge Web Gateways include pulse count and analog inputs.  For example, analog input values on web gateway modules are typically a value between 0 and 5 volts DC.  Inside the web gateway the 0-5 V value is converted to a “RAW” scale most often between 0 and 1023.   This so-called 10-bit conversion (2^10 = 1024) is common in micro-controllers but other scales are also used in some ioBridge gateways. For example a voltage of 2.5 volts would provide a RAW reading of 512 because

2.5/5 x 1023 = 512

(511.5 actually but since the value needs to be discrete the RAW value will likely read 511 or 512)

To be useful the RAW value of 512 needs to be converted to a scale that is more meaningful for the sensor being used.  This scale will depend on the sensor. Some are linear like ioBridge’s humidity sensor and some are very non-linear like the thermistor used in the ioBridge temperature sensor.  In the case of the humidity and temperature sensors, ioBridge includes pre-calculated scales to present the RAW readings in more meaningful ways.  This is not the case though with third-party sensors.  To provide a flexible way to scale a sensor, ioBridge offers mathematical conversion using a tool called Expression Builder.  The following diagram explains the basic concept where a reading from a range sensor is converted using Expression Builder to display depth in meters of a water tank.  See the tutorials for a similar example.

Once one understands the syntax to get input values from a channel or variable, and how to manipulate the values, the Expression Builder tool is pretty simple.  The following diagrams show where the Expression is created.  This page is accessed by selecting “Expression Monitor” as your choice when creating a new widget.

Expression Monitor Widget

Note that expressions can also be used in a Data Log

 

The first and most important concept to understand is how to get a value from an input or variable.  This is done using “Module Input” expression.

Expression Variables

Before we define the Module Input expression is is useful to define the concept of an expression variable (not to be confused with gateway variables – see below). Expression variables can be used to make expressions more understandable by using them to assign values or to assign the results of an expression. You can add multiple expression variables separated by a semicolon. Variable names may be a single letter, contain multiple letters and numbers, and use the underscore special character “_”.

x = y;

Example

Set expression variable “x” to 32 and add 10 to “x”

x = 32; answer_to_life = x + 10

Result: 42

(Note that “Result” is the value of the Expression Builder widget or the transformed value in the diagram above.  In this case the variable is not dependent on any input value.)

Module Input

This operation retrieves live values from a module that can be used in the expression as a variable.  This is one of the most important expressions and in the case of analog input values is in the range of 0-1023 (in the case of 10-bit inputs).

%%input:[Module Serial],[Input Type],[Channel / Location]%%

[Module Serial]

Module Serial Number, 8 digits

[Input Type]

2 digit input type code

  • AI – Analog Input 16 bit
  • DI – Digital Input – 1 bit
  • DO – Digital Output – 1 bit
  • PC – Pulse Count – 32 bit
  • V1 – Variable 1 – 8 bit
  • V2 – Variable 2 – 32 bit
  • VV – Gamma Variable 2 – 32 bit (see below)

[Channel / Location]

1 – 4

A – D

1-48 (Gamma – see below)

Pulse Count Example

Set variable “pulseCount” to the live pulse count on channel one of module 25000001

pulseCount = %%input:25000001,PC,1%%;

Result: 14

Analog Input Example

Set variable “analogValue” to the RAW analog value on channel one of module 25000001

analogValue = %%input:25000001,AI,1%%;

Result: a value between 0 and 1023 (for 10-bit web gateways)

Variable Value Example

Set variable “MyValue” to the live value of Variable 2-B of module 25000001

MyValue = %%input:25000001,V2,B%%;

Result: 23567

Note that “MyValue =” is not strictly necessary. i.e. writing

%%input:25000001,V2,B%%

would give the same result.   That being said, assigning the input to the variable MyValue makes the expression clearer to read and MyValue can be used in a subsequent formula which can greatly simplify the overall expression.

Gamma Variables

Note above that the IO-204 series have two variable types V1 and V2 while the Gamma has one type VV.

The format for the command is: %%input:(serial),(variable type),(variable number)%%

Variable types are either: V1, V2, or VV
Variable number is the 1-4, A-D, or 1-48

For example.  Referencing gamma variable 9 is:

%%input:(serial),VV,9%%

Writing a Mathematical Equation

Now that an input value has been accessed using the above operation is is a simple matter to manipulate the value using common mathematical syntax.

For example, taking

MyValue = %%input:25000001,V2,B%%;

and assuming MyValue represents 0-5 volts from a humidity sensor that happens to be scaled so that 0-5V is 0-100% humidity (as is the case with many Honeywell humidity sensors) then it is possible to convert MyValue to a humidity percentage by writing

HumidityPercentage = MyValue/1023 * 100

This simple example is one of endless expressions that can be created.  Without worrying about the details the following is an example of a non-linear equation used to scale the analog input from a voltage divider that uses a thermistor to measure temperature and shows how pre-defined variables can be used in an expression.

A1=0.003354016 B1=0.000256985 C1=0.000002620131 D1=0.00000006383091
B3=%%input:25000002,AI,1%%
DegreesC = 1/(A1+B1*log((1023-B3)/B3)+C1*(log((1023-B3)/B3))^2+D1*(log((1023-B3)/B3))^3)-273.15
%%unit:C%%%%format:1%%

The expression above includes syntax to define a unit as well as syntax to define the format of the result.  The following is a listing of the syntax that may be used in expressions:

Constants

π (pi)

pi()

Math Operations

Add

x + y

Subtract

x - y

Multiply

x * y

Divide

x / y

Modulo

x % y

Exponent

x ^ y

Square Root

sqrt(x)

Trigonometric Functions

Inputs and results use Radians

Sine

sin(x)

Cosine

cos(x)

Tangent

tan(x)

Inverse Trigonometric Functions

Inputs and results use Radians

Arcsine

asin(x)

Arccosine

acos(x)

Arctangent

atan(x)

Exponentials

Exponential Function (e^x)

exp(x)

Hyperbolic Sine

sinh(x)

Hyperbolic Cosine

cosh(x)

Logarithms

Natural (Log Base e)

ln(x)

Binary (Log Base 2)

log2(x)

Common (Log Base 10)

log(x)

Rounding

Ceiling

ceil(x)

Floor

floor(x)

Other

theta

theta(x)

theta(x)= 1 for x > 0, theta(x) = 0 for x < 0

Example

This expression limits x between variable low and variable high.

theta(high-x)*theta(x-low)*x+theta(x-high)*high+theta(low-x)*low

For example if

 low=-11; high=150; x=200 theta(high-x)*theta(x-low)*x+theta(x-high)*high+theta(low-x)*low

Result: 150

or

 low=-11; high=150; x=88; theta(high-x)*theta(x-low)*x+theta(x-high)*high+theta(low-x)*low

Result: 88

Formatting

This operation formats the end result before display by rounding the result to a specified number of digits.

%%format:[decimal places]%%

Example

Display 4 decimal places for the square root of 2

sqrt(2) %%format:4%%

Result: 1.4142

Prefixes and Units

Either prefixes or units can be displayed with a result of an expression.

%%prefix:[prefix]%%
%%unit:[unit]%%

Example

Set variable “tempF” to 34 and convert it to Celsius and display the result with 2 decimal places with the unit “C”

tempF = 34; (tempF - 32) * 5/9 %%format:2%% %%unit:C%%

Result: 1.11 C

Display currency in Dollars

value = 5.04; %%format:2%% %%prefix:$%%

Result: $5.04

Module Mapping

This operation maps the result of an expression to a module register. More than one map can be in an expression.

%%map:[Module Serial],[Input Type],[Channel / Location],[Value]%%

[Module Serial]

Module Serial Number, 8 digits

[Input Type]

2 digit input type code

  • V1 – Variable 1 – 8 bit
  • V2 – Variable 2 – 16 bit
  • PC – Pulse Count – 32 bit
  • SP – Serial Port

[Channel / Location]

1 – 4

A – D

0 is used for the on-board serial port used with input type of “SP”

[Value]

Optional

Override the expression result with a specified value

Pulse Count Example

Map the result of the expression “6 + 7” to the pulse count on channel 4 of module 25000001

6 + 7 %%map:25000001,PC,4%%

Result: 13

Scaling Data Logs using Expressions

Data Logs can be scaled using Expressions.  The values in the Data Log are referenced using the %%point%% reference in place of the “input” reference described above.  %%point%% refers to all the logged data values while %%input%% references real-time values.