core/homeassistant/components/sensor/statistics.py

302 lines
11 KiB
Python

"""
Support for statistics for sensor values.
For more details about this platform, please refer to the documentation at
https://home-assistant.io/components/sensor.statistics/
"""
import logging
import statistics
from collections import deque
import voluptuous as vol
import homeassistant.helpers.config_validation as cv
from homeassistant.components.sensor import PLATFORM_SCHEMA
from homeassistant.const import (
CONF_NAME, CONF_ENTITY_ID, EVENT_HOMEASSISTANT_START, STATE_UNKNOWN,
ATTR_UNIT_OF_MEASUREMENT)
from homeassistant.core import callback
from homeassistant.helpers.entity import Entity
from homeassistant.helpers.event import async_track_state_change
from homeassistant.util import dt as dt_util
from homeassistant.components.recorder.util import session_scope, execute
_LOGGER = logging.getLogger(__name__)
ATTR_AVERAGE_CHANGE = 'average_change'
ATTR_CHANGE = 'change'
ATTR_CHANGE_RATE = 'change_rate'
ATTR_COUNT = 'count'
ATTR_MAX_AGE = 'max_age'
ATTR_MAX_VALUE = 'max_value'
ATTR_MEAN = 'mean'
ATTR_MEDIAN = 'median'
ATTR_MIN_AGE = 'min_age'
ATTR_MIN_VALUE = 'min_value'
ATTR_SAMPLING_SIZE = 'sampling_size'
ATTR_STANDARD_DEVIATION = 'standard_deviation'
ATTR_TOTAL = 'total'
ATTR_VARIANCE = 'variance'
CONF_SAMPLING_SIZE = 'sampling_size'
CONF_MAX_AGE = 'max_age'
CONF_PRECISION = 'precision'
DEFAULT_NAME = 'Stats'
DEFAULT_SIZE = 20
DEFAULT_PRECISION = 2
ICON = 'mdi:calculator'
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
vol.Required(CONF_ENTITY_ID): cv.entity_id,
vol.Optional(CONF_NAME, default=DEFAULT_NAME): cv.string,
vol.Optional(CONF_SAMPLING_SIZE, default=DEFAULT_SIZE):
vol.All(vol.Coerce(int), vol.Range(min=1)),
vol.Optional(CONF_MAX_AGE): cv.time_period,
vol.Optional(CONF_PRECISION, default=DEFAULT_PRECISION):
vol.Coerce(int)
})
async def async_setup_platform(hass, config, async_add_entities,
discovery_info=None):
"""Set up the Statistics sensor."""
entity_id = config.get(CONF_ENTITY_ID)
name = config.get(CONF_NAME)
sampling_size = config.get(CONF_SAMPLING_SIZE)
max_age = config.get(CONF_MAX_AGE, None)
precision = config.get(CONF_PRECISION)
async_add_entities([StatisticsSensor(entity_id, name, sampling_size,
max_age, precision)], True)
return True
class StatisticsSensor(Entity):
"""Representation of a Statistics sensor."""
def __init__(self, entity_id, name, sampling_size, max_age,
precision):
"""Initialize the Statistics sensor."""
self._entity_id = entity_id
self.is_binary = self._entity_id.split('.')[0] == 'binary_sensor'
if not self.is_binary:
self._name = '{} {}'.format(name, ATTR_MEAN)
else:
self._name = '{} {}'.format(name, ATTR_COUNT)
self._sampling_size = sampling_size
self._max_age = max_age
self._precision = precision
self._unit_of_measurement = None
self.states = deque(maxlen=self._sampling_size)
self.ages = deque(maxlen=self._sampling_size)
self.count = 0
self.mean = self.median = self.stdev = self.variance = None
self.total = self.min = self.max = None
self.min_age = self.max_age = None
self.change = self.average_change = self.change_rate = None
async def async_added_to_hass(self):
"""Register callbacks."""
@callback
def async_stats_sensor_state_listener(entity, old_state, new_state):
"""Handle the sensor state changes."""
self._unit_of_measurement = new_state.attributes.get(
ATTR_UNIT_OF_MEASUREMENT)
self._add_state_to_queue(new_state)
self.async_schedule_update_ha_state(True)
@callback
def async_stats_sensor_startup(event):
"""Add listener and get recorded state."""
_LOGGER.debug("Startup for %s", self.entity_id)
async_track_state_change(
self.hass, self._entity_id, async_stats_sensor_state_listener)
if 'recorder' in self.hass.config.components:
# Only use the database if it's configured
self.hass.async_create_task(
self._async_initialize_from_database()
)
self.hass.bus.async_listen_once(
EVENT_HOMEASSISTANT_START, async_stats_sensor_startup)
def _add_state_to_queue(self, new_state):
"""Add the state to the queue."""
if new_state.state == STATE_UNKNOWN:
return
try:
if self.is_binary:
self.states.append(new_state.state)
else:
self.states.append(float(new_state.state))
self.ages.append(new_state.last_updated)
except ValueError:
_LOGGER.error("%s: parsing error, expected number and received %s",
self.entity_id, new_state.state)
@property
def name(self):
"""Return the name of the sensor."""
return self._name
@property
def state(self):
"""Return the state of the sensor."""
return self.mean if not self.is_binary else self.count
@property
def unit_of_measurement(self):
"""Return the unit the value is expressed in."""
return self._unit_of_measurement if not self.is_binary else None
@property
def should_poll(self):
"""No polling needed."""
return False
@property
def device_state_attributes(self):
"""Return the state attributes of the sensor."""
if not self.is_binary:
return {
ATTR_SAMPLING_SIZE: self._sampling_size,
ATTR_COUNT: self.count,
ATTR_MEAN: self.mean,
ATTR_MEDIAN: self.median,
ATTR_STANDARD_DEVIATION: self.stdev,
ATTR_VARIANCE: self.variance,
ATTR_TOTAL: self.total,
ATTR_MIN_VALUE: self.min,
ATTR_MAX_VALUE: self.max,
ATTR_MIN_AGE: self.min_age,
ATTR_MAX_AGE: self.max_age,
ATTR_CHANGE: self.change,
ATTR_AVERAGE_CHANGE: self.average_change,
ATTR_CHANGE_RATE: self.change_rate,
}
@property
def icon(self):
"""Return the icon to use in the frontend, if any."""
return ICON
def _purge_old(self):
"""Remove states which are older than self._max_age."""
now = dt_util.utcnow()
_LOGGER.debug("%s: purging records older then %s(%s)",
self.entity_id, dt_util.as_local(now - self._max_age),
self._max_age)
while self.ages and (now - self.ages[0]) > self._max_age:
_LOGGER.debug("%s: purging record with datetime %s(%s)",
self.entity_id, dt_util.as_local(self.ages[0]),
(now - self.ages[0]))
self.ages.popleft()
self.states.popleft()
async def async_update(self):
"""Get the latest data and updates the states."""
_LOGGER.debug("%s: updating statistics.", self.entity_id)
if self._max_age is not None:
self._purge_old()
self.count = len(self.states)
if not self.is_binary:
try: # require only one data point
self.mean = round(statistics.mean(self.states),
self._precision)
self.median = round(statistics.median(self.states),
self._precision)
except statistics.StatisticsError as err:
_LOGGER.debug("%s: %s", self.entity_id, err)
self.mean = self.median = STATE_UNKNOWN
try: # require at least two data points
self.stdev = round(statistics.stdev(self.states),
self._precision)
self.variance = round(statistics.variance(self.states),
self._precision)
except statistics.StatisticsError as err:
_LOGGER.debug("%s: %s", self.entity_id, err)
self.stdev = self.variance = STATE_UNKNOWN
if self.states:
self.total = round(sum(self.states), self._precision)
self.min = round(min(self.states), self._precision)
self.max = round(max(self.states), self._precision)
self.min_age = self.ages[0]
self.max_age = self.ages[-1]
self.change = self.states[-1] - self.states[0]
self.average_change = self.change
self.change_rate = 0
if len(self.states) > 1:
self.average_change /= len(self.states) - 1
time_diff = (self.max_age - self.min_age).total_seconds()
if time_diff > 0:
self.change_rate = self.average_change / time_diff
self.change = round(self.change, self._precision)
self.average_change = round(self.average_change,
self._precision)
self.change_rate = round(self.change_rate, self._precision)
else:
self.total = self.min = self.max = STATE_UNKNOWN
self.min_age = self.max_age = dt_util.utcnow()
self.change = self.average_change = STATE_UNKNOWN
self.change_rate = STATE_UNKNOWN
async def _async_initialize_from_database(self):
"""Initialize the list of states from the database.
The query will get the list of states in DESCENDING order so that we
can limit the result to self._sample_size. Afterwards reverse the
list so that we get it in the right order again.
If MaxAge is provided then query will restrict to entries younger then
current datetime - MaxAge.
"""
from homeassistant.components.recorder.models import States
_LOGGER.debug("%s: initializing values from the database",
self.entity_id)
with session_scope(hass=self.hass) as session:
query = session.query(States)\
.filter(States.entity_id == self._entity_id.lower())
if self._max_age is not None:
records_older_then = dt_util.utcnow() - self._max_age
_LOGGER.debug("%s: retrieve records not older then %s",
self.entity_id, records_older_then)
query = query.filter(States.last_updated >= records_older_then)
else:
_LOGGER.debug("%s: retrieving all records.", self.entity_id)
query = query\
.order_by(States.last_updated.desc())\
.limit(self._sampling_size)
states = execute(query)
for state in reversed(states):
self._add_state_to_queue(state)
self.async_schedule_update_ha_state(True)
_LOGGER.debug("%s: initializing from database completed",
self.entity_id)