十六 Home Assistant 平台对接“装灯“的实例

平台对接"装灯"的实例

这个示例用于为虚构的 “Awesome Lights” 添加支持，展示了开发平台的不同最佳实践。
与示例传感器平台类似，复制下面的代码，并在<config_dir>/custom_components/light/awesomelights.py中创建为一个文件。
将以下内容添加到你的configuration.yaml中：

light:
  - platform: awesomelights
    host: HOST_HERE
    username: USERNAME_HERE
    password: PASSWORD_HERE_OR_secrets.yaml

注意，platform名称与源代码文件名匹配。
代码

import logging

import voluptuous as vol

# 从你想要支持的组件中导入设备类
from homeassistant.components.light import ATTR_BRIGHTNESS, Light, PLATFORM_SCHEMA
from homeassistant.const import CONF_HOST, CONF_USERNAME, CONF_PASSWORD
import homeassistant.helpers.config_validation as cv

# Home Assistant依赖第三方包来实现特定于API的代码
REQUIREMENTS = ['awesome_lights==1.2.3']

_LOGGER = logging.getLogger(__name__)

# 用户配置的验证
PLATFORM_SCHEMA = PLATFORM_SCHEMA.extend({
    vol.Required(CONF_HOST): cv.string,
    vol.Optional(CONF_USERNAME, default='admin'): cv.string,
    vol.Optional(CONF_PASSWORD): cv.string,
})


def setup_platform(hass, config, add_devices, discovery_info=None):
    """设置Awesome Light平台。"""
    import awesomelights

    # 分配配置变量。配置检查确保它们存在。
    host = config.get(CONF_HOST)
    username = config.get(CONF_USERNAME)
    password = config.get(CONF_PASSWORD)

    # 设置与设备/云的连接
    hub = awesomelights.Hub(host, username, password)

    # 验证传入的配置是否有效
    if not hub.is_valid_login():
        _LOGGER.error("无法连接到AwesomeLight中心")
        return False

    # 添加设备
    add_devices(AwesomeLight(light) for light in hub.lights())


class AwesomeLight(Light):
    """Awesome Light的表示。"""

    def __init__(self, light):
        """初始化一个AwesomeLight。"""
        self._light = light
        self._name = light.name
        self._state = None
        self._brightness = None

    @property
    def name(self):
        """返回此灯光的显示名称。"""
        return self._name

    @property
    def brightness(self):
        """返回灯光的亮度。

        此方法是可选的。删除它表示Home Assistant此灯光不支持亮度调节。
        """
        return self._brightness

    @property
    def is_on(self):
        """如果灯光打开则返回True。"""
        return self._state

    def turn_on(self, **kwargs):
        """指示灯光打开。

        如果你的灯光不支持亮度控制，可以跳过亮度部分。
        """
        self._light.brightness = kwargs.get(ATTR_BRIGHTNESS, 255)
        self._light.turn_on()

    def turn_off(self, **kwargs):
        """指示灯光关闭。"""
        self._light.turn_off()

    def update(self):
        """获取此灯光的新状态数据。

        这是应该为Home Assistant获取新数据的唯一方法。
        """
        self._light.update()
        self._state = self._light.is_on()
        self._brightness = self._light.brightness

总结
一个为虚构的 “Awesome Lights” 开发灯光平台的完整示例，涵盖从安装到代码实现的全过程。安装部分清晰说明了代码放置位置及在配置文件中的配置方式，方便开发者快速搭建测试环境。代码方面，详细展示了平台设置函数中连接设备、验证配置及添加设备的流程，以及灯光实体类中属性定义、开关控制和状态更新方法的实现，体现了最佳实践。整体为开发者提供了一个全面且实用的模板，有助于深入理解在 Home Assistant 中开发灯光平台的规范和要点，可作为开发复杂灯光控制功能的基础，降低开发门槛，提高开发效率，确保新平台与 Home Assistant 系统的良好兼容性和功能性。