---
author: Erik Montnémery
authorURL: https://github.com/emontnemery
title: "New sensor state class: total"
---

Note: This post was edited 2021-10-21 to remove references to total accumulated increases
and decreases which were removed and never included in the Home Assistant 2021.10 release.

A new state class, `total` has been added and the `last_reset` attribute has been
added back to `SensorEntity` and is no longer deprecated. The driver for the change
is to support cases where `total_increasing`, which was introduced in Home Assistant
2021.9, is too restrictive to cover all cases. Note that setting `last_reset` for sensors
with state class `measurement` is still deprecated.

### State classes

There are 3 defined state classes:

- `measurement`, the state represents a measurement in present time, for example a
   temperature, electric power, etc. For supported sensors, statistics of min,
   max and average sensor readings are updated periodically.
- `total`, the state represents a total amount that can both increase and
   decrease, e.g. a net energy meter. When supported, the accumulated growth
   or decline of the sensor's value since it was first added is updated periodically.
- `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 periodically.

#### State class `total`
For sensors with state class `total`, the `last_reset` attribute can
optionally be set to gain manual control of meter cycles.
The sensor's state when it's first added to Home Assistant is used as an initial
zero-point. When a `last_reset` changes, the zero-point will be set to 0.
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  |

Example of state class `total` 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  | 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  |


#### State class `total_increasing`

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 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  |
| :--------------------- | -----: | ---: |
|   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 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  |  15  |
|   2021-08-01T16:00:00  |    10  |  20  |
