Home Assistant Risco 集成实战：用 `risco.set_time` 动作同步报警主机时钟-平芜编程栈

Home Assistant Risco 集成实战：用`risco.set_time`动作同步报警主机时钟

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

导读

risco.set_time是 Home Assistant Risco 集成提供的一个维护型动作（action），用于直接设置 Risco 报警主机的系统时钟，典型场景是在停电恢复或夏令时切换后让报警主机与 Home Assistant 时间保持一致。本文将带你掌握它的 UI 图形化调用方式、YAML 字段参考、可复制的「每日自动校时」自动化模板，并结合仓库中 Risco 集成文档厘清其「仅限本地连接」的底层约束，让你能安全、准确地维护这套安防系统的时间基准。

什么是`risco.set_time`动作

risco.set_time的官方定义是"Sets the time of a Risco alarm panel"，即设置 Risco 报警主机的时钟。它的作用对象不是某个实体（entity），而是整个报警系统的配置条目（config entry）——你通过它把 Home Assistant 系统当前的时间写入报警主机，例如在以下场景保持主机的时钟准确：

停电恢复后：报警主机断电重启，内置时钟可能丢失或漂移；
夏令时切换后：本地时间偏移导致主机记录的事件时间戳与家庭自动化时间线不一致；
日常校时维护：作为定时任务周期性校准主机时间。

该动作的元数据定义在 source/_actions/risco.set_time.markdown，属于risco域（domain）。在自动化中调用时，动作名称为risco.set_time，不支持 targets——也就是说在 UI 中它不会提示你选择区域、设备、实体或标签，你只需要指定报警面板的配置条目即可。

为什么这个动作只在本地连接下可用

理解risco.set_time的限制，需要先了解 Risco 集成的两种连接方式：

连接方式	特点	适用动作
Risco Cloud（云）	配置简单、兼容广泛，但依赖云端轮询；Risco 自 2021 年 1 月起对云功能收费	常规布防/撤防、事件传感器
Local（本地）	不依赖云端、更新即时，但配置更复杂；需要报警面板访问码（默认 5678，注意它不是安装商/子安装商代码）	`risco.set_time`等面板级维护操作

文档在Good to know一节明确指出：设置面板时间仅在本地连接下可用，无法通过 Risco Cloud 完成（见 risco.set_time.markdown）。原因从集成文档可以推断：本地版本直连面板、无需云轮询，才能向面板下发此类系统级指令；而云连接只是通过 Risco Cloud 轮询状态与下发常规指令，并不开放面板时钟写入通道。因此，若你的 Risco 集成配置的是云连接，调用risco.set_time将无法生效，需要先将集成切换到本地连接。

此外，从 source/_integrations/risco.markdown 还可以看到本地连接的两点特性：本地版本不提供事件传感器与arming状态，但会为每个分区额外生成一个带_alarmed后缀的二进制传感器，用于指示该分区当前是否触发报警。

方式一：在 UI 中通过图形化界面调用

Home Assistant 会在你操作时逐步引导完成动作配置，无需手写 YAML。文档给出了标准操作路径：

打开设置（Settings）>自动化与场景（Automations & scenes）；
打开已有的自动化或脚本；或选择创建自动化（Create automation）>创建新自动化（Create new automation）；
若新建的是自动化，需在When（触发条件）区添加触发器；脚本无需触发器，它们在被其他东西调用时运行；
在Then do（执行动作）区选择添加动作（Add action）；
搜索并选择Risco: Set the alarm panel time；
为要设置时间的报警面板选择配置条目（Config entry），可选填时间（Time）；
点击保存（Save）。

UI 中出现的选项如下：

选项	说明	必填
Config entry（配置条目）	要设置时间的 Risco 报警面板	是（Required）
Time（时间）	发送给报警面板的时间；留空则使用 Home Assistant 系统时间	否（Optional）

