From ec175df14e5f10e96d1cef91dcb2defeeeb0fe75 Mon Sep 17 00:00:00 2001 From: G Johansson Date: Sun, 3 Nov 2024 18:32:58 +0000 Subject: [PATCH] Clarify state attributes rules for entity --- docs/core/entity.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/core/entity.md b/docs/core/entity.md index cc33b8c3..8c74a870 100644 --- a/docs/core/entity.md +++ b/docs/core/entity.md @@ -119,6 +119,17 @@ The following properties are also available on entities. However, they are for a | state_attributes | dict | None | `None` | State attributes of a base domain. This property is implemented by the domain base entity and should not be implemented by integrations. | unit_of_measurement | str | None | The unit of measurement that the entity's state is expressed in. In most cases, for example for the `number` and `sensor` domains, this is implemented by the domain base entity and should not be implemented by integrations. +## State attributes + +Entities can provide additional state attributes besides the built-in ones, to provide further details to it's state. +This should be done by providing a dictionary with keys and values to the `extra_state_attributes` property. + +Providing additional state attributes comes with some rules: + +- If an attribute is expected, it should be in the dictionary. Attributes should not "come and go". +- If an attribute is expected, but it's not providing a value right now, its value should be `None` and remain in the dictionary +- If an attributes is not expected, it should not be in the dictionary. As example, only some attributes might provide additional context to the state when the entity runs with a certain configuration. + ## System properties The following properties are used and controlled by Home Assistant, and should not be overridden by integrations.