Reorganize architecture section (#839)

This commit is contained in:
Paulus Schoutsen 2021-03-10 09:17:54 -08:00 committed by GitHub
parent 83d19c10ba
commit bc55ccd987
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
13 changed files with 89 additions and 64 deletions

View File

@ -0,0 +1,57 @@
---
title: "Entities: integrating devices & services"
sidebar_label: "Introduction"
---
Integrations can represent devices & services in Home Assistant. The data points are represented as entities. Entities are standardized by other integrations like `light`, `switch`, etc. Standardized entities come with services for control, but an integration can also provide their own services in case something is not standardized.
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 className='invertDark'
src='/img/en/architecture/integrating-devices-services.svg'
alt='Integrating devices & services' />
<!--
https://docs.google.com/drawings/d/1oysZ1VMcPPuyKhY4tequsBWcblDdLydbWxlu6bH6678/edit?usp=sharing
-->
Configuration is provided by the user via a [Config Entry](../config_entries_index.md) or in special/legacy cases via [configuration.yaml](../configuration_yaml_index.md).
The device integration (i.e. `hue`) will use this configuration to set up a connection with the device/service. It will forward the config entry (legacy uses discovery helper) to set up its entities in their respective integrations (light, switch). The device integration can also register their own services for things that are not made standardized. These services are published under the integration's domain, ie `hue.activate_scene`.
The entity integration (i.e. `light`) is responsible for defining the abstract entity class and services to control the entities.
The Entity Component helper is responsible for distributing the configuration to the platforms, forward discovery and collect entities for service calls.
The Entity Platform helper manages all entities for the platform and polls them for updates if necessary. When adding entities, the Entity Platform is responsible for registering the entity with the device and entity registries.
Integration Platform (i.e. `hue.light`) uses configuration to query the external device/service and create entities to be added. It is also possible for integration platforms to register entity services. These services will work on all entities of the device integration for the entity integration (i.e. all Hue light entities). These services are published under the device integration domain.
## Entity interaction with Home Assistant Core
The integration entity class that inherits from the entity base class is responsible for fetching the data and handle the service calls. If polling is disabled, it is also responsible for telling Home Assistant when data is available.
<img className='invertDark'
src='/img/en/architecture/entity-core-interaction.svg'
alt='Entities interacting with core' />
<!--
https://docs.google.com/drawings/d/12Z0t6hriYrQZ2L5Ou7BVhPDd9iGvOvFiGniX5sgqsE4/edit?usp=sharing
-->
The entity base class (defined by the entity integration) is responsible for formatting the data and writing it to the state machine.
The entity registry will write an `unavailable` state for any registered entity that is not currently backed by an entity object.
## Entity data hierarchy
<img className='invertDark'
style={{maxWidth: "200px"}}
src='/img/en/architecture/entity-data-hierarchy.svg'
alt='Entity hierarchy' />
<!--
https://docs.google.com/drawings/d/1TorZABszaj3m7tgTyf-EMrheYCj3HAvwXB8YmJW5NZ4/edit?usp=sharing
-->
Delete, disable or re-enable any object and all objects below will be adjusted accordingly.

View File

@ -1,29 +1,29 @@
---
title: "Components Architecture"
sidebar_label: "Components"
title: "Integration Architecture"
sidebar_label: "Integrations"
---
Home Assistant can be extended with **components**. Each component is responsible for a specific domain within Home Assistant. Components can listen for or trigger events, offer services, and maintain states. Components are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in components](https://www.home-assistant.io/integrations/).
Home Assistant can be extended with **integrations**. Each integration is responsible for a specific domain within Home Assistant. Integrations can listen for or trigger events, offer services, and maintain states. Integrations are made up of a component (the base logic) and platforms (bits that integrate with other integrations). Integrations are written in Python and can do all the goodness that Python has to offer. Out of the box, Home Assistant offers a bunch of [built-in integrations](https://www.home-assistant.io/integrations/).
<img class='invertDark'
src='/img/en/architecture/component_interaction.png'
alt='Diagram showing interaction between components and the Home Assistant core.' />
alt='Diagram showing interaction between integrations and the Home Assistant core.' />
There are two types of components within Home Assistant: components that interact with an Internet of Things domain, and components that respond to events that happen within Home Assistant. Read on to learn about each type!
There are two types of integrations within Home Assistant: integrations that interact with an Internet of Things domain, and integrations that respond to events that happen within Home Assistant. Read on to learn about each type!
## Components that interact with an Internet-of-Things domain
## Integrations that interact with an Internet-of-Things domain
These components track devices within a specific domain and consist of a core part and platform-specific logic. These components make their information available via the State Machine and the Event Bus. The components also register services in the Service Registry to expose control of the devices.
These integrations track devices within a specific domain and consist of a core part and platform-specific logic. These integrations make their information available via the State Machine and the Event Bus. The integrations also register services in the Service Registry to expose control of the devices.
For example, the built-in [`switch` component](https://www.home-assistant.io/components/switch/) is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform and a light component might interact with the Hue or LIFX platform.
For example, the built-in [`switch` component](https://www.home-assistant.io/integrations/switch/) is responsible for interaction with different types of switches. A platform provides support for a particular kind or brand of device. For example, a switch could use a WeMo or Orvibo platform and a light component might interact with the Hue or LIFX platform.
If you want to add support for a new platform, check out the [add new platform section](creating_platform_index.md).
## Components that respond to events that happen within Home Assistant
## Integrations that respond to events that happen within Home Assistant
These components provide small pieces of home automation logic or involve services that do common tasks within your house.
These integrations provide small pieces of home automation logic or involve services that do common tasks within your house.
For example, the [`device_sun_light_trigger` component](https://www.home-assistant.io/components/device_sun_light_trigger/) tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and people are home. The component uses logic like this:
For example, the [`device_sun_light_trigger` component](https://www.home-assistant.io/integrations/device_sun_light_trigger/) tracks the state of devices and the sun to make sure that the lights are turned on when it gets dark and people are home. The component uses logic like this:
```text
In the event that device 'Paulus Nexus 5' changes to the 'Home' state:
@ -49,7 +49,7 @@ When we put all the different pieces of Home Assistant together, it's a close ma
<img class='invertDark'
src='/img/en/architecture/ha_full_architecture.png'
alt='Overview of the full Home Assistant architecture with a couple of loaded components and platforms'
alt='Overview of the full Home Assistant architecture with a couple of loaded integrations and platforms'
/>
The platform logic for components uses third-party Python libraries to communicate with the devices. Through this, we can leverage some of the best libraries in the Python community.
The platform logic for integrations uses third-party Python libraries to communicate with the devices. Through this, we can leverage some of the best libraries in the Python community.

View File

@ -1,6 +1,5 @@
---
title: Area Registry
sidebar_label: Introduction
---
The area registry is a registry where Home Assistant keeps track of areas. An area represents a physical location for Home Assistant. It can be used to place devices in different areas.

View File

@ -1,6 +1,5 @@
---
title: Config Entries
sidebar_label: Introduction
---
Config Entries are configuration data that are persistently stored by Home Assistant. A config entry is created by a user via the UI. The UI flow is powered by a [config flow handler](config_entries_config_flow_handler.md) as defined by the component. Config entries can also have an extra [options flow handler](config_entries_options_flow_handler.md), also defined by the component.

View File

@ -3,46 +3,9 @@ title: Entity
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.
For a generic introduction of entities, see [entities architecture](../architecture/devices-and-services.md).
<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

View File

@ -1,6 +1,5 @@
---
title: Data Entry Flow
sidebar_label: Introduction
---
Data Entry Flow is a data entry framework that is part of Home Assistant. Data entry is done via data entry flows. A flow can represent a simple login form or a multi-step setup wizard for a component. A Flow Manager manages all flows that are in progress and handles creation of new flows.
@ -309,10 +308,10 @@ class TestFlow(config_entries.ConfigFlow, domain=DOMAIN):
VERSION = 1
task_one = None
task_two = None
async def _async_do_task(self, task):
await task # A task that take some time to complete.
# Continue the flow after show progress when the task is done.
# To avoid a potential deadlock we create a new task that continues the flow.
# The task must be completely done so the flow can await the task

View File

@ -1,6 +1,5 @@
---
title: Device Registry
sidebar_label: Introduction
---
The device registry is a registry where Home Assistant keeps track of devices. A device is represented in Home Assistant via one or more entities. For example, a battery-powered temperature and humidity sensor might expose entities for temperature, humidity and battery level.
@ -80,7 +79,7 @@ device_registry.async_get_or_create(
connections={(dr.CONNECTION_NETWORK_MAC, config.mac)},
identifiers={(DOMAIN, config.bridgeid)},
manufacturer="Signify",
suggested_area="Kitchen",
suggested_area="Kitchen",
name=config.name,
model=config.modelid,
sw_version=config.swversion,

View File

@ -1,6 +1,5 @@
---
title: Entity Registry
sidebar_label: Introduction
---
The entity registry is a registry where Home Assistant keeps track of entities. Any entity that is added to Home Assistant which specifies the [`unique_id` attribute](/core/entity.md#generic-properties) will be registered in the registry.

View File

@ -93,11 +93,18 @@ module.exports = {
"auth_auth_provider",
"auth_auth_module",
],
"Config Entries": ["config_entries_index"],
"Data Entry Flow": ["data_entry_flow_index"],
"Entity Registry": ["entity_registry_index", "entity_registry_disabled_by"],
"Device Registry": ["device_registry_index"],
"Area Registry": ["area_registry_index"],
Configuration: [
"config_entries_index",
"data_entry_flow_index"
],
"Integrating devices & services": [
"architecture/devices-and-services",
"entity_registry_index",
"entity_registry_disabled_by",
"device_registry_index",
"area_registry_index"
]
},
Core: {
"Development Workflow": [

Binary file not shown.

Before

Width:  |  Height:  |  Size: 34 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 97 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 27 KiB

File diff suppressed because one or more lines are too long

After

Width:  |  Height:  |  Size: 233 KiB