Home Assistant 项目详解

Home Assistant 项目详解

目录

1. 项目概述
2. 核心特性
3. 工作原理
4. 架构设计
5. 安装与部署
6. 快速上手
7. 支持的设备与协议
8. 自动化与脚本
9. DIY 项目实战
10. 生态扩展
11. 适用场景

项目概述

Home Assistant（HA）是面向家庭自动化的开源平台，强调本地控制与隐私保护。项目由Paulus Schoutsen于2013年9月17日发起，采用Apache 2.0许可，已从个人项目发展为活跃的全球社区生态。

自2024年4月起，项目源代码与品牌归属Open Home Foundation（非营利组织），治理与方向继续聚焦开源与隐私。平台可作为本地"智能中枢"，统一接入与管理来自不同品牌与协议的设备与服务。

项目定位

Home Assistant 的核心定位是：

• 本地优先：默认本地运行与存储，远程访问需显式配置
• 隐私保护：支持两因素认证，生态中插件有分级安全权限
• 跨品牌统一：实现不同品牌设备的统一管理与联动
• 开源社区驱动：由全球开发者社区共同维护与发展

核心特性

1. 本地优先与隐私保护

• 默认本地运行与存储：所有数据默认存储在本地设备上
• 远程访问需显式配置：不会自动暴露到公网，需要用户主动配置
• 两因素认证支持：提供额外的安全保护层
• 分级安全权限：生态中插件有明确的安全权限分级
• 适合对隐私与可用性有较高要求的家庭环境

2. 广泛兼容与集成

• 内置协议支持：
  • Zigbee
  • Z-Wave
  • Bluetooth
  • MQTT
  • HTTP/REST
  • Thread
• 云端生态对接：可通过开放 API 对接云端生态
• 设备覆盖：覆盖上千种设备与品牌，实现跨品牌联动
• 生态集成超过 2500+

3. 自动化与脚本

• 触发器-条件-动作模型：基于经典的事件驱动自动化模型
• 蓝图（Blueprints）：支持复用社区自动化配置
• 配置方式：
  • YAML 配置文件（适合高级用户）
  • 图形化编辑器（适合新手）
• 支持复杂逻辑编排

4. 仪表盘与界面

• Lovelace 前端：
  • 卡片化设计
  • 主题支持
  • 响应式布局
  • 适配手机/平板/桌面
• 配置方式：
  • GUI 快速配置
  • 深度自定义（YAML）

5. 生态扩展

• 官方体系：
  • Home Assistant OS
  • Supervisor（系统管理）
  • Add-ons（插件系统）
• 社区资源：
  • HACS（Home Assistant Community Store）：社区商店
  • 便于发现与维护自定义集成与前端资源

工作原理

事件驱动与状态机

Home Assistant 的核心架构基于事件驱动和状态机模型：

核心组件

1. 事件总线（Event Bus）

   • 负责事件的发布与订阅
   • 设备状态变化会作为事件广播
   • 支持事件过滤与路由

2. 状态机（State Machine）

   • 维护所有实体的当前状态
   • 状态变化会触发相应事件
   • 提供状态历史记录

3. 服务注册表（Service Registry）

   • 注册所有可用的服务
   • 服务是控制设备的主要接口
   • 支持服务调用与参数传递

4. 定时器（Timer）

   • 处理定时任务
   • 支持 Cron 表达式
   • 管理延迟执行的任务

工作流程

设备状态变化 → 事件总线 → 状态机更新 → 自动化引擎 → 服务调用 → 设备联动

集成与平台模型

架构层次

1. 集成（Integration）

   • 负责一个领域（如 light、sensor、media）
   • 管理设备发现与配置
   • 提供统一的接口

2. 组件（Component）

   • 集成的基础功能模块
   • 处理协议通信
   • 管理连接与认证

3. 平台（Platform）

   • 具体的设备实现
   • 将设备抽象为实体
   • 实现设备控制逻辑

4. 实体（Entity）

   • 设备在系统中的表示
   • 暴露状态与服务
   • 供自动化与脚本调用

