OpenTherm

OpenTherm (OT) 是集中供暖系统中用于中央供暖设备与恒温控制器之间通信的标准通信协议。作为一种标准，OpenTherm 不依赖于任何单一制造商。A 制造商的控制基调原理上可以用来控制 B 制造商的锅炉。

由于 OpenTherm 不是在标准电压范围内工作，因此需要特殊的硬件。你可以从几个现成的适配器中选择，也可以自己制作：

NOTE

此组件仅充当 OpenTherm 主机（例如恒温器或控制器），而不充当从机或网关。当你使用 ESPHome 搭配此组件控制锅炉时，你现有的恒温器将无法使用。

快速术语表

CH: 中央供暖（Central Heating）
DHW: 生活热水（Domestic Hot Water）

Hub

首先，你需要在配置中定义 OpenTherm hub。请注意，大多数 OpenTherm 适配器的 in 和 out 引脚是相对于它们自身标注的；而此组件的 in 和 out 引脚是相对于运行 ESPHome 的微控制器标注的。因此，你的桥接器的 in 引脚成为 hub 的 out 引脚，反之亦然。

opentherm:
  in_pin: GPIOXX
  out_pin: GPIOXX

配置变量

in_pin (必选, number): OpenTherm 硬件桥接器上通常标注为 out 的引脚。
out_pin (必选, number): OpenTherm 硬件桥接器上通常标注为 in 的引脚。
sync_mode (可选, boolean，默认 false): 同步通信模式可防止其他组件在我们与锅炉通信期间禁用中断。如果你遇到大量随机间歇性无效响应错误（在使用 Dallas 温度传感器时很可能发生），请启用此选项。
id (可选, ID): 手动指定用于代码生成的 ID。如果你有多个总线，则此选项为必选。

可选锅炉特定配置

一些锅炉要求恒温器在初始化时发送某些 OpenTherm 消息才能正常工作。你可以在 hub 配置中使用以下设置来让你的特定锅炉满意。

controller_product_type (可选, byte [0-255]，OpenTherm 消息 id 126 高字节): 控制器产品类型。
controller_product_version (可选, byte [0-255]，OpenTherm 消息 id 126 低字节): 控制器产品版本。
opentherm_version_controller (可选, float，OpenTherm 消息 id 124): 控制器实现的 OpenTherm 版本。
controller_configuration (可选, byte [0-255]，OpenTherm 消息 id 2 高字节): 控制器配置。
controller_id (可选, byte [0-255]，OpenTherm 消息 id 2 低字节): 控制器 ID 代码。

自动化

before_send（可选）: 在 OpenTherm 消息发送到锅炉之前对其执行的自动化。
before_process_response（可选）: 在锅炉响应被处理之前对其执行的自动化。

参见即时消息编辑了解详情。

关于同步模式的说明

某些组件的使用（如 Dallas 温度传感器）可能导致 OpenTherm 的帧丢失和协议警告。由于 OpenTherm 在设计上具有弹性，并且会持续循环发送消息，因此这些丢失的帧通常不会引起任何问题。不过，如果你想减少日志中的协议警告数量，可以启用 sync_mode，它会阻塞 ESPHome 的主应用循环，直到与锅炉的一次完整对话完成。这可以大大减少丢帧的数量，但通常不会完全消除它们。启用 sync_mode 后，在某些情况下，ESPHome 的主应用循环可能被阻塞超过推荐的时间，导致日志中出现警告。如果这让你感到困扰，你可以通过向配置中添加以下内容来调整 ESPHome 的日志级别：

logger:
  logs:
    component: ERROR

用作恒温器

恒温器最重要的功能是设置锅炉温度设定点。此组件有三种方式来提供此输入：使用可以从 Home Assistant 传感器读取设定点的方式，使用 Number，或定义一个可供其他组件写入的输出。对大多数用户来说，最后一种选项最有用，因为可以将其与 Pid 组件结合起来创建一个像你所期望的恒温器那样工作的恒温器。参见基本 PID 恒温器了解示例。

数值

有三种方式设置数值：

