返回博客

Home Assistant 手机推送通知:用 rest_command 实现漏水、洗衣机、门磁告警

Home Assistant 手机推送通知:用 rest_command 实现漏水、洗衣机、门磁告警

Home Assistant 的 Companion 应用对自己运行 Home Assistant 的人来说,通知功能已经很好用。但如果该知道地下室漏水的人是从没装过它的伴侣、父母,或者持有你备用钥匙的邻居,就麻烦了。为了让他们收到一条推送而给他们开一个 Home Assistant 账户,权限就给多了。

还有噪音的问题。“洗衣机已完成”和“浴室地板有水”不应该听起来一样。而且如果你的服务器告警已经通过另一个应用发送,你就得盯两个信息流。

本指南使用 Home Assistant 的 rest_command 通过 Pocket Alert 发送推送。它不需要任何插件或自定义集成,并涵盖三个自动化:水浸告警(关键级别)、洗衣完成(低级别),以及无人在家时门被打开。

准备工作

  • 能访问 configuration.yaml 的 Home Assistant(使用 File editor 或 Studio Code Server 插件,或通过 SSH)。
  • 一个 Pocket Alert 账户、来自 API Keys 的 API 密钥,以及需要接收告警的手机上的应用,iPhone 或 Android。免费套餐每台设备每天可发送 50 条消息。

rest_command

把密钥放进 secrets.yaml,与 configuration.yaml 位于同一文件夹:

pocketalert_token: "YOUR_API_KEY"

然后在 configuration.yaml 中添加一个命令:

rest_command:
  pocketalert:
    url: https://api.pocketalert.app/v1/messages
    method: post
    content_type: application/json
    timeout: 10
    headers:
      Token: !secret pocketalert_token
    payload: >-
      {% set body = {"title": title, "message": message,
                     "level": level | default("default")} %}
      {% if button_url is defined %}
        {% set req = {"url": button_url, "method": "POST"} | to_json %}
        {% set body = dict(body, actions=[{"type": "http",
              "label": button_label | default("Run"), "value": req}]) %}
      {% endif %}
      {{ body | to_json }}

重启 Home Assistant。现在你有了一个名为 rest_command.pocketalert 的操作,传入其 data 的内容会成为模板变量:title、message、可选的 level,以及可选的按钮。

为什么要用 to_json 构建 JSON,而不是手写?传感器名称里如果有引号,手写的字符串就会出错,而 to_json 会替你完成转义。Pocket Alert API 只接受 JSON,这也是设置 content_type 的原因:没有它,请求发出时不会带 JSON 的内容类型。

在 Developer tools → Actions 中测试:选择 rest_command.pocketalert,切换到 YAML 模式并运行:

action: rest_command.pocketalert
data:
  title: "Hello from Home Assistant"
  message: "rest_command works"

推送应在一两秒内到达。

三个自动化

在自动化编辑器(Edit in YAML)中或 automations.yaml 里添加这些内容。把实体 ID 替换成你自己的。

水浸:关键

alias: "Leak under the sink"
triggers:
  - trigger: state
    entity_id: binary_sensor.kitchen_leak
    to: "on"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Water leak: kitchen"
      message: "The sensor under the sink is wet. Check it now."
      level: critical

critical 用于那些不能等到早上的事情。在 iPhone 上,它会以独立音量播放,并穿透静音开关和勿扰模式;在 Android 上,它使用单独的通知渠道,绕过勿扰模式并占满屏幕。critical 属于付费套餐;在免费套餐中,同样的消息会以 high 送达,它仍能穿透专注模式,但无法穿透静音开关。

洗衣完成:低

没有“洗衣机已完成”的传感器,但带功率监测的智能插座可以告诉你:当功耗在几分钟内持续低于几瓦时,这一轮就结束了。

alias: "Washer finished"
triggers:
  - trigger: numeric_state
    entity_id: sensor.washer_plug_power
    below: 5
    for: "00:03:00"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Washer finished"
      message: "Laundry is ready to hang."
      level: low

