mirror of
https://github.com/home-assistant/developers.home-assistant.git
synced 2025-06-05 17:56:30 +00:00
Move and merge entity documentation (#544)
This commit is contained in:
Franck Nijhof
GitHub
parent
12348dcbc4
commit
0145bbbfa7
@ -1,43 +0,0 @@
|
||||
---
|
||||
title: "Entity Architecture"
|
||||
sidebar_label: Entity
|
||||
---
|
||||
|
||||
<img class='invertDark'
|
||||
src='/img/en/architecture/entities_architecture.png'
|
||||
alt='Architecture Overview of Home Assistant' />
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration is provided by the [configuration.yaml file](configuration_yaml_index.md) or by a [Config Entry](config_entries_index.md).
|
||||
|
||||
## Component
|
||||
|
||||
Examples of components: `light`, `switch`.
|
||||
|
||||
The component is responsible for defining the Abstract Entity Class and services to control the entities.
|
||||
|
||||
## Entity Component
|
||||
|
||||
The Entity Component is responsible for:
|
||||
|
||||
- Distributing the configuration to the platforms
|
||||
- Forward config entries and discoveries
|
||||
- Collect entities for service calls
|
||||
- Optionally maintain a group of all entities
|
||||
|
||||
## Entity Platform
|
||||
|
||||
The Entity Platform manages all entities for the platform and polls them for updates if necessary.
|
||||
|
||||
When adding entities, the Entity Platform will query the Entity Registry to make sure that the entities to be added have the correct entity IDs.
|
||||
|
||||
## Entity Registry
|
||||
|
||||
The [Entity Registry](entity_registry_index.md) will track entities and allows users to store extra settings for an entity.
|
||||
|
||||
## Platform
|
||||
|
||||
Examples of platforms: `light.hue`, `switch.wemo`.
|
||||
|
||||
Platform uses configuration to query the external device/service and add entities to the entity platform.
|
||||
@ -126,7 +126,7 @@ For each platform that you forwarded the config entry to, you will need to forwa
|
||||
await self.hass.config_entries.async_forward_entry_unload(self.config_entry, "light")
|
||||
```
|
||||
|
||||
If you need to clean up resources used by an entity in a platform, have the entity implement the [`async_will_remove_from_hass`](entity_index.md#async_will_remove_from_hass) method.
|
||||
If you need to clean up resources used by an entity in a platform, have the entity implement the [`async_will_remove_from_hass`](core/entity.md#async_will_remove_from_hass) method.
|
||||
|
||||
## Removal of entries
|
||||
|
||||
|
||||
@ -5,6 +5,47 @@ sidebar_label: Introduction
|
||||
|
||||
Each device is represented in Home Assistant as an entity. An entity abstracts away the internal working of Home Assistant. As an integrator you don't have to worry about how services or the state machine work. Instead, you extend an entity class and implement the necessary properties and methods for the device type that you're integrating.
|
||||
|
||||
<img class='invertDark'
|
||||
src='/img/en/architecture/entities_architecture.png'
|
||||
alt='Architecture Overview of Home Assistant' />
|
||||
|
||||
## Configuration
|
||||
|
||||
Configuration is provided by the [configuration.yaml file](configuration_yaml_index.md) or by a [Config Entry](config_entries_index.md).
|
||||
|
||||
## Component
|
||||
|
||||
Examples of components: `light`, `switch`.
|
||||
|
||||
The component is responsible for defining the Abstract Entity Class and services to control the entities.
|
||||
|
||||
## Entity Component
|
||||
|
||||
The Entity Component is responsible for:
|
||||
|
||||
- Distributing the configuration to the platforms
|
||||
- Forward config entries and discoveries
|
||||
- Collect entities for service calls
|
||||
- Optionally maintain a group of all entities
|
||||
|
||||
## Entity Platform
|
||||
|
||||
The Entity Platform manages all entities for the platform and polls them for updates if necessary.
|
||||
|
||||
When adding entities, the Entity Platform will query the Entity Registry to make sure that the entities to be added have the correct entity IDs.
|
||||
|
||||
## Entity Registry
|
||||
|
||||
The [Entity Registry](entity_registry_index.md) will track entities and allows users to store extra settings for an entity.
|
||||
|
||||
## Platform
|
||||
|
||||
Examples of platforms: `light.hue`, `switch.wemo`.
|
||||
|
||||
Platform uses configuration to query the external device/service and add entities to the entity platform.
|
||||
|
||||
## Basic implementation
|
||||
|
||||
Below is an example switch entity that keeps track of their state in memory.
|
||||
|
||||
```python
|
||||
@ -63,7 +104,7 @@ Properties should always only return information from memory and not do I/O (lik
|
||||
| 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. |
|
||||
| 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](core/entity.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). |
|
||||
@ -14,7 +14,7 @@ The bare minimum content of this folder looks like this:
|
||||
|
||||
If your integration is going to integrate one or more devices, you will need to do this by creating a platform that interacts with an entity integration. For example, if you want to represent a light device inside Home Assistant, you will create `light.py`, which will contain a light platform for the light integration.
|
||||
|
||||
- More info on [available entity integrations](entity_index.md).
|
||||
- More info on [available entity integrations](core/entity.md).
|
||||
- More info on [creating platforms](creating_platform_index.md).
|
||||
|
||||
## Integrating services - `services.yaml`
|
||||
|
||||
@ -72,7 +72,7 @@ PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend(
|
||||
3. Do not call `update()` in constructor, use `add_entities(devices, True)` instead.
|
||||
4. Do not do any I/O inside properties. Cache values inside `update()` instead.
|
||||
5. When dealing with time, state and/or attributes should not contain relative time since something happened. Instead, it should store UTC timestamps.
|
||||
6. Leverage the [entity lifecycle callbacks](entity_index.md#lifecycle-hooks) to attach event listeners or clean up connections.
|
||||
6. Leverage the [entity lifecycle callbacks](core/entity.md#lifecycle-hooks) to attach event listeners or clean up connections.
|
||||
|
||||
### 5. Communication with devices/services
|
||||
|
||||
|
||||
@ -3,7 +3,7 @@ title: "Integration Platforms"
|
||||
sidebar_label: "Platforms"
|
||||
---
|
||||
|
||||
Home Assistant has various built-in integrations that abstract device types. There are [lights](entity_light.md), [switches](entity_switch.md), [covers](entity_cover.md), [climate devices](entity_climate.md), and [many more](entity_index.md). Your integration can hook into these integrations by creating a platform. You will need a platform for each integration that you are integrating with.
|
||||
Home Assistant has various built-in integrations that abstract device types. There are [lights](core/entity/light.md), [switches](core/entity/switch.md), [covers](core/entity/cover.md), [climate devices](core/entity/climate.md), and [many more](core/entity.md). Your integration can hook into these integrations by creating a platform. You will need a platform for each integration that you are integrating with.
|
||||
|
||||
To create a platform, you will need to create a file with the domain name of the integration that you are building a platform for. So if you are building a light, you will add a new file `light.py` to your integration folder.
|
||||
|
||||
@ -18,4 +18,4 @@ One Home Assistant rule is that the integration should never interface directly
|
||||
|
||||
Once you have your Python library ready and published to PyPI, add it to the [manifest](creating_integration_manifest.md). It will now be time to implement the Entity base class that is provided by the integration that you are creating a platform for.
|
||||
|
||||
Find your integration at the [entity index](entity_index.md) to see what methods and properties are available to implement.
|
||||
Find your integration at the [entity index](core/entity.md) to see what methods and properties are available to implement.
|
||||
|
||||
@ -25,7 +25,7 @@ This integration is able to cope when things go wrong. It will not print any exc
|
||||
- Handles expiration of auth credentials. Refresh if possible or print correct error and fail setup. If based on a config entry, should trigger a new config entry flow to re-authorize.
|
||||
- Handles internet unavailable. Log a warning once when unavailable, log once when reconnected.
|
||||
- Handles device/service unavailable. Log a warning once when unavailable, log once when reconnected.
|
||||
- Set `available` property to `False` if appropriate ([docs](entity_index.md#generic-properties))
|
||||
- Set `available` property to `False` if appropriate ([docs](core/entity.md#generic-properties))
|
||||
- Entities have unique ID (if available) ([docs](entity_registry_index.md#unique-id-requirements))
|
||||
|
||||
## Gold 🥇
|
||||
@ -40,9 +40,9 @@ This is a solid integration that is able to survive poor conditions and can be c
|
||||
- Entities have device info (if available) ([docs](device_registry_index.md#defining-devices))
|
||||
- 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 popular entities ([docs](entity_index.md#advanced-properties))
|
||||
- Entities only subscribe to updates inside `async_added_to_hass` and unsubscribe inside `async_will_remove_from_hass` ([docs](core/entity.md#lifecycle-hooks))
|
||||
- Entities have correct device classes where appropriate ([docs](core/entity.md#generic-properties))
|
||||
- Supports entities being disabled and leverages `Entity.entity_registry_enabled_default` to disable less popular entities ([docs](core/entity.md#advanced-properties))
|
||||
- If the device/service API can remove entities, the integration should make sure to clean up the entity and device registry.
|
||||
|
||||
## Platinum 🏆
|
||||
|
||||
44
sidebars.js
44
sidebars.js
@ -73,29 +73,7 @@ module.exports = {
|
||||
Supervisor: ["supervisor", "supervisor/developing", "supervisor/debugging"],
|
||||
// Old structure, still to move/migrate
|
||||
Architecture: {
|
||||
Architecture: [
|
||||
"architecture_index",
|
||||
"architecture_components",
|
||||
"architecture_entities",
|
||||
],
|
||||
Entities: [
|
||||
"entity_index",
|
||||
"entity_air_quality",
|
||||
"entity_alarm_control_panel",
|
||||
"entity_binary_sensor",
|
||||
"entity_climate",
|
||||
"entity_cover",
|
||||
"entity_fan",
|
||||
"entity_light",
|
||||
"entity_lock",
|
||||
"entity_media_player",
|
||||
"entity_remote",
|
||||
"entity_sensor",
|
||||
"entity_switch",
|
||||
"entity_vacuum",
|
||||
"entity_water_heater",
|
||||
"entity_weather",
|
||||
],
|
||||
Architecture: ["architecture_index", "architecture_components"],
|
||||
Authentication: [
|
||||
"auth_index",
|
||||
"auth_permissions",
|
||||
@ -109,7 +87,7 @@ module.exports = {
|
||||
"Device Registry": ["device_registry_index"],
|
||||
"Area Registry": ["area_registry_index"],
|
||||
},
|
||||
"Extending Home Assistant": {
|
||||
Core: {
|
||||
"Development Workflow": [
|
||||
"development_index",
|
||||
"development_environment",
|
||||
@ -144,6 +122,24 @@ module.exports = {
|
||||
"dev_101_states",
|
||||
"dev_101_config",
|
||||
],
|
||||
Entities: [
|
||||
"core/entity",
|
||||
"core/entity/air-quality",
|
||||
"core/entity/alarm-control-panel",
|
||||
"core/entity/binary-sensor",
|
||||
"core/entity/climate",
|
||||
"core/entity/cover",
|
||||
"core/entity/fan",
|
||||
"core/entity/light",
|
||||
"core/entity/lock",
|
||||
"core/entity/media-player",
|
||||
"core/entity/remote",
|
||||
"core/entity/sensor",
|
||||
"core/entity/switch",
|
||||
"core/entity/vacuum",
|
||||
"core/entity/water-heater",
|
||||
"core/entity/weather",
|
||||
],
|
||||
"Device Automations": [
|
||||
"device_automation_index",
|
||||
"device_automation_trigger",
|
||||
|
||||
@ -8,9 +8,27 @@
|
||||
/docs/app_integration_sensors /docs/api/native-app-integration/sensors
|
||||
/docs/app_integration_setup /docs/api/native-app-integration/setup
|
||||
/docs/app_integration_webview /docs/api/native-app-integration/webview
|
||||
/docs/architecture_entities /docs/core/entity
|
||||
/docs/architecture_hassio /docs/supervisor
|
||||
/docs/documentation_create_page /docs/documenting/create-page
|
||||
/docs/documentation_index /docs/documenting
|
||||
/docs/documentation_standards /docs/documenting/standards
|
||||
/docs/entity_air_quality /docs/core/entity/air-quality
|
||||
/docs/entity_alarm_control_panel /docs/core/entity/alarm-control-panel
|
||||
/docs/entity_binary_sensor /docs/core/entity/binary-sensor
|
||||
/docs/entity_climate /docs/core/entity/climate
|
||||
/docs/entity_cover /docs/core/entity/cover
|
||||
/docs/entity_fan /docs/core/entity/fan
|
||||
/docs/entity_index /docs/core/entity
|
||||
/docs/entity_light /docs/core/entity/light
|
||||
/docs/entity_lock /docs/core/entity/lock
|
||||
/docs/entity_media_player /docs/core/entity/media-player
|
||||
/docs/entity_remote /docs/core/entity/remote
|
||||
/docs/entity_sensor /docs/core/entity/sensor
|
||||
/docs/entity_switch /docs/core/entity/switch
|
||||
/docs/entity_vacuum /docs/core/entity/vacuum
|
||||
/docs/entity_water_heater /docs/core/entity/water-heater
|
||||
/docs/entity_weather /docs/core/entity/weather
|
||||
/docs/external_api_rest /docs/api/rest
|
||||
/docs/external_api_websocket /docs/api/websocket
|
||||
/docs/frontend_add_card /docs/frontend/extending/adding-state-card
|
||||
@ -39,4 +57,3 @@
|
||||
/docs/internationalization_index /docs/internationalization
|
||||
/docs/internationalization_translation /docs/translations
|
||||
/docs/lovelace_custom_card /docs/frontend/custom-ui/lovelace-custom-card
|
||||
/docs/architecture_hassio /docs/supervisor
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user