作为输入传感器，在 hub 配置中定义：

    opentherm:
      t_set: setpoint_sensor

    sensor:
      - platform: homeassistant
        id: setpoint_sensor
        entity_id: sensor.boiler_setpoint

如果你有一个外部类恒温器设备以传感器形式提供设定点，这会很有用。

作为数字：

    number:
      - platform: opentherm
        t_set:
          name: Boiler Setpoint

如果你希望对锅炉进行完全控制，并想手动设置所有值，这会很有用。

作为输出：

    output:
      - platform: opentherm
      t_set:
        id: setpoint

这与 PID 气候组件结合使用时尤其有用：

    climate:
      - platform: pid
        heat_output: setpoint
        # ...

对于输出和数字变体，除了 output 和 number 组件默认包含的选项外，还有四个属性你可以配置：

min_value (float): 最小值。对于数字，这是允许你输入的最小值。对于输出，这是当输出为 0% 时将发送给锅炉的值。
max_value (float): 最大值。对于数字，这是允许你输入的最大值。对于输出，这是当输出为 100% 时将发送给锅炉的值。
auto_max_value (boolean): 自动将最大值配置为锅炉报告的值。并非所有输入都可用。
auto_min_value (boolean): 自动将最小值配置为锅炉报告的值。并非所有输入都可用。

以下数值可用：

t_set ：控制设定点：锅炉供水温度设定点（°C）
- 默认 min_value ：0
- 默认 max_value ：100
- 支持 auto_max_value
t_set_ch2 ：控制设定点 2：第二供暖回路锅炉供水温度设定点（°C）
- 默认 min_value ：0
- 默认 max_value ：100
- 支持 auto_max_value
cooling_control ：冷却控制信号（%）
- 默认 min_value ：0
- 默认 max_value ：100
t_dhw_set ：生活热水温度设定点（°C）
- 默认 min_value ：0
- 默认 max_value ：127
- 支持 auto_min_value
- 支持 auto_max_value
max_t_set ：允许的最大 CH 水设定点（°C）
- 默认 min_value ：0
- 默认 max_value ：127
- 支持 auto_min_value
- 支持 auto_max_value
t_room_set ：当前室温设定点（仅供参考）（°C）
- 默认 min_value ：-40
- 默认 max_value ：127
t_room_set_ch2 ：CH2 当前室温设定点（仅供参考）（°C）
- 默认 min_value ：-40
- 默认 max_value ：127
t_room ：当前感测到的室温（仅供参考）（°C）
- 默认 min_value ：-40
- 默认 max_value ：127
max_rel_mod_level ：最大相对调制水平（%）
- 默认 min_value ：0
- 默认 max_value ：100
- 支持 auto_min_value
otc_hc_ratio ：OTC 热曲线比（°C）
- 默认 min_value ：0
- 默认 max_value ：127
- 支持 auto_min_value
- 支持 auto_max_value

开关

可以使用开关来手动切换以下七个状态码中的任何一个：

ch_enable ：中央供暖已启用
dhw_enable ：生活热水已启用
cooling_enable ：冷却已启用
otc_active ：室外温度补偿已激活
ch2_active ：中央供暖 2 已激活
summer_mode_active ：夏季模式已激活
dhw_block ：阻止 DHW

如果你不希望使用开关，也可以在 hub 配置中永久设置相同的值，如下所示：

opentherm:
  ch_enable: true
  dhw_enable: true

如果你在初始配置后永远不想再切换它，这会很有用。

这些配置变量的默认值如下所列。

要启用中央供暖和冷却，只有在满足以下条件时，标志才会发送给锅炉：

该标志在 hub 配置中设为 true，
开关处于开启状态（如果配置了开关），
设定点或冷却控制值不为 0（如果配置了）。

对于生活热水和室外温度补偿，只需要满足前两个条件。

最后一点确保：如果设定点为 0 而表示没有请求供暖，则不会启用中央供暖。如果你使用数字作为设定点输入，并使用大于 0 的最小值，你必须使用 ch_enable 开关来关闭你的中央供暖。在这种情况下，标志将在 hub 配置中设为 true，并且设定点始终大于 0，因此添加开关是你关闭中央供暖的唯一方法。（这同样适用于冷却和 CH2。）