5. 服务（Service）

   • 控制设备的接口
   • 可被自动化与脚本调用
   • 支持参数传递

多协议网关能力

Home Assistant 可作为多种低功耗协议的本地网关：

• Zigbee：通过 USB 适配器（如 ConBee II、CC2652）
• Z-Wave：通过 USB 适配器
• Thread：通过支持 Thread 的硬件
• 蓝牙：通过蓝牙适配器或内置蓝牙

配合 USB/串口/GPIO 等适配器，可以桥接多类设备到统一平台。

架构设计

系统架构图

┌─────────────────────────────────────────┐ │ Home Assistant Core │ │ ┌──────────┐ ┌──────────┐ │ │ │ 事件总线 │ │ 状态机 │ │ │ └──────────┘ └──────────┘ │ │ ┌──────────┐ ┌──────────┐ │ │ │服务注册表 │ │ 定时器 │ │ │ └──────────┘ └──────────┘ │ └─────────────────────────────────────────┘ │ │ ┌──────┴──────┐ ┌────────┴────────┐ │ 集成层 │ │ 自动化引擎 │ └──────┬──────┘ └────────┬────────┘ │ │ ┌──────┴────────────────────┴──────┐ │ 设备与协议层 │ │ Zigbee Z-Wave MQTT HTTP... │ └──────────────────────────────────┘

数据流

1. 设备 → 集成 → 实体 → 状态机

   • 设备状态变化被集成捕获
   • 转换为实体状态
   • 更新到状态机

2. 自动化 → 服务 → 集成 → 设备

   • 自动化触发服务调用
   • 服务通过集成发送命令
   • 设备执行相应动作

安装与部署

安装方式对比

Home Assistant OS（推荐）

硬件要求

• 推荐设备：
  • Raspberry Pi 4B/5
  • Intel NUC
  • 旧电脑（x86_64 架构）
• 存储要求：
  • 建议64GB+ SSD
  • 避免使用 SD 卡（性能与可靠性问题）

安装步骤

1. 下载镜像

   • 访问 Home Assistant 官网下载对应设备的镜像
   • 使用Raspberry Pi Imager或Balena Etcher烧录

2. 首次启动

   • 将设备连接到网络
   • 等待系统初始化完成（约 5-10 分钟）

3. 访问界面

   • 浏览器访问：http://homeassistant.local:8123
   • 或使用 IP 地址：http://<设备IP>:8123

4. 初始配置

   • 创建管理员账户
   • 设置时区与位置
   • 完成基础设置向导

Docker 容器部署

快速启动

dockerrun-d\--namehomeassistant\--privileged\--restart=unless-stopped\-eTZ=Asia/Shanghai\-v/path/to/config:/config\--network=host\ghcr.io/home-assistant/home-assistant:stable

注意事项

• 容器模式通常无法使用 Add-ons 的完整能力
• 需要手动管理依赖（如 Zigbee 适配器）
• 适合已有服务器环境的用户

Python 虚拟环境安装

适用场景

• 高级用户与开发场景
• 需要深度自定义
• 开发集成或调试

安装步骤

# 创建虚拟环境python3-mvenv homeassistant# 激活虚拟环境sourcehomeassistant/bin/activate# Linux/macOS# 或homeassistant\Scripts\activate# Windows# 安装 Home Assistantpip3installhomeassistant# 启动hass

快速上手

第一步：添加设备

1. 进入设置

   • 点击左侧菜单 →设置
   • 选择设备与服务

2. 添加集成

   • 点击右下角+ 添加集成
   • 搜索品牌或协议名称
   • 常见集成：
     • Zigbee：需要 Zigbee USB 适配器
     • Z-Wave：需要 Z-Wave USB 适配器
     • MQTT：需要 MQTT Broker
     • Philips Hue：支持 Hue Bridge
     • 小米：支持米家设备
     • TP-Link：支持 Kasa 系列设备

3. 按向导配置

   • 按照集成向导完成配置
   • 设备会自动被发现并添加

第二步：创建自动化

