集成设备和服务

介绍

集成可以代表HA中的设备和服务。数据节点被表示为实体。实体是由其他集成来标准化的，比如灯、开关等。标准化的实体附带了用于控制的服务，但是如果某些东西没有标准化，集成也可以提供自己的服务。

实体抽象了HA的内部工作。作为一个集成商，您不必担心服务或状态机是如何工作的。相反，您可以扩展一个实体类，并为正在集成的设备类型实现必要的属性和方法。

• 配置由用户通过Config Entry提供，或者在特殊/空缺情况下通过Configuration .yaml提供。
• Device Integration(例如hue)将使用这个配置来建立与设备/服务的连接。它将转发配置项(遗留系统使用discovery helper)以在各自的集成(light、switch)中设置其实体。该设备集成还可以为未标准化的事物注册自己的服务。这些服务发布在集成的域下，比如hue.activate_scene。
• entity integration负责定义抽象实体类和服务来控制实体。
• Entity Component helper负责将配置分发到平台，转发服务调用的发现和收集实体。
• Entity Platform helper管理平台的所有实体，并在必要时轮询它们以获取更新。添加实体时，实体平台负责向设备和实体注册中心注册实体。
• Integration Platform集成平台(比如hue.light)使用配置来查询外部设备/服务，并创建要添加的实体。集成平台也可以注册实体服务。这些服务将工作在设备集成的所有实体上进行实体集成(比如所有Hue灯光实体)。这些服务在设备集成域下发布。

实体与HA Core交互

从实体基类继承的集成实体类负责获取数据并处理服务调用。如果轮询被禁用，它还负责告诉Home Assistant何时有数据可用。

实体基类(由实体集成定义)负责格式化数据并将其写入状态机。

实体注册表将为任何当前未受实体对象支持的已注册实体写一个不可用状态。

实体数据层次结构

删除、禁用或重新启用任何对象，下面的所有对象都会相应调整。

实体注册表（Entity Registry）

实体注册表是Home Assistant跟踪实体的注册表。添加到Home Assistant的任何指定unique_id属性的实体都将在注册表中注册。

注册的好处是相同的实体将总是获得相同的实体ID。它还将阻止其他实体使用该实体ID。

用户还可以在实体注册表中覆盖实体的名称。设置实体注册表时，使用实体注册表的名称，而不是设备本身的名称。

唯一ID

用户不可能更改唯一ID，这一点很重要，因为系统会丢失与唯一ID相关的所有设置。

根据平台类型(例如，light)、集成名称(例如，hue)和实体的唯一ID在注册表中查找实体。实体不应该在他们的Unique ID中包含域(如your_integration)和平台类型(如light)，因为系统已经为这些标识提供了账号。

如果一个设备有一个唯一id，但提供了多个实体，则可以将唯一id与实体的唯一标识符结合使用。例如，当设备同时测量温度和湿度时，可以使用{unique_id}-{sensor_type}唯一标识该实体。

惟一的ID要求

唯一ID的可接受源示例

• 设备序列号
• MAC地址:使用homeassistant.helpers.device_registry.format_mac;只能从设备API或发现处理程序（discovery handler）中获取MAC地址。依赖于读取arp缓存或本地网络访问的工具，如getmac，将不能在所有支持的网络环境中工作，这是不可接受的。
• 经纬度或其他独特的地理位置
• 在设备上打印或刻录到EEPROM中的唯一标识符

最后的唯一id

对于由配置条目设置的实体，如果没有其他惟一ID可用，则可以使用配置条目ID作为最后的手段。

无法接受的唯一ID来源

• IP地址
• 设备名称
• 主机名
• URL
• 电子邮件地址
• 用户名

实体注册表和禁用实体

实体注册中心跟踪所有具有唯一id的实体。对于每个实体，注册中心跟踪影响实体与核心交互方式的选项。其中一个选项是disabled_by。

当设置了disabled_by而不是None时，当集成将实体传递给async_add_entities时，该实体将不会被添加到Home Assistant。

集成架构

集成将需要确保它们在实体被禁用时能够正确工作。如果你的集成保持对创建的实体对象的引用，它应该只在实体的生命周期方法async_added_to_hass中注册这些引用。这个生命周期方法只有在实体实际添加到Home Assistant时才会被调用(因此它没有被禁用)。

实体禁用作用于通过配置条目或configuration.yaml中的条目提供的实体。如果您的集成是通过配置条目设置的，并且支持卸载，那么Home Assistant将能够在启用/禁用实体后重新加载集成，从而无需重新启动即可应用更改。

用户编辑实体注册表

禁用实体的一种方法是用户通过UI编辑实体注册表。在本例中，disabled_by值将被设置为RegistryEntryDisabler.USER。这只适用于已经注册的实体。

为新的实体注册表项设置disabled_by的默认值

作为一个集成，您可以控制您的实体在第一次注册时是否启用。这是由entity_registry_enabled_default属性控制的。它默认为True，这意味着实体将被启用。

如果属性返回False，新注册实体的disabled_by值将被设置为RegistryEntryDisabler.INTEGRATION。