low 会安静送达,没有声音,也不会打断你。当你查看手机时它会出现在列表里,这恰好符合湿衣服的紧急程度。请根据你的机器调整 below 和 for:有些洗衣机在运行中途会暂停一两分钟。

无人在家时门被打开:高

zone.home 的状态是其中的人数,所以 "0" 表示所有人都不在家。

alias: "Front door opened while away"
triggers:
  - trigger: state
    entity_id: binary_sensor.front_door
    to: "on"
conditions:
  - condition: state
    entity_id: zone.home
    state: "0"
actions:
  - action: rest_command.pocketalert
    data:
      title: "Front door opened"
      message: "Opened at {{ now().strftime('%H:%M') }} and nobody is home."
      level: high

在 iPhone 上,high 会被标记为时间敏感,因此能穿透专注模式和定时发送的摘要。消息这一行是模板:data 中的值会在传给命令之前渲染完成。

关闭水阀的按钮

当你能直接操作时,漏水告警会更有用。Pocket Alert 通知最多可以带三个操作按钮,而 http 按钮会从手机本身发送请求。Pocket Alert 不会代理它。这意味着只要手机能访问到,按钮就可以调用一个未对互联网开放的 Home Assistant Webhook。

首先,添加一个自动化,在其 Webhook 被调用时关闭水阀:

alias: "Close main water valve (from push)"
triggers:
  - trigger: webhook
    webhook_id: "close-valve-9f2c41d7a3b8e605"
    allowed_methods:
      - POST
    local_only: true
actions:
  - action: valve.close_valve
    target:
      entity_id: valve.main_water

如果你的水阀显示为开关,就改用 switch.turn_off。请把 Webhook ID 设得足够长且随机:Home Assistant 的 Webhook 除了知道 ID 之外没有任何身份验证。

然后把按钮添加到漏水自动化中:

actions:
  - action: rest_command.pocketalert
    data:
      title: "Water leak: kitchen"
      message: "The sensor under the sink is wet."
      level: critical
      button_label: "Close water valve"
      button_url: "https://ha.example.com/api/webhook/close-valve-9f2c41d7a3b8e605"

上面的 rest_command 会把 button_url 转换为方法为 POST 的 http 操作。点击按钮后,手机会在后台发送请求,无需打开应用。

使用哪个 URL:

  • 仅在家中: 你的手机在 Wi-Fi 下访问 Home Assistant 的地址。local_only: true 可让 Webhook 对互联网保持关闭。如果你的网络中有 https:// 地址,建议优先使用。
  • 在任何地方: 漏水往往发生在你外出时。Home Assistant 文档指出,带 local_only 的 Webhook 仍然可以通过 Home Assistant Cloud(Nabu Casa)的 Webhook 工作,因此云端 URL 是最简单的选择。手机上的 VPN(例如 Tailscale 或 WireGuard)也可以配合局域网地址使用。

Home Assistant 官方建议不要把破坏性或不安全的操作放在 Webhook 后面,例如解锁门。关闭水阀是安全的方向;打开水阀则不是,因此不要把它放到手机按钮上。第二次点击会发送第二个请求,这在这里无害,因为关闭一个已关闭的水阀不会产生任何影响。

关于按钮有两点需要了解。它们属于付费套餐功能,在免费套餐中会从消息里移除,但告警本身仍会送达。另外,iOS 和 Android 都会直接在通知上显示你自定义的标签,即使 Pocket Alert 应用已关闭也是如此(2.0.1 或更高版本)。按钮也会随消息一起保存在应用中,因此横幅消失后你仍然可以点击它们。

给没有 Home Assistant 的人发告警

