返回首页

给家做一块状态屏:我的 Home Assistant 折腾记录

3521 字15 分钟

整个中控屏#

我想给我的电脑桌上放一块不用操心,瞥一眼就能看见的状态屏。房间里的温度,设备的电量,家里有那些灯是开着的。或者,我只是想玩玩自动化,比如看看洗衣机的衣服洗好了,小爱音响提醒我收衣服。空气炸锅的食物熟了,小爱提醒我按时吃饭什么的。这些信息原本是可以在米家找到的,只是如果不同品牌的设备要实现自动化,那就需要用上Home Assistant了。(以下简称为HA)

于是,我脑海里就浮现了一个想法,既然现在Vibe Coding这么方便,那我是否可以完成HA的部署。(某人:之前让你弄你不弄),于是,这个项目从接入设备、搭页面,一路变成了现在这套基于HA的家庭面板。接下来,我准备把它放到一台 LCD Android 平板上,让它成为家里一块固定的屏幕。问就是我的iPad是OLED,我怕屏幕烧了。

本次选用的平板是Google的 Tablet,定位是家庭音响,性能不强。或者可以说,这算是Apple家的平替了。还自带一个音响,没什么用,做支架用的。

Google Pixel Tablet 正面与初始设置界面

Google Pixel Tablet 背面与音响底座

最开始,我是完成了一个独立的网站,里面接入了一些东西。但涉及到隐私和安全性,我把网站删库跑路了。里面的一些必要的东西留了下来,比如设备电量。这一部分我打算加入HA里面。现在再看,这段折腾的过程让我理清了一些真正想留下的东西:可控的家庭的状态,设备的信息查询。

现在,家庭服务由 Mac mini 承载,Android 平板负责显示和触控。自动化在服务器上执行,屏幕只是访问它的一个入口。理论上这个也是接上了公网的,外网也是可以访问。我配置了2FA以加强安全性。

实现项目#

真正开始接入设备前,首先要理解的是HA到底是什么?

平时,我们可能用米家查看温湿度、控制灯光,用另一个 App 操作音箱,再去洗衣机的 App 里看剩余时间。HA 可以连接这些设备,把它们的状态放到同一个界面里,也提供统一的操作入口。

连接方式取决于设备:有些可以直接通过家里的局域网通信,有些仍然需要经过厂商的云服务。因此,接入 HA 之后,各个设备的功能和更新速度也可能不同。

在我的项目里,整套系统可以这样理解:

  • 家里的设备负责感知和执行:温湿度计测量环境,插座报告功率,灯具接收开关指令。
  • Mac mini 上的 HA 负责连接和处理:收集设备状态,执行规则,把信息提供给页面。
  • Android 平板负责显示和触控:打开家庭面板,让我看见状态、点击操作。

比如我在平板上点击开灯,指令会先交给 HA,再由它通过对应的设备集成发送给灯具;设备返回的新状态,也会更新到页面上。就像是米家的操作,换在了HA上实现,与米家不同的是,这是可以跨设备的,只要你的设备是联网的,理论上都可以接入HA。这与文章开头说的一些小功能如出一辙。

知道了HA是什么后,我们运用到实际中。

在日常使用中,我把一个插座看成一个设备;在系统里,它可能同时提供开关、功率、电量等多个实体。洗衣机也一样,运行状态、剩余时间、模式,可能分别对应不同的实体。

这样一来,设备与页面之间就多了一层统一的数据表示。前端可以读取温度实体、显示开关状态,自动化也可以根据同一份状态作判断。

这套系统的数据流大致是这样:

家庭设备与传感器 → 设备集成(局域网或云端)
                         ↓
               Home Assistant 实体与状态
                   ↕              ↓
             自动化与状态汇总   仪表盘与自定义卡片
                                  ↓
                             Android 平板
                                  ↓
                               触摸操作
                                  ↓
                       Home Assistant 服务调用
                                  ↓
                     设备集成 → 家庭设备与传感器

设备接入和数据显示之间,也不是每一项都能直接画上等号。有些原始信息适合直接显示,比如温度和插座功率;有些则需要先整理,例如把洗衣机的多个字段组合成“正在洗涤、还剩多久、预计几点结束”。我家的是小天鹅洗衣机,调用了美的API可以正常接入HA.