1. 进入自动化

   • 点击左侧菜单 →自动化与场景
   • 选择创建自动化

2. 配置自动化

   • 触发器（Trigger）：何时触发
     • 时间触发（如"日落时"）
     • 状态触发（如"门磁打开"）
     • 事件触发（如"收到通知"）
   • 条件（Condition）：满足什么条件
     • 设备状态检查
     • 时间范围
     • 逻辑组合（AND/OR）
   • 动作（Action）：执行什么操作
     • 控制设备（开灯、关灯）
     • 发送通知
     • 调用服务

3. 示例自动化

   • 日落开灯：触发器 = 日落，动作 = 打开指定灯光
   • 门磁通知：触发器 = 门磁打开，动作 = 发送通知
   • 温度报警：触发器 = 温度 > 阈值，动作 = 推送通知

第三步：界面美化

1. 进入 Lovelace

   • 点击右上角⋮→编辑仪表盘

2. 添加卡片

   • 点击+ 添加卡片
   • 选择卡片类型：
     • 实体卡片：显示单个设备状态
     • 历史图表：显示历史数据曲线
     • 图片卡片：显示摄像头画面
     • 按钮卡片：快速控制设备
     • 标记卡片：显示地图位置

3. 分组与布局

   • 创建视图（View）分组设备
   • 使用网格布局或垂直布局
   • 设置图标与标题

4. 主题设置

   • 安装社区主题（通过 HACS）
   • 自定义颜色与样式

第四步：远程访问与安全

推荐方案：VPN

• 优点：最安全，完全本地控制
• 实现方式：
  • 在路由器上配置 VPN 服务器
  • 或使用 WireGuard/OpenVPN

备选方案：Home Assistant Cloud

• 服务商：Nabu Casa（官方）
• 功能：
  • 加密远程访问
  • 自动 HTTPS
  • Google Assistant / Alexa 集成
• 费用：约 $6.50/月

安全建议

• 设置强密码：使用复杂密码
• 启用两因素认证：在设置中开启 2FA
• 访问控制：限制管理员账户数量
• 定期更新：保持系统与集成最新版本
• 备份配置：定期备份配置文件

支持的设备与协议

协议支持

Zigbee

• 适配器：
  • ConBee II / ConBee III
  • CC2652 系列
  • Sonoff Zigbee 3.0 USB Dongle
• 集成方式：通过 Zigbee Home Automation（ZHA）或 Zigbee2MQTT
• 支持设备：数千种 Zigbee 设备

Z-Wave

• 适配器：
  • Aeotec Z-Stick
  • Zooz ZST10
  • Nortek HUSBZB-1（同时支持 Zigbee）
• 集成方式：通过 Z-Wave JS
• 支持设备：数百种 Z-Wave 设备

MQTT

• Broker：
  • Mosquitto（推荐）
  • EMQX
  • HiveMQ
• 集成方式：原生 MQTT 集成
• 应用场景：自定义设备、ESP8266/ESP32 项目

Bluetooth

• 适配器：USB 蓝牙适配器或内置蓝牙
• 集成方式：通过 Bluetooth 集成
• 支持设备：蓝牙传感器、智能锁等

HTTP/REST

• 集成方式：RESTful Command 集成
• 应用场景：对接第三方 API、自定义设备

品牌支持

Home Assistant 支持超过2500+ 集成，涵盖主流智能家居品牌：

• 照明：Philips Hue、LIFX、Yeelight、IKEA
• 插座：TP-Link、Sonoff、Shelly
• 传感器：Aqara、Sonoff、Tuya
• 摄像头：Hikvision、UniFi、Ring
• 空调：小米、美的、格力（部分型号）
• 门锁：Yale、Schlage、August
• 音箱：Sonos、Google Home、Amazon Echo（通过集成）

设备发现

Home Assistant 支持多种设备发现方式：

1. 自动发现：部分设备支持 UPnP/SSDP 自动发现
2. 手动添加：通过集成向导手动配置
3. 配置文件：通过 YAML 配置文件添加

