mirror of
https://github.com/home-assistant/home-assistant.io.git
synced 2025-07-15 21:36:52 +00:00
Entity state attribute: merge sections (#34975)
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
c0ffeeca7
GitHub
parent
47a5b77769
commit
90120afacf
@ -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**" %}.
|
||||
|
||||
<p class='img'><img src='/images/getting-started/entities.png' style='border: 0;box-shadow: none;' alt="Screenshot showing the Entities table">Screenshot of the Entities table. Each line represents an entity.</p>
|
||||
|
||||
## 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 %}.
|
||||
|
||||
<p class='img'>
|
||||
<img src='/images/integrations/light/state_light.png' alt='Screenshot showing three lights with different states and attributes'>
|
||||
Example showing three lights with differents states and different attributes.
|
||||
</p>
|
||||
|
||||
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.
|
||||
|
||||
@ -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
|
||||
<p class='img'>
|
||||
<img src='/images/integrations/light/state_light.png' alt='Screenshot showing three lights with different states and attributes'>
|
||||
Example showing three lights with different entity state attributes.
|
||||
</p>
|
||||
|
||||
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')`.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user