Back to Details

home-automation

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

home-automation

家庭自动化

Purpose

用途

This skill integrates smart home systems using Home Assistant, HomeKit, Google Home, and Matter protocols, allowing the AI to control IoT devices programmatically for automation tasks.
本技能可通过Home Assistant、HomeKit、Google Home和Matter协议集成智能家居系统，让AI能够以编程方式控制IoT设备，实现自动化任务。

When to Use

适用场景

Use this skill for automating home environments, such as controlling lights, thermostats, or security systems via IoT platforms. Apply it in scenarios like smart home apps, voice assistant integrations, or custom scripts for daily routines (e.g., turning off lights at bedtime).
当你需要自动化家庭环境时使用本技能，例如通过IoT平台控制灯光、恒温器或安防系统。可应用于智能家居应用、语音助手集成或日常任务自定义脚本（如睡前关灯）等场景。

Key Capabilities

核心功能

  • Connect to Home Assistant via REST API for device state management.
  • Integrate with HomeKit using the HAP protocol for Apple ecosystem devices.
  • Use Google Home APIs for controlling compatible smart devices.
  • Handle Matter devices through bridge APIs for cross-platform compatibility.
  • Specifics: Home Assistant API endpoint for states is 
    GET /api/states
    ; HomeKit requires Bonjour discovery; Google Home uses OAuth 2.0 with scopes like 
    https://www.googleapis.com/auth/homeautomation
    ; Matter involves IP-based commissioning.
  • 通过REST API连接Home Assistant，实现设备状态管理。
  • 使用HAP协议集成HomeKit，支持苹果生态系统设备。
  • 借助Google Home API控制兼容的智能设备。
  • 通过桥接API处理Matter设备，实现跨平台兼容。
  • 细节说明：Home Assistant的状态API端点为
    GET /api/states
    ；HomeKit需要Bonjour发现；Google Home使用OAuth 2.0，权限范围如
    https://www.googleapis.com/auth/homeautomation
    ；Matter涉及基于IP的设备入网配置。

Usage Patterns

使用模式

To use this skill, first initialize it with authentication. Import via 
skill.use('home-automation')
, then call methods like 
skill.connect(service, key)
. For sequential tasks, chain calls: connect, query state, execute action. Always handle async operations with promises or callbacks. Config format: JSON objects, e.g., 
{"service": "home-assistant", "api_url": "http://localhost:8123"}
.
使用本技能前，需先通过认证初始化。通过
skill.use('home-automation')
导入，然后调用
skill.connect(service, key)
等方法。对于连续任务，可链式调用：连接、查询状态、执行操作。务必使用Promise或回调处理异步操作。配置格式为JSON对象，例如
{"service": "home-assistant", "api_url": "http://localhost:8123"}
。

Common Commands/API

常用命令/API

  • CLI: Run 
    openclaw home-automation connect --service home-assistant --api-url http://localhost:8123 --key $HOME_ASSISTANT_API_KEY
    to establish a connection.
  • API: Use 
    POST /api/services
    for Home Assistant actions; example endpoint for Google Home: 
    GET https://homegraph.googleapis.com/v1/devices
    .
  • Code snippets:
    skill
    skill.use('home-automation')
skill.connect('home-assistant', { apiUrl: 'http://localhost:8123', key: process.env.HOME_ASSISTANT_API_KEY })
    skill
    const state = await skill.call('getState', { entity: 'light.living_room' })
console.log(state)
    skill
    skill.execute('turnOn', { device: 'light.kitchen', service: 'homekit' })
    Use env vars for keys: 
    $HOME_ASSISTANT_API_KEY
    for Home Assistant, 
    $GOOGLE_HOME_TOKEN
    for Google Home.
  • CLI：运行
    openclaw home-automation connect --service home-assistant --api-url http://localhost:8123 --key $HOME_ASSISTANT_API_KEY
    建立连接。
  • API：使用
    POST /api/services
    执行Home Assistant操作；Google Home的示例端点：
    GET https://homegraph.googleapis.com/v1/devices
    。
  • 代码片段：
    skill
    skill.use('home-automation')
skill.connect('home-assistant', { apiUrl: 'http://localhost:8123', key: process.env.HOME_ASSISTANT_API_KEY })
    skill
    const state = await skill.call('getState', { entity: 'light.living_room' })