自动化与脚本

自动化模型

Home Assistant 的自动化基于触发器-条件-动作模型：

触发器（Trigger） ↓ 条件（Condition，可选） ↓ 动作（Action）

触发器类型

时间触发器

• 特定时间：每天 18:00
• 日出/日落：基于地理位置计算
• Cron 表达式：灵活的时间规则

状态触发器

• 设备状态变化：门磁打开/关闭
• 数值阈值：温度超过 30°C
• 设备上线/下线：设备连接状态变化

事件触发器

• 收到通知：收到特定通知
• Webhook：收到 HTTP 请求
• MQTT 消息：收到特定 MQTT 消息

条件类型

• 设备状态：检查设备当前状态
• 时间范围：在指定时间段内
• 数值比较：大于、小于、等于
• 逻辑组合：AND、OR、NOT

动作类型

• 控制设备：开灯、关灯、调亮度
• 调用服务：调用任意服务
• 发送通知：推送通知到手机
• 执行脚本：运行预定义脚本
• 延迟执行：等待指定时间后执行

蓝图（Blueprints）

蓝图是社区共享的自动化模板，可以：

• 快速复用：使用社区已验证的自动化
• 学习参考：查看自动化实现方式
• 自定义修改：基于蓝图创建自己的自动化

脚本（Scripts）

脚本是预定义的动作序列：

• 可重复调用：在多个自动化中复用
• 参数化：支持传入参数
• 可视化编辑：通过 GUI 或 YAML 配置

DIY 项目实战

DIY 思路总览

明确场景 → 选择协议/设备 → 在 HA 中完成集成 → 用自动化编排逻辑 → 仪表盘展示与通知 → 备份与迭代

示例一：低成本 Zigbee 传感器与灯光联动

场景描述

实现夜间自动照明：当检测到有人移动且光照较低时自动开灯，5 分钟后无人自动关灯。

所需设备

• Zigbee USB 网关：
  • ConBee II（约 ¥200）
  • 或 CC2652 USB 适配器（约 ¥100）
• Zigbee 传感器：
  • 人体传感器（约 ¥30-50）
  • 光照传感器（可选，约 ¥40）
• Zigbee 灯光：
  • Zigbee 灯泡（约 ¥30-80）
  • 或 Zigbee 灯带控制器（约 ¥50）

实施步骤

1. 硬件连接

   • 将 Zigbee USB 适配器插入 Home Assistant 设备
   • 在 HA 中添加 Zigbee 集成（ZHA）
   • 按照向导完成适配器配对

2. 设备配对

   • 在 ZHA 集成中进入"添加设备"
   • 将 Zigbee 设备置于配对模式
   • 等待设备自动被发现并添加

3. 界面展示

   • 在 Lovelace 中添加实体卡片
   • 添加历史图表显示传感器数据
   • 创建灯光控制按钮

4. 创建自动化

   触发器：-人体传感器：状态变为"检测到移动" 条件：-光照传感器：亮度 < 50 lux-时间：在 18:00-06:00 之间 动作：-打开指定灯光-延迟 5 分钟-检查人体传感器状态-如果无移动，关闭灯光

示例二：基于 ESPHome 的自制 Wi‑Fi 传感器

场景描述

使用 ESP32 开发板制作温湿度传感器，接入 Home Assistant 并实现温度超阈值推送通知。

所需设备

• ESP32 开发板（约 ¥20-40）
• DHT22 温湿度传感器（约 ¥15）
• MicroUSB 数据线
• 杜邦线若干

实施步骤

1. 安装 ESPHome Add-on

   • 在 Supervisor 中安装 ESPHome
   • 启动 ESPHome 服务

2. 创建设备配置

   • 在 ESPHome 中点击"新建设备"
   • 选择 ESP32 开发板
   • 添加 DHT22 传感器配置：

   sensor:-platform:dhtpin:GPIO4temperature:name:"Living Room Temperature"humidity:name:"Living Room Humidity"update_interval:60s

