diff --git a/docs/architecture_entities.md b/docs/architecture_entities.md deleted file mode 100644 index 32e8da62..00000000 --- a/docs/architecture_entities.md +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: "Entity Architecture" -sidebar_label: Entity ---- - -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. diff --git a/docs/config_entries_index.md b/docs/config_entries_index.md index dd86170b..e044dcb8 100644 --- a/docs/config_entries_index.md +++ b/docs/config_entries_index.md @@ -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 diff --git a/docs/entity_index.md b/docs/core/entity.md similarity index 87% rename from docs/entity_index.md rename to docs/core/entity.md index f834156f..a03de840 100644 --- a/docs/entity_index.md +++ b/docs/core/entity.md @@ -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. +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). | diff --git a/docs/entity_air_quality.md b/docs/core/entity/air-quality.md similarity index 100% rename from docs/entity_air_quality.md rename to docs/core/entity/air-quality.md diff --git a/docs/entity_alarm_control_panel.md b/docs/core/entity/alarm-control-panel.md similarity index 100% rename from docs/entity_alarm_control_panel.md rename to docs/core/entity/alarm-control-panel.md diff --git a/docs/entity_binary_sensor.md b/docs/core/entity/binary-sensor.md similarity index 100% rename from docs/entity_binary_sensor.md rename to docs/core/entity/binary-sensor.md diff --git a/docs/entity_climate.md b/docs/core/entity/climate.md similarity index 100% rename from docs/entity_climate.md rename to docs/core/entity/climate.md diff --git a/docs/entity_cover.md b/docs/core/entity/cover.md similarity index 100% rename from docs/entity_cover.md rename to docs/core/entity/cover.md diff --git a/docs/entity_fan.md b/docs/core/entity/fan.md similarity index 100% rename from docs/entity_fan.md rename to docs/core/entity/fan.md diff --git a/docs/entity_light.md b/docs/core/entity/light.md similarity index 100% rename from docs/entity_light.md rename to docs/core/entity/light.md diff --git a/docs/entity_lock.md b/docs/core/entity/lock.md similarity index 100% rename from docs/entity_lock.md rename to docs/core/entity/lock.md diff --git a/docs/entity_media_player.md b/docs/core/entity/media-player.md similarity index 100% rename from docs/entity_media_player.md rename to docs/core/entity/media-player.md diff --git a/docs/entity_remote.md b/docs/core/entity/remote.md similarity index 100% rename from docs/entity_remote.md rename to docs/core/entity/remote.md diff --git a/docs/entity_sensor.md b/docs/core/entity/sensor.md similarity index 100% rename from docs/entity_sensor.md rename to docs/core/entity/sensor.md diff --git a/docs/entity_switch.md b/docs/core/entity/switch.md similarity index 100% rename from docs/entity_switch.md rename to docs/core/entity/switch.md diff --git a/docs/entity_vacuum.md b/docs/core/entity/vacuum.md similarity index 100% rename from docs/entity_vacuum.md rename to docs/core/entity/vacuum.md diff --git a/docs/entity_water_heater.md b/docs/core/entity/water-heater.md similarity index 100% rename from docs/entity_water_heater.md rename to docs/core/entity/water-heater.md diff --git a/docs/entity_weather.md b/docs/core/entity/weather.md similarity index 100% rename from docs/entity_weather.md rename to docs/core/entity/weather.md diff --git a/docs/creating_integration_file_structure.md b/docs/creating_integration_file_structure.md index 3d2c9e1c..c1683442 100644 --- a/docs/creating_integration_file_structure.md +++ b/docs/creating_integration_file_structure.md @@ -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` diff --git a/docs/creating_platform_code_review.md b/docs/creating_platform_code_review.md index 33a801fa..fd1d1c55 100644 --- a/docs/creating_platform_code_review.md +++ b/docs/creating_platform_code_review.md @@ -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 diff --git a/docs/creating_platform_index.md b/docs/creating_platform_index.md index e84d366d..97accba6 100644 --- a/docs/creating_platform_index.md +++ b/docs/creating_platform_index.md @@ -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. diff --git a/docs/integration_quality_scale_index.md b/docs/integration_quality_scale_index.md index a364a21b..8421fe24 100644 --- a/docs/integration_quality_scale_index.md +++ b/docs/integration_quality_scale_index.md @@ -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 🏆 diff --git a/sidebars.js b/sidebars.js index e2cc5ec1..e4531559 100644 --- a/sidebars.js +++ b/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", diff --git a/static/_redirects b/static/_redirects index 2480ecbb..1df1055f 100644 --- a/static/_redirects +++ b/static/_redirects @@ -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