二进制传感器

该组件可以通过多个二进制传感器报告锅炉状态。状态（Status）传感器在每个消息周期更新，而其他传感器只在初始化期间设置，因为如果不重启锅炉，它们不太可能改变。

fault_indication ：状态：故障指示
ch_active ：状态：中央供暖已激活
dhw_active ：状态：生活热水已激活
flame_on ：状态：火焰已点燃
cooling_active ：状态：冷却已激活
ch2_active ：状态：中央供暖 2 已激活
diagnostic_indication ：状态：诊断事件
electricity_production ：状态：发电
dhw_present ：配置：存在 DHW
control_type_on_off ：配置：控制类型为开/关
cooling_supported ：配置：支持冷却
dhw_storage_tank ：配置：DHW 储水箱
controller_pump_control_allowed ：配置：允许控制器泵控制
ch2_present ：配置：存在 CH2
water_filling ：配置：远程注水
heat_mode ：配置：供暖或冷却
dhw_setpoint_transfer_enabled ：远程锅炉参数：DHW 设定点传输已启用
max_ch_setpoint_transfer_enabled ：远程锅炉参数：CH 最大设定点传输已启用
dhw_setpoint_rw ：远程锅炉参数：DHW 设定点可读写
max_ch_setpoint_rw ：远程锅炉参数：CH 最大设定点可读写
service_request ：需要维护
lockout_reset ：联锁复位
low_water_pressure ：低水压故障
flame_fault ：火焰故障
air_pressure_fault ：气压故障
water_over_temp ：水温过高

传感器

锅炉还可以报告几个数值，这些数值可通过传感器获得。你的锅炉可能不支持所有这些值，在这种情况下，不会有任何值发布到该传感器。以下传感器可用：

rel_mod_level ：相对调制水平（%）
ch_pressure ：CH 回路中的水压（bar）
dhw_flow_rate ：DHW 回路中的水流量（l/min）
t_boiler ：锅炉水温（°C）
t_dhw ：DHW 温度（°C）
t_outside ：室外温度（°C）
t_ret ：回水温度（°C）
t_storage ：太阳能储热罐温度（°C）
t_collector ：太阳能集热器温度（°C）
t_flow_ch2 ：CH2 回路供水温度（°C）
t_dhw2 ：生活热水温度 2（°C）
t_exhaust ：锅炉排气温度（°C）
fan_speed ：锅炉风机转速（RPM）
fan_speed_setpoint ：锅炉风机转速设定点（RPM）
flame_current ：锅炉火焰电流（µA）
burner_starts ：燃烧器启动次数
ch_pump_starts ：CH 泵启动次数
dhw_pump_valve_starts ：DHW 泵/阀门启动次数
dhw_burner_starts ：DHW 模式下燃烧器启动次数
burner_operation_hours ：燃烧器运行小时数
ch_pump_operation_hours ：CH 泵运行小时数
dhw_pump_valve_operation_hours ：DHW 泵运行或 DHW 阀门开启的小时数
dhw_burner_operation_hours ：DHW 模式下燃烧器运行小时数
t_dhw_set_ub ：DHW 设定点调整的上限（°C）
t_dhw_set_lb ：DHW 设定点调整的下限（°C）
max_t_set_ub ：CH 最大设定点调整的上限（°C）
max_t_set_lb ：CH 最大设定点调整的下限（°C）
t_dhw_set ：生活热水温度设定点（°C）
max_t_set ：允许的最大 CH 水设定点（°C）
opentherm_version_device ：设备实现的 OpenTherm 版本
device_type ：设备产品类型
device_version ：设备产品版本
device_id ：设备 ID 代码
otc_hc_ratio_ub ：OTC 热曲线比上限
otc_hc_ratio_lb ：OTC 热曲线比下限

即时消息编辑

有些锅炉使用非标准的消息 ID 和格式。例如，已知 Daikin D2C 锅炉使用消息 ID 162 而不是 56 来设置目标 DHW 温度。为了适应各种非标准行为，我引入了两个自动化，允许编辑底层 OpenTherm 消息：

