Formula language

Calc parameters (parameter sources), value-type transforms (value types), the expressions in automations and alarm rules, and the values of document dashboards are formulas in one language. Setup, push and hmi check reject a formula that does not compile. Problems that depend on the values, such as division by zero, fail when the formula is evaluated.

if(#1 * #2 >= 101, 1, 0.1)
floor(#1 / 256) + (#1 % 256) / 10
x * 0.1 - 40

Inputs

Name	Where	Type
#1 … #n	Calc formulas: the inputs in inputParamIds order	number
x (and #1)	Transforms: the scaled number read, or the value written	number
Variable names	Automations and alarm rules: their variables, such as level	the variable’s type
Names	Documents: their variables and source values	the value’s type

A calc input that is a boolean is 1 or 0. A calc formula gives a number or a boolean (true is stored as 1). A transform gives a number.

Values

Type	Literals	Notes
number	42, -1.5, .5, 2.5e-3, 0xFF	64-bit floating point
boolean	true, false
string	'text', "text"	Escapes: \\, \', \", \n, \t
duration	500ms, 30s, 5min, 2h, 1d	1.5h is 90 minutes; no space before unit
timeOfDay	07:30, 23:59:59	Wall-clock time, 00:00 to 23:59:59
instant	none; from now(), sunrise() and inputs	A point in time

There is no implicit multiplication: 2pi, #1#2 and 2(#1) are errors, and 2 * pi is the product.

The constants pi and e are numbers. The names and, or, not, true, false, pi and e are reserved.

Operators

From lowest to highest precedence:

Operators	Operands
or	booleans
and	booleans
not	boolean
== !=	two values of the same type
< <= > >=	two numbers, durations, instants or times of day; comparisons do not chain
+ -	numbers; durations; instant ± duration; timeOfDay ± duration (wraps at midnight)
* / %	numbers; duration × number; duration ÷ number; duration ÷ duration is a number
unary -	number or duration
^	numbers, right to left: 2 ^ 3 ^ 2 is 2 ^ 9; -2 ^ 2 is -4

Also: + joins two strings; instant − instant and timeOfDay − timeOfDay give a duration; % keeps the sign of the left operand (-7 % 3 is -1). n * 1s turns a number of seconds into a duration, and d / 1min turns a duration into a number of minutes.

Functions

Editors show each function’s signature and a line about it as you type; these sections explain them.

Conditions and unknown values

Function	Result
if(condition, then, else)	then or else, which must have the same type; only the chosen one runs
isKnown(value)	false when the value is unknown
coalesce(a, b, …)	The first known value

Numbers

Function	Result
abs sign floor ceil trunc sqrt exp ln log10	Number functions of one number (abs also takes a duration)
round(n), round(n, digits)	Halves round away from zero: round(-2.5) is -3
min(a, b, …), max(a, b, …), clamp(value, low, high)	Numbers, durations, instants or times of day, all of one type
pow(base, exponent)	Same as ^

Angles

Function	Result
sin cos tan asin acos atan atan2(y, x)	Radians
sinh cosh tanh asinh acosh atanh
deg(radians), rad(degrees)	Angle conversion

Bits

Function	Result
bitAnd bitOr bitXor shiftLeft shiftRight (two numbers)	Non-negative integers up to 2⁵³ − 1
bit(value, index)	Whether bit index (0 is the lowest) is set

Text

Function	Result
text(value), text(number, decimals)	Text: 1h 30min, 07:05, 2026-03-29 03:30:00, 12.50
number(text)	The number in the text, or unknown when it is not one
len lower upper trim (one string), contains(text, part)	String functions

Times of day

Function	Result
time(hour, minute), time(hour, minute, second)	A time of day

Formatting

These give text for people, in a locale: the viewer’s language in a document, English elsewhere. decimals is 0–15.

Function	Result
formatNumber(n), formatNumber(n, decimals)	Grouped digits, up to two decimals or exactly decimals: 1,234.57
formatCurrency(n, code), formatCurrency(n, code, decimals)	An amount in an ISO 4217 currency such as "EUR": €1,234.50
formatPercent(fraction), formatPercent(fraction, decimals)	A share: formatPercent(0.256) is 25.6%

A currency code that is not three letters fails with invalid_argument.

Clock and calendar

These read the clock, the workspace timezone or location. Calc formulas and transforms cannot use them; they are for automations, alarm rules and documents.

Function	Result
now()	The current instant
timeOfDay(), timeOfDay(instant)	Wall-clock time in the workspace timezone
weekday(), weekday(instant)	1 for Monday to 7 for Sunday
day(), month(), year() (or of an instant)	Calendar date parts
sunrise(), sunset() (or of an instant’s date)	Instant of sunrise or sunset at the workspace location

Without a workspace location, sunrise() and sunset() fail with location_required. On a day the sun does not rise or set, they are unknown.

Unknown values

An input that is stale, unavailable or not set is unknown. Unknown spreads through operators and functions, with three exceptions:

• false and unknown is false, true or unknown is true. Otherwise and, or and not with an unknown operand are unknown.
• if(unknown, a, b) is unknown: no branch is taken.
• isKnown and coalesce see unknown values and replace them.

Calc parameters and transforms always have known inputs; a failed input fails the reading instead.

Errors

Compile errors carry a code and the character range of the problem:

Code	Meaning
empty_formula, unexpected_character, unexpected_token, unexpected_end, missing_closing_parenthesis, unterminated_string	Syntax
invalid_number, invalid_time_of_day	A malformed literal
chained_comparison	a < b < c; comparisons do not chain
too_deep	More than 64 levels of nesting
unknown_name, unknown_function, not_a_function	A name the formula cannot use
placeholder_out_of_range	#n beyond the inputs
argument_count, argument_types, operand_types, result_type	Wrong number or types of values
time_unavailable	A clock function where there is no clock

Evaluation errors: division_by_zero, not_finite (overflow, sqrt(-1), ln(0)), invalid_argument (for example bitAnd(-1, 1) or time(25, 0)) and location_required. In calc parameters and transforms they surface as formula_error.

Examples

Formula	Result
floor(#1 / 256) + (#1 % 256) / 10	A major.minor version packed in one word: 1.1 from 257
if(#1 * #2 >= 101, 1, 0.1)	One of two values, chosen by a condition
#1 > 80 and #2 == 0	A status from two inputs; a calc parameter stores it as 1 or 0
x * 0.1 - 40	A transform: scale and offset of the number read

Two values from one register, such as its high and low bytes, are two Modbus parameters with filterBytes (value types), not a formula.

Older syntax equivalents

The language does not accept the syntax of the older formula evaluator. A formula from an old archive or setup.db in that syntax does not compile. The equivalents are:

Older syntax	Now
a Mod b	a % b
int(x)	floor(x)
root(x)	sqrt(x)
log(x) (base 10)	log10(x)
sin(x), degrees	sin(rad(x))
asin(x), degrees	deg(asin(x))
2(x), #1 #2	2 * (x), #1 * #2
root 4	sqrt(4)

In code

@overvis/hmi-shared/expression compiles and evaluates formulas in browsers, the CLI and services:

import { compileExpression, UNKNOWN } from "@overvis/hmi-shared/expression";

const result = compileExpression("level > limit and running", {
  variables: { level: "number", limit: "number", running: "boolean" },
  result: ["boolean"],
});
if (!result.ok) throw new Error(result.diagnostics[0]?.code);
result.expression.evaluate({ variables: { level: 7, limit: 5, running: UNKNOWN } }); // UNKNOWN

ExpressionScope declares the #n count, named variables with their types, whether clock functions are allowed (time: true), and the accepted result types. evaluate takes the input values, the current instant, the timezone (UTC by default), the location, and the locale of the formatting functions (en by default). Instants, durations and times of day are milliseconds. describeExpressionDiagnostic gives English text for logs; user interfaces translate the diagnostic code with its args.