From 90120afacf608e6e54736b947261765dbb77d75e Mon Sep 17 00:00:00 2001 From: c0ffeeca7 <38767475+c0ffeeca7@users.noreply.github.com> Date: Mon, 30 Sep 2024 13:37:11 +0200 Subject: [PATCH] Entity state attribute: merge sections (#34975) Co-authored-by: Martin Hjelmare --- .../configuration/entities_domains.markdown | 15 ++-------- .../_docs/configuration/state_object.markdown | 29 ++++++++++--------- 2 files changed, 18 insertions(+), 26 deletions(-) diff --git a/source/_docs/configuration/entities_domains.markdown b/source/_docs/configuration/entities_domains.markdown index 2285ff5fdd1..01164ff5193 100644 --- a/source/_docs/configuration/entities_domains.markdown +++ b/source/_docs/configuration/entities_domains.markdown @@ -3,26 +3,15 @@ title: "Entities and domains" description: "Describes what entities and domains are in Home Assistant." related: - docs: /docs/configuration/state_object/ - title: State object, entity state + title: State object, entity state and attributes --- -Your devices are represented in Home Assistant as entities. Entities are the basic building blocks to hold data in Home Assistant. An entity represents a {% term sensor %}, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a {% term device %} or a {% term service %}. Entities have [states](/docs/configuration/state_object/) and [attributes](#entity-attributes). +Your devices are represented in Home Assistant as entities. Entities are the basic building blocks to hold data in Home Assistant. An entity represents a {% term sensor %}, actor, or function in Home Assistant. Entities are used to monitor physical properties or to control other entities. An entity is usually part of a {% term device %} or a {% term service %}. Entities have [states](/docs/configuration/state_object/) and [state attributes](/docs/configuration/state_object/#about-entity-state-attributes). All your entities are listed in the entities table, under {% my entities title="**Settings** > **Devices & services** > **Entities**" %}.

Screenshot showing the Entities tableScreenshot of the Entities table. Each line represents an entity.

-## Entity attributes - -Many entities have attributes. There are a few attributes that are available on all entities, such as `friendly_name` and `icon`. In addition to those, each integration has its own attributes to represent extra state data about the entity. For example, the light integration has attributes for the current brightness and color of the light. When an attribute is not available, Home Assistant will not write it to the state. The list of available attributes depends on the {% term device %}. - -

- Screenshot showing three lights with different states and attributes - Example showing three lights with differents states and different attributes. -

- -For more information on entity attributes, refer to the [attributes](/docs/configuration/state_object/#attributes) section on the state objects page. - ## Domains Each integration in Home Assistant has a unique identifier: a domain. All entities and actions available in Home Assistant are provided by integrations and thus belong to such a domain. The first part of the entity or action, before the `.` shows the domain they belong to. For example, `light.bed_light` is an entity in the light domain. `bed_light` is the ID of the entity. diff --git a/source/_docs/configuration/state_object.markdown b/source/_docs/configuration/state_object.markdown index 08ab4614d35..7f70fd8a92e 100644 --- a/source/_docs/configuration/state_object.markdown +++ b/source/_docs/configuration/state_object.markdown @@ -49,26 +49,29 @@ entity has exactly one state, and the state only holds one value at a time. The state only holds one value at a time. However, entities can store related entity state attributes in the state object. For example, the state of a light is _on_, and the related attributes could be its current brightness and color values. [State change events](/docs/configuration/events/#events-and-state-changes) can be used as triggers. -The current state can be used in [conditions](/docs/automation/condition/). +The current state can be used in [conditions](/docs/automation/condition/). The example below shows three lights with different entity state attributes. -### About entity attributes +

+ Screenshot showing three lights with different states and attributes + Example showing three lights with different entity state attributes. +

Entities have some attributes that are not related to its state, such as `friendly_name`. A few attributes are available on all entities, such as `friendly_name` or `icon`. In addition to those, each integration has its own attributes to represent extra state data about the entity. For example, the light integration has attributes for the current brightness and color of the light. When an attribute is not available, Home Assistant will not write it to the state. Entity attributes are optional. When using templates, attributes will be available by their name. For example `state.attributes.assumed_state`. -The table lists some common state attributes that may be present, depending on the entity domain. +The table lists common state attributes that may be present, depending on the entity domain. -| Attribute | Description | -| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| `friendly_name` | Name of the entity. Example: `Kitchen Ceiling`. | -| `icon` | Icon to use for the entity in the frontend. Example: `mdi:home`. | -| `entity_picture` | URL to a picture that should be used instead of showing the domain icon. Example: `http://example.com/picture.jpg`. | -| `assumed_state` | Boolean if the current state is an assumption. [More info](/blog/2016/02/12/classifying-the-internet-of-things/#classifiers) Example: `True`. | -| `unit_of_measurement` | The unit of measurement the state is expressed in. Used for grouping graphs or understanding the entity. Example: `°C`. | -| `attribution` | The provider of the data. For example, "Data provided by rejseplanen.dk", "Data provided by openSenseMap" | -| `device_class` | The type of device that an entity represents. Used to display device specific information in the UI.| -| `supported_features` | The features an entity supports. For covers, for example, it might list `opening`, `closing`, `stopping`, `setting position`. For media players, it might list `play`, `pause`, `stop`, and `volume control`| +| Attribute | Description | +| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `friendly_name` | Name of the entity. Example: `Kitchen Ceiling`. | +| `icon` | Icon to use for the entity in the frontend. Example: `mdi:home`. | +| `entity_picture` | URL to a picture that should be used instead of showing the domain icon. Example: `http://example.com/picture.jpg`. | +| `assumed_state` | Boolean if the current state is an assumption. [More info](/blog/2016/02/12/classifying-the-internet-of-things/#classifiers) Example: `True`. | +| `unit_of_measurement` | The unit of measurement the state is expressed in. Used for grouping graphs or understanding the entity. Example: `°C`. | +| `attribution` | The provider of the data. For example, "Data provided by rejseplanen.dk", "Data provided by openSenseMap" | +| `device_class` | The type of device that an entity represents. Used to display device specific information in the UI. | +| `supported_features` | The features an entity supports. For covers, for example, it might list `opening`, `closing`, `stopping`, `setting position`. For media players, it might list `play`, `pause`, `stop`, and `volume control` | When an attribute contains spaces, you can retrieve it like this: `state_attr('sensor.livingroom', 'Battery numeric')`.