企业官网建设流程全解析

Home Assistant OpenTherm Gateway Set LED Mode 动作详解：LED 功能配置与 YAML 实战

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

导读

opentherm_gw.set_led_mode是 Home Assistant 中用于修改 OpenTherm Gateway（OTGW）LED 指示灯功能的动作（action）。通过它，你可以为网关的 LEDA至F六个指示灯分配不同的通信状态、加热状态或故障提示功能，从而快速掌握家庭供暖系统的运行状况。读完本文，你将完整掌握该动作的全部参数、LED 模式对照表、UI 可视化配置步骤与 YAML 自动化写法。

动作概述：这是什么？

OpenTherm Gateway 是一款用于桥接 Home Assistant 与 OpenTherm 供暖协议设备（恒温器、锅炉）的硬件网关。网关面板上带有一组 LED 指示灯，用于显示通信与供热状态。Set LED mode动作的作用正是"更改网关上 LED 的功能"——即把某个 LED 重新指派给另一项状态指示。

在 Home Assistant 文档体系中，该动作归属于opentherm_gw集成（domain），完整的动作标识为opentherm_gw.set_led_mode。官方对它的定义是：

Changes the function of the LEDs of the gateway.

动作说明文档位于 source/_actions/opentherm_gw.set_led_mode.markdown，其所属集成的主文档为 source/_integrations/opentherm_gw.markdown。

与 Select 实体的关系

从集成文档看，OpenTherm Gateway 集成会为每个配置的网关添加三个设备，其中OpenTherm Gateway设备上带有多个select配置实体，这些实体同样可以用于配置网关的 LED 和 GPIO 引脚（见 source/_integrations/opentherm_gw.markdown）。也就是说，除了通过动作在自动化中动态设置 LED 模式，你也可以在界面上直接操作 select 实体来配置。动作方式更适合"按事件动态切换"的场景，实体方式更适合"一次性静态配置"。

参数说明（Options）

该动作共接受三个参数，全部为必填项（required: true），且不支持 targets——在 UI 中不会被提示选择区域、设备、实体或标签。

gateway_id 从哪来？

gateway_id对应集成配置阶段填写的id字段。根据集成文档（source/_integrations/opentherm_gw.markdown），该值用于在动作中标识特定网关，并用于生成该网关相关实体的 entity ID；输入值会被 slugify 处理——即所有空格和特殊字符转换为下划线，并移除字符上的重音符号。例如配置时填写thermostat或living_room，动作中的gateway_id就相应填写thermostat或living_room。

LED 模式对照表

mode参数的可选值及含义，与集成文档 LED modes 章节完全一致。完整对照如下：

这些模式同时也是 OTGW 固件配置命令所支持的 LED 功能（可参考 OpenTherm Gateway 固件的 configuration 文档理解底层实现，本文不再展开外部链接）。

通过 UI 配置（可视化操作）

如果你倾向于在界面中可视化地构建自动化或脚本，可以按以下步骤操作：

1. 进入Settings>Automations & scenes（自动化与场景）。
2. 打开一个现有的自动化或脚本，或者选择Create automation>Create new automation新建。
3. 如果是新建自动化，在When（何时）部分添加触发器；脚本则不需要触发器，它们在被其他内容调用时运行。
4. 在Then do（然后执行）部分，选择Add action（添加动作）。
5. 在搜索框中搜索并选择OpenTherm Gateway: Set LED mode。
6. 填写Gateway ID，选择 LED 的ID，并设置Mode。
7. 点击Save保存。

需要再次强调的是，该动作不支持 targets，因此在 UI 中不会提示你选择区域、设备、实体或标签，只需直接填写上述三个字段。

通过 YAML 配置（自动化/脚本写法）

在 YAML 中，动作通过action: opentherm_gw.set_led_mode引用。官方文档给出的基础示例：

action: opentherm_gw.set_led_mode data: gateway_id: opentherm_gateway id: A mode: F

该示例将火焰开启（Flame is on）功能分配给选中网关的 LEDA。你可以根据实际需要，把id换成B–F，把mode换成上表中的任意模式值。

YAML 参数速查

自动化中的完整用法示例

将 LEDB配置为"中央供暖开启"指示，同时把 LEDE配置为"传输错误"指示：

alias: "Configure OTGW LEDs at startup" triggers: - trigger: homeassistant event: start actions: - action: opentherm_gw.set_led_mode data: gateway_id: opentherm_gateway id: B mode: H - action: opentherm_gw.set_led_mode data: gateway_id: opentherm_gateway id: E mode: E mode: single

无需编写 YAML 的即时测试

想在不写任何 YAML 的情况下先验证效果？打开Settings>Tools>Actions（工具 > 动作），搜索opentherm_gw.set_led_mode，填写字段后点击Perform action（执行动作），即可在你的真实实体上立即看到 LED 配置的变化。

相关动作：Set GPIO mode

该动作在 front matter 中声明了关联动作opentherm_gw.set_gpio_mode（见 opentherm_gw.set_gpio_mode.markdown）。两者功能逻辑完全对称：

• opentherm_gw.set_led_mode：配置 LEDA–F的功能；
• opentherm_gw.set_gpio_mode：配置 GPIO 引脚A/B的功能，取值0–6对两个引脚均有效，7仅 GPIOB可用。

例如，set_gpio_mode的示例将 GPIOA设为5（Home——拉低时恒温器切换至回退温度），其 GPIO 模式完整含义（Input、Ground、Vcc、LED E/F、Home、Away、DS1820 温度传感器数据线等）同样收录在集成文档 GPIO modes 章节。如果你的自定义面板接入了额外 LED 或传感器，这两个动作通常需要配合使用。

注意事项

• 协议轮询特性：OpenTherm 协议基于轮询，恒温器按固定间隔向锅炉发送请求，因此 Home Assistant 与恒温器之间的变更传播可能存在延迟（见集成文档 source/_integrations/opentherm_gw.markdown）。配置 LED 后其生效同样遵循这一机制。
• 单一连接：请确保没有其他设备或应用同时连接 OpenTherm Gateway，这是不受支持的场景，可能导致意外结果。
• gateway_id必须精确匹配：它与配置集成时填写的id一致，slugify 后的值才是动作实际使用的标识。

实现机制备忘（文档站点侧）

该动作页面的 UI/YAML 参数区块由仓库 Jekyll 插件渲染：options_ui标签由 plugins/options_ui.rb 实现，用于生成带 Required/Optional 徽标的 UI 参数表；options_yaml标签由 plugins/options_yaml.rb 实现，复用共享的ConfigurationBlock渲染 YAML 参数表。页面中的操作步骤、测试入口与相关动作区块则来自 source/_includes/actions/ 下的一组 include 文件（ui_header.md、yaml_header.md、try_it.md、stuck.md、related.md）。对于想要为文档贡献类似动作页面的开发者，这是一套可复用的标准模板。

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