Expression Editor

The ControlCom platform includes a powerful expression editor that allows you to create dynamic calculations and logic in various components like dashboards and diagrams.

Overview

The expression editor enables you to write freeform expressions that can reference device variables, perform calculations, and apply logical operations. Expressions are evaluated in real-time as data updates, making your dashboards and diagrams truly dynamic.

Basic Usage

Expressions can be used in:

Dashboard Components: For calculated values, conditional formatting, and dynamic content
Diagram Elements: For status indicators, calculated displays, and conditional visibility
Virtual Variables: For creating computed data points based on existing variables

Syntax

Expressions use a straightforward syntax that supports mathematical operations, logical conditions, and function calls:

{{variable1}} + {{variable2}} * 2

Variables

Reference device variables in your expressions by wrapping them in double curly braces:

Variable Syntax

{{deviceId.variableId}}

Variable Types

Number: Numeric values that support mathematical operations
String: Text values that can be concatenated and compared
Boolean: True/false values for logical operations

Operators

Arithmetic Operators

Operator	Description	Example
`+`	Addition	`{{temp1}} + {{temp2}}`
`-`	Subtraction	`{{temp1}} - {{temp2}}`
`*`	Multiplication	`{{power}} * 1.5`
`/`	Division	`{{total}} / {{count}}`
`%`	Remainder	`{{value}} % 10`
`^`	Exponentiation	`{{base}} ^ 2`

Comparison Operators

Operator	Description	Example
`==`	Equal to	`{{status}} == "online"`
`!=`	Not equal to	`{{status}} != "offline"`
`<`	Less than	`{{temp}} < 75`
`<=`	Less than or equal	`{{temp}} <= 75`
`>`	Greater than	`{{temp}} > 85`
`>=`	Greater than or equal	`{{temp}} >= 85`

Logical Operators

Operator	Description	Example
`and`	Logical AND	`{{temp}} > 70 and {{temp}} < 90`
`or`	Logical OR	`{{status}} == "alarm" or {{status}} == "warning"`
`not`	Logical NOT	`not {{maintenance}}`

Unary Operators

Operator	Description	Example
`-`	Negation	`-{{value}}`
`+`	Positive	`+{{value}}`
`abs`	Absolute value	`abs {{difference}}`
`sqrt`	Square root	`sqrt {{area}}`
`ceil`	Round up	`ceil {{value}}`
`floor`	Round down	`floor {{value}}`

Mathematical Functions

Basic Math Functions

min(a, b, ...) - Returns the smallest value
max(a, b, ...) - Returns the largest value
pow(base, exponent) - Raises base to the power of exponent
random() - Returns a random number between 0 and 1

Trigonometric Functions

sin(x) - Sine function
cos(x) - Cosine function
tan(x) - Tangent function
asin(x) - Arcsine function
acos(x) - Arccosine function
atan(x) - Arctangent function
atan2(y, x) - Two-argument arctangent

Logarithmic Functions

ln(x) - Natural logarithm
log(x) - Natural logarithm (alias for ln)
log10(x) - Base-10 logarithm

Utility Functions

round(x) - Rounds to nearest integer
sign(x) - Returns -1, 0, or 1 based on sign
hypot(a, b, ...) - Euclidean distance (hypotenuse)

Logical Functions

Conditional Function

The if function provides conditional logic:

if(condition, value_if_true, value_if_false)

Examples:

if({{temperature}} > 80, "Hot", "Normal")
if({{status}} == "online", 1, 0)
if({{power}} > 100, {{power}} * 0.9, {{power}})

Ternary Operator

You can also use the ternary conditional operator:

{{temperature}} > 80 ? "Hot" : "Normal"

Array Functions

When working with arrays or multiple values:

Array Operations

map(array, expression) - Transform each element
filter(array, condition) - Filter elements by condition
fold(array, initial, expression) - Reduce array to single value
indexOf(array, value) - Find index of value
join(array, separator) - Join array elements into string
length(array) - Get array length

Constants

Pre-defined constants available in expressions:

Mathematical Constants

PI - π (3.14159...)
E - Euler's number (2.71828...)

Boolean Constants

true - Boolean true value
false - Boolean false value

Best Practices

Performance

Keep expressions simple when possible
Avoid complex nested calculations in frequently updated components
Use parentheses to clarify operator precedence

Readability

Use descriptive variable names
Break complex expressions into multiple simpler ones
Add comments in dashboard configurations to explain complex logic

Error Handling

Test expressions with edge cases (null values, zero division)
Use conditional checks before mathematical operations
Provide fallback values for unreliable data sources

Examples

Temperature Monitoring

// Temperature status indicator
if({{sensor.temperature}} > 85, "Critical", 
   if({{sensor.temperature}} > 75, "Warning", "Normal"))

// Temperature in Fahrenheit from Celsius
{{sensor.tempC}} * 9/5 + 32

Power Calculations

// Power efficiency percentage
({{generator.actualPower}} / {{generator.ratedPower}}) * 100

// Total power consumption
{{load1.power}} + {{load2.power}} + {{load3.power}}

// Power factor calculation
{{realPower}} / sqrt({{realPower}}^2 + {{reactivePower}}^2)

Status Logic

// System health indicator
if({{device.online}} and {{device.errors}} == 0, "Healthy", 
   if({{device.online}}, "Degraded", "Offline"))

// Alarm condition
{{temperature}} > 90 or {{pressure}} > 150 or not {{safety.ok}}

Time-based Calculations

// Runtime hours from milliseconds
{{runtime.totalMs}} / (1000 * 60 * 60)

// Efficiency over time
{{totalOutput}} / {{totalInput}} * 100

Complex Conditional Logic

// Multi-tier alarm severity
if({{criticalAlarms}} > 0, "Critical",
   if({{majorAlarms}} > 0, "Major",
      if({{minorAlarms}} > 0, "Minor", "Normal")))

// Load balancing calculation
if({{load}} > {{capacity}} * 0.8, 
   "Reduce Load", 
   if({{load}} < {{capacity}} * 0.3, "Increase Load", "Optimal"))