Document sensor total and total_increasing state classes (#1026)

docs/core/entity/sensor.md

@@ -15,7 +15,7 @@ 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 and the meter will never reset, set to UNIX epoch 0: `homeassistant.util.dt.utc_from_timestamp(0)`. 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.
+| 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.
 
@@ -46,20 +46,84 @@ 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.
+| 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.
+| 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.
+
 
 ## 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 `state_class` set to `measurement`. That means that the current value represents the current value.
+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
+`total_increasing`.
 
-### Metered entities
+### Entities tracking a total amount
 
-Metered entities have a value that keeps increasing until reset, like energy consumption or production. To have Home Assistant track this entity, you need to include a [`last_reset` property](#properties).
+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`.
 
-Home Assistant will track the growth over the statistics period for metered entities.
+#### `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.
+
+Example of `STATE_CLASS_TOTAL_INCREASING`:
+
+| 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  |
+| :--------------------- | -----: | ---: |
+|   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  |
 
 ### Value entities
 
-Home Assistant tracks the min, max and mean value during the statistics period.
+Home Assistant tracks the min, max and mean value during the statistics period. The
+`state_class` property must be set to `measurement`.
 
-All sensors with a unit of measurement of `%` are automatically tracked. Other entities opt-in based on their `device_class`.
+All sensors with a unit of measurement of `%` are automatically tracked. Other entities
+opt-in based on their `device_class`.