From fc7ffff3302f3eb5cf1397aba336092d34724373 Mon Sep 17 00:00:00 2001 From: Erik Montnemery Date: Fri, 15 Oct 2021 13:01:08 +0200 Subject: [PATCH] Document entity category (#1088) Co-authored-by: Martin Hjelmare Co-authored-by: Franck Nijhof --- docs/core/entity.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/docs/core/entity.md b/docs/core/entity.md index 9fb3f649..8d715e2b 100644 --- a/docs/core/entity.md +++ b/docs/core/entity.md @@ -62,15 +62,16 @@ Properties should always only return information from memory and not do I/O (lik | 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. | +| 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. | +| entity_category | string | `None` | Classification of a non-primary entity. Set to `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 `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. | -| entity_picture | URL | `None` | Url of a picture to show for the entity. | -| name | string | `None` | Name of the entity | -| 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). | -| 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) | +| name | string | `None` | Name of the entity | +| 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). | +| 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 @@ -78,9 +79,9 @@ The following properties are also available on entities. However, they are for a | 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. | | 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. | -| entity_registry_enabled_default | boolean | `True` | Indicate if the entity should be enabled or disabled when it is first added to the entity registry. | +| 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. | ## System properties