home-assistant

Home Assistant

概述

此技能可帮助用户将 Home Assistant 集成到项目中，无论是控制智能家居设备，还是采集传感器数据和状态信息。此技能会引导用户完成连接设置、验证凭据，并提供适用于 Python 和 Node.js 的完整 API 参考文档。

何时使用此技能

在用户希望进行以下操作时使用此技能：

• 将应用连接到 Home Assistant
• 控制智能家居设备（灯、开关、恒温器等）
• 读取 Home Assistant 中的传感器数据或实体状态
• 根据自定义逻辑自动控制家居
• 使用 Home Assistant 数据构建仪表板或监控工具
• 将 Home Assistant 集成到现有的 Python 或 Node.js 项目中

连接设置工作流

步骤 1：收集连接信息

向用户收集两项信息：

1. Home Assistant URL：Home Assistant 的访问地址
2. 长期访问令牌：用于 API 访问的身份验证令牌

步骤 2：规范化 URL

如果用户提供的 URL 带有路径部分（例如，http://homeassistant.local:8123/lovelace/dashboard），请删除主机和端口之后的所有内容进行规范化。基本 URL 只应包含协议、主机和端口：

• ✓ 正确：http://homeassistant.local:8123
• ✗ 错误：http://homeassistant.local:8123/lovelace/dashboard

步骤 3：帮助用户找到令牌

如果用户不知道在哪里找到长期访问令牌，请提供以下说明：

1. 登录 Home Assistant 网页界面
2. 点击用户个人资料（左下角的用户图标或名称）
3. 点击“安全”选项卡
4. 向下滚动到“长期访问令牌”部分
5. 点击“创建令牌”
6. 为令牌命名（例如，“我的项目”）
7. 复制生成的令牌（令牌只会显示一次）

步骤 4：验证连接

使用 curl 测试连接并获取 Home Assistant 配置信息。

curl -X GET \
  -H "Authorization: Bearer <TOKEN>" \
  -H "Content-Type: application/json" \
  <URL>/api/config

示例：

curl -X GET \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  http://homeassistant.local:8123/api/config

成功输出：

{
  "location_name": "Home",
  "latitude": 37.7749,
  "longitude": -122.4194,
  "elevation": 0,
  "unit_system": {
    "length": "km",
    "mass": "g",
    "temperature": "°C",
    "volume": "L"
  },
  "time_zone": "America/Los_Angeles",
  "version": "2024.1.0",
  "config_dir": "/config",
  "allowlist_external_dirs": [],
  "allowlist_external_urls": [],
  "components": ["automation", "light", "switch", ...],
  "config_source": "storage"
}

响应中的关键信息：

• version：Home Assistant 版本（例如，“2024.1.0”）
• location_name：Home Assistant 实例的名称
• time_zone：配置的时区
• components：已加载的组件/集成列表

失败情形：

身份验证失败（401）：

{"message": "Invalid authentication"}

连接失败：

curl: (7) Failed to connect to homeassistant.local port 8123: Connection refused

如果身份验证失败，请确认：

1. 长期访问令牌正确
2. 令牌尚未被删除或过期
3. URL 正确（包括 http/https 和端口）

步骤 5：开始实施

连接验证通过后，根据用户的编程语言和需求，帮助其实现集成。

核心交互模式

重要提示：以下 WebSocket API 命令构成了用户与 Home Assistant 交互的核心方式。这些命令利用自动化引擎和 Home Assistant 原生语法，让脚本保持精简。

自动化引擎命令（WebSocket API）

这些命令需要通过 WebSocket API 连接，并提供了与 Home Assistant 交互时最强大、最灵活的方式：

1. subscribe_trigger - 监听特定事件

适用场景：需要在特定条件出现时（状态变化、时间模式、Webhook 等）收到通知

命令结构：

{
  "type": "subscribe_trigger",
  "trigger": {
    "platform": "state",
    "entity_id": "binary_sensor.motion_sensor",
    "to": "on"
  },
  "variables": {
    "custom_var": "value"
  }
}

使用原因：无需订阅所有状态变化再进行筛选，直接订阅所关注的触发器即可。这样效率更高，并且使用 Home Assistant 原生的触发器语法。

2. test_condition - 在服务端测试条件

适用场景：需要检查条件是否满足，但不想在脚本中实现相关逻辑

命令结构：

