Add dev reg info

docs/device_registry_index.md

@@ -3,23 +3,66 @@ title: Device Registry
 sidebar_label: Introduction
 ---
 
-The device registry is a registry where Home Assistant keeps track of devices that exposes entities. Any entity that is added to Home Assistant through a config entry and follows entity registry requirements can be put in the registry.
+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 a humidity sensor might expose entities for temperature, humidity and battery level.
 
-Assigning an entity to the device registry is done by having a device_info property. For hubs you need to manually create a device entry to the device registry.
+<img
+  src='/img/en/device_registry/overview.png'
+  alt='Device registry overview'
+/>
 
-Being registered has the advantage that there is a single point of identifying entities belonging to one device.
+| Attribute | Description |
+| --------- | ----------- |
+| id | Unique ID of device (generated by Home Assistant)
+| name | Name of this device
+| connections | A set of tuples of `(connection_type, connection identifier)`. Connection types are defined in the device registry module.
+| identifiers | Identifiers identify the device in the outside world. An example is a serial number.
+| manufacturer | The manufacturer of the device.
+| model | The model of the device.
+| config_entries | Config entries that are linked to this device.
+| sw_version | The firmware version of the device.
 
-## Defining a device
+## Defining devices
 
-Attributes for a device are connections, identifiers, manufacturer, model, name and sw_version. For hubs the config entry is also required.
+Each entity is able to define a device via the `device_info` property. This property is read when an entity is added to Home Assistant via a config entry. A device will be be matched up with an existing device via supplied identifiers and connections, like serial numbers or MAC addresses.
 
-A device is looked up in the registry based on its' identifiers and connections (sets of tuples with keyword and a unique value). Identifiers needs to be common spanning all related entities.
+```python
+# Inside a platform
+class HueLight(LightEntity):
 
-Good sources for identifiers are
+    @property
+    def device_info(self):
+        return {
+            'identifiers': {
+                # Serial numbers are unique identifiers within a specific domain
+                (hue.DOMAIN, self.unique_id)
+            },
+            'name': self.name,
+            'manufacturer': self.light.manufacturername,
+            'model': self.light.productname,
+            'sw_version': self.light.swversion,
+        }
 
- - Serial number of a device
- - MAC address of a device
+```
 
-Good sources for connections are
+Components are also able to register devices in the case that there are no entities representing them. An example is a hub that communicates with the lights.
 
-- MAC address of a device
+```python
+# Inside a component
+from homeassistant.helpers import device_registry as dr
+
+device_registry = await dr.async_get_registry(hass)
+
+device_registry.async_get_or_create(
+    config_entry=entry.entry_id,
+    connections={
+        (dr.CONNECTION_NETWORK_MAC, config.mac)
+    },
+    identifiers={
+        (DOMAIN, config.bridgeid)
+    },
+    manufacturer='Signify',
+    name=config.name,
+    model=config.modelid,
+    sw_version=config.swversion,
+)
+```

website/i18n/en.json

@@ -52,6 +52,7 @@
     "development_testing": "Testing your code",
     "development_typing": "Adding type hints to your code",
     "development_validation": "Validate the input",
+    "device_registry_index": "Device Registry",
     "documentation_create_page": "Create a new page",
     "documentation_index": "Documentation",
     "documentation_standards": "Standards",
@@ -104,6 +105,7 @@
     "hassio_addon_presentation": "Presenting your add-on",
     "hassio_addon_publishing": "Publishing your add-on",
     "hassio_addon_repository": "Create an add-on repository",
+    "hassio_addon_security": "hassio_addon_security",
     "hassio_addon_testing": "Local add-on testing",
     "hassio_addon_tutorial": "Tutorial: Making your first add-on",
     "hassio_debugging": "Debugging Hass.io",
@@ -133,6 +135,7 @@
     "Config Entries": "Config Entries",
     "Data Entry Flow": "Data Entry Flow",
     "Entity Registry": "Entity Registry",
+    "Device Registry": "Device Registry",
     "Extending the frontend": "Extending the frontend",
     "Custom UI": "Custom UI",
     "Developing a feature": "Developing a feature",