console.log(state)
    skill
    skill.execute('turnOn', { device: 'light.kitchen', service: 'homekit' })
    使用环境变量存储密钥：Home Assistant使用
    $HOME_ASSISTANT_API_KEY
    ，Google Home使用
    $GOOGLE_HOME_TOKEN
    。

Integration Notes

集成注意事项

Authenticate using env vars (e.g., 
$HOME_ASSISTANT_API_KEY
) before operations. For HomeKit, ensure devices are paired via the Home app; use HAP-NodeJS library for custom integrations. Google Home requires OAuth flow—redirect to 
https://accounts.google.com/o/oauth2/v2/auth
. Matter integration needs a compatible bridge; config format: YAML like 
matter: { bridge_ip: '192.168.1.100', port: 5540 }
. Avoid mixing protocols in one call; use wrappers for error-free transitions between services.
操作前需使用环境变量（如
$HOME_ASSISTANT_API_KEY
）完成认证。对于HomeKit，确保设备已通过Home应用配对；自定义集成可使用HAP-NodeJS库。Google Home需要OAuth流程——重定向至
https://accounts.google.com/o/oauth2/v2/auth
。Matter集成需要兼容的桥接设备；配置格式为YAML，例如
matter: { bridge_ip: '192.168.1.100', port: 5540 }
。避免在单次调用中混合多种协议；使用包装器实现服务间无错误切换。

Error Handling

错误处理

Check for HTTP errors (e.g., 401 Unauthorized) by wrapping calls in try-catch blocks. For authentication failures, retry with refreshed tokens. Common errors: API rate limits (e.g., Home Assistant returns 429); handle with exponential backoff. Code snippet:
skill
try {
  await skill.call('getState', { entity: 'light.living_room' })
} catch (error) {
  if (error.code === 401) console.error('Reauthenticate with $HOME_ASSISTANT_API_KEY')
  else throw error
}
Log detailed responses and use skill-specific error codes for debugging.
通过try-catch块捕获HTTP错误（如401未授权）。若认证失败，使用刷新后的令牌重试。常见错误：API速率限制（如Home Assistant返回429）；可使用指数退避策略处理。代码片段：
skill
try {
  await skill.call('getState', { entity: 'light.living_room' })
} catch (error) {
  if (error.code === 401) console.error('Reauthenticate with $HOME_ASSISTANT_API_KEY')
  else throw error
}
记录详细响应信息，并使用技能专属错误代码进行调试。

Concrete Usage Examples

实际使用示例

  1. Automate lights based on time: Use 
    skill.connect('home-assistant', { key: process.env.HOME_ASSISTANT_API_KEY })
    , then 
    skill.execute('turnOff', { entity: 'light.all' })
    in a scheduled script to turn off all lights at 11 PM.
  2. Integrate with Google Home for temperature control: Call 
    skill.use('home-automation').connect('google-home', { token: process.env.GOOGLE_HOME_TOKEN })
    , followed by 
    skill.call('setThermostat', { deviceId: 'thermostat.living_room', temperature: 72 })
    to adjust the thermostat.
  1. 基于时间自动化灯光控制：使用
    skill.connect('home-assistant', { key: process.env.HOME_ASSISTANT_API_KEY })
    ，然后在定时脚本中调用
    skill.execute('turnOff', { entity: 'light.all' })
    ，实现晚上11点关闭所有灯光。
  2. 集成Google Home控制温度：调用
    skill.use('home-automation').connect('google-home', { token: process.env.GOOGLE_HOME_TOKEN })
    ，随后调用
    skill.call('setThermostat', { deviceId: 'thermostat.living_room', temperature: 72 })
    调整恒温器温度。

Graph Relationships

关联图谱

  • Cluster: Connected to 'iot' cluster for broader IoT integrations.
  • Tags: Links to skills with 'iot' and 'home' tags, such as device-control or smart-security skills.
  • Relationships: This skill depends on authentication services; it integrates with external APIs like Home Assistant's REST endpoints and Google Home's OAuth flows.
  • 集群：连接至'iot'集群，用于更广泛的IoT集成。
  • 标签：关联带有'iot'和'home'标签的技能，如设备控制或智能安防技能。
  • 依赖关系：本技能依赖认证服务；与外部API集成，如Home Assistant的REST端点和Google Home的OAuth流程。