Home Assistant 中的小天鹅洗衣机状态卡片

目前这套面板涉及的技术,可以按用途整理成下面这张表:

部分使用的技术在项目里的作用
服务承载Mac mini、macOS、HAOS 虚拟机环境运行家庭服务
家庭平台Home Assistant管理实体、设备状态与自动化
设备接入米家/MIoT、Sonos、Apple TV、美的等集成连接不同品牌和协议的设备
基础界面HA Dashboard/Lovelace、Mushroom 卡片提供设备展示与操作组件
自定义界面JavaScript、Web Components、Shadow DOM实现家庭布局和补充卡片
布局与视觉CSS Grid、Flex、容器查询、主题变量、SVG处理尺寸适配、主题和图标
维护功能Python、asyncio、HA 事件与存储接口判断维护事项、保存处理记录
外部汇总任务Node.js、macOS launchd执行洗衣状态等监控任务
自动化YAML、Jinja、HA 脚本与助手编排条件、动作和会话状态
显示终端LCD Android 平板今晚接入后补充实测

遇到的问题#

把数据接通是第一步。接下来是一个很常见的问题:这么多设备,我们怎么快速的查看到设备的状态。于是我开始按实际使用场景整理它们:环境、照明、媒体、洗衣、设备维护。常看的信息放得直接一点,偶尔才需要的参数留在详情里。

界面也没有全部重新写一遍。已有卡片能够完成的灯光操作、媒体控制,就继续使用已有组件;自定义代码主要负责整体布局,以及电量、环境读数和维护信息等补充展示。

这部分使用的是原生 JavaScript 和 Web Components。自定义卡片接收 Home Assistant 传来的 hass 对象,从中读取实体状态,并把它继续传给内部的卡片。

下面这段是现有代码的摘录,只调整了排版:

// Home Assistant 更新状态时,向卡片传入新的 hass 对象
set hass(hass) {
  this._hass = hass;

  // 内嵌卡片也需要继续接收状态更新
  for (const card of this._children) {
    card.hass = hass;
  }

  this._updateReadings();
}

这里的 _children 保存了页面里复用的卡片。它们继续处理各自的展示和操作,我自己的代码再更新额外的读数。

HA 前端通过 WebSocket 接收状态更新,自定义卡片再通过这套接口使用数据。相关机制可以参考官方的自定义卡片文档和 WebSocket API 文档。

布局主要用了 CSS Grid、Flex 和容器查询。宽一些时,可以让几组信息并排;宽度缩小时,再调整为更少的列数。颜色尽量跟随 HA 的主题变量,减少切换明暗主题时需要单独维护的样式。

Home Assistant 家庭面板总览

Home Assistant 设备维护页面

不过,电脑上缩放浏览器只能帮助检查布局。平板上实际的字号、观看距离、触控区域和滚动感受,还得等设备接上以后确认。

比布局更容易被忽略的,是数值本身的含义。

比如温度显示 0,和温度没有读到,完全是两回事。JavaScript 的 Number("") 却会得到 0,如果没有提前处理,空值就可能变成一个看起来很正常的数字。

所以在读取数值时,我先把缺失、未知、不可用和无效数值排除掉。下面按现有 _number() 方法的逻辑整理了排版:

_number(entityId, digits = 0) {
  const raw = this._hass?.states[entityId]?.state;

  if (
    raw == null ||
    String(raw).trim() === "" ||
    ["unknown", "unavailable"].includes(raw) ||
    !Number.isFinite(Number(raw))
  ) {
    return null;
  }

  return Number(Number(raw).toFixed(digits));
}

显示层再把 null 渲染成 —,有效的零值则照常显示。电量还要额外检查是否在合理范围内。

项目页面可以在家里内网访问了,此时我还想解决一个问题:如果我不在家,能不能继续查看家里的状态?

家庭网络里的地址通常只能在家里使用。手机切到移动网络以后,就需要一个能够从外部到达的入口。出于安全性,我用的方案是 Cloudflare Tunnel。

可以把它理解成一条由家里的电脑主动建立的通道。Mac mini 上运行一个叫 cloudflared 的程序,它连接 Cloudflare;我在外面访问域名时,请求再沿着这条通道转发到家里的 Home Assistant。这个机制不要求家庭网络拥有可供外部直接访问的公网 IP。Cloudflare Tunnel 原理

