jeans/developers.home-assistant
jeans/developers.home-assistant
1
0
Fork 0
mirror of https://github.com/home-assistant/developers.home-assistant.git synced 2025-05-06 11:08:39 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revert "Document how entity properties are consumed (#1908)" (#1909)

Browse Source 
This reverts commit 0e8d42850253af0a1f2e3bc70033e15c62bfd8a8.
This commit is contained in:
Erik Montnemery 2023-09-15 11:49:07 +02:00 committed by GitHub
parent 59e72e4a30
commit ae7bf6b080
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 10 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
docs/core/entity.md
View File

@ -57,56 +57,40 @@ Whenever you receive a new state from your subscription, you can tell Home Assis
## Generic properties
The entity base class has a few properties common among all Home Assistant entities. These properties can be added to any entity regardless of the type. All these properties are optional and don't need to be implemented.
The entity base class has a few properties that are common among all entities in Home Assistant. These can be added to any entity regardless of the type. All these properties are optional and don't need to be implemented.
:::tip
Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data.
Because these properties are always called when the state is written to the state machine, it is crucial to do as little work as possible in the property.
:::
| Name | Type | Default | Description |
| ----------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| assumed_state | boolean | `False` | Return `True` if the state is based on our assumption instead of reading it from the device. |
| attribution | string | `None` | The branding text required by the API provider. |
| available | boolean | `True` | Indicate if Home Assistant is able to read the state and control the underlying device. |
| device_class | string | `None` | Extra classification of what the device is. Each domain specifies their own. Device classes can come with extra requirements for unit of measurement and supported features. |
| device_info | dict | `None` | [Device registry](/docs/device_registry_index) descriptor for [automatic device registration.](/docs/device_registry_index#automatic-registration-through-an-entity)
| entity_category | string | `None` | Classification of a non-primary entity. Set to `EntityCategory.CONFIG` for an entity which allows changing the configuration of a device, for example a switch entity making it possible to turn the background illumination of a switch on and off. Set to `EntityCategory.DIAGNOSTIC` for an entity exposing some configuration parameter or diagnostics of a device but does not allow changing it, for example a sensor showing RSSI or MAC-address. |
| entity_picture | URL | `None` | Url of a picture to show for the entity. |
| extra_state_attributes | dict | `None` | Extra information to store in the state machine. It needs to be information that further explains the state, it should not be static information like firmware version. |
| has_entity_name | boolean | | Return `True` if the entity's `name` property represents the entity itself (required for new integrations). This is explained in more detail below.
| name | string | `None` | Name of the entity. Avoid hard coding a natural language name, use a [translated name](/docs/internationalization/core/#name-of-entities) instead. |
| should_poll | boolean | `True` | Should Home Assistant check with the entity for an updated state. If set to `False`, entity will need to notify Home Assistant of new updates by calling one of the [schedule update methods](integration_fetching_data.md#push-vs-poll). |
| translation_key | string | `None` | A key for looking up translations of the entity's state in [`entity` section of the integration's `strings.json`](/docs/internationalization/core#state-of-entities).
| unique_id | string | `None` | A unique identifier for this entity. Needs to be unique within a platform (ie `light.hue`). Should not be configurable by the user or be changeable. [Learn more.](entity_registry_index.md#unique-id-requirements) |
:::warning
Entities that generate a significant amount of state changes can quickly increase the size of the database when the `extra_state_attributes` also change frequently. Minimize the number of `extra_state_attributes` for these entities by removing non-critical attributes or creating additional `sensor` entities.
:::
## Cached properties
The following properties are calculated only once using the `@cached_property` decorator. While it is possible to override the `@cached_property` behavior by defining `attribution` or `device_class` as a `@property`, integrations should avoid changing `device_class` at run time since anything that consumes the state may be unable to handle the `device_class` unexpectedly changing.
| Name | Type | Default | Description |
| ----------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| attribution | string | `None` | The branding text required by the API provider. |
| device_class | string | `None` | Extra classification of what the device is. Each domain specifies their own. Device classes can come with extra requirements for unit of measurement and supported features. |
| translation_key | string | `None` | A key for looking up translations of the entity's state in [`entity` section of the integration's `strings.json`](/docs/internationalization/core#state-of-entities).
## Registry properties
The following properties are used to populate the entity and device registries. They are only read when the entity is added to Home Assistant. These properties only have an effect if `unique_id` has been set.
| Name | Type | Default | Description |
| ------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| device_info | dict | `None` | [Device registry](/docs/device_registry_index) descriptor for [automatic device registration.](/docs/device_registry_index#automatic-registration-through-an-entity)
| entity_category | string | `None` | Classification of a non-primary entity. Set to `EntityCategory.CONFIG` for an entity which allows changing the configuration of a device, for example a switch entity making it possible to turn the background illumination of a switch on and off. Set to `EntityCategory.DIAGNOSTIC` for an entity exposing some configuration parameter or diagnostics of a device but does not allow changing it, for example a sensor showing RSSI or MAC-address. |
| entity_registry_enabled_default | boolean | `True` | Indicate if the entity should be enabled or disabled when first added to the entity registry. This includes fast-changing diagnostic entities or, assumingly less commonly used entities. For example, a sensor exposing RSSI or battery voltage should typically be set to `False`; to prevent unneeded (recorded) state changes or UI clutter by these entities. |
| entity_registry_visible_default | boolean | `True` | Indicate if the entity should be hidden or visible when first added to the entity registry. |
| unique_id | string | `None` | A unique identifier for this entity. Needs to be unique within a platform (ie `light.hue`). Should not be configurable by the user or be changeable. [Learn more.](entity_registry_index.md#unique-id-requirements) |
## Advanced properties
The following properties are also available on entities. However, they are for advanced use only and should be used with caution. These properties always called when the state is written to the state machine.
The following properties are also available on entities. However, they are for advanced use only and should be used with caution.
| Name | Type | Default | Description |
| ------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| entity_registry_enabled_default | boolean | `True` | Indicate if the entity should be enabled or disabled when first added to the entity registry. This includes fast-changing diagnostic entities or, assumingly less commonly used entities. For example, a sensor exposing RSSI or battery voltage should typically be set to `False`; to prevent unneeded (recorded) state changes or UI clutter by these entities. |
| entity_registry_visible_default | boolean | `True` | Indicate if the entity should be hidden or visible when first added to the entity registry. |
| force_update | boolean | `False` | Write each update to the state machine, even if the data is the same. Example use: when you are directly reading the value from a connected sensor instead of a cache. Use with caution, will spam the state machine. |
| icon | icon | `None` | Icon to use in the frontend. Icons start with `mdi:` plus an [identifier](https://materialdesignicons.com/). You probably don't need this since Home Assistant already provides default icons for all entities according to its `device_class`. This should be used only in the case where there either is no matching `device_class` or where the icon used for the `device_class` would be confusing or misleading. |