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-21 16:26:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document sum statistics for sensors with state_class measurement (#1045)

Browse Source 
* Document `sum` statistics for sensors with state_class measurement

* Update docs/core/entity/sensor.md

* Update docs/core/entity/sensor.md

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

* Fix typo

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Erik Montnemery 2021-08-31 15:23:39 +02:00 committed by GitHub
parent bdc7adfc99
commit 4b53f13e65
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 48 additions and 17 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -14,6 +14,7 @@ Properties should always only return information from memory and not do I/O (lik
| Name | Type | Default | Description
| ---- | ---- | ------- | -----------
| 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.
| native_value | string | **Required** | The value of the sensor in the sensor's `native_unit_of_measurement`.
| native_unit_of_measurement | string | `None` | The unit of measurement that the sensor's value is expressed in. If the `native_unit_of_measurement` is °C or °F, and its `device_class` is temperature, the sensor's `unit_of_measurement` will be the preferred temperature unit configured by the user and the sensor's `state` will be the `native_value` after an optional unit conversion.
| state_class | string | `None` | Type of state.
@ -57,33 +58,41 @@ 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, 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.
| total_increasing | Similar to `measurement`, with the restriction that the state represents a monotonically increasing total, e.g. an amount of consumed gas, water or energy. Statistics of the accumulated growth of the sensor's value since it was first added is updated hourly.
## Long-term Statistics
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
the right properties. To opt-in for statistics, the sensor must have
`state_class` set to one of the valid state classes: `measurement` or
`total_increasing`.
### Entities tracking a total amount
### Value entities - entities not representing a total amount
Home Assistant tracks the min, max and mean value during the statistics period. The
`state_class` property must be set to `measurement`, and the `device_class` must not be
either of `energy`, `gas`, or `monetary`
### Entities representing a total amount
Entities tracking a total amount have a value that may optionally reset periodically,
like this month's energy consumption, today's energy production or the yearly growth of
a stock portfolio.
a stock portfolio. The sensor's value when the first statistics is compiled is used as
the intial zero-point.
#### `STATE_CLASS_TOTAL_INCREASING`
#### State class `total_increasing`
For sensors with state_class `STATE_CLASS_TOTAL_INCREASING`, a decreasing value is
For sensors with 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.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.
the case of calculating a value from a sensor with measurement noise present. There is
some tolerance, a decrease between state changes of < 10% will not trigger a new meter
cycle. 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`:
Example of state class `total_increasing`:
| t | state | sum |
| :--------------------- | -----: | ---: |
@ -92,7 +101,7 @@ 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 sensor does not reset to 0:
| t | state | sum |
| :--------------------- | -----: | ---: |
@ -101,10 +110,32 @@ Example of `STATE_CLASS_TOTAL_INCREASING` where the sensor does not reset to 0:
| 2021-08-01T15:00:00 | 5 | 15 |
| 2021-08-01T16:00:00 | 10 | 20 |
### Value entities
#### State class `measurement`
Home Assistant tracks the min, max and mean value during the statistics period. The
`state_class` property must be set to `measurement`.
For sensors with state_class `measurement` a total amount is calculated if:
- The sensor's device class is `DEVICE_CLASS_ENERGY`, `DEVICE_CLASS_GAS`, or `DEVICE_CLASS_MONETARY`.
- The sensor's `last_reset` property is set to a valid datatime. If the time of initialization is unknown and the meter will never reset, set to UNIX epoch 0: `homeassistant.util.dt.utc_from_timestamp(0)`.
All sensors with a unit of measurement of `%` are automatically tracked. Other entities
opt-in based on their `device_class`.
A change of the `last_reset` attribute is interpreted as the start of a new meter cycle
or the replacement of the meter. The sensor's value when last_reset changes will not be
used as zero-point when calculating `sum` statistics, instead the zero-point will be set to 0.
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 |
Example of state class `measurement` with last_reset, where the sensor does not reset to 0:
| 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 | 5 | 2021-09-01T16:00:00 | 10 |
| 2021-08-01T17:00:00 | 10 | 2021-09-01T16:00:00 | 15 |