diff --git a/docs/entity_index.md b/docs/entity_index.md index 3916cf7a..b837f88b 100644 --- a/docs/entity_index.md +++ b/docs/entity_index.md @@ -56,43 +56,44 @@ The entity base class has a few properties that are common among all entities in > Properties should always only return information from memory and not do I/O (like network requests). Implement `update()` or `async_update()` to fetch data. -| 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. -| available | boolean | `True` | Indicate if Home Assistant is able to read the state and control the underlying device. -| device_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. See [below](entity_index.md#standard-attributes) for details of standard attributes. -| 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](#methods). -| 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 | Type | Default | Description | +| ----------------------- | ------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| assumed_state | boolean | `False` | Return `True` if the state is based on our assumption instead of reading it from the device. | +| 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_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. See [below](entity_index.md#standard-attributes) for details of standard attributes. | +| 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](#methods). | +| 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. -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| 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. -| hidden | boolean | `False` | Indicate if the entity should not be shown on the frontend. -| 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 devices. -| entity_registry_enabled_default | boolean | `True` | Indicate if the entity should be enabled or disabled when it is first added to the entity registry. +| Name | Type | Default | Description | +| ------------------------------- | ------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| 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. | +| hidden | boolean | `False` | Indicate if the entity should not be shown on the frontend. Deprecated. Will be removed in 0.107.0 | +| 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 devices. | +| entity_registry_enabled_default | boolean | `True` | Indicate if the entity should be enabled or disabled when it is first added to the entity registry. | ## System properties The following properties are used and controlled by Home Assistant, and should not be overridden by integrations. -| Name | Type | Default | Description -| ---- | ---- | ------- | ----------- -| enabled | boolean | `True` | Indicate if entity is enabled in the entity registry. It also returns `True` if the platform doesn't support the entity registry. Disabled entities will not be added to Home Assistant. +| Name | Type | Default | Description | +| ------- | ------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| enabled | boolean | `True` | Indicate if entity is enabled in the entity registry. It also returns `True` if the platform doesn't support the entity registry. Disabled entities will not be added to Home Assistant. | ## Standard attributes The following `device_state_attributes` are considered standard and should follow the convention below. The constant should be imported from `homeassistant/const.py`. -| Name | Type | Unit | Constant | Description -| ---- | ---- | ---- | -------- | ----------- -| battery_charging | boolean | N/A | `ATTR_BATTERY_CHARGING` | Battery charging status of the entity, shown as a boolean `true` or `false`. If charging is not supported, then this attribute should not be created. -| battery_level | integer | % | `ATTR_BATTERY_LEVEL` | Battery level of the entity, shown as an integer percentage between 0-100. +| Name | Type | Unit | Constant | Description | +| ---------------- | ------- | ---- | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| battery_charging | boolean | N/A | `ATTR_BATTERY_CHARGING` | Battery charging status of the entity, shown as a boolean `true` or `false`. If charging is not supported, then this attribute should not be created. | +| battery_level | integer | % | `ATTR_BATTERY_LEVEL` | Battery level of the entity, shown as an integer percentage between 0-100. | ## Lifecycle hooks diff --git a/docs/integration_quality_scale_index.md b/docs/integration_quality_scale_index.md index 870ad69c..128ba0dd 100644 --- a/docs/integration_quality_scale_index.md +++ b/docs/integration_quality_scale_index.md @@ -10,8 +10,8 @@ The Integration Quality Scale scores each integration based on the code quality This integration passes the bare minimum requirements to become part of the index. - - Satisfy all requirements for [creating components](creating_component_code_review.md) and [creating platforms](creating_platform_code_review.md). - - Configurable via `configuration.yaml` +- Satisfy all requirements for [creating components](creating_component_code_review.md) and [creating platforms](creating_platform_code_review.md). +- Configurable via `configuration.yaml` # Silver 🥈 @@ -34,14 +34,17 @@ This is a solid integration that is able to survive poor conditions and can be c - Don't allow configuring already configured device/service (example: no 2 entries for same hub) - Tests for the config flow - Discoverable (if available) + - Set unique ID in config flow (if available) - Entities have device info (if available) ([docs](device_registry_index.md#defining-devices)) -- States are translated in the frontend (text-based sensors only, [docs](internationalization_index.md)) -- Tests for reading data from/controlling the integration ([docs](development_testing.md)) +- Tests for fetching data from the integration and controlling it ([docs](development_testing.md)) - Has a code owner ([docs](creating_integration_manifest.md#code-owners)) +- Entities only subscribe to updates inside `async_added_to_hass` and unsubscribe inside `async_will_remove_from_hass` ([docs](entity_index.md#lifecycle-hooks)) +- Entities have correct device classes where appropriate ([docs](entity_index.md#generic-properties)) +- Supports entities being disabled and leverages `Entity.entity_registry_enabled_default` to disable less popuplar entities ([docs](entity_index.md#advanced-properties)) # Platinum 🏆 -Best of the best. The integration is completely async, meaning it's super fast. Integrations that reach platinum level will require approval by the code owner for each PR. +Best of the best. The integration is completely async, meaning it's super fast. Integrations that reach platinum level will require approval by the code owner for each PR. - Set appropriate `PARALLEL_UPDATES` constant - Support config entry unloading (called when config entry is removed) @@ -51,4 +54,3 @@ Best of the best. The integration is completely async, meaning it's super fast. # Internal 🏠 Integrations which are part of Home Assistant are not rated but marked as **internal**. -