Entity Attribute Condition

An Entity Attribute condition reacts to a change the value of an attribute on an entity. Whenever an entity changes, the rule re-evaluates the condition, and applies any changes in the result to the condition's parent group.

Every entity stores values in attributes. To create a Entity Attribute condition, you select the entity you want to watch and the attribute that should be watched, and set the operator and value appropriate to the test. For example, if entity "motion_sensor_17" was a motion sensor, when you select that entity from the list, the attribute list will update to show the list of attributes defined for the capabilities of the entity. One of these will be binary_sensor.state, which is the tripped condition of the motion sensor, so you would choose that. You would then choose the operator "is TRUE" to see if the sensor is tripped.

Operators

The operator specifies what kind of test is performed on the attribute's value: equality, inequality, string match, etc. An operator may have operands, the values against which the operation is performed. For example, the between operator takes two operands: the low and high values of the range to match.

The operators should be fairly straight-forward to interpret, but there are a few special ones worth mentioning, and some special cases for the operands:

• Relational operators >, >=, <, and <= operators require that the attribute value and operand be numeric; if the attribute value or operand is non-numeric, the result is always false;
• The is TRUE operator is satisfied when the attribute value is a non-zero number or any of the strings "y", "yes", "t" or "true" (case-insensitive). The is FALSE is satisfied when the value is zero (number) or not one of the foregoing strings. The is NOT TRUE operator is satisfied when the attribute value is false (equivalent) or null, and the is NOT FALSE operator is satisfied when the attribute value is true (equivalent) or null;
• The in operator checks to see if the attribute value (as a string) is one of values listed in the comma-separated list contained in the operand. It will be true if a matching value is found, false otherwise; not in is the inverse;
• The is EMPTY/is NOT EMPTY operators check the attribute value for emptiness. Empty values are: strings of zero length or only whitespacee; arrays of zero length (contain no elements); objects with no key/value pairs; and null.
• The changes operator can operate with terminal values, or without. A blank terminal operand means "any value". If both terminal values are missing, the condition will pulse true briefly and reset itself.

Note

Unlike most operators, changes produces a (very rapidly) pulsed output rather than a continuous state. The default pulse length is less than one second. This is often too fast to be seen in the UI, so if you use this operator, you may not be able to catch it working. However, its operation can be confirmed by any related reactions being run. You may also stretch out the pulse time using a delay reset condition option. Just be aware that long reset delays "desensitize" the condition to multiple rapid changes in the tested attribute, because repeats inside the delay period will not trigger additional pulses. That may or may not be significant to your logic--only you can know. If in doubt, use a reset delay for debugging, but remove it for "production" use. Another good way to tell if it's working is to notice the "as of" time on the condition (which will reflect the latest change triggering).

Substitutions - Using Expressions as Operands

Most operators take one or two operands. For example, the == operator takes one operand, while the between operator takes two. Operands entered into the input field(s) are treated as constants, but it is also possible to use a substitution in the operand field(s): ${{ expression }}. This syntax is used in many places in Reactor, and it means that the value of the operand will be the result of the expression. One of the simplest expressions is the name of the local (rule) or global variable by itself, and results in the value of that variable (e.g. ${{ my_global_varname }} will be replaced in the condition with the current value of the global variable).

Expressions can produce more types than strings and numbers; they can also produce boolean values (true and false), arrays, objects, and null. Some of the operators treat these specially (or not), so please note the following:

• For the in and not in operators, if the operand is an object, the condition will be true if the entity attribute value exists as a key in the object; if the operand is an array, the condition will be true if the attribute value exists as an element of the array.
• Comparison of objects and arrays using == (equals) and <> (not equals) will perform a deep comparison. For arrays to be equal, they must contain contents in the identical order. For objects to be equal, they must contain identical key/value pairs (order of keys is not significant in objects).
• For equality/inequality of primitive types (strings, numbers, and booleans), when the type of the attribute value and the operand are not the same, an attempt is made to coerce the operand to the type of the attribute, and the comparison then made. For example, if the attribute value is 64 and the result of the operand substitution expression produces the string "64", the string will be coerced to a number (they'll be reported as equal). Likewise an attribute value of false compared to the numeric value 0 would be seen as equal, and an attribute value of true compared to any non-zero value would also be considered equal.

Condition Options

Entity Attribute conditions support most of the condition options available. Condition options modify the behavior of the condition when the test state changes. For example, the "Sustained For" condition option, when set, requires that the test remain true for a configurable period of time before the condition state goes true.

Please see the Condition Options page for detail on the available condition options and usage examples.

Updated 2023-Apr-03