这些字段由文档中的{% options_ui %}块定义，并由仓库中的 plugins/options_ui.rb 插件渲染为统一的config-vars表格结构。注意该动作不支持 targets，UI 中不会出现区域、设备、实体或标签的选择提示。

方式二：在 YAML 中使用`risco.set_time`

如果你直接编写 YAML 自动化/脚本，或想确切了解 Home Assistant 底层做了什么，可以按以下方式调用：

action: risco.set_time data: config_entry_id: 1b9a8a9d2c3e4f5061728394a5b6c7d8

上面的例子不传time字段，risco.set_time会把报警主机时钟设置为 Home Assistant 当前的系统时间。YAML 字段参考如下（由文档{% options_yaml %}块定义，经 plugins/options_yaml.rb 渲染）：

字段	类型	必填	说明
`config_entry_id`	string	是	要设置时间的 Risco 报警面板配置条目 ID
`time`	datetime	否	发送给报警面板的时间；留空则使用 Home Assistant 系统时间

关于config_entry_id：它是你在设置 > 设备与服务（Devices & Services）中为该 Risco 报警面板创建的配置条目的唯一标识符。集成文档（source/_integrations/risco.markdown）说明该集成通过配置流程（config flow）接入，每个报警面板对应一个配置条目；调用本动作时需指向目标面板对应的那个条目。示例中的1b9a8a9d2c3e4f5061728394a5b6c7d8是文档提供的示意 ID，实际使用时请替换为你自己的条目 ID。

time字段为可选，传入时按datetime类型解析。留空是最常见的用法——直接采用 Home Assistant 系统时间，天然与家庭自动化时间线一致，无需手工换算时区。

实战模板：自动化每日同步报警主机时钟

文档提供了一个开箱即用的自动化示例：每天凌晨 3 点，用 Home Assistant 系统时间重新同步报警主机时钟，使其在停电或夏令时变化后保持准确。

触发器（Trigger）：时间（Time），03:00:00
动作（Action）：Risco: Set the alarm panel time
- 配置条目（Config entry）：你的 Risco 报警面板

对应的完整 YAML 如下：

automation: - alias: "Sync the Risco alarm panel clock" triggers: - trigger: time at: "03:00:00" actions: - action: risco.set_time data: config_entry_id: 1b9a8a9d2c3e4f5061728394a5b6c7d8

几点使用提示：

选择凌晨 3 点执行，可避开日常活动对报警系统的干扰，也避免与布防/撤防时段冲突；
若你的自动化环境中 Risco 集成为本地连接，此模板可直接生效；若为云连接，请先按上文切换到本地连接；
如需在脚本中按需触发（例如停电恢复后的手动校时），把上面的actions段抽出来放到脚本里即可，脚本无需触发器。

在开发者工具中试运行

在把动作写进自动化之前，可以在设置 > 工具（Tools）> 动作（Actions）（即 Developer Tools 的服务调用界面）中直接测试：搜索risco.set_time，填写字段后点击执行动作（Perform action），无需写一行 YAML 就能在真实环境中看到效果。

注意事项与故障排查

仅本地连接可用：这是risco.set_time最重要的约束。调用前请确认 Risco 集成使用的是 Local 本地连接，而非 Risco Cloud；集成文档 source/_integrations/risco.markdown 还提到本地连接需要面板访问码（默认 5678），并可能在旧型号上需要断开云连接或设置代理以同时支持本地与云端访问。
不需要 targets：动作不面向实体，UI 中不会提示选择区域、设备、实体或标签，只需正确指定配置条目。
配置条目选择错误：若目标面板选错，时间会被写入错误的报警系统。多站点环境下请核对config_entry_id。
排查思路：若动作执行后主机时间未更新，优先检查连接模式是否为本地、访问码配置是否正确，再核对config_entry_id是否指向目标面板。

Home Assistant Risco 集成实战：用 `risco.set_time` 动作同步报警主机时钟