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-07-14 12:56:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add some more things to quality scale (#389)

Browse Source 
* 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 2020-01-18 21:34:07 -08:00 committed by GitHub
parent 84b21aa5d5
commit 0d1b6a2f6f
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 31 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs/entity_index.md
View File

@ -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

14
docs/integration_quality_scale_index.md
View File

@ -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**.