before_send: 在完整形成的消息发送给锅炉之前触发。当你使用 lambda 时，消息通过引用作为 x 传递。
before_process_response: 当从锅炉收到响应消息且即将处理时触发。当你使用 lambda 时，消息通过引用作为 x 传递。

这允许对任何消息进行任意修改。以下是为 Daikin D2C 锅炉覆盖 DHW 设定点消息 ID 的示例：

opentherm:
    # 常规 hub 配置
    before_send:
        then:
            - lambda: |-
                if (x.id == 56) { // 56 是 DHW 设定点的标准消息 ID
                    x.id = 162;     // 消息通过引用传递，因此我们可以更改任何内容，包括消息 ID
                }
    before_process_response:
        then:
            - lambda: |-
                if (x.id == 162) { // 我们将原始 ID 替换回来，这样 esphome 就不会混淆。
                x.id = 56;
                }

你可以查看 API 参考：OpenthermData 了解所有可用字段的列表。

示例

带数字输入的最小示例

# 一个极其简约的配置，仅允许你将锅炉的
# 水温设定点设置为一个数字。

opentherm:
  in_pin: GPIOXX
  out_pin: GPIOXX
  ch_enable: true

number:
  - platform: opentherm
    t_set:
      name: "Boiler Control setpoint"

基本 PID 恒温器

# 一个用于具有单个中央供暖回路和
# 生活热水的锅炉的基本恒温器。它报告火焰、CH 和 DHW 状态，类似于
# 你在恒温器上期望看到的内容，并报告内部锅炉
# 温度和当前调制水平。温度通过 PID 气候控制器调节，
# 当前室温从 Home Assistant 的传感器获取。

# 此配置应满足大多数需求，如果你只想要一个带有
# 外部温度传感器的恒温器，这是推荐的起点。

opentherm:
  in_pin: GPIOXX
  out_pin: GPIOXX
  dhw_enable: true    # 请注意，当我们在 hub 配置中以静态值指定输入时，如果不重新上传新固件，
                      # 就无法更改它。如果你希望能够打开或关闭某些功能，
                      # 请使用开关（参见下面的 ch_enable 开关）。
                      # 还要注意，当我们以开关（或其他平台）定义输入时，我们不需要
                      # 在 hub 级别设置它。

output:
  - platform: opentherm
    t_set:
      id: t_set
      min_value: 20
      max_value: 65
      zero_means_zero: true

sensor:
  - platform: opentherm
    rel_mod_level:
      name: "Boiler Relative modulation level"
    t_boiler:
      name: "Boiler water temperature"
    t_ret:
      name: "Boiler Return water temperature"

  - platform: homeassistant
    id: ch_room_temperature
    entity_id: sensor.temperature
    filters:
      # 每秒推送一次室温以更新 PID 参数
      - heartbeat: 1s

binary_sensor:
  - platform: opentherm
    ch_active:
      name: "Boiler Central Heating active"
    dhw_active:
      name: "Boiler Domestic Hot Water active"
    flame_on:
      name: "Boiler Flame on"
    fault_indication:
      name: "Boiler Fault indication"
      entity_category: diagnostic
    diagnostic_indication:
      name: "Boiler Diagnostic event"
      entity_category: diagnostic

switch:
  - platform: opentherm
    ch_enable:
      name: "Boiler Central Heating enabled"
      restore_mode: RESTORE_DEFAULT_ON

climate:
  - platform: pid
    name: "Central heating"
    heat_output: t_set
    default_target_temperature: 20
    sensor: ch_room_temperature
    control_parameters:
      kp: 0.4
      ki: 0.004

另请参阅

使用 ESPHome 和 Home Assistant 的 OpenTherm 恒温器 — 此组件的真实世界用例。
开发仓库 — 新功能将在此处测试，然后再提交给 ESPHome 核心。
API 参考：API Reference: OpenthermHub
API 参考：API Reference: OpenthermInput
API 参考：API Reference: OpenthermNumber
API 参考：API Reference: OpenthermOutput
API 参考：API Reference: OpenthermSwitch