mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-07-14 12:56:30 +00:00
Add some more things to quality scale (#389)
* Add some more things to quality scale * Update docs/entity_index.md Co-Authored-By: Bram Kragten <mail@bramkragten.nl> Co-authored-by: Bram Kragten <mail@bramkragten.nl>
This commit is contained in:
Paulus Schoutsen
GitHub
parent
84b21aa5d5
commit
0d1b6a2f6f
@ -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
|
||||
|
||||
|
||||
@ -34,10 +34,13 @@ 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 🏆
|
||||
|
||||
@ -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**.
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user