Home Assistant Skill

Control smart home devices via the Home Assistant REST API.

Setup

Set environment variables:

- HA_URL — Your Home Assistant URL (e.g., http://10.0.0.10:8123)
INLINECODE2 — Long-lived access token (create in HA → Profile → Long-Lived Access Tokens)

Safety Rules

Always confirm with the user before performing these actions:

- Locks — locking or unlocking any lock
Alarm panels — arming or disarming
Garage doors — opening or closing (cover.* with device_class: garage)
Security automations — disabling automations related to security or safety
Covers — opening or closing covers that control physical access (gates, barriers)

Never act on security-sensitive devices without explicit user confirmation.

Entity Discovery

List all entities

CODEBLOCK0

List entities by domain

CODEBLOCK1

Replace the domain prefix (switch., light., sensor., etc.) to discover entities
in any domain.

Get single entity state

CODEBLOCK2

Area & Floor Discovery

Use the template API to query areas, floors, and labels.

CODEBLOCK3

Switches

CODEBLOCK4

Lights

CODEBLOCK5

Scenes

CODEBLOCK6

Scripts

CODEBLOCK7

Automations

CODEBLOCK8

Climate Control

CODEBLOCK9

Covers (Blinds, Garage Doors)

Safety: Confirm with the user before opening/closing garage doors or gates.

CODEBLOCK10

Locks

Safety: Always confirm with the user before locking/unlocking.

CODEBLOCK11

Fans

CODEBLOCK12

Media Players

CODEBLOCK13

Vacuum

CODEBLOCK14

Alarm Control Panel

Safety: Always confirm with the user before arming/disarming.

CODEBLOCK15

Notifications

CODEBLOCK16

Replace mobile_app_phone with the actual service name from the list command.

Person & Presence

CODEBLOCK17

States: home, not_home, or a zone name.

Weather

CODEBLOCK18

Input Helpers

CODEBLOCK19

Calendar

CODEBLOCK20

Text-to-Speech

CODEBLOCK21

Replace tts.google_en with your TTS entity and media_player.living_room_speaker with the target speaker.

Call Any Service

The general pattern for any HA service:

CODEBLOCK22

Batch operations

Control multiple entities in one call by passing an array of entity IDs:

CODEBLOCK23

Error Handling

Check API connectivity

CODEBLOCK24

Verify entity exists before acting

CODEBLOCK25

HTTP status codes

Code	Meaning
200	Success
400

Bad request (malformed JSON or invalid service data) | | 401 | Unauthorized (bad or missing token) | | 404 | Entity or endpoint not found | | 405 | Method not allowed (wrong HTTP method) | | 503 | Home Assistant is starting up or unavailable |

Response Format

Service calls return an array of state objects for affected entities:

CODEBLOCK26

- Successful call with no state change: returns [] (empty array)
State read (/api/states/...): returns a single state object
Errors: returns {"message": "..."} with an HTTP error code

Template Evaluation

The /api/template endpoint evaluates Jinja2 templates server-side. Useful for computed queries.

CODEBLOCK27

Examples

CODEBLOCK28

Available template functions: states(), is_state(), state_attr(), areas(), area_entities(), area_name(), floors(), floor_areas(), labels(), label_entities(), devices(), device_entities(), now(), relative_time().

History & Logbook

Entity state history

CODEBLOCK29

Logbook

CODEBLOCK30

Dashboard Overview

Quick status of all active devices:

CODEBLOCK31

Entity Domains

Domain	Examples
INLINECODE31	Smart plugs, generic switches
INLINECODE32

Notes

- API returns JSON by default
Long-lived tokens don't expire — store securely
Test entity IDs with the list command first
For locks, alarms, and garage doors — always confirm actions with the user

Home Assistant 技能

通过 Home Assistant REST API 控制智能家居设备。

设置

设置环境变量：

- HAURL — 你的 Home Assistant URL（例如 http://10.0.0.10:8123）
HATOKEN — 长期访问令牌（在 HA → 个人资料 → 长期访问令牌中创建）

安全规则

在执行以下操作前，务必先征得用户确认：

- 门锁 — 锁定或解锁任何门锁
报警面板 — 布防或撤防
车库门 — 打开或关闭（cover.* 且 device_class: garage）
安全自动化 — 禁用与安全相关的自动化
卷帘/遮阳帘 — 打开或关闭控制物理通道的卷帘（大门、闸门）

未经用户明确确认，切勿对安全敏感设备进行操作。

实体发现

列出所有实体

bash
curl -s $HAURL/api/states -H Authorization: Bearer $HATOKEN \
| jq -r .[].entity_id | sort

按域列出实体

bash

开关

curl -s $HAURL/api/states -H Authorization: Bearer $HATOKEN \
| jq -r .[] | select(.entityid | startswith(switch.)) | \(.entityid): \(.state)

灯光

curl -s $HAURL/api/states -H Authorization: Bearer $HATOKEN \ | jq -r .[] | select(.entityid | startswith(light.)) | \(.entityid): \(.state)

传感器

curl -s $HAURL/api/states -H Authorization: Bearer $HATOKEN \ | jq -r .[] | select(.entityid | startswith(sensor.)) | \(.entityid): \(.state) \(.attributes.unitofmeasurement // )

替换域前缀（switch.、light.、sensor. 等）以发现任何域中的实体。

获取单个实体状态

bash
curl -s $HAURL/api/states/ENTITYID -H Authorization: Bearer $HA_TOKEN

区域与楼层发现

使用模板 API 查询区域、楼层和标签。

bash

列出所有区域

curl -s -X POST $HA_URL/api/template \
-H Authorization: Bearer $HA_TOKEN \
-H Content-Type: application/json \
-d {template: {{ areas() }}}

特定区域中的实体

curl -s -X POST $HA_URL/api/template \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {template: {{ area_entities(\kitchen\) }}}

仅区域中的灯光

curl -s -X POST $HA_URL/api/template \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {template: {{ area_entities(\kitchen\) | select(\match\, \light.\) | list }}}

查找实体所属区域

curl -s -X POST $HA_URL/api/template \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {template: {{ area_name(\light.kitchen\) }}}

列出所有楼层及其区域

curl -s -X POST $HA_URL/api/template \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {template: {% for floor in floors() %}{{ floor }}: {{ floor_areas(floor) }}\n{% endfor %}}

开关

bash

打开

curl -s -X POST $HAURL/api/services/switch/turnon \
-H Authorization: Bearer $HA_TOKEN \
-H Content-Type: application/json \
-d {entityid: switch.officelamp}

关闭

curl -s -X POST $HAURL/api/services/switch/turnoff \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {entityid: switch.officelamp}

切换

curl -s -X POST $HA_URL/api/services/switch/toggle \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {entityid: switch.officelamp}

灯光

bash

带亮度打开

curl -s -X POST $HAURL/api/services/light/turnon \
-H Authorization: Bearer $HA_TOKEN \
-H Content-Type: application/json \
-d {entityid: light.livingroom, brightness_pct: 80}

带颜色打开（RGB）

curl -s -X POST $HAURL/api/services/light/turnon \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {entityid: light.livingroom, rgb_color: [255, 150, 50]}

带色温打开（微倒度）

curl -s -X POST $HAURL/api/services/light/turnon \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {entityid: light.livingroom, color_temp: 300}

关闭

curl -s -X POST $HAURL/api/services/light/turnoff \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {entityid: light.livingroom}

场景

bash
curl -s -X POST $HAURL/api/services/scene/turnon \
-H Authorization: Bearer $HA_TOKEN \
-H Content-Type: application/json \
-d {entityid: scene.movietime}

脚本

bash

列出所有脚本

curl -s $HAURL/api/states -H Authorization: Bearer $HATOKEN \
| jq -r .[] | select(.entityid | startswith(script.)) | \(.entityid): \(.state)

运行脚本

curl -s -X POST $HAURL/api/services/script/turnon \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {entityid: script.bedtimeroutine}

带变量运行脚本

curl -s -X POST $HAURL/api/services/script/bedtimeroutine \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {variables: {brightness: 20, delay_minutes: 5}}

自动化

bash

列出所有自动化

curl -s $HAURL/api/states -H Authorization: Bearer $HATOKEN \
| jq -r .[] | select(.entityid | startswith(automation.)) | \(.entityid): \(.state)

触发自动化

curl -s -X POST $HA_URL/api/services/automation/trigger \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {entityid: automation.morningroutine}

启用自动化

curl -s -X POST $HAURL/api/services/automation/turnon \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {entityid: automation.morningroutine}

禁用自动化

curl -s -X POST $HAURL/api/services/automation/turnoff \ -H Authorization: Bearer $HA_TOKEN \ -H Content-Type: application/json \ -d {entityid: automation.morningroutine}

气候控制

bash

获取恒温器状态

curl -s $HAURL/api/states/climate.thermostat -H Authorization: Bearer $HATOKEN \
| jq {state: .state, currenttemp: .attributes.currenttemperature, target_temp: .attributes.temperature}

设置温度

curl -s

homeassistant-skillHomeAssistant技能