3. 编译与烧录

   • ESPHome 自动编译固件
   • 通过 USB 线烧录到 ESP32
   • 设备自动连接到 Wi‑Fi

4. 在 HA 中添加设备

   • ESPHome 设备会自动被发现
   • 点击"添加"完成集成

5. 创建自动化

   触发器：-温度传感器：温度>30°C 动作：-发送通知到手机-内容："客厅温度过高，当前温度：{{states('sensor.living_room_temperature')}}°C"

示例三：能耗监测与用电优化

场景描述

监测家庭用电情况，在电价高峰期自动关闭高耗电设备，在光伏发电充足时启动热水器。

所需设备

• 智能插座（支持能耗监测）
  • TP-Link Kasa HS110/HS300
  • Sonoff POW
  • Shelly Plug S
• 智能电表（可选）
  • 支持 Modbus 的电表
  • 或通过智能插座汇总

实施步骤

1. 添加设备

   • 在 HA 中添加智能插座集成
   • 配置所有需要监测的设备

2. 配置能源仪表盘

   • 进入设置 → 仪表盘 → 能源
   • 添加用电设备
   • 配置电价信息（如分时电价）

3. 查看能耗数据

   • 能源仪表盘显示：
     • 实时用电功率
     • 日/月/年用电量
     • 用电成本
     • 设备用电排行

4. 创建优化自动化

   自动化 1：电价高峰期关闭设备

   触发器：-时间：每天 10:00-12:00,14:00-17:00（高峰时段） 条件：-高耗电设备：状态为"开启" 动作：-关闭指定设备-发送通知："已自动关闭高耗电设备以节省电费"

   自动化 2：光伏发电充足时启动热水器

   触发器：-光伏发电功率>3000W 条件：-热水器：状态为"关闭"-时间：在 10:00-16:00 之间 动作：-打开热水器-发送通知："光伏发电充足，已启动热水器"

示例四：安防与语音联动

场景描述

实现离家模式自动布防，门磁触发时录像并推送通知，支持语音控制。

所需设备

• 门窗传感器（Zigbee/Z-Wave）
• 摄像头（支持 RTSP/ONVIF）
• 智能门锁（可选）
• 语音助手（可选）：
  • Google Home
  • Amazon Alexa
  • Apple HomeKit

实施步骤

1. 添加设备

   • 添加门窗传感器集成
   • 添加摄像头集成（如 UniFi、ONVIF）
   • 配置智能门锁（如支持）

2. 创建"离家模式"

   • 创建输入布尔（Input Boolean）实体
   • 在 Lovelace 中添加开关

3. 配置自动化

   自动化 1：离家模式布防

   触发器：-离家模式开关：状态变为"开启" 动作：-启用所有安防传感器-启动摄像头录像-发送通知："已启用离家模式"

   自动化 2：门磁触发报警

   触发器：-门窗传感器：状态变为"打开" 条件：-离家模式：状态为"开启" 动作：-触发摄像头快照-开始录像（如支持）-发送紧急通知到手机-播放警报声音（如有音箱）

4. 语音控制集成

   • Google Assistant：
     • 通过 Home Assistant Cloud（Nabu Casa）
     • 或使用自建 Google Actions
   • Amazon Alexa：
     • 通过 Home Assistant Cloud
     • 或使用自建 Alexa Skill
   • Apple HomeKit：
     • 通过 HomeKit Bridge 集成
     • 支持 Siri 语音控制

5. 语音命令示例

   • “Hey Google, 打开离家模式”
   • “Alexa, 关闭所有灯光”
   • “Hey Siri, 客厅温度多少”

生态扩展

HACS（Home Assistant Community Store）

HACS 是社区驱动的插件商店，提供：

• 自定义集成：社区开发的设备集成
• 前端资源：主题、卡片、侧边栏
• 自动化蓝图：社区共享的自动化模板
• Python 脚本：实用工具脚本

安装 HACS

1. 访问 HACS 官网获取安装脚本
2. 在 Home Assistant 中执行安装命令
3. 重启 Home Assistant
4. 在侧边栏出现 HACS 菜单