访问路径大致是:

外面的手机或电脑
        ↓ HTTPS
家庭面板的域名
        ↓
Cloudflare
        ↓ 已建立的隧道
Mac mini 上的 cloudflared
        ↓ 本机或局域网转发
Home Assistant

HA 和设备数据仍然留在家里的服务器上,公网这一层负责提供访问入口。

如果从头搭建,主要有这样几个步骤:

  1. 把准备使用的域名接入 Cloudflare,选一个子域名作为家庭面板入口。
  2. 在 Cloudflare 控制台创建隧道。
  3. 按控制台提示,在承载服务的机器上安装并运行 cloudflared。
  4. 给隧道添加公开应用路由,把子域名指向 HA 的实际访问地址。
  5. 配置 HA 对代理的信任关系,再从家庭 Wi-Fi 之外验证登录、状态更新和操作。

控制台管理的隧道可以直接填写这些路由信息,具体入口以官方部署文档为准。

用配置文件表达,核心关系类似下面这样。这里只展示路由部分,域名和地址都是示例,不是完整的现网配置:

ingress:
  # 访问这个域名时,转发给 Home Assistant
  - hostname: ha.example.com
    service: http://127.0.0.1:8123

  # 没有匹配到的请求返回 404
  - service: http_status:404

这几行的意思很直接:访问 ha.example.com,就把请求交给指定的本地服务;其他请求不匹配这条规则。配置文件说明

这里有一个很容易照抄出错的地方:127.0.0.1 指的是运行 cloudflared 的那台机器。 如果 HA 在另一台电脑、虚拟机或容器里,必须确认这个地址确实能够到达它。示例中的 8123 也要换成实际使用的端口。

接下来是 HA 这一侧的设置。

经过代理的请求,和浏览器直接访问 HA 的请求有所不同。按目前官方文档,可以在“设置 → 系统 → 网络”的 HTTP 服务设置里启用 Trust X-Forwarded-For,并把 HA 实际看到的直接代理地址加入 Trusted proxies。具体地址取决于部署结构,不能直接照抄别人的配置。HA 代理配置说明

公网入口建立后,仍然保留 HA 的账号登录与两步验证。HTTPS 负责加密访问过程,账号权限负责决定谁可以看、谁可以操作;隧道凭据则由服务器保存。

验证也不能只停在“域名能打开”。

HA 页面依靠 WebSocket 长连接接收状态变化。我需要确认登录之后数据能够继续更新,点击操作后也能得到反馈。Cloudflare 支持代理 WebSocket,但连接中断后的恢复仍然值得实际观察。Cloudflare WebSocket 说明

另外,代理或 CDN 的缓存规则也要留意。登录接口和实时数据接口应该取得当前响应,不能把旧数据当作新状态返回;HA 官方文档也明确列出了 /api/、/auth/ 等路径的缓存注意事项。缓存配置说明

这条公网链路早期确实访问成功过,但后来也出现了故障。11 月 2 日的诊断记录里,公网返回 HTTP 530,Cloudflare 错误码为 1033,控制台中的隧道显示离线;当时尚未完成恢复。

所以,这部分记录的是采用过的方案和部署原理。当前公网是否恢复,还需要在修复后重新验证。域名、隧道、HA 服务和设备数据分别处在不同层次,排查时也得一层一层确认。

实际效果#

公网访问解决的是出门以后怎么连接。回到家里,我更想要的还是一块固定摆着、抬一眼就能看到的屏幕。

这也是我准备接入 Android 平板的原因。(好吧只是变相捡了个洋垃圾)

Android 平板上的 Home Assistant 家庭面板实际效果

手机适合随手操作,但查看之前总要先拿起来、打开页面。我希望平板能放在一个固定的位置,把温湿度、洗衣状态和几个常用操作留在那里。

它承担的是显示和触控。HA、设备集成和自动化继续在 Mac mini 上运行。这样的分工也方便以后更换屏幕:只要新的终端能够正常访问面板,就可以继续使用服务器上的配置。

对于放在家里的这块屏幕,我准备优先验证局域网访问,让它能够直接连接家里的服务;公网入口则单独验证,供外出时使用。这样也更容易判断故障发生在哪一段。

评论区