接收推送的人只需要 Pocket Alert 应用。有两种设置方式:

  • 他们自己的账户。 他们免费注册,创建 API 密钥并发送给你。再添加第二个命令 pocketalert_family,把他们的密钥放进 secrets.yaml,并在漏水自动化中同时调用这两个命令。你的服务器告警仍然留在你的账户中;他们只能看到你发给他们的内容。
  • 你账户下的第二台设备。 付费套餐包含多台设备。添加他们的手机,然后复制一份命令,并在 body 字典中加入 "device_id": "THEIR_DEVICE_ID",这样只有家庭相关的告警会发送给他们。

无论哪种方式,他们都能收到同样级别和按钮的漏水告警,而无需你的 Home Assistant 账户。

一个应用管理家庭与其他一切

同一个 API 密钥也可用于 cron 任务、备份、可用性检查和 CI。如果你在运行家庭实验室,Proxmox、NAS 和备份告警会与漏水传感器进入同一个信息流,每条都有自己的级别,而且应用可以按级别过滤信息流,因此在四十条消息中也能轻松找到那两条重要的。其他传感器(ESP32 开发板、树莓派、Node-RED)请参阅物联网与传感器告警。

对于只能发送 JSON Webhook 的设备,有一种无代码方案:在控制台中创建 Webhook,并根据负载模板化消息内容。请参阅 Webhook 转推送。

作为 notify 操作的 RESTful Notifications

如果你更喜欢 notify.* 操作,Home Assistant 的 RESTful Notifications 平台同样可以发送到 Pocket Alert:

notify:
  - name: pocketalert
    platform: rest
    resource: https://api.pocketalert.app/v1/messages
    method: POST_JSON
    title_param_name: title
    headers:
      Token: !secret pocketalert_token
    data:
      level: high

POST_JSON 发送 JSON 请求体,title_param_name 将通知标题映射到我们的 title 字段,data 则添加固定字段。使用 action: notify.pocketalert 调用,并传入 title 和 message。级别按通知器固定,因此如果你需要多个级别,就为每个级别各创建一个;或者直接使用 rest_command,它还支持按钮。

如果什么都没收到

  • 检查日志。 请求失败时,rest_command 会记录一条带状态码的警告。401 表示 secrets.yaml 中的密钥有误;400 通常表示负载不是有效的 JSON。
  • 第一次要重启。 第一个 rest_command 配置块需要重启 Home Assistant 后操作才会出现;之后的修改可通过 rest_command.reload 操作加载。
  • 手动运行操作。 在 Developer tools 中运行。如果这样可以,问题出在自动化的触发器或条件上,请检查它的追踪记录。
  • 按钮没反应: 在手机浏览器中打开 Webhook URL 的主机。如果手机无法访问该地址处的 Home Assistant,按钮也就无法工作。
  • 检查当日配额。 免费套餐每天上限为 50 条消息,一个频繁触发的传感器很容易耗尽它。在触发器上加一个 for: 会有所帮助。

常见问题

我需要 Home Assistant Companion 应用吗?

不需要。推送来自 Pocket Alert,因此手机只需要安装 Pocket Alert 应用。你仍然可以保留 Companion 应用,用于它的传感器和位置追踪功能。

这能与 Home Assistant Cloud 一起使用吗?

可以。rest_command 直接从你的 Home Assistant 调用 Pocket Alert API,因此不依赖 Nabu Casa。只有在你不在家时,Home Assistant Cloud 才会对水阀按钮有帮助。

漏水告警能在夜里把我叫醒吗?

在 critical 级别下可以:在 iPhone 上它会穿透静音开关,在 Android 上会穿透勿扰模式。该级别需要付费套餐;在免费套餐中,它会以 high 送达。

我的 API 密钥会暴露吗?

密钥保存在 secrets.yaml 中,并通过 HTTPS 在 Token 请求头中发送。请为 Home Assistant 单独使用一个密钥,这样你可以撤销它而不影响其他脚本。

免费注册账户,添加一个 rest_command,让家里在需要你的时候告诉你。

分享这篇文章