A calculated tag is evaluated by the server within the current Runtime Unit. It combines existing live inputs into a numeric or Boolean result. It does not connect to a PLC, write to inputs, or execute scripts. Editing, publishing, enabling, and runtime diagnostics remain separate for controlled operation.
- Suitable for power or unit conversion, combined run conditions, interlock state, and simple conditional selection.
- The result type is
number or boolean.
- Inputs must be local IO TagRefs in the current Runtime Unit or published calculated TagRefs.
- Remote inputs, time windows, Average / Min / Max / Counter, Link, and script execution are not supported.
- In Phase 1, inspect runtime values in Calculated Tags or through the dedicated value endpoint. Do not assume they are already available through ordinary tags, screens, alarms, trends, or the IO State API.
- Open Tag Management → Calculated Tags and select New.
- Enter a stable, meaningful code such as
<calculated-tag-code>, then select the result type.
- Give each input a meaningful alias, such as
line_voltage, line_current, and power_factor.
- Select the canonical TagRef from the catalog and declare its value type. A definition accepts at most 32 inputs.
# Local IO input
hq://io/<io-domain-id>/<device-uid>/<tag-uid>
# Published calculated-tag input
hq://calc/<runtime-unit-id>/<calculated-tag-uid>
Expressions support numeric and Boolean constants, arithmetic, comparisons, logic, conditional selection, if, and abs. An input alias becomes the variable in the expression and must match exactly.
- Arithmetic:
+ - * / %
- Comparison:
== != < <= > >=
- Logic:
&& || !
- Conditional:
condition ? yes : no or if(condition, yes, no)
- Function:
abs(value)
# Business power conversion
line_voltage * line_current * power_factor / 1000
# Run-permitted state
run_command && !fault_active
# Conditional shaft-power estimate
if(motor_running && motor_speed > 0, abs(motor_torque) * motor_speed / 9550, 0)
An expression is limited to 2048 bytes, 256 AST nodes, 32 levels of depth, and 512 evaluation steps. Keep each definition small enough to review as one clear business calculation.
- Run server validation first to check aliases, types, references, syntax, and the cost preview.
- Save a draft after validation. A draft remains editable and does not automatically run.
- Publish an immutable generation that records the exact version intended for runtime.
- Enable the reviewed generation, then inspect its value, quality, evaluation time, and diagnostics.
Input quality propagates to the result. Short-circuit logic and conditional expressions propagate quality only from the branch that is actually evaluated. Division by zero, modulo by zero, or a non-finite result produces calculation_error. Inspect diagnostics, edit the draft, and publish a new generation.
For production, assign editing, publishing, and enabling according to operational responsibility, and ensure that inputs, expression, and result type are reviewed before publication.
calculated-tag:view: view definitions, runtime values, and diagnostics.calculated-tag:manage: create and edit drafts.calculated-tag:publish: publish immutable generations.calculated-tag:enable: enable or disable a runtime generation.
