History Statistics Sensor
The history_stats
sensor platform provides quick statistics about another component or platforms, using data from the history.
It can track how long the component has been in a specific state, in a custom time period.
Examples of what you can track:
- How long you were at home this week
- How long the lights were ON yesterday
- How long you watched TV today
Configuration
To enable the history statistics sensor, add the following lines to your configuration.yaml
:
# Example configuration.yaml entry
sensor:
- platform: history_stats
name: Lamp ON today
entity_id: light.my_lamp
state: 'on'
type: time
start: '{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}'
end: '{{ now() }}'
Configuration variables:
- entity_id (Required): The entity you want to track
- state (Required): The state you want to track
- name (Optional): Name displayed on the frontend
- type (Optional): The type of sensor:
time
,ratio
, orcount
. Defaults totime
- start: When to start the measure (timestamp or datetime).
- end: When to stop the measure (timestamp or datetime)
- duration: Duration of the measure
You have to provide exactly 2 of start
, end
and duration
.
You can use template extensions such as now()
or as_timestamp()
to handle dynamic dates, as shown in the examples below.
Sensor type
Depending on the sensor type you choose, the history_stats
component can show different values:
- time: The default value, which is the tracked time, in hours
- ratio: The tracked time divided by the length of your period, as a percentage
- count: How many times the component you track was changed to the state you track
Time periods
The history_stats
component will execute a measure within a precise time period. You should always provide 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.
# 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
Examples
Here are some examples of periods you could work with, and what to write in your configuration.yaml
:
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 (6AM - 11AM): 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() }}'
The /dev-template
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 from
and to
attributes will show the start and end of the period, nicely formatted.