Home Assistant UniFi Protect:用 set_chime_paired_doorbells 动作管理门铃与智能蜂鸣器的配对-平芜编程栈

Home Assistant UniFi Protect:用 set_chime_paired_doorbells 动作管理门铃与智能蜂鸣器的配对

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

本文围绕 Home Assistant 官方文档中unifiprotect.set_chime_paired_doorbells动作展开,完整覆盖其在图形界面与 YAML 中的使用方法、device_id与doorbells参数详解,并结合 UniFi Protect 集成文档中智能蜂鸣器(Smart Chime)的设备实体,讲解一套「夜间静音、清晨恢复」的门铃蜂鸣器配对自动化实战方案。

动作概览:它解决什么问题

UniFi Protect 门铃本身带有蜂鸣器,也可以将铃声转接到其他房间的 Smart Chime(智能蜂鸣器)设备。unifiprotect.set_chime_paired_doorbells就是用来控制「哪些门铃会响某一台蜂鸣器」的动作:先选定一台蜂鸣器,再选择要与它配对的门铃。

需要特别理解的一点是它的替换语义:

你传入的门铃列表会整体替换该蜂鸣器之前已有的配对关系;
列表里没有包含的门铃会被自动解除配对;
如果门铃列表留空,则解除该蜂鸣器上的所有门铃配对。

也就是说,这不是「追加配对」,而是「声明式设置」——每次调用都是把目标配对状态一次性写全。这个语义直接决定了自动化里怎么写才正确(见后文「夜间静音」示例)。

前提:UniFi Protect 集成中的 Smart Chime 设备

要使用这个动作,系统中需要已有 UniFi Protect 集成接入的 Smart Chime 设备。根据 UniFi Protect 集成文档,每台 UniFi Protect 智能蜂鸣器在 Home Assistant 中会生成一个设备,包含:

Button— 一个可手动触发蜂鸣器响铃的按钮;另有一个默认禁用的按钮用于重启该智能蜂鸣器设备;
Device Configuration— 一个音量滑块(调节蜂鸣器响度)以及一个记录蜂鸣器上次响铃时间的传感器。

此外,门铃(Doorbell)摄像头设备会带有一个 "Doorbell Chime" 传感器(如果该摄像头配有蜂鸣器),摄像头设备的配置项中还提供 Chime Type(蜂鸣器类型)等调节项。

集成文档中的设备类型与连接模式对照表还明确:Smart Chime 需要Full access(完整访问)连接模式才可用,仅 API key 的连接方式不支持该设备类型。因此如果看不到蜂鸣器设备,应优先检查集成配置的连接模式是否为完整访问。

在图形界面中使用

如果你偏好可视化构建自动化,Home Assistant 会引导你逐步完成。完整步骤如下:

前往Settings>Automations & scenes(设置 > 自动化与场景);
打开一个已有的自动化或脚本,或选择Create新建;
如果是新建自动化,在When(触发条件)部分添加触发器;脚本则无需触发器;
在Then do(执行动作)部分,选择Add action;
在搜索框中搜索并选择UniFi Protect: Set chime paired doorbells;
在Chime字段中选择蜂鸣器设备;
在Doorbells字段中选择要与该蜂鸣器配对的门铃;留空则解除所有门铃的配对;
选择Save保存。

界面选项说明

选项	说明
Chime	要配对或解除配对门铃的蜂鸣器设备。
Doorbells	要与该蜂鸣器配对的门铃。留空可解除该蜂鸣器上所有门铃的配对。此字段非必填。

在 YAML 中使用

在 YAML 中,该动作的标识符为unifiprotect.set_chime_paired_doorbells。一个最基础的调用示例:

action: unifiprotect.set_chime_paired_doorbells data: device_id: 1234567890abcdef1234567890abcdef doorbells: entity_id: binary_sensor.front_doorbell_doorbell

这条动作的效果是:将前门铃与所选择的蜂鸣器配对(同时替换掉该蜂鸣器之前的全部配对)。

YAML 参数详解

参数	类型	必填	说明
`device_id`	string	是	要配对或解除配对门铃的蜂鸣器设备 ID。注意这里是设备 ID,不是实体 ID。
`doorbells`	map	否	一个标准的目标(target)结构,用于选择要与蜂鸣器配对的门铃,可以传`entity_id`、`device_id`或`area_id`。省略该参数则解除该蜂鸣器上的所有门铃配对。

关于doorbells参数,有几点实操细节值得注意:

示例中使用entity_id传入了门铃的一个二元传感器实体(binary_sensor.front_doorbell_doorbell),因为门铃类摄像头在 Home Assistant 中通常以这类传感器实体暴露;
doorbells支持 target 结构,意味着你也可以用area_id按区域批量选择门铃(例如把整个「玄关」区域下的门铃一次性配到前台蜂鸣器上),或用device_id精确指定;
由于动作语义是「整体替换」,如果你希望某台门铃继续留在某蜂鸣器上,必须在列表里把它再次包含进来,否则它会被解绑。

去哪里找 device_id

device_id是设备注册表中的设备 ID,而不是entity_id。你可以在 Home Assistant 的开发者工具或设备页面中查看目标蜂鸣器设备的 Device ID 字段,复制 32 位十六进制字符串填入 YAML。

实用自动化:夜间静音门铃蜂鸣器

这是该动作文档给出的实战场景:晚上把卧室蜂鸣器上的所有门铃全部解绑,让夜间无人打扰;清晨再把它们配回去。

触发器:定时触发(time)
动作:UniFi Protect: Set chime paired doorbells

夜间解绑的完整 YAML 自动化:

alias: "Unpair the bedroom chime at night" triggers: - trigger: time at: "22:00:00" actions: - action: unifiprotect.set_chime_paired_doorbells data: device_id: 1234567890abcdef1234567890abcdef

注意这里没有传doorbells参数——正利用了「省略即全部解绑」的语义,一条动作即可清空卧室蜂鸣器上的所有门铃。

对应的清晨恢复自动化需要把要配对的门铃重新列出(因为解绑后原来的配对已经不存在了,必须显式重建):

alias: "Re-pair the bedroom chime in the morning" triggers: - trigger: time at: "07:00:00" actions: - action: unifiprotect.set_chime_paired_doorbells data: device_id: 1234567890abcdef1234567890abcdef doorbells: entity_id: - binary_sensor.front_doorbell_doorbell - binary_sensor.back_doorbell_doorbell

说明:「清晨重新配对」是文档场景描述(“unpair all doorbells from a bedroom chime at night, then pair them again in the morning”)所要求的补全写法;恢复时具体列哪些门铃,取决于你家的实际门铃实体。

验证与排查

试跑一下:不想写 YAML 也可以直接验证动作。打开Settings>Tools>Actions(开发者工具中的动作面板),搜索unifiprotect.set_chime_paired_doorbells,填入字段后选择Perform action,即可在不写任何 YAML 的情况下对真实实体执行一次,观察蜂鸣器配对是否按预期变化。

排查配对问题时,可以从 UniFi Protect 集成文档描述的实体入手:

查看门铃设备上的 "Doorbell Chime" 传感器状态;
查看智能蜂鸣器设备的「上次响铃时间」传感器,确认解绑后确实不再响铃;
用智能蜂鸣器设备上的手动触发按钮,确认蜂鸣器本身工作正常,再回头检查配对动作的参数(尤其是device_id是否指向了正确的蜂鸣器设备)。

另外,如前所述,若集成是以「仅 API key」模式接入,Smart Chime 设备根本不会出现,也就无法使用该动作——请确认连接模式为 Full access。

动作	文档位置	用途
`unifiprotect.add_doorbell_text`	add_doorbell_text	为门铃添加自定义屏幕文字(小于 30 个字符)
`unifiprotect.remove_doorbell_text`	remove_doorbell_text	移除门铃上的自定义文字
`unifiprotect.ptz_goto_preset`	ptz_goto_preset	让 PTZ 摄像头移动到预设位置(含 home 位)
`unifiprotect.get_user_keyring_info`	get_user_keyring_info	获取用户密钥环信息
`unifiprotect.remove_privacy_zone`	remove_privacy_zone	移除隐私区域

小结

unifiprotect.set_chime_paired_doorbells是一个语义简单的声明式动作:用device_id指定蜂鸣器,用doorbellstarget 一次性设定该蜂鸣器的完整配对集合;省略doorbells即解绑全部。理解了「替换而非追加」这一点,界面操作、YAML 编写和夜间静音自动化都能轻松落地。本文所有参数说明与示例均来自 set_chime_paired_doorbells 动作文档与 UniFi Protect 集成文档,可直接对照当前仓库查阅。

【免费下载链接】home-assistant.io:blue_book: Home Assistant User documentation项目地址: https://gitcode.com/GitHub_Trending/ho/home-assistant.io

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考