comparator

Description

The comparator block compares two values and returns a boolean result true or false at the output.

The block can operate in two modes:

• comparing values from the tag1 and tag2 inputs
• comparing each received value with one constant value stored in the configuration

The block supports three comparison groups:

• boolean bool values with other bool values
• text text values with other text values
• all numeric values with each other: integer, float, temperature, percent

If the comparison cannot be performed, the output becomes null and the block description shows the reason for the error.

Configuration parameters

Parameter name	Value
Operator (operator)	Required text parameter. Allowed values are >, >=, <, <=, ==, !=. For bool and text values, only == and != are valid.
Hysteresis (hysteresis)	Required numeric parameter. It affects numeric comparisons only. A negative value is treated the same as a positive one. The parameter defines the full width of the deadband, and the block uses half of that value on each side of the switching point. For example, hysteresis = 2 means a +-1 band.
Block duplicated value (filter_duplicated_values)	Required boolean value true or false. When set to true, the block does not emit the same true or false result again. When set to false, each subsequent successful recalculation is emitted even if the result does not change. This parameter does not block repeated error emissions that end with the null value.
Compare with constant value (compare_with_const_value)	Optional text parameter. Only the value true enables comparison of the input with a constant value. If the parameter is missing or has any other value, the block stays in tag1 versus tag2 comparison mode.
Constant type (const_value_type)	Parameter required only when compare_with_const_value = true. Allowed values are bool, num, str.
Constant value (const_value)	Parameter required only when compare_with_const_value = true. For bool, it must be the text true or false. For num, it must be a non-empty numeric value different from null. For str, it must be a non-empty text value.

Input handling

The operating mode depends on the compare_with_const_value parameter.

tag1 versus tag2 comparison mode

In this mode, the block requires exactly one tag1 connection and exactly one tag2 connection. No blocks other than tag may be connected to the input.

Operating rules:

• when a change arrives from tag1, it is compared with the last known value from tag2
• when a change arrives from tag2, it is compared with the last known value from tag1
• if the other side does not yet have a last known value, the output becomes null

Constant-value comparison mode

In this mode, each received input change is compared with the const_value value.

Operating rules:

• tag2 must not be connected
• tag1 may be used as the named data input, but it is not required
• each received change is treated as the left side of the comparison, and the configured constant is treated as the right side

Input lines labeled with the tag block

Input number and name	Description
tag1: First comparison value	In two-input mode, this connection is required and provides the first compared value. In constant-value mode, it may be used as the data input, but it is not required.
tag2: Second comparison value	In two-input mode, this connection is required and provides the second compared value. In constant-value mode, it must not be connected.

Supported types and operators

• bool can be compared only with the == and != operators
• text can be compared only with the == and != operators
• integer, float, temperature, and percent can be compared with all operators
• different numeric types may be mixed; the block treats them simply as numeric values and does not verify unit compatibility

Ignored cases:

• receiving the same true or false result again when filter_duplicated_values = true
• in numeric comparisons with the > and < operators, small changes that stay inside the hysteresis band when the block already has a previously established result

Hysteresis and numeric comparisons

Hysteresis is used only for numeric comparisons.

The block calculates the absolute difference between two values and compares it with half of the hysteresis parameter.

Operating rules:

• for ==, the result is true when the difference is less than or equal to half of the hysteresis
• for !=, the result is true when the difference is greater than half of the hysteresis
• for >= and <=, values inside the hysteresis band are treated as equal, so both operators return true there
• for > and <, entering the hysteresis band does not force an immediate result change; the block keeps the previous state until the difference leaves the hysteresis band
• if > or < is evaluated for the first time and the block does not yet have a previous result, the result is calculated from a normal comparison of both values

Block outputs

The block has one output.

The output becomes:

• boolean true or false if the comparison was performed successfully
• null if the comparison cannot be performed because of a configuration error, a missing second value, null at the input, or incompatible types

Block status description

The description shown below the block takes one of the following forms:

• null before the first successful comparison
• true or false after a successful comparison
• an error message if the last comparison attempt ended with an error

Errors visible to the user

The block can show the following error messages:

Error code	Error description
Missing operator configuration.	The operator parameter is missing in the configuration or cannot be read as non-empty text.
Invalid operator configuration.	The operator parameter has a value outside the supported list.
Invalid hysteresis configuration.	The hysteresis parameter is not a valid numeric value.
Missing filter_duplicated_values configuration.	The filter_duplicated_values parameter is missing in the configuration or cannot be read as a boolean value.
Missing const_value_type configuration.	In constant-value comparison mode, the const_value_type parameter is missing.
Missing constant value configuration.	In constant-value comparison mode, the const_value parameter is missing or an empty text was provided where a non-empty text is required.
Invalid constant value configuration.	The const_value parameter has an invalid value for the selected constant type. This includes null and an unsupported boolean value.
Expected numeric constant value configuration.	For const_value_type = num, a non-numeric value was provided.
Invalid constant value type configuration.	The const_value_type parameter has a value other than bool, num, or str.
Non-tag block connected.	In tag1 versus tag2 mode, a block other than tag is connected to the input.
Multiple tag1 blocks connected.	More than one tag1 line is connected to the block.
Multiple tag2 blocks connected.	More than one tag2 line is connected to the block.
Only tag1 and tag2 blocks supported.	A tag line other than tag1 or tag2 is connected to the block.
Missing tag1 block connection.	In two-input mode, tag1 is not connected.
Missing tag2 block connection.	In two-input mode, tag2 is not connected.
Invalid tag2 connection with constant value enabled.	In constant-value comparison mode, tag2 is connected, which is not allowed.
Missing value from tag1.	A change arrived from tag2, but the block does not yet know the last value from tag1.
Missing value from tag2.	A change arrived from tag1, but the block does not yet know the last value from tag2.
Invalid tag1 value.	The first compared value is invalid.
Invalid tag2 value.	The second compared value is invalid.
Null tag1 value.	The first compared value is null.
Null tag2 value.	The second compared value is null.
Invalid operator for bool value.	An operator other than == or != was selected while both compared values are boolean.
Invalid operator for text value.	An operator other than == or != was selected while both compared values are text values.
Can't compare <typ1> with <typ2>	The block received two incompatible types, for example bool and text or integer and text.

In rare runtime inconsistency situations, defensive messages such as Missing tag1 or tag2 block connection. or Failed to get ... value. may also appear. They mean the block could not safely read one of the values required for the comparison.

Examples

• If operator = ">", hysteresis = 0, tag1 = 23, and tag2 = 20, the output becomes true.
• If operator = "==", hysteresis = 1.0, tag1 = 20.0, and tag2 = 20.4, the output becomes true because the difference 0.4 is inside the +-0.5 band.
• If operator = ">", hysteresis = 2, and the previous result was already true for the values 22 and 20, then a later change to 21 and 20.4 does not switch the result because the difference still stays inside the +-1 band.
• If compare_with_const_value = "true", const_value_type = "str", const_value = "auto", and the text auto arrives at the input, the == comparison result becomes true.
• If you choose the > operator for comparing two boolean values, the block shows the Invalid operator for bool value. error and emits null at the output.