From fa29b0bbee48b85e2d1a3087e60c083ec8dd961f Mon Sep 17 00:00:00 2001 From: Erik Date: Thu, 12 Aug 2021 15:36:01 +0200 Subject: [PATCH 1/8] Add blog post about new sensor state classes --- blog/2021-08-12-state_class_total.md | 68 ++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) create mode 100644 blog/2021-08-12-state_class_total.md diff --git a/blog/2021-08-12-state_class_total.md b/blog/2021-08-12-state_class_total.md new file mode 100644 index 00000000000..eebfce2e282 --- /dev/null +++ b/blog/2021-08-12-state_class_total.md @@ -0,0 +1,68 @@ +--- +author: Erik Montnémery +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 in order +for `sum` statistics to be generated. The driver for the changes is to make it easier to +integrate with utility meters etc. + +### State classes + +There are now 3 defined state classes: +- `STATE_CLASS_MEASUREMENT`, the state represents a measurement in present time, for + example a temperature, electric power etc. +- `STATE_CLASS_TOTAL`, the state represents a total amount which can both increase and + decrease, e.g. the value of a stock portfolio +- `STATE_CLASS_TOTAL_INCREASING`, a monotonically increasing total, e.g. an amount of + consumed gas, water or energy + +#### STATE_CLASS_TOTAL +If the sensor's state class is `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 used as the +zero-point when calculating `sum` statistics. + +Example of `STATE_CLASS_TOTAL` without last_reset: +| t | state | sum | +| ---: | -----: | -----: | +| 0 | 1000 | 0 | +| 1 | 1010 | 10 | +| 2 | 0 | -1000 | +| 3 | 5 | -995 | + +Example of `STATE_CLASS_TOTAL` with last_reset: +| t | state | last_reset | sum | +| ---: | -----: | ------------------- | -----: | +| 0 | 1000 | 2021-08-01T13:30:00 | 0 | +| 1 | 1010 | 2021-08-01T13:30:00 | 10 | +| 2 | 1005 | 2021-08-01T13:30:00 | 5 | +| 3 | 0 | 2021-09-01T13:30:00 | 5 | +| 4 | 5 | 2021-09-01T13:30:00 | 10 | + + +#### STATE_CLASS_TOTAL_INCREASING +If the sensor's state class is `STATE_CLASS_TOTAL_INCREASING`, a decreasing value is +interpreted as the start of a new meter cycle or the replacement of the meter. 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. + +Example of `STATE_CLASS_TOTAL_INCREASING`: +| t | state | sum | +| ---: | -----: | ---: | +| 0 | 1000 | 0 | +| 1 | 1010 | 10 | +| 2 | 0 | 10 | +| 3 | 5 | 15 | + +Example of `STATE_CLASS_TOTAL_INCREASING` where the sensor does not reset to 0: +| t | state | sum | +| ---: | -----: | ---: | +| 0 | 1000 | 0 | +| 1 | 1010 | 10 | +| 2 | 5 | 10 | +| 3 | 10 | 15 | From 58a66db6fdf927a595e3f93239e3906c03eff6d8 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Thu, 12 Aug 2021 15:44:32 +0200 Subject: [PATCH 2/8] Update blog/2021-08-12-state_class_total.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Joakim Sørensen --- blog/2021-08-12-state_class_total.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/blog/2021-08-12-state_class_total.md b/blog/2021-08-12-state_class_total.md index eebfce2e282..367aac531ad 100644 --- a/blog/2021-08-12-state_class_total.md +++ b/blog/2021-08-12-state_class_total.md @@ -1,7 +1,7 @@ --- author: Erik Montnémery authorURL: https://github.com/emontnemery -title: New sensor state classes: total and total_increasing +title: "New sensor state classes: total and total_increasing" --- Two new state classes, `STATE_CLASS_TOTAL` and `STATE_CLASS_TOTAL_INCREASING` have been From 7be1326020585379fdc9025ea39dd5980291760b Mon Sep 17 00:00:00 2001 From: Erik Date: Thu, 12 Aug 2021 15:48:14 +0200 Subject: [PATCH 3/8] Attempt to fix tables --- blog/2021-08-12-state_class_total.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/blog/2021-08-12-state_class_total.md b/blog/2021-08-12-state_class_total.md index 367aac531ad..3916ee51fa6 100644 --- a/blog/2021-08-12-state_class_total.md +++ b/blog/2021-08-12-state_class_total.md @@ -27,6 +27,7 @@ If last_reset is not set, the sensor's value when it was first added used as the zero-point when calculating `sum` statistics. Example of `STATE_CLASS_TOTAL` without last_reset: + | t | state | sum | | ---: | -----: | -----: | | 0 | 1000 | 0 | @@ -35,6 +36,7 @@ Example of `STATE_CLASS_TOTAL` without last_reset: | 3 | 5 | -995 | Example of `STATE_CLASS_TOTAL` with last_reset: + | t | state | last_reset | sum | | ---: | -----: | ------------------- | -----: | | 0 | 1000 | 2021-08-01T13:30:00 | 0 | @@ -52,6 +54,7 @@ useful for gas meters, electricity meters, water meters etc. The value when the reading decreases will be used as zero-point when calculating `sum` statistics. Example of `STATE_CLASS_TOTAL_INCREASING`: + | t | state | sum | | ---: | -----: | ---: | | 0 | 1000 | 0 | @@ -60,6 +63,7 @@ Example of `STATE_CLASS_TOTAL_INCREASING`: | 3 | 5 | 15 | Example of `STATE_CLASS_TOTAL_INCREASING` where the sensor does not reset to 0: + | t | state | sum | | ---: | -----: | ---: | | 0 | 1000 | 0 | From 08e5fdfa3c91abc03035f6ca53b9a6fb6e538b28 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Thu, 12 Aug 2021 17:21:24 +0200 Subject: [PATCH 4/8] Apply suggestions from code review Co-authored-by: Martin Hjelmare Co-authored-by: Tom Brien --- blog/2021-08-12-state_class_total.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/blog/2021-08-12-state_class_total.md b/blog/2021-08-12-state_class_total.md index 3916ee51fa6..da88600dbf0 100644 --- a/blog/2021-08-12-state_class_total.md +++ b/blog/2021-08-12-state_class_total.md @@ -23,7 +23,7 @@ There are now 3 defined state classes: If the sensor's state class is `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 used as the +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: @@ -48,7 +48,9 @@ Example of `STATE_CLASS_TOTAL` with last_reset: #### STATE_CLASS_TOTAL_INCREASING If the sensor's state class is `STATE_CLASS_TOTAL_INCREASING`, a decreasing value is -interpreted as the start of a new meter cycle or the replacement of the meter. The +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. From b17c1949350da573db02be7b2e7a42023642d30a Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 13 Aug 2021 12:37:29 +0200 Subject: [PATCH 5/8] Apply suggestions from code review Co-authored-by: Franck Nijhof --- blog/2021-08-12-state_class_total.md | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/blog/2021-08-12-state_class_total.md b/blog/2021-08-12-state_class_total.md index da88600dbf0..34db86bd5f0 100644 --- a/blog/2021-08-12-state_class_total.md +++ b/blog/2021-08-12-state_class_total.md @@ -5,22 +5,24 @@ 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 in order -for `sum` statistics to be generated. The driver for the changes is to make it easier to -integrate with utility meters etc. +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: + - `STATE_CLASS_MEASUREMENT`, the state represents a measurement in present time, for - example a temperature, electric power etc. -- `STATE_CLASS_TOTAL`, the state represents a total amount which can both increase and + example a temperature, electric power, etc. +- `STATE_CLASS_TOTAL`, the state represents a total amount that can both increase and decrease, e.g. the value of a stock portfolio - `STATE_CLASS_TOTAL_INCREASING`, a monotonically increasing total, e.g. an amount of consumed gas, water or energy -#### STATE_CLASS_TOTAL -If the sensor's state class is `STATE_CLASS_TOTAL`, the last_reset attribute can +#### `STATE_CLASS_TOTAL` + +If the sensor's state class is `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 @@ -46,9 +48,10 @@ Example of `STATE_CLASS_TOTAL` with last_reset: | 4 | 5 | 2021-09-01T13:30:00 | 10 | -#### STATE_CLASS_TOTAL_INCREASING +#### `STATE_CLASS_TOTAL_INCREASING` + If the sensor's state class is `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 +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 From acfde8d906d6f29dd08ff4191fb10ee501d88387 Mon Sep 17 00:00:00 2001 From: Erik Date: Fri, 13 Aug 2021 12:51:28 +0200 Subject: [PATCH 6/8] Tweak --- blog/2021-08-12-state_class_total.md | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/blog/2021-08-12-state_class_total.md b/blog/2021-08-12-state_class_total.md index 34db86bd5f0..ada5e02aadb 100644 --- a/blog/2021-08-12-state_class_total.md +++ b/blog/2021-08-12-state_class_total.md @@ -14,15 +14,23 @@ integrate with devices, like utility meters. There are now 3 defined state classes: - `STATE_CLASS_MEASUREMENT`, the state represents a measurement in present time, for - example a temperature, electric power, etc. + 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 + 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 - consumed gas, water or energy + 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` -If the sensor's state class is `STATE_CLASS_TOTAL`, the `last_reset` attribute can +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 @@ -50,7 +58,7 @@ Example of `STATE_CLASS_TOTAL` with last_reset: #### `STATE_CLASS_TOTAL_INCREASING` -If the sensor's state class is `STATE_CLASS_TOTAL_INCREASING`, a decreasing value is +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 From 07468ee1d0e9b0651ab96440972b7a609be2db34 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Mon, 16 Aug 2021 11:24:39 +0200 Subject: [PATCH 7/8] Update 2021-08-12-state_class_total.md --- blog/2021-08-12-state_class_total.md | 50 ++++++++++++++-------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/blog/2021-08-12-state_class_total.md b/blog/2021-08-12-state_class_total.md index ada5e02aadb..8cb56a457c2 100644 --- a/blog/2021-08-12-state_class_total.md +++ b/blog/2021-08-12-state_class_total.md @@ -38,22 +38,22 @@ zero-point when calculating `sum` statistics. Example of `STATE_CLASS_TOTAL` without last_reset: -| t | state | sum | -| ---: | -----: | -----: | -| 0 | 1000 | 0 | -| 1 | 1010 | 10 | -| 2 | 0 | -1000 | -| 3 | 5 | -995 | +| 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 | -| ---: | -----: | ------------------- | -----: | -| 0 | 1000 | 2021-08-01T13:30:00 | 0 | -| 1 | 1010 | 2021-08-01T13:30:00 | 10 | -| 2 | 1005 | 2021-08-01T13:30:00 | 5 | -| 3 | 0 | 2021-09-01T13:30:00 | 5 | -| 4 | 5 | 2021-09-01T13:30:00 | 10 | +| 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` @@ -68,18 +68,18 @@ reading decreases will be used as zero-point when calculating `sum` statistics. Example of `STATE_CLASS_TOTAL_INCREASING`: -| t | state | sum | -| ---: | -----: | ---: | -| 0 | 1000 | 0 | -| 1 | 1010 | 10 | -| 2 | 0 | 10 | -| 3 | 5 | 15 | +| t | state | sum | +| :--------------------- | -----: | ---: | +| 2021-08-01T13:00:00 | 1000 | 0 | +| 2021-08-01T14:00:00 | 1010 | 10 | +| 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: -| t | state | sum | -| ---: | -----: | ---: | -| 0 | 1000 | 0 | -| 1 | 1010 | 10 | -| 2 | 5 | 10 | -| 3 | 10 | 15 | +| 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 | From ba155eb6b95176c70a8524ec62d00a1c45eb9c23 Mon Sep 17 00:00:00 2001 From: Erik Date: Mon, 16 Aug 2021 13:14:46 +0200 Subject: [PATCH 8/8] Bump date of the blogpost --- ...08-12-state_class_total.md => 2021-08-16-state_class_total.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename blog/{2021-08-12-state_class_total.md => 2021-08-16-state_class_total.md} (100%) diff --git a/blog/2021-08-12-state_class_total.md b/blog/2021-08-16-state_class_total.md similarity index 100% rename from blog/2021-08-12-state_class_total.md rename to blog/2021-08-16-state_class_total.md