Here are the docs for what I have built thus far. Comments and suggestions on functionality appreciated!
Custom Attributes
In addition to setting the primary attribute for a dynamic group, users may add custom attributes to the group. The values of these custom attributes are typically derived from attribute values of the group's members. For example, a group of temperature sensors can have a calculated average of the readings of all the sensors.
Custom attributes are defined under the calculate: object in a group's configuration. Here's a possible configuration for the example given above as a group with ID temp_sensors. The select configuration simply selects all entities having the temperature_sensor capability, for illustration purposes (in practice, we'd probably want to include_entity some specific entities for this purpose).
temp_sensors:
select:
- include_capability: temperature_sensor
calculate:
- attribute: 'temperature_sensor.value'
source:
attribute: temperature_sensor.value # Where to get data values
op: average
This is the most basic form of custom attribute configuration. The calculate object is an array of configuration objects. The attribute key is required for each array element and specifies the attribute to be defined and calculated on the group. The source substructure tells DynamicGroupController what attributes on the member entities should be used for calculation. Any member entity that does not have the specified source attribute, or for which the attribute's value is null, is simply ignored. The op tells DGC how to reduce (or aggregate) the multiple values from the member entities down to a single value. Pre-defined operations for op are defined below:
op |
Type |
Description |
average, avg, mean |
numeric |
The average (arithmetic mean) of the available values. |
median |
numeric |
The median of the available values (i.e. the middle value of the values when sorted). |
min, max |
numeric |
The minimum or maximum of the available values. |
sum |
numeric |
The sum of the available values. |
count |
numeric |
Count of non-null values. |
and, nand |
boolean |
Logical AND of available values. All values must be boolean true for the result to be true. If nand is used, the result is inverted (i.e. false when all values are true) |
or, nor |
boolean |
Logical OR of available values. If any value is true, the result is true. nor inverts the results (false when any value is true) |
xor, xnor |
boolean |
Logical XOR. Since more than two values may be considered, this operation is only true when exactly one of the values is true. If multiple are true, or all are false, the result is false. The xnor inverts the result. |
first |
string |
Given a string or an array of strings to match in a value key (at the same level as op), this operation returns the first matching value. That is, each element of value is checked to see if it matches a source value from any of the group's member entities; if so, that element/value is the result; if not, the test moves on to the next element. If no match, null results. |
!!! note "null Member Attribute Values"
All of the above operations ignore null values from the source, unless otherwise indicated.
There may be circumstances where the source values require some pre-conditioning or filtering. This is enabled by the value_expr subkey under source. The result of the expression is the value that will be added to the array of values for op or reduce_expr. For example, in our temperature sensor group, some of the sensors return temperatures in Celsius, and others in Fahrenheit. We can use value_expr to convert the values to a consistent unit, so that the resulting reduction operation yields a consistent value in that same unit:
temp_sensors:
select:
- include_capability: temperature_sensor
calculate:
- attribute: 'temperature_sensor.value'
source:
attribute: temperature_sensor.value # Where to get data values
# Convert Celsius temperatures to Fahrenheight
value_expr: >
local units = entity.attributes.temperature_sensor.units;
local d = ( units === 'C' || units === '°C' ) ? value * 1.8 + 32 : value;
( d <= 0 || indexOf( ['C','F','°C','°F'], units ) < 0 ) ? null : d
op: average
prec: 2 # two decimal digit max result
Step by step, the value_expr above first fetches the member entity's temperature units into a local variable called units. Since the attribute under source is temperature_sensor.value, the context variable value will contain the raw value from that attribute. The second line of the expression then checks if the units are Celsius, and if so, converts them to Fahrenheit (if units are not Celsius, it just takes the current value) and assigns it to a local variable d. Finally (third line of the expression), if the value is in range and the units are known, the value of d is returned, otherwise null. As stated above, most of the predefined operations ignore null values in their computation. So value_expr can function both to condition values and to filter them.
The prec key allows you to define the number of decimal digits precision for the result value; the result is rounded to comply. For example, a calculated value of 3.14159265 with prec: 4 results in 3.1416.
If none of the pre-defined operations addresses the need, the op: key can be replaced with an expression defined by reduce_expr:. The result value of the expression will be the value assigned to the custom attribute. The context for reduce_expr includes the following variables: group refers to the group entity being defined; members is an array of canonical IDs of the member entities at the time of evaluation (which may change in a truly dynamic group); and values is an array of the member values (as derived from source).
temp_sensors:
select:
- include_capability: temperature_sensor
calculate:
- attribute: 'temperature_sensor.value'
source:
attribute: temperature_sensor.value # Where to get data values
# Compute harmonic mean (not predefined) using expression (trivialized for illustration)
reduce_expr: >
local s = 0;
each v of values: do
s = s + (1.0 / v)
done;
len(values) / s
prec: 2 # two decimal digit max result
Finally, custom attributes that should have fixed values can be defined by simply supplying value: under source:, like this:
- attribute: 'temperature_sensor.units'
source:
value: '°F'
Make sure the data type of the value configured matches the expected type of attribute being defined.
