二十五 Home Assistant 实体-风扇

风扇实体

风扇实体是一种控制风扇不同属性（如速度、方向和摆动）的设备。实体平台需继承自 homeassistant.components.fan.FanEntity。

属性

• 提示：属性应始终仅从内存返回信息，不应进行I/O操作（如网络请求）。请实现 update() 或 async_update() 来获取数据。

名称	类型	默认值	描述
current_direction	str | None	None	风扇当前的方向。
is_on	bool | None	None	如果风扇打开，则为True。
oscillating	bool | None	None	如果风扇正在摆动，则为True。
percentage	int | None	0	当前速度百分比。必须是0（关闭）到100之间的值。
preset_mode	str | None	None	当前预设模式。预设模式列表中的值之一，如果没有预设模式处于活动状态，则为None。
preset_modes	list[str] | None	None	支持的预设模式列表。这是一个任意的字符串列表，不应包含任何速度。
speed_count	int	100	风扇支持的速度数量。

预设模式

风扇可能有预设模式，可自动控制速度百分比或其他功能。常见示例包括 “自动”、“智能”、“呼呼声”、“节能” 和 “微风”。如果未设置预设模式，则 preset_mode 属性必须设置为None。

预设模式不应包括命名（手动）速度设置，因为这些应表示为百分比。手动设置速度必须禁用任何已设置的预设模式。如果可以在不禁用预设模式的情况下手动设置百分比速度，请创建一个开关或服务来表示该模式。

支持的功能

支持的功能通过使用 FanEntityFeature 枚举中的值来定义，并使用按位或（|）运算符组合。

值	描述
DIRECTION	风扇支持改变方向。
OSCILLATE	风扇支持摆动。
PRESET_MODE	风扇支持预设模式。
SET_SPEED	风扇支持设置速度百分比和可选的预设模式。

方法

• 设置方向：仅当设置了 SUPPORT_DIRECTION 标志时才实现此方法。

class FanEntity(ToggleEntity):
    # 实现以下方法之一
    def set_direction(self, direction: str) -> None:
        """设置风扇的方向。"""

    async def async_set_direction(self, direction: str) -> None:
        """设置风扇的方向。"""

• 设置预设模式：仅当设置了 SUPPORT_PRESET_MODE 标志时才实现此方法。

class FanEntity(ToggleEntity):
    # 实现以下方法之一
    def set_preset_mode(self, preset_mode: str) -> None:
        """设置风扇的预设模式。"""

    async def async_set_preset_mode(self, preset_mode: str) -> None:
        """设置风扇的预设模式。"""

• 设置速度百分比：仅当设置了 SUPPORT_SET_SPEED 标志时才实现此方法。

class FanEntity(ToggleEntity):
    # 实现以下方法之一
    def set_percentage(self, percentage: int) -> None:
        """设置风扇的速度百分比。"""

    async def async_set_percentage(self, percentage: int) -> None:
        """设置风扇的速度百分比。"""

转换速度

Home Assistant包括一个转换速度的实用程序。

如果设备有命名速度列表：

from homeassistant.util.percentage import ordered_list_item_to_percentage, percentage_to_ordered_list_item

ORDERED_NAMED_FAN_SPEEDS = ["one", "two", "three", "four", "five", "six"]  # off不包括在内
percentage = ordered_list_item_to_percentage(ORDERED_NAMED_FAN_SPEEDS, "three")
named_speed = percentage_to_ordered_list_item(ORDERED_NAMED_FAN_SPEEDS, 23)

@property
def percentage(self) -> Optional[int]:
    """返回当前速度百分比。"""
    return ordered_list_item_to_percentage(ORDERED_NAMED_FAN_SPEEDS, current_speed)

@property
def speed_count(self) -> int:
    """返回风扇支持的速度数量。"""
    return len(ORDERED_NAMED_FAN_SPEEDS)

如果设备有数字范围的速度：

from homeassistant.util.percentage import ranged_value_to_percentage, percentage_to_ranged_value
from homeassistant.util.scaling import int_states_in_range

SPEED_RANGE = (1, 255)  # off不包括在内
percentage = ranged_value_to_percentage(SPEED_RANGE, 127)
value_in_range = math.ceil(percentage_to_ranged_value(SPEED_RANGE, 50))

@property
def percentage(self) -> Optional[int]:
    """返回当前速度百分比。"""
    return ranged_value_to_percentage(SPEED_RANGE, current_speed)

@property
def speed_count(self) -> int:
    """返回风扇支持的速度数量。"""
    return int_states_in_range(SPEED_RANGE)

打开风扇

class FanEntity(ToggleEntity):
    # 实现以下方法之一
    def turn_on(self, speed: Optional[str] = None, percentage: Optional[int] = None, preset_mode: Optional[str] = None, **kwargs: Any) -> None:
        """打开风扇。"""

    async def async_turn_on(self, speed: Optional[str] = None, percentage: Optional[int] = None, preset_mode: Optional[str] = None, **kwargs: Any) -> None:
        """打开风扇。"""

speed 已弃用。对于新的集成，不应实现 speed，而应仅使用 percentage 和 preset_mode。

关闭风扇

class FanEntity(ToggleEntity):
    # 实现以下方法之一
    def turn_off(self, **kwargs: Any) -> None:
        """关闭风扇。"""

    async def async_turn_off(self, **kwargs: Any) -> None:
        """关闭风扇。"""

切换风扇状态

可选。如果未实现，将默认使用 is_on 属性检查调用哪个方法。

class FanEntity(ToggleEntity):
    # 实现以下方法之一
    def toggle(self, **kwargs: Any) -> None:
        """切换风扇状态。"""

    async def async_toggle(self, **kwargs: Any) -> None:
        """切换风扇状态。"""

摆动风扇

仅当设置了 SUPPORT_OSCILLATE 标志时才实现此方法。

class FanEntity(ToggleEntity):
    # 实现以下方法之一
    def oscillate(self, oscillating: bool) -> None:
        """摆动风扇。"""

    async def async_oscillate(self, oscillating: bool) -> None:
        """摆动风扇。"""

总结

此文档介绍了Home Assistant中的风扇实体（Fan Entity）相关内容，包括其属性（如风扇方向、开关状态、摆动状态、速度百分比、预设模式等）、预设模式的规则、支持的功能（如改变方向、摆动、预设模式、设置速度等）以及相关方法（如设置方向、预设模式、速度百分比、打开/关闭/切换风扇、摆动风扇等），还提到了速度转换的方法，为开发人员在Home Assistant中集成风扇设备提供了详细的指导和规范。