jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-07-13 20:36:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation and dev blog post with removal of STATE_CLASS_TOTAL and SensorEntity.last_reset (#1028)

Browse Source 
Co-authored-by: Paulus Schoutsen <paulus@home-assistant.io>
This commit is contained in:
Erik Montnemery 2021-08-17 22:32:33 +02:00 committed by GitHub
parent ca7b514775
commit 92b2bc0932
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 32 additions and 92 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

76
blog/2021-08-16-state_class_total.md
View File

@ -4,69 +4,36 @@ authorURL: https://github.com/emontnemery
title: "New sensor state classes: total and total_increasing"
---
Two new state classes, `STATE_CLASS_TOTAL` and `STATE_CLASS_TOTAL_INCREASING` have been
added. In addition, it is no longer mandatory to set the `last_reset` attribute for
`sum` statistics to be generated. The driver for the changes is to make it easier to
integrate with devices, like utility meters.
A new state class, `total_increasing` has been added. In addition, the
`last_reset` attribute is removed from `SensorEntity`. The driver for the changes is to
make it easier to integrate with devices, like utility meters.
### State classes
There are now 3 defined state classes:
There are 2 defined state classes:
- `STATE_CLASS_MEASUREMENT`, the state represents a measurement in present time, for
example a temperature, electric power, etc. For supported sensors, statistics of
hourly min, max and average sensor readings are compiled.
- `STATE_CLASS_TOTAL`, the state represents a total amount that can both increase and
decrease, e.g. the value of a stock portfolio. When supported, the accumulated growth
or decline of the sensor's value since it was first added is updated hourly.
- `STATE_CLASS_TOTAL_INCREASING`, a monotonically increasing total, e.g. an amount of
- `measurement`, the state represents a measurement in present time, for
example a temperature, electric power, the value of a stock portfolio, etc. For
supported sensors, statistics of hourly min, max and average sensor readings or of
the accumulated growth or decline of the sensor's value since it was first added is
updated hourly.
- `total_increasing`, a monotonically increasing total, e.g. an amount of
consumed gas, water or energy. When supported, the accumulated growth of the sensor's
value since it was first added is updated hourly.
#### `STATE_CLASS_MEASUREMENT`
For sensors with state_class `STATE_CLASS_MEASUREMENT`, it is deprecated to set the
`last_reset` attribute, and it will be ignored in Home Assistant 2021.10.
#### `STATE_CLASS_TOTAL`
For sensors with state_class `STATE_CLASS_TOTAL`, the `last_reset` attribute can
optionally be set to gain manual control of meter cycles; each time last_reset changes
the corresponding value is used as the zero-point when calculating `sum` statistics.
If last_reset is not set, the sensor's value when it was first added is used as the
zero-point when calculating `sum` statistics.
Example of `STATE_CLASS_TOTAL` without last_reset:
| t | state | sum |
| :--------------------- | -----: | -----: |
| 2021-08-01T13:00:00 | 1000 | 0 |
| 2021-08-01T14:00:00 | 1010 | 10 |
| 2021-08-01T15:00:00 | 0 | -1000 |
| 2021-08-01T16:00:00 | 5 | -995 |
Example of `STATE_CLASS_TOTAL` with last_reset:
| t | state | last_reset | sum |
| :--------------------- | -----: | ------------------- | -----: |
| 2021-08-01T13:00:00 | 1000 | 2021-08-01T13:00:00 | 0 |
| 2021-08-01T14:00:00 | 1010 | 2021-08-01T13:00:00 | 10 |
| 2021-08-01T15:00:00 | 1005 | 2021-08-01T13:00:00 | 5 |
| 2021-08-01T16:00:00 | 0 | 2021-09-01T16:00:00 | 5 |
| 2021-08-01T17:00:00 | 5 | 2021-09-01T16:00:00 | 10 |
#### `STATE_CLASS_TOTAL_INCREASING`
For sensors with state_class `STATE_CLASS_TOTAL_INCREASING`, a decreasing value is
interpreted as the start of a new meter cycle or the replacement of the meter. It is
important that the integration ensures that the value cannot erroneously decrease in
the case of calculating a value from a sensor with measurement noise present. The
last_reset attribute will be ignored when compiling statistics. This state class is
useful for gas meters, electricity meters, water meters etc. The value when the sensor
reading decreases will be used as zero-point when calculating `sum` statistics.
the case of calculating a value from a sensor with measurement noise present. This state
class is useful for gas meters, electricity meters, water meters etc.
Example of `STATE_CLASS_TOTAL_INCREASING`:
The sensor's state when it's first added to Home Assistant is used as an initial
zero-point. When a new meter cycle is detected the zero-point will be set to 0.
Please refer to the tables below for how this affects the statistics.
Example of `STATE_CLASS_TOTAL_INCREASING` with a new meter cycle:
| t | state | sum |
| :--------------------- | -----: | ---: |
@ -75,11 +42,14 @@ Example of `STATE_CLASS_TOTAL_INCREASING`:
| 2021-08-01T15:00:00 | 0 | 10 |
| 2021-08-01T16:00:00 | 5 | 15 |
Example of `STATE_CLASS_TOTAL_INCREASING` where the sensor does not reset to 0:
Example of `STATE_CLASS_TOTAL_INCREASING` where the there initial state at the beginning
of the new meter cycle is not 0, but 0 is used as zero-point:
| t | state | sum |
| :--------------------- | -----: | ---: |
| 2021-08-01T13:00:00 | 1000 | 0 |
| 2021-08-01T14:00:00 | 1010 | 10 |
| 2021-08-01T15:00:00 | 5 | 10 |
| 2021-08-01T16:00:00 | 10 | 15 |
| 2021-08-01T15:00:00 | 5 | 15 |
| 2021-08-01T16:00:00 | 10 | 20 |
This state class used to be represented by state class `measurement` in combination with a `last_reset` value. This approach has been deprecated and will be interpreted as a `total_increasing` state class instead with an automatic last reset.

48
docs/core/entity/sensor.md
View File

@ -15,7 +15,6 @@ Properties should always only return information from memory and not do I/O (lik
| ---- | ---- | ------- | -----------
| state | string | **Required** | The value of the sensor.
| device_class | string | `None` | Type of sensor.
| last_reset | `datetime.datetime` | `None` | The time when an accumulating sensor such as an electricity usage meter, gas meter, water meter etc. was initialized. If the time of initialization is unknown, set it to `None`. Note that the `datetime.datetime` returned by the `last_reset` property will be converted to an ISO 8601-formatted string when the entity's state attributes are updated. When changing `last_reset`, the `state` must be a valid number.
| state_class | string | `None` | Type of state.
| unit_of_measurement | string | `None` | The unit of measurement that the sensor is expressed in.
@ -55,8 +54,7 @@ If specifying a device class, your sensor entity will need to also return the co
| Type | Description
| ---- | -----------
| measurement | The state represents _a measurement in present time_, not a historical aggregation such as statistics or a prediction of the future. Examples of what should be classified `measurement` are: current temperature, current electricity usage, current battery level. Examples of what should not be classified as `measurement`: Forecasted temperature for tomorrow, yesterday's energy consumption or anything else that doesn't include the _current_ measurement. For supported sensors, statistics of hourly min, max and average sensor readings are compiled.
| total | The state represents a total amount that can both increase and decrease, e.g. the value of a stock portfolio. When supported, statistics of the accumulated growth or decline of the sensor's value since it was first added is updated hourly.
| measurement | The state represents _a measurement in present time_, not a historical aggregation such as statistics or a prediction of the future. Examples of what should be classified `measurement` are: current temperature, accumulated energy consumption, accumulated cost. Examples of what should not be classified as `measurement`: Forecasted temperature for tomorrow, yesterday's energy consumption or anything else that doesn't include the _current_ measurement. For supported sensors, statistics of hourly min, max and average sensor readings or of the accumulated growth or decline of the sensor's value since it was first added is updated hourly.
| total_increasing | The state represents a monotonically increasing total, e.g. an amount of consumed gas, water or energy. When supported, statistics of the accumulated growth of the sensor's value since it was first added is updated hourly.
@ -64,52 +62,24 @@ If specifying a device class, your sensor entity will need to also return the co
Home Assistant has support for storing sensors as long-term statistics if the entity has
the right properties. A requirement to opt-in for statistics is that the sensor has
`state_class` set to one of the valid state classes: `measurement`, `total` or
`state_class` set to one of the valid state classes: `measurement` or
`total_increasing`.
### Entities tracking a total amount
Entities tracking a total amount have a value that may optionally reset periodically,
like energy consumption, energy production or the value of a stock portfolio. To have
Home Assistant track this entity, `state_class` property must be set to `total` or
`total_increasing`.
#### `STATE_CLASS_TOTAL`
For sensors with state_class `STATE_CLASS_TOTAL`, the `last_reset` attribute can
optionally be set to gain manual control of meter cycles; each time last_reset changes
the corresponding value is used as the zero-point when calculating `sum` statistics.
If last_reset is not set, the sensor's value when it was first added is used as the
zero-point when calculating `sum` statistics.
Example of `STATE_CLASS_TOTAL` without last_reset:
| t | state | sum |
| :--------------------- | -----: | -----: |
| 2021-08-01T13:00:00 | 1000 | 0 |
| 2021-08-01T14:00:00 | 1010 | 10 |
| 2021-08-01T15:00:00 | 0 | -1000 |
| 2021-08-01T16:00:00 | 5 | -995 |
Example of `STATE_CLASS_TOTAL` with last_reset:
| t | state | last_reset | sum |
| :--------------------- | -----: | ------------------- | -----: |
| 2021-08-01T13:00:00 | 1000 | 2021-08-01T13:00:00 | 0 |
| 2021-08-01T14:00:00 | 1010 | 2021-08-01T13:00:00 | 10 |
| 2021-08-01T15:00:00 | 1005 | 2021-08-01T13:00:00 | 5 |
| 2021-08-01T16:00:00 | 0 | 2021-09-01T16:00:00 | 5 |
| 2021-08-01T17:00:00 | 5 | 2021-09-01T16:00:00 | 10 |
like this month's energy consumption, today's energy production or the yearly growth of
a stock portfolio.
#### `STATE_CLASS_TOTAL_INCREASING`
For sensors with state_class `STATE_CLASS_TOTAL_INCREASING`, a decreasing value is
interpreted as the start of a new meter cycle or the replacement of the meter. It is
important that the integration ensures that the value cannot erroneously decrease in
the case of calculating a value from a sensor with measurement noise present. The
last_reset attribute will be ignored when compiling statistics. This state class is
the case of calculating a value from a sensor with measurement noise present.This state class is
useful for gas meters, electricity meters, water meters etc. The value when the sensor
reading decreases will be used as zero-point when calculating `sum` statistics.
reading decreases will not be used as zero-point when calculating `sum` statistics,
instead the zero-point will be set to 0.
Example of `STATE_CLASS_TOTAL_INCREASING`:
@ -126,8 +96,8 @@ Example of `STATE_CLASS_TOTAL_INCREASING` where the sensor does not reset to 0:
| :--------------------- | -----: | ---: |
| 2021-08-01T13:00:00 | 1000 | 0 |
| 2021-08-01T14:00:00 | 1010 | 10 |
| 2021-08-01T15:00:00 | 5 | 10 |
| 2021-08-01T16:00:00 | 10 | 15 |
| 2021-08-01T15:00:00 | 5 | 15 |
| 2021-08-01T16:00:00 | 10 | 20 |
### Value entities