配置条目系统选项设置新实体注册表项的disabled_by的默认值

用户还可以通过将配置条目的系统选项disable_new_entities设置为True来控制如何接收与配置条目相关的新实体。这可以通过UI来完成。

如果一个实体正在注册并且这个系统选项被设置为True, disabled_by属性将被初始化为RegistryEntryDisabler.CONFIG_ENTRY。

如果disable_new_entities设置为True，而entity_registry_enabled_default返回False, disabled_by值将被设置为RegistryEntryDisabler.INTEGRATION。

提供控制disabled_by选项的集成

有些集成希望向用户提供选项，以控制哪些实体被添加到Home Assistant中。例如，Unifi集成提供了启用/禁用无线和有线客户端的选项。

集成可以通过配置为用户提供configuration.yaml或使用options flow。

如果这个选项是由集成提供的，那么您不应该利用实体注册表中的disabled_by属性。相反，如果实体通过配置选项流被禁用，则将它们从设备和实体注册表中删除。

设备注册表

设备注册表是Home Assistant跟踪设备的注册表。在HA中，设备通过一个或多个实体来表示。例如，电池供电的温湿度传感器可能会暴露温度、湿度和电池级别的实体。

什么是设备？

HA中的设备表示具有自己的控制单元的物理设备。控制单元本身不需要很聪明，但它应该控制所发生的事情。例如，带有4个房间传感器的Ecobee恒温器相当于家庭助手中的5个设备，一个用于恒温器，包括它内部的所有传感器，每个传感器都有一个。每个设备存在于特定的地理区域，并且在该区域内可能有多个输入或输出。

如果您将一个传感器连接到另一个设备来读取它的一些数据，它仍然应该表示为两个不同的设备。这样做的原因是，可以移动传感器来读取另一个设备的数据。

一个提供多个端点的设备，其中设备的部分在不同的区域感知或输出，应该被分割成单独的设备，并使用via_device属性返回到父设备。这允许将单独的端点分配到建筑中的不同区域。

虽然目前还无法实现，但我们可以考虑为用户提供合并设备的选项。

设备属性

名称	描述
area_id	放置设备的区域。
config_entries	Config entries that are linked to this device.
configuration_url	可以使用Home Assistant://来配置设备或服务的URL，链接到Home Assistant UI内部的路径。
connections	一组元组(connection_type，连接标识符)。connection_type在设备注册表模块中定义。
default_name	此设备的默认名称，如果设置name，将被覆盖。例如，对于显示网络上所有设备的集成很有用。
default_manufacturer	如果设置了manufacturer，设备的制造商将被覆盖。例如，对于显示网络上所有设备的集成很有用。
default_model	如果设置了model，设备的型号将被覆盖。例如，对于显示网络上所有设备的集成很有用。
entry_type	条目的类型。取值为“None”和“DeviceEntryType”enum成员。
id
identifiers	(DOMAIN，标识符)元组的集合。标识符在外部世界识别设备。例如序列号。
name
manufacturer
model
suggested_area	设备所在区域的建议名称
sw_version	设备固件版本号。
hw_version	设备的硬件版本。
via_device	设备标识符，用于在该设备和Home Assistant之间路由消息。这样的设备的例子是集线器，或者子设备的父设备。用于在“家庭助手”中显示设备拓扑。

定义设备

只有当实体通过config entry加载并且定义了unique_id属性时，实体设备信息才会被读取。

每个实体都可以通过device_info属性定义一个设备。当通过配置条目将实体添加到Home Assistant时，将读取此属性。一个Device将通过提供的标识符或连接(如序列号或MAC地址)与现有设备进行匹配。如果提供了标识符和连接，设备注册表将首先尝试通过标识符进行匹配。每个标识符和每个连接都是单独匹配的(例如，只需要匹配一个连接就被认为是相同的设备)。

# Inside a platform
class HueLight(LightEntity):
    @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,
            "via_device": (hue.DOMAIN, self.api.bridgeid),
        }

除了设备属性，device_info还可以包括default_manufacturer、default_model、default_name。如果还没有定义其他值，这些值将被添加到设备注册表中。这可以用于知道一些信息但不是非常具体的集成。例如，基于MAC地址识别设备的路由器。

手工注册

组件还能够在没有实体表示它们的情况下注册设备。一个例子是与灯通信的枢纽。

# Inside a component
from homeassistant.helpers import device_registry as dr

device_registry = dr.async_get(hass)

device_registry.async_get_or_create(
    config_entry_id=entry.entry_id,
    connections={(dr.CONNECTION_NETWORK_MAC, config.mac)},
    identifiers={(DOMAIN, config.bridgeid)},
    manufacturer="Signify",
    suggested_area="Kitchen",
    name=config.name,
    model=config.modelid,
    sw_version=config.swversion,
    hw_version=config.hwversion,
)

区域注册表

区域注册表是Home Assistant跟踪区域的一个注册表。区域表示“家庭助理”的物理位置。可以将设备放置在不同的区域。

属性	描述
id
name