Contents
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 05 V value is converted to a “RAW” scale most often between 0 and 1023. This socalled 10bit conversion (2^10 = 1024) is common in microcontrollers 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 nonlinear like the thermistor used in the ioBridge temperature sensor. In the case of the humidity and temperature sensors, ioBridge includes precalculated scales to present the RAW readings in more meaningful ways. This is not the case though with thirdparty 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 01023 (in the case of 10bit 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
148 (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 10bit web gateways)
Variable Value Example
Set variable “MyValue” to the live value of Variable 2B 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 IO204 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 14, AD, or 148
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 05 volts from a humidity sensor that happens to be scaled so that 05V is 0100% 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 nonlinear equation used to scale the analog input from a voltage divider that uses a thermistor to measure temperature and shows how predefined 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((1023B3)/B3)+C1*(log((1023B3)/B3))^2+D1*(log((1023B3)/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(highx)*theta(xlow)*x+theta(xhigh)*high+theta(lowx)*low
For example if
low=11; high=150; x=200 theta(highx)*theta(xlow)*x+theta(xhigh)*high+theta(lowx)*low
Result: 150
or
low=11; high=150; x=88; theta(highx)*theta(xlow)*x+theta(xhigh)*high+theta(lowx)*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 onboard 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 realtime values.