{
  "type": "test_condition",
  "condition": {
    "condition": "numeric_state",
    "entity_id": "sensor.temperature",
    "above": 20
  },
  "variables": {
    "custom_var": "value"
  }
}

使用原因：将条件逻辑交由 Home Assistant 处理。这样脚本可以保持简洁，同时利用 Home Assistant 强大的条件引擎。

3. execute_script - 执行多个操作

适用场景：需要执行一系列操作，包括 wait_for_trigger、延迟、服务调用等

命令结构：

{
  "type": "execute_script",
  "sequence": [
    {
      "service": "light.turn_on",
      "target": {"entity_id": "light.living_room"}
    },
    {
      "wait_for_trigger": [
        {
          "platform": "state",
          "entity_id": "binary_sensor.motion",
          "to": "off",
          "for": {"minutes": 5}
        }
      ]
    },
    {
      "service": "light.turn_off",
      "target": {"entity_id": "light.living_room"}
    }
  ],
  "variables": {
    "custom_var": "value"
  }
}

使用理由：

• 使用 Home Assistant 原生语法执行复杂的自动化逻辑
• 使用 wait_for_trigger 等待事件
• 将多个操作串联起来
• 保持脚本精简——所有逻辑都使用 HA 语法编写
• 获取响应数据：若要获取服务调用的响应，请将结果存储在响应变量中，并将其设为脚本结果

包含响应数据的示例：

{
  "type": "execute_script",
  "sequence": [
    {
      "service": "weather.get_forecasts",
      "target": {"entity_id": "weather.home"},
      "response_variable": "weather_data"
    },
    {
      "stop": "Done",
      "response_variable": "weather_data"
    }
  ]
}

必备注册表信息

若要了解 Home Assistant 的信息架构，还应使用：

• config/entity_registry/list：了解实体及其唯一 ID
• config/device_registry/list：了解设备及其实体
• config/area_registry/list：了解空间的组织方式
• config/floor_registry/list：了解多层布局信息

家庭当前状态

如果用户正在构建一个需要呈现家庭当前状态的应用，请使用：

• subscribe_entities：获取所有实体状态的实时更新（Home Assistant JS WebSocket 内置支持此功能）

实现指南

Python 项目

对于基于 Python 的项目，请参阅 Python API 参考：

• 文件：references/python_api.md
• 用法：实现 Python 集成时加载此参考
• 包含内容：
  • 示例代码：演示常见用例的 Python 脚本。
• 关键操作：自动化引擎命令、获取状态、调用服务、订阅事件、错误处理

Node.js 项目

对于基于 Node.js 的项目，请参阅 Node.js API 参考：

• 文件：references/node_api.md
• 用法：实现 Node.js 集成时加载此参考
• 包含内容：
  • 使用 home-assistant-js-websocket 库的 WebSocket API 示例

最佳实践

1. 错误处理：始终针对网络故障和身份验证问题实现适当的错误处理
2. 连接测试：继续实现前先验证连接
3. 实时更新：在监控场景中，使用 WebSocket API，而非轮询 REST 端点

使用 empty-hass 进行测试

如果用户想在不连接真实 Home Assistant 实例的情况下测试代码，可以使用 empty-hass。这是一款 CLI 工具，可启动一个预先配置好身份验证的空 Home Assistant 实例。

快速开始

使用 uvx 运行 empty-hass（需要安装了 uv 的 Python）：

uvx --from git+https://github.com/balloob/empty-hass empty-hass

这将在 http://localhost:8123 启动一个 Home Assistant 实例，并提供：

• 已完成初始设置的配置（跳过设置向导）
• 临时配置目录（退出时清理）

运行 --help 查看可用选项和登录凭据：

uvx --from git+https://github.com/balloob/empty-hass empty-hass --help

适用于：

• 在连接生产实例前测试 API 集成代码
• 在不影响真实设备的情况下进行开发和调试
• 需要 Home Assistant 实例进行测试的 CI/CD 流水线

常见集成模式

数据仪表板

读取传感器状态，并在自定义仪表板或监控应用中显示。

自动化逻辑

订阅实体状态变化，并根据条件触发自定义操作。

外部触发器

根据外部事件（Webhook、计划任务、用户操作）调用 Home Assistant 服务。

数据导出

从 Home Assistant 获取历史数据，用于分析或备份。