Homepage自动化工具：Home Assistant集成指南

你是否还在为智能家居设备管理与主页监控分离而烦恼？本文将详细介绍如何在Homepage中集成Home Assistant，实现智能家居状态的实时监控与自动化控制，让你的主页成为真正的智能家居控制中心。读完本文后，你将能够轻松配置Home Assistant小部件，实时查看家居状态，并根据需求自定义监控项。

准备工作

在开始集成之前，你需要确保已经满足以下条件：

• 已安装并运行Home Assistant（家庭助理）服务
• 拥有Home Assistant的有效用户账户
• Homepage已成功部署并可正常访问

获取长期访问令牌

要实现Homepage与Home Assistant的通信，你需要为Home Assistant用户生成一个长期访问令牌。具体步骤如下：

1. 登录Home Assistant管理界面
2. 点击右上角的用户头像，进入用户配置页面
3. 在"安全"选项中，找到"长期访问令牌"部分
4. 点击"创建令牌"，输入令牌名称（如"Homepage集成"）并确认
5. 保存生成的令牌，后续配置将用到此令牌

配置Home Assistant小部件

Homepage提供了专门的Home Assistant小部件，通过简单的配置即可实现状态监控。配置文件位于项目的widgets目录下，具体实现可参考Home Assistant小部件源码和组件代码。

基本配置

在Homepage的配置文件中添加以下内容，即可启用Home Assistant小部件：

widget:
  type: homeassistant
  url: http://homeassistant.host.or.ip:port  # 替换为你的Home Assistant地址
  key: YOUR_LONG_LIVED_ACCESS_TOKEN  # 替换为你生成的访问令牌
  fields: ["people_home", "lights_on", "switches_on"]  # 可选监控字段

允许的监控字段包括：["people_home", "lights_on", "switches_on"]，分别对应"在家人数"、"开启的灯"和"开启的开关"。

自定义状态监控

除了基本字段外，Homepage还支持通过custom属性查询最多四个自定义状态和/或模板。当定义了fields属性时，custom属性将不起作用。

以下是一个自定义配置示例：

widget:
  type: homeassistant
  url: http://homeassistant.host.or.ip:port
  key: YOUR_LONG_LIVED_ACCESS_TOKEN
  custom:
    - state: sensor.total_power  # 查询指定实体的状态
    - state: sensor.total_energy_today
      label: 今日能耗  # 自定义标签
    - template: "{{ states.switch|selectattr('state','equalto','on')|list|length }}"
      label: 开关数量
    - state: weather.forecast_home
      label: 风速
      value: "{attributes.wind_speed} {attributes.wind_speed_unit}"  # 自定义值格式

自定义配置支持两种类型：

• state: 查询指定entity_id的状态，可自定义标签和值格式
• template: 使用Home Assistant模板查询，支持复杂的状态计算

小部件工作原理

Home Assistant小部件的工作流程如下：

1. 通过长期访问令牌与Home Assistant API建立连接
2. 根据配置的字段或自定义模板查询相应的状态数据
3. 将获取的数据通过组件渲染到Homepage界面上
4. 定期（默认60秒）刷新数据，保持状态实时性

组件渲染逻辑主要在component.jsx中实现，使用了Homepage的通用组件和状态管理工具。

实际效果展示

配置完成后，Homepage将显示类似以下的Home Assistant状态卡片：

卡片将展示你配置的各项状态信息，如当前在家人数、开启的设备数量等。通过自定义模板，你还可以实现更复杂的状态监控，如能源消耗统计、天气信息展示等。

故障排除

如果小部件无法正常显示数据，请检查以下几点：

1. Home Assistant服务是否正常运行
2. 访问令牌是否正确，是否具有足够的权限
3. 网络连接是否正常，Homepage是否能够访问Home Assistant地址
4. 配置文件格式是否正确，特别是YAML语法是否有误

详细的故障排除指南可参考项目的故障排除文档。

总结

通过本文介绍的方法，你已经成功将Home Assistant集成到Homepage中，实现了智能家居状态的实时监控。这不仅简化了你的日常管理流程，还为打造个性化的智能家居控制中心奠定了基础。

如果你想进一步扩展功能，可以参考官方提供的Home Assistant小部件配置文档，探索更多高级用法。

希望本文对你有所帮助，如有任何问题或建议，欢迎参与项目贡献或提交issue。