From 62cfcec6f495b567a7757df05a8352f3a89a3539 Mon Sep 17 00:00:00 2001 From: Erik Date: Tue, 17 Aug 2021 15:00:40 +0200 Subject: [PATCH 1/6] Update documentation and dev blog post with removal of STATE_CLASS_TOTAL --- blog/2021-08-16-state_class_total.md | 37 ++++++++++++---------------- docs/core/entity/sensor.md | 25 +++++++++---------- 2 files changed, 28 insertions(+), 34 deletions(-) diff --git a/blog/2021-08-16-state_class_total.md b/blog/2021-08-16-state_class_total.md index 8cb56a457c2..d56ec34794f 100644 --- a/blog/2021-08-16-state_class_total.md +++ b/blog/2021-08-16-state_class_total.md @@ -4,39 +4,33 @@ 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, `STATE_CLASS_TOTAL_INCREASING` has 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. ### 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. + 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. - `STATE_CLASS_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 +For sensors with state_class `STATE_CLASS_MEASUREMENT`, 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: +Example of `STATE_CLASS_MEASUREMENT` without last_reset: | t | state | sum | | :--------------------- | -----: | -----: | @@ -45,7 +39,7 @@ Example of `STATE_CLASS_TOTAL` without last_reset: | 2021-08-01T15:00:00 | 0 | -1000 | | 2021-08-01T16:00:00 | 5 | -995 | -Example of `STATE_CLASS_TOTAL` with last_reset: +Example of `STATE_CLASS_MEASUREMENT` with last_reset: | t | state | last_reset | sum | | :--------------------- | -----: | ------------------- | -----: | @@ -64,7 +58,8 @@ important that the integration ensures that the value cannot erroneously decreas 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. +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`: @@ -81,5 +76,5 @@ 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 | diff --git a/docs/core/entity/sensor.md b/docs/core/entity/sensor.md index bef9ca5012a..31d370462d8 100644 --- a/docs/core/entity/sensor.md +++ b/docs/core/entity/sensor.md @@ -55,8 +55,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,25 +63,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`. +like this month's energy consumption, today's energy production or the yearly growth of +a stock portfolio. -#### `STATE_CLASS_TOTAL` +#### `STATE_CLASS_MEASUREMENT` -For sensors with state_class `STATE_CLASS_TOTAL`, the `last_reset` attribute can +For sensors with state_class `STATE_CLASS_MEASUREMENT`, 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: +Example of `STATE_CLASS_MEASUREMENT` without last_reset: | t | state | sum | | :--------------------- | -----: | -----: | @@ -91,7 +89,7 @@ Example of `STATE_CLASS_TOTAL` without last_reset: | 2021-08-01T15:00:00 | 0 | -1000 | | 2021-08-01T16:00:00 | 5 | -995 | -Example of `STATE_CLASS_TOTAL` with last_reset: +Example of `STATE_CLASS_MEASUREMENT` with last_reset: | t | state | last_reset | sum | | :--------------------- | -----: | ------------------- | -----: | @@ -109,7 +107,8 @@ important that the integration ensures that the value cannot erroneously decreas 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. +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 +125,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 From a8e7e01c3877d75eaeef0bab6eb8a6e94eb3d9d1 Mon Sep 17 00:00:00 2001 From: Erik Date: Tue, 17 Aug 2021 18:22:25 +0200 Subject: [PATCH 2/6] Kill last_reset --- blog/2021-08-16-state_class_total.md | 42 ++++------------------------ docs/core/entity/sensor.md | 31 +------------------- 2 files changed, 7 insertions(+), 66 deletions(-) diff --git a/blog/2021-08-16-state_class_total.md b/blog/2021-08-16-state_class_total.md index d56ec34794f..8c5ab830322 100644 --- a/blog/2021-08-16-state_class_total.md +++ b/blog/2021-08-16-state_class_total.md @@ -4,10 +4,9 @@ authorURL: https://github.com/emontnemery title: "New sensor state classes: total and total_increasing" --- -A new state class, `STATE_CLASS_TOTAL_INCREASING` has 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, `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 @@ -22,43 +21,14 @@ There are 2 defined state classes: 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`, 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_MEASUREMENT` 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_MEASUREMENT` 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 not 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. The value when the +sensor 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`: diff --git a/docs/core/entity/sensor.md b/docs/core/entity/sensor.md index 31d370462d8..f2783ef1894 100644 --- a/docs/core/entity/sensor.md +++ b/docs/core/entity/sensor.md @@ -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. @@ -72,40 +71,12 @@ Entities tracking a total amount have a value that may optionally reset periodic like this month's energy consumption, today's energy production or the yearly growth of a stock portfolio. -#### `STATE_CLASS_MEASUREMENT` - -For sensors with state_class `STATE_CLASS_MEASUREMENT`, 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_MEASUREMENT` 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_MEASUREMENT` 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 +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 not be used as zero-point when calculating `sum` statistics, instead the zero-point will be set to 0. From a2154ba0e6c9161789d092b496d185424b2dc063 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Tue, 17 Aug 2021 21:25:00 +0200 Subject: [PATCH 3/6] Update blog/2021-08-16-state_class_total.md Co-authored-by: Paulus Schoutsen --- blog/2021-08-16-state_class_total.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/blog/2021-08-16-state_class_total.md b/blog/2021-08-16-state_class_total.md index 8c5ab830322..ce528d404f2 100644 --- a/blog/2021-08-16-state_class_total.md +++ b/blog/2021-08-16-state_class_total.md @@ -48,3 +48,5 @@ Example of `STATE_CLASS_TOTAL_INCREASING` where the sensor does not reset to 0: | 2021-08-01T14:00:00 | 1010 | 10 | | 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. From a5cc6eb3116e34832dd5ba5c5f63767fe04f5a8c Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Tue, 17 Aug 2021 21:26:10 +0200 Subject: [PATCH 4/6] Update 2021-08-16-state_class_total.md --- blog/2021-08-16-state_class_total.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/blog/2021-08-16-state_class_total.md b/blog/2021-08-16-state_class_total.md index ce528d404f2..19fb7ef6454 100644 --- a/blog/2021-08-16-state_class_total.md +++ b/blog/2021-08-16-state_class_total.md @@ -4,7 +4,7 @@ authorURL: https://github.com/emontnemery title: "New sensor state classes: total and total_increasing" --- -A new state class, `STATE_CLASS_TOTAL_INCREASING` has been added. In addition, the +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. @@ -12,12 +12,12 @@ make it easier to integrate with devices, like utility meters. There are 2 defined state classes: -- `STATE_CLASS_MEASUREMENT`, the state represents a measurement in present time, for +- `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. -- `STATE_CLASS_TOTAL_INCREASING`, a monotonically increasing total, e.g. an amount of +- `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. From 16a829f80c9aec5af49652be0b0796552ae33f88 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Tue, 17 Aug 2021 21:31:32 +0200 Subject: [PATCH 5/6] Update blog/2021-08-16-state_class_total.md Co-authored-by: Paulus Schoutsen --- blog/2021-08-16-state_class_total.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/blog/2021-08-16-state_class_total.md b/blog/2021-08-16-state_class_total.md index 19fb7ef6454..87a37105175 100644 --- a/blog/2021-08-16-state_class_total.md +++ b/blog/2021-08-16-state_class_total.md @@ -27,9 +27,11 @@ For sensors with state_class `STATE_CLASS_TOTAL_INCREASING`, a decreasing value 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. This state -class is useful for gas meters, electricity meters, water meters etc. The value when the -sensor reading decreases will not be used as zero-point when calculating `sum` statistics, -instead the zero-point will be set to 0. +class is useful for gas meters, electricity meters, water meters etc. + +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`: From eae0dc6a09211cd8afb5881584480788becdd463 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Tue, 17 Aug 2021 21:33:42 +0200 Subject: [PATCH 6/6] Update 2021-08-16-state_class_total.md --- blog/2021-08-16-state_class_total.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/blog/2021-08-16-state_class_total.md b/blog/2021-08-16-state_class_total.md index 87a37105175..eb8f8ba9f81 100644 --- a/blog/2021-08-16-state_class_total.md +++ b/blog/2021-08-16-state_class_total.md @@ -33,7 +33,7 @@ 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`: +Example of `STATE_CLASS_TOTAL_INCREASING` with a new meter cycle: | t | state | sum | | :--------------------- | -----: | ---: | @@ -42,7 +42,8 @@ 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 | | :--------------------- | -----: | ---: |