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-10 02:46:29 +00:00
Code Issues Packages Projects Releases Wiki Activity

Document config entry removal from device (#1215)

Browse Source 
* Document config entry removal from device

* Update docs/device_registry_index.md

Co-authored-by: Franck Nijhof <git@frenck.dev>

* Update docs/device_registry_index.md

Co-authored-by: Martin Hjelmare <marhje52@gmail.com>

Co-authored-by: Franck Nijhof <git@frenck.dev>
Co-authored-by: Martin Hjelmare <marhje52@gmail.com>
This commit is contained in:
Erik Montnemery 2022-02-21 10:12:45 +01:00 committed by GitHub
parent df72f05d41
commit 97666fc85d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 12 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/device_registry_index.md
View File

@ -11,7 +11,7 @@ The device registry is a registry where Home Assistant keeps track of devices. A
## What is a device?
A device in Home Assistant represents a physical device that has its own control unit. The control unit itself does not have to be smart, but it should be in control of what happens. For example, an Ecobee thermostat with 4 room sensors equals 5 devices in Home Assistant, one for the thermostat including all sensors inside it, and one for each sensor. Each device exists in a specific geographical area, and may have more than one input or output within that area.
A device in Home Assistant represents either a physical device that has its own control unit, or a service. The control unit itself does not have to be smart, but it should be in control of what happens. For example, an Ecobee thermostat with 4 room sensors equals 5 devices in Home Assistant, one for the thermostat including all sensors inside it, and one for each sensor. Each device exists in a specific geographical area, and may have more than one input or output within that area.
If you connect a sensor to another device to read some of its data, it should still be represented as two different devices. The reason for this is that the sensor could be moved to read the data of another device.
@ -32,7 +32,7 @@ Although not currently available, we could consider offering an option to users
| default_name | Default name of this device, will be overridden if `name` is set. Useful for example for an integration showing all devices on the network. |
| default_manufacturer | The manufacturer of the device, will be overridden if `manufacturer` is set. Useful for example for an integration showing all devices on the network. |
| default_model | The model of the device, will be overridden if `model` is set. Useful for example for an integration showing all devices on the network. |
| entry_type | The type of entry. Possible values are `None` and `DeviceEntryType` enum members. |
| entry_type | The type of entry. Possible values are `None` and `DeviceEntryType` enum members (only `service`). |
| id | Unique ID of device (generated by Home Assistant) |
| identifiers | Set of `(DOMAIN, identifier)` tuples. Identifiers identify the device in the outside world. An example is a serial number. |
| name | Name of this device |
@ -45,6 +45,7 @@ Although not currently available, we could consider offering an option to users
## Defining devices
### Automatic registration through an entity
:::tip
Entity device info is only read if the entity is loaded via a [config entry](config_entries_index.md) and the `unique_id` property is defined.
:::
@ -93,3 +94,12 @@ device_registry.async_get_or_create(
hw_version=config.hwversion,
)
```
## Removing devices
Integrations can opt-in to allow the user to delete a device from the UI. To opt-in to allow removing devices, the integration should implement `async_remove_config_entry_device` in its `__init__.py`. If the device is shared between multiple config entries, only the config entry opting into removing devices will be removed from the device.
When the user deletes the device (or removes one of its config entries for devices with multiple config entries) the following will happen:
- `async_remove_config_entry_device` is called, the integration should take necessary steps to prepare for device removal and return `True` if successful.
- If `async_remove_config_entry_device` returned True, the config entry is removed from the device and all entities included in the device belonging to the config entry are automatically removed too. If this was the only config entry, the device is automatically removed.
- The integration may optionally act on `EVENT_DEVICE_REGISTRY_UPDATED` if that's more convenient than doing the cleanup in `async_remove_config_entry_device`.