|
| 1 | +--- |
| 2 | +layout: page |
| 3 | +title: "History Statistics" |
| 4 | +description: "Instructions about how to integrate history_stats sensors into Home Assistant." |
| 5 | +date: 2017-02-10 12:00 |
| 6 | +sidebar: true |
| 7 | +comments: false |
| 8 | +sharing: true |
| 9 | +footer: true |
| 10 | +logo: home-assistant.png |
| 11 | +ha_category: Sensor |
| 12 | +ha_iot_class: "Local Polling" |
| 13 | +ha_release: "0.38" |
| 14 | +--- |
| 15 | + |
| 16 | +The `history_stats` sensor platform provides quick statistics about another component, using data from the history. |
| 17 | + |
| 18 | +It can track how long the component has been in a specific state, in a custom time period. |
| 19 | + |
| 20 | +Examples of what you can track : |
| 21 | +- How long you were at home this week |
| 22 | +- How long the lights were ON yesterday |
| 23 | +- How long you watched TV today |
| 24 | + |
| 25 | +## {% linkable_title Configuration %} |
| 26 | + |
| 27 | +To enable the history statistics sensor, add the following lines to your `configuration.yaml`: |
| 28 | + |
| 29 | +```yaml |
| 30 | +# Example configuration.yaml entry |
| 31 | +sensor: |
| 32 | + - platform: history_stats |
| 33 | + name: Lamp ON today |
| 34 | + entity_id: light.my_lamp |
| 35 | + state: 'on' |
| 36 | + start: '{% raw %}{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}{% endraw %}' |
| 37 | + end: '{% raw %}{{ now() }}{% endraw %}' |
| 38 | +``` |
| 39 | +
|
| 40 | +Configuration variables: |
| 41 | +
|
| 42 | + - **entity_id** (*Required*): The entity you want to track |
| 43 | + - **state** (*Required*): The state you want to track |
| 44 | + - **name** (*Optional*): Name displayed on the frontend |
| 45 | + - **start**: When to start the measure (timestamp or datetime). |
| 46 | + - **end**: When to stop the measure (timestamp or datetime) |
| 47 | + - **duration**: Duration of the measure |
| 48 | +
|
| 49 | +
|
| 50 | +
|
| 51 | +<p class='note'> |
| 52 | + You have to provide **exactly 2** of `start`, `end` and `duration`. |
| 53 | +<br/> |
| 54 | + You can use [template extensions](/topics/templating/#home-assistant-template-extensions) such as `now()` or `as_timestamp()` to handle dynamic dates, as shown in the examples below. |
| 55 | +</p> |
| 56 | + |
| 57 | +## {% linkable_title Time periods %} |
| 58 | + |
| 59 | +The `history_stats` component will execute a measure within a precise time period. You should always provide 2 of the following : |
| 60 | +- When the period starts (`start` variable) |
| 61 | +- When the period ends (`end` variable) |
| 62 | +- How long is the period (`duration` variable) |
| 63 | + |
| 64 | +As `start` and `end` variables can be either datetimes or timestamps, you can configure almost any period you want. |
| 65 | + |
| 66 | + |
| 67 | +### {% linkable_title Duration %} |
| 68 | + |
| 69 | +The duration variable is used when the time period is fixed. Different syntaxes for the duration are supported, as shown below. |
| 70 | + |
| 71 | +```yaml |
| 72 | +# 6 hours |
| 73 | +duration: 06:00 |
| 74 | +``` |
| 75 | + |
| 76 | +```yaml |
| 77 | +# 1 minute, 30 seconds |
| 78 | +duration: 00:01:30 |
| 79 | +``` |
| 80 | + |
| 81 | +```yaml |
| 82 | +# 2 hours and 30 minutes |
| 83 | +duration: |
| 84 | + # supports seconds, minutes, hours, days |
| 85 | + hours: 2 |
| 86 | + minutes: 30 |
| 87 | +``` |
| 88 | + |
| 89 | +### {% linkable_title Examples %} |
| 90 | + |
| 91 | +Here are some examples of periods you could work with, and what to write in your `configuration.yaml`: |
| 92 | + |
| 93 | +**Today**: starts at 00:00 of the current day and ends right now. |
| 94 | +```yaml |
| 95 | + start: '{% raw %}{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}{% endraw %}' |
| 96 | + end: '{% raw %}{{ now() }}{% endraw %}' |
| 97 | +``` |
| 98 | + |
| 99 | +**Yesterday**: ends today at 00:00, lasts 24 hours. |
| 100 | +```yaml |
| 101 | + end: '{% raw %}{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}{% endraw %}' |
| 102 | + duration: |
| 103 | + hours: 24 |
| 104 | +``` |
| 105 | + |
| 106 | +**This morning (6AM - 11AM)**: starts today at 6, lasts 5 hours. |
| 107 | +```yaml |
| 108 | + start: '{% raw %}{{ now().replace(hour=6).replace(minute=0).replace(second=0) }}{% endraw %}' |
| 109 | + duration: |
| 110 | + hours: 5 |
| 111 | +``` |
| 112 | + |
| 113 | +**Current week**: starts last Monday at 00:00, ends right now. |
| 114 | + |
| 115 | +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). |
| 116 | +```yaml |
| 117 | + start: '{% raw %}{{ as_timestamp( now().replace(hour=0).replace(minute=0).replace(second=0) ) - now().weekday() * 86400 }}{% endraw %}' |
| 118 | + end: '{% raw %}{{ now() }}{% endraw %}' |
| 119 | +``` |
| 120 | + |
| 121 | +**Last 30 days**: ends today at 00:00, lasts 30 days. Easy one. |
| 122 | +```yaml |
| 123 | + end: '{% raw %}{{ now().replace(hour=0).replace(minute=0).replace(second=0) }}{% endraw %}' |
| 124 | + duration: |
| 125 | + days: 30 |
| 126 | +``` |
| 127 | + |
| 128 | +**All your history** starts at timestamp = 0, and ends right now. |
| 129 | +```yaml |
| 130 | + start: '{% raw %}{{ 0 }}{% endraw %}' |
| 131 | + end: '{% raw %}{{ now() }}{% endraw %}' |
| 132 | +``` |
| 133 | + |
| 134 | +<p class='note'> |
| 135 | + 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. |
| 136 | +</p> |
0 commit comments