企业官网建设流程全解析

Home Assistant OpenTherm Gateway：set_setback_temperature 动作完整指南

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

导读

本文聚焦 Home Assistant 中opentherm_gw集成提供的Set setback temperature动作，讲解如何通过 UI 与 YAML 为 OpenTherm Gateway 配置"回退温度"（setback temperature）。该温度配合 GPIO 的Home与Away模式使用，是实现离家/回家自动降温和升温的关键参数。读完本文，你将掌握该动作的完整调用方式、参数约束（温度 0～30℃）、底层 GPIO 模式语义，以及它与set_gpio_mode、set_outside_temperature等动作的协作关系。

动作概述：setback temperature 是什么

Set setback temperature动作用于在 OpenTherm Gateway 上配置回退温度（setback temperature）。该值本身不会直接改变温控器设定点，而是作为 GPIOHome（5）与Away（6）模式下的目标温度使用——即当 GPIO 引脚被拉低（Home）或拉高（Away）时，温控器被切换到回退温度。

该动作来自 Home Assistant 官方文档库，动作域为opentherm_gw，完整动作名为opentherm_gw.set_setback_temperature，定义于 source/_actions/opentherm_gw.set_setback_temperature.markdown。其官方描述为："Configures the setback temperature used with the GPIO home and away modes."

使用前提

在通过此动作设置回退温度前，通常需要先将 GPIO 引脚配置为 Home 或 Away 模式，否则该温度没有实际作用对象。GPIO 模式通过opentherm_gw.set_gpio_mode动作或集成页面中的select实体配置。

GPIO 模式与回退温度的底层关系

根据 OpenTherm Gateway 集成文档，GPIO 引脚（A 与 B）支持以下模式，其中与回退温度直接相关的有两个：

从源码结构看，set_setback_temperature动作写入的正是 GPIO Home/Away 模式所引用的回退温度值。典型场景是：在门口开关或智能锁联动下，当外出（GPIO 拉高）时温控器自动切到 Away 回退温度；回家（GPIO 拉低）时切到 Home 回退温度。Home 与 Away 模式共用同一个回退温度值。

从 UI 使用该动作

若偏好可视化方式构建自动化或脚本，可按照以下步骤操作：

1. 打开设置>自动化与场景（Settings > Automations & scenes）。
2. 打开现有自动化或脚本，或选择创建自动化>创建新自动化。
3. 新建自动化时，在当...时（When）区域添加触发器；脚本无需触发器，由其他对象调用时直接运行。
4. 在然后执行（Then do）区域选择添加动作。
5. 在搜索框中搜索并选择OpenTherm Gateway: Set setback temperature。
6. 填写Gateway ID与Temperature。
7. 点击保存。

UI 中的选项

注意：该动作不支持目标（targets）。在 UI 中不会提示选择区域、设备、实体或标签，因为它作用于整个网关节点的配置，而非某个实体。

在 YAML 中使用该动作

在 YAML（automation 或 script）中，动作以opentherm_gw.set_setback_temperature引用。基本示例：

action: opentherm_gw.set_setback_temperature data: gateway_id: opentherm_gateway temperature: 16

该示例在指定网关上将回退温度设为 16 度。

YAML 字段参考

gateway_id 的由来

gateway_id来自集成配置时的id字段。根据 opentherm_gw 集成配置说明，该值用于在动作中标识具体网关，并用于生成该网关相关实体的实体 ID。输入值会被 slugify：所有空格和特殊字符转换为下划线，重音字符被移除。例如thermostat、living_room。因此 YAML 中必须填写与你实例中配置一致（且已 slugify）的 ID。

temperature 的取值范围

temperature为float类型，仅接受0 到 30之间的值。超出此范围的值会触发校验错误，动作不会下发到网关。与室外温度动作不同，回退温度没有"清除已配置值"的特殊约定（室外温度为大于 64.0 时清除，详见下文相关动作）。

结合其他动作实现完整场景

该动作通常与以下动作搭配使用，官方文档将其列为相关动作（related actions）：

opentherm_gw.set_gpio_mode

Set GPIO mode 用于更改网关 GPIO 引脚的功能。参数为gateway_id、id（A或B）与mode（0～6 两脚均接受，7 仅 GPIO B 接受）。典型配置示例：

action: opentherm_gw.set_gpio_mode data: gateway_id: opentherm_gateway id: A mode: 5 # Home 模式：拉低时切换回退温度

先设置 GPIO 模式为 Home/Away，再通过set_setback_temperature写入回退温度，即可让引脚电平变化时自动切换温度。

opentherm_gw.set_outside_temperature

Set outside temperature 用于向温控器提供室外温度（-40.0 到 64.0 之间），用于室外温度补偿（OTC）；任何大于 64.0 的值（建议 99）会清除之前配置的值。它不直接作用于回退温度，但同属网关配置类动作，常在同一个自动化或脚本中一起调用。

使用注意事项

• 无目标支持：该动作作用于网关本身，不支持 targets，UI 中不会出现选择区域/设备/实体/标签的步骤。
• 轮询协议延迟：OpenTherm 协议基于轮询——温控器按固定间隔向锅炉发送请求。因此 Home Assistant 与温控器之间的变更传播可能存在延迟，切换回退温度不会立即生效（见 opentherm_gw 集成文档 中的说明）。
• 单实例独占：请确保没有其他设备或应用程序同时连接 OpenTherm Gateway，这不是受支持的场景，可能导致意外结果。
• 区分"取消房间设定点覆盖"：集成还提供Cancel Room Setpoint Override按钮，用于取消激活中的房间设定点覆盖，但它不会改变目标温度，仅将控制权交还温控器，与回退温度动作是两个不同的概念。

测试与验证

配置完成后，可在开发者工具>操作（Developer Tools > Actions）中选择opentherm_gw.set_setback_temperature，填入gateway_id与temperature后执行，观察是否返回成功。随后可将 GPIO 引脚按对应模式拉低/拉高，验证温控器是否切换到回退温度；也可以在网关上查看当前配置的回退温度值予以确认。

小结

opentherm_gw.set_setback_temperature是 Home Assistant 控制 OpenTherm Gateway 回退温度的核心动作，参数简洁（gateway_id+temperature，0～30），但只有与 GPIO Home/Away 模式配合时才有实际意义。理解 GPIO 模式表、正确获取 slugify 后的gateway_id、并留意 OpenTherm 轮询协议的延迟特性，是正确使用该动作的关键。

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