实体 | FLY

介绍

基础实现

下面是一个开关实体的例子，它在内存中跟踪它的状态。

from homeassistant.components.switch import SwitchEntity


class MySwitch(SwitchEntity):
    def __init__(self):
        self._is_on = False

    @property
    def name(self):
        """Name of the entity."""
        return "My Switch"

    @property
    def is_on(self):
        """If the switch is currently on or off."""
        return self._is_on

    def turn_on(self, **kwargs):
        """Turn the switch on."""
        self._is_on = True

    def turn_off(self, **kwargs):
        """Turn the switch off."""
        self._is_on = False

这就是建立一个开关实体所要做的一切!继续阅读了解更多或查看video tutorial。

更新实体

一个实体代表一个设备。有多种策略可以使实体与设备状态保持同步，最流行的策略是轮询（poll）。

poll

使用轮询，Home Assistant将不时地请求实体(取决于组件的更新间隔)获取最新的状态。当should_poll属性返回True(默认值)时，Home Assistant将轮询一个实体。您可以使用update()或async_update()实现更新逻辑。这个方法应该从设备获取最新的状态，并将其存储在一个实例变量中，以便属性返回它。

订阅更新

当您订阅更新时，您的代码负责让Home Assistant知道有更新可用。确保should_poll属性返回False。

每当您从订阅中收到一个新状态时，您可以通过调用schedule_update_ha_state()或async_schedule_update_ha_state()通知Home Assistant一个更新可用。如果您希望Home Assistant在将更新写入Home Assistant之前调用您的更新方法，则将boolean True传递给该方法。

通用属性

实体基类有几个属性，这些属性在Home Assistant中的所有实体中都是通用的。这些可以添加到任何实体中，而不考虑其类型。所有这些属性都是可选的，不需要实现。

属性应该总是只从内存中返回信息，而不做I/O(比如网络请求)。实现update()或async_update()来获取数据。

name	类型	默认值	描述
assumed_state	boolean	`False`	如果状态是基于我们的假设而不是从设备读取，则返回`True`。
attribution	string	None	API提供程序所需的品牌文本。
available	boolean	True	指示Home Assistant是否能够读取状态并控制底层设备。
device_class	string	None	设备的额外分类。每个域指定它们自己的域。设备类别可以附带额外的测量单位要求和支持的特性。
entity_category	string	None	非主要实体的分类。设置为允许更改设备配置的实体的`config`，例如一个开关实体，它可以打开或关闭开关的背景照明。对于暴露某些配置参数或设备诊断但不允许更改的实体，例如显示RSSI或mac地址的传感器，设置为`diagnostic`。对于一个对用户没有交互作用的实体，设置为`system`。例如，汽车产生的能量成本传感器本身是没有用的，因为每次HA重启或能量设置改变时，它们都会从0重置，从而将它们的实体类别设置为`system`。
entity_picture	URL	None	要为实体显示的图片的Url。
extra_state_attributes	dict	None	要存储在状态机中的额外信息。它需要是进一步解释状态的信息，不应该是静态信息，如固件版本。
name	string	None	Name of the entity
should_poll	boolean	True	HA是否应与实体检查为了更新的状态。如果设置为False，实体将需要通过调用其中一个方法来通知Home Assistant有新的更新schedule update methods.
unique_id	string	None	此实体的唯一标识符。需要在平台中是唯一的(如light.hue)。不应该由用户配置或可更改

高级属性

以下属性也可用于实体。然而，它们只用于高级用途，应该谨慎使用。

name	类型	默认值	描述
entity_registry_enabled_default	boolean	True	指示在第一次将实体添加到实体注册中心时应启用或禁用该实体。这包括快速变化的诊断实体，或者假设不太常用的实体。例如，暴露RSSI或电池电压的传感器通常应该设置为False;以防止这些实体造成不必要的(记录的)状态变化或UI混乱。
force_update	boolean	False	将每个更新写入状态机，即使数据是相同的。例如:当你直接从连接的传感器读取值，而不是从缓存。小心使用，将向状态机发送垃圾邮件即信息或状态。
icon	icon	None	在前端使用的图标。图标以`mdi:`plus an identifier。您可能不需要这样做，因为Home Assistant已经根据其`device_class`为所有实体提供了默认图标。这应该只在以下情况下使用:没有匹配的`device_class`，或者用于`device_class`的图标令人困惑或误导。

系统属性

以下属性由HA使用和控制，不应被集成覆盖。

name	类型	默认值	描述
enabled	boolean	True	指示实体注册表中是否启用了实体。如果平台不支持实体注册表，它也返回True。禁用实体将不会被添加到HA中。

属性实现

属性方法

例如，为每个属性编写属性方法只需几行代码

class MySwitch(SwitchEntity):

    @property
    def icon(self) -> str | None:
        """Icon of the entity."""
        return "mdi:door"

    ...

实体类或示例的属性

或者，更短的形式是设置实体类或实例属性，根据以下模式之一:

class MySwitch(SwitchEntity):

    _attr_icon = "mdi:door"

    ...
    
class MySwitch(SwitchEntity):

    def __init__(self, icon: str) -> None:
        self._attr_icon = icon

    ...

这与第一个示例完全相同，但依赖于基类中属性的默认实现。属性名以_attr_开头，后跟属性名。例如，默认的device_class属性返回_attr_device_class类属性。

并不是所有实体类都支持_attr_属性用于实体特定属性，请参阅相应实体类的文档以获取详细信息。

如果一个集成需要访问它自己的属性，它应该访问属性(self.name)，而不是类或实例属性(self._attr_name)。

生命周期钩子

当实体发生某些事件时，使用这些生命周期钩子来执行代码。所有生命周期钩子都是异步方法。

`async_added_to_hass()`

当一个实体的entity_id和hass对象被赋值时，在它第一次被写入状态机之前调用。示例使用:恢复状态、订阅更新或设置回调/调度函数/监听器。

`async_will_remove_from_hass()`

当实体即将从HA中移除时调用。示例使用:断开与服务器的连接或取消订阅更新

更改实体model

如果你想给一个实体或它的任何子类型(灯，开关等)添加一个新特性，你需要在我们的architecture repo.中首先提出它。我们只考虑不同供应商之间的通用特性。

介绍