Limych/ha-average

Average Sensor for Home Assistant

Please ⭐ this repo if you find it useful

Average Sensor for Home Assistant

This sensor allows you to calculate the average state for one or more sensors over a specified period. Or just the average current state for one or more sensors, if you do not need historical data.

Initially it was written special for calculating of average temperature, but now it can calculate average of any numerical data.

What makes this sensor different from others built into HA:

Compare with the min-max sensor:
This sensor in the mean mode produces exactly the same average value from several sensors. But, unlike our sensor, it cannot receive the current temperature data from a weather, climate and water heater entities.

Compare with statistics sensor:
This sensor copes with the averaging of data over a certain period of time. However… 1) it cannot work with several sources at once (and can't receive temperature from weather, climate and water heater entities, like min-max sensor), 2) when calculating the average, it does not take into account how much time the temperature value was kept, 3) it has a limit on the number of values ​​it averages - if by chance there are more values, they will be dropped.

Note:
You can find a real example of using this component in my Home Assistant configuration.

I also suggest you visit the support topic on the community forum.

Breaking changes

• Since version 2.0.0 the mechanism for specifying the unique ID of sensors has been changed. To prevent duplicate sensors from being created, add option unique_id: __legacy__ to the settings of already available sensors. For more information, see below.
  Another way is to manually delete all old sensors via Configuration > Entities. Then restart HA and all the _2’s were was the original sensors again complete with their history.
  
• Since version 1.3.0 the default sensor name is “Average” instead of “Average Temperature”

Known Limitations and Issues

• Due to the fact that HA does not store in history the temperature units of measurement for weather, climate and water heater entities, the average sensor always assumes that their values ​​are specified in the same units that are now configured in HA globally.

Installation

Install from HACS (recommended)

1. Have HACS installed, this will allow you to easily manage and track updates.
2. Search in HACS for "Average" integration or just press the button below:
   
3. Click Install below the found integration.

... then if you want to use configuration.yaml to configure sensor...

1. Add average sensor to your configuration.yaml file. See configuration examples below.
2. Restart Home Assistant

Manual installation

1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
2. If you do not have a custom_components directory (folder) there, you need to create it.
3. In the custom_components directory (folder) create a new folder called average.
4. Download file average.zip from the latest release section in this repository.
5. Extract all files from this archive you downloaded in the directory (folder) you created.

... then if you want to use configuration.yaml to configure sensor...

1. Add average sensor to your configuration.yaml file. See configuration examples below.
2. Restart Home Assistant

Configuration Examples

To measure the average of current values from multiple sources:

# Example configuration.yaml entry
sensor:
  - platform: average
    name: 'Average Temperature'
    entities:
      - weather.gismeteo
      - sensor.owm_temperature
      - sensor.dark_sky_temperature

To measure the average of all values of a single source over a period:

# Example configuration.yaml entry
sensor:
  - platform: average
    name: 'Average Temperature'
    duration:
      days: 1
    entities:
      - sensor.gismeteo_temperature

or you can combine this variants for some reason.

* * *

I put a lot of work into making this repo and component available and updated to inspire and help others! I will be glad to receive thanks from you — it will give me new strength and add enthusiasm:

or support via Bitcoin or Etherium:

16yfCfz9dZ8y8yuSwBFVfiAa3CNYdMh7Ts

Configuration Variables

entities:
(list) (Required)
A list of temperature sensor entity IDs.

Note:
You can use weather provider, climate and water heater entities as a data source. For that entities sensor use values of current temperature.

Note:
You can use groups of entities as a data source. These groups will be automatically expanded to individual entities.

unique_id
(string) (Optional)
An ID that uniquely identifies this sensor. Set this to a unique value to allow customization through the UI.

Note:
If you used the component version 1.4.0 or earlier, you can specify the special value __legacy__, so that no duplicates of already existing sensors are created.
The use of this special value in newly created sensors is not recommended.

Another way is to manually delete all old sensors via Configuration > Entities. Then restart HA and all the _2’s were was the original sensors again complete with their history.

name:
(string) (Optional)
Name to use in the frontend.
Default value: "Average"

start:
(template) (Optional)
When to start the measure (timestamp or datetime).

end:
(template) (Optional)
When to stop the measure (timestamp or datetime).

duration:
(time) (Optional)
Duration of the measure.

precision:
(number) (Optional)
The number of decimals to use when rounding the sensor state.
Default value: 2

process_undef_as:
(number) (Optional)
Process undefined values (unavailable, sensor undefined, etc.) as specified value.

By default, undefined values are not included in the average calculation. Specifying this parameter allows you to calculate the average value taking into account the time intervals of the undefined sensor values.

Note:
This parameter does not affect the calculation of the count, min and max attributes.

Average Sensor Attributes

start:
Timestamp of the beginning of the calculation period (if period was set).

end:
Timestamp of the end of the calculation period (if period was set).

sources:
Total expanded list of source sensors.

count_sources:
Total count of source sensors.

available_sources:
Count of available source sensors (for current calculation period).

count:
Total count of processed values of source sensors.

min_value:
Minimum value of processed values of source sensors.

min_datetime:
Date and time of minimum value of processed values of source sensors (if period was set).

max_value:
Maximum value of processed values of source sensors.

max_datetime:
Date and time of maximum value of processed values of source sensors (if period was set).

trending_towards:
The predicted value if monitored entities keep their current states for the remainder of the period. Requires "end" configuration variable to be set to actual end of period and not now().

Time periods

The average integration will execute a measure within a precise time period. You should provide none, only duration (when period ends at now) or exactly 2 of the following:

• When the period starts (start variable)
• When the period ends (end variable)
• How long is the period (duration variable)

As start and end variables can be either datetimes or timestamps, you can configure almost any period you want.

Duration

The duration variable is used when the time period is fixed. Different syntaxes for the duration are supported, as shown below.

# 15 seconds
duration: 15

# 6 hours
duration: 06:00

# 1 minute, 30 seconds
duration: 00:01:30

# 2 hours and 30 minutes
duration:
  # supports seconds, minutes, hours, days
  hours: 2
  minutes: 30

* * *

I put a lot of work into making this repo and component available and updated to inspire and help others! I will be glad to receive thanks from you — it will give me new strength and add enthusiasm:

or support via Bitcoin or Etherium:

16yfCfz9dZ8y8yuSwBFVfiAa3CNYdMh7Ts

Examples

Here are some examples of periods you could work with, and what to write in your configuration.yaml:

Last 5 minutes: ends right now, last 5 minutes.

duration:
  minutes: 5

Today: starts at 00:00 of the current day and ends right now.

start: '{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}'
end: '{{ now() }}'

Yesterday: ends today at 00:00, lasts 24 hours.

end: '{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}'
duration:
  hours: 24

This morning (06:00–11:00): starts today at 6, lasts 5 hours.

start: '{{ now().replace(hour=6).replace(minute=0).replace(second=0) }}'
duration:
  hours: 5

Current week: starts last Monday at 00:00, ends right now.

Here, last Monday is today as a timestamp, minus 86400 times the current weekday (86400 is the number of seconds in one day, the weekday is 0 on Monday, 6 on Sunday).

start: '{{ as_timestamp( now().replace(hour=0).replace(minute=0).replace(second=0) ) - now().weekday() * 86400 }}'
end: '{{ now() }}'

Last 30 days: ends today at 00:00, lasts 30 days. Easy one.

end: '{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}'
duration:
  days: 30

All your history starts at timestamp = 0, and ends right now.

start: '{{ 0 }}'
end: '{{ now() }}'

Note:
The Template Dev Tools page of your home-assistant UI can help you check if the values for start, end or duration are correct. If you want to check if your period is right, just click on your component, the start and end attributes will show the start and end of the period, nicely formatted.

Track updates

You can automatically track new versions of this component and update it by HACS.

Troubleshooting

To enable debug logs use this configuration:

# Example configuration.yaml entry
logger:
  default: info
  logs:
    custom_components.average: debug

... then restart HA.

Contributions are welcome!

This is an active open-source project. We are always open to people who want to use the code or contribute to it.

We have set up a separate document containing our contribution guidelines.

Thank you for being involved! 😍

Authors & contributors

The original setup of this component is by Andrey "Limych" Khrolenok.

For a full list of all authors and contributors, check the contributor's page.

This Home Assistant custom component was created and is updated using the HA-Blueprint template. You can use this template to maintain your own Home Assistant custom components.

License

creative commons Attribution-NonCommercial-ShareAlike 4.0 International License

See separate license file for full text.

---