使用 HACS

• 浏览分类查找需要的集成
• 点击安装并按照说明配置
• 定期更新以获取最新功能

ESPHome

ESPHome 是用于 ESP8266/ESP32 的固件框架：

• YAML 配置：通过配置文件定义设备功能
• OTA 更新：支持无线固件更新
• 自动发现：设备自动接入 Home Assistant
• 丰富传感器支持：温湿度、光照、运动等

Node-RED

Node-RED 是可视化流程编程工具：

• 图形化编程：拖拽节点创建流程
• 复杂逻辑：适合复杂自动化场景
• 丰富节点：支持 MQTT、HTTP、数据库等
• Home Assistant 集成：通过 Add-on 安装

其他常用 Add-ons

• Mosquitto broker：MQTT 消息代理
• File editor：Web 文件编辑器
• Terminal & SSH：Web 终端访问
• Samba share：网络文件共享
• Zigbee2MQTT：Zigbee 转 MQTT 桥接

适用场景

典型应用场景

1. 跨品牌设备统一管理

• 问题：不同品牌设备需要各自 APP 控制
• 解决方案：通过 Home Assistant 统一接入，一个界面控制所有设备
• 优势：减少 APP 数量，统一操作体验

2. 智能照明系统

• 场景：根据时间、光照、人员位置自动调节灯光
• 实现：
  • 日出/日落自动开关灯
  • 人体传感器联动
  • 场景模式切换（阅读、观影、睡眠）

3. 环境监测与调节

• 场景：监测温湿度、空气质量，自动调节空调、加湿器
• 实现：
  • 温度超阈值自动开启空调
  • 湿度不足自动启动加湿器
  • 空气质量差时开启新风系统

4. 安防监控

• 场景：门窗传感器、摄像头、报警器联动
• 实现：
  • 离家模式自动布防
  • 异常触发立即通知
  • 自动录像与快照

5. 能耗管理

• 场景：监测用电情况，优化用电成本
• 实现：
  • 实时用电监测
  • 分时电价优化
  • 光伏发电联动

6. 媒体控制

• 场景：统一控制音响、电视、投影仪
• 实现：
  • 场景模式切换媒体设备
  • 语音控制播放
  • 跨房间音频同步

适用人群

• 技术爱好者：喜欢 DIY 和自定义
• 隐私重视者：希望数据本地存储
• 多品牌用户：拥有多个不同品牌设备
• 自动化需求者：需要复杂自动化场景
• 学习开发者：想学习 IoT 和自动化开发

不适合的场景

• 完全新手：对技术不感兴趣，只想简单使用
• 单一品牌用户：只使用一个品牌设备（如全屋小米）
• 云端依赖者：必须使用云端服务
• 资源受限：无法提供运行 Home Assistant 的设备

总结

Home Assistant 是一个功能强大、生态丰富的开源家庭自动化平台。它通过本地优先的设计理念，为用户提供了隐私保护、跨品牌统一管理和强大的自动化能力。

核心优势

1. 本地控制：数据存储在本地，隐私得到保护
2. 广泛兼容：支持 2500+ 集成，覆盖主流设备
3. 强大自动化：灵活的触发器-条件-动作模型
4. 活跃社区：丰富的插件、蓝图和文档资源
5. 持续发展：由 Open Home Foundation 保障长期维护

学习建议

1. 从简单开始：先添加一个设备，创建一个简单自动化
2. 逐步扩展：随着需求增加逐步添加更多设备
3. 利用社区：参考社区蓝图和文档
4. 做好备份：定期备份配置文件
5. 保持更新：及时更新系统和集成

资源推荐

• 官方网站：https://www.home-assistant.io
• 文档中心：https://www.home-assistant.io/docs
• 社区论坛：https://community.home-assistant.io
• GitHub：https://github.com/home-assistant/core
• HACS：https://hacs.xyz

本文档基于 Home Assistant 项目公开资料整理，旨在帮助零基础用户快速了解和使用 Home Assistant。建议结合官方文档和社区资源深入学习。