From bcefc60ab9e82b9fc2c255478e283f5e9ffbbd75 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Thu, 6 Oct 2022 08:17:11 +0200 Subject: [PATCH] Update sensor.md, to make it easier to find the section about choosing state class (#1486) * Update sensor.md * Update sensor.md --- docs/core/entity/sensor.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/core/entity/sensor.md b/docs/core/entity/sensor.md index faa8074e..67162338 100644 --- a/docs/core/entity/sensor.md +++ b/docs/core/entity/sensor.md @@ -68,11 +68,15 @@ If specifying a device class, your sensor entity will need to also return the co ### Available state classes +:::caution +Choose the state class for a sensor with care. In most cases, state class `measurement` or state class `total` without `last_reset` should be chosen, this is explained further in [How to choose `state_class` and `last_reset`](#how-to-choose-state_class-and-last_reset) below. +:::: + | 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, humidify or electric power. 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 is updated every 5 minutes. | total | The state represents a total amount that can both increase and decrease, e.g. a net energy meter. Statistics of the accumulated growth or decline of the sensor's value since it was first added is updated every 5 minutes. This state class should not be used for sensors where the absolute value is interesting instead of the accumulated growth or decline, for example remaining battery capacity or CPU load; in such cases state class `measurement` should be used instead. -| total_increasing | Similar to `total`, with the restriction that the state represents a monotonically increasing positive total, e.g. a daily amount of consumed gas, weekly water consumption or lifetime energy consumption. Statistics of the accumulated growth of the sensor's value since it was first added is updated every 5 minutes. A decreasing value is interpreted as the start of a new meter cycle or the replacement of the meter. +| total_increasing | Similar to `total`, with the restriction that the state represents a monotonically increasing positive total which periodically restarts counting from 0, e.g. a daily amount of consumed gas, weekly water consumption or lifetime energy consumption. Statistics of the accumulated growth of the sensor's value since it was first added is updated every 5 minutes. A decreasing value is interpreted as the start of a new meter cycle or the replacement of the meter. ### Entity options