跳转到内容
ESPHome - 智能家居，简单易用

OpenTherm

OpenTherm（OT）是一种用于中央供暖系统的标准通信协议，用于中央供暖设备与恒温控制器之间的通信。作为标准，OpenTherm 独立于任何单一制造商。原则上，来自制造商 A 的控制器可用于控制来自制造商 B 的锅炉。

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

DIYLESS Master OpenTherm Shield。

NOTE

此组件仅作为 OpenTherm 主机（例如，恒温器或控制器），而不是从机或网关。当您使用 ESPHome 和此组件控制锅炉时，您现有的恒温器将不可用。

快速术语表

Section titled “快速术语表”
  • CH: 中央供暖（Central Heating）
  • DHW: 生活热水（Domestic Hot Water）

集线器

Section titled “集线器”

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

opentherm:
  in_pin: GPIOXX
  out_pin: GPIOXX

配置变量

Section titled “配置变量”

  • in_pin (必需, 数字): OpenTherm 硬件桥接的引脚，通常在板上标记为 out。

  • out_pin (必需, 数字): OpenTherm 硬件桥接的引脚，通常在板上标记为 in。

  • sync_mode (可选, 布尔值, 默认 false): 同步通信模式防止其他组件在我们与锅炉通信时禁用中断。如果您遇到大量随机间歇性无效响应错误，请启用此选项（在使用 Dallas 温度传感器时很可能会发生）。

  • id (可选, ID): 手动指定用于代码生成的 ID。如果您有多个总线，则必需。

可选锅炉特定配置

Section titled “可选锅炉特定配置”

某些锅炉需要恒温器在初始化时发送特定的 OpenTherm 消息才能正常工作。您可以在集线器配置中使用以下设置使您的特定锅炉正常工作。

  • controller_product_type (可选, 字节 [0-255], OpenTherm 消息 id 126 高字节): 控制器产品类型

  • controller_product_version (可选, 字节 [0-255], OpenTherm 消息 id 126 低字节): 控制器产品版本

  • opentherm_version_controller (可选, 浮点数, OpenTherm 消息 id 124): 控制器实现的 OpenTherm 版本

  • controller_configuration (可选, 字节 [0-255], OpenTherm 消息 id 2 高字节): 控制器配置

  • controller_id (可选, 字节 [0-255], OpenTherm 消息 id 2 低字节): 控制器 ID 代码

自动化

Section titled “自动化”
  • before_send (可选) 在 OpenTherm 消息发送到锅炉之前执行的自动化。
  • before_process_response (可选) 在处理来自锅炉的响应消息之前执行的自动化。

有关详细信息，请参阅实时消息编辑。

关于同步模式的说明

Section titled “关于同步模式的说明”

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

logger:
  logs:
    component: ERROR

作为恒温器使用

Section titled “作为恒温器使用”

恒温器最重要的功能是设置锅炉温度设定点。此组件有三种方式提供此输入：使用可以读取设定点的 Home Assistant 传感器，使用 Number，或定义其他组件可以写入的输出。对于大多数用户，最后一个选项是最有用的，因为它可以与 Pid 组件结合使用，创建一个按预期工作的恒温器。有关示例，请参阅基本 PID 恒温器。

数值

Section titled “数值”

有三种设置数值的方式：

  • 作为输入传感器，定义在集线器配置中：
    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 组件结合使用特别有用：

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

对于输出和数值变体，除了输出和数值组件默认包含的属性外，您还可以配置另外四个属性：

  • min_value（浮点数）：最小值。对于数值，这是允许输入的最小值。对于输出，这是当输出为 0% 时将发送到锅炉的数值。

  • max_value（浮点数）：最大值。对于数值，这是允许输入的最大值。对于输出，这是当输出为 100% 时将发送到锅炉的数值。

  • auto_max_value（布尔值）：自动将最大值配置为锅炉报告的值。并非所有输入都可用。

  • auto_min_value（布尔值）：自动将最小值配置为锅炉报告的值。并非所有输入都可用。

以下数值可用：

  • 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

开关

Section titled “开关”

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

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

如果您不想要开关，可以在集线器配置中永久设置相同的值，如下所示：

opentherm:
  ch_enable: true
  dhw_enable: true

这在您在初始配置后不想切换的情况下很有用。

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

要启用中央供暖和冷却，标志仅在满足以下条件时发送到锅炉：

  • 标志在集线器配置中设置为 true，
  • 开关处于开启状态（如果已配置），
  • 设定点或冷却控制值不为 0（如果已配置）

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

最后一点确保如果没有请求加热（如设定点为 0 所示），则不会启用中央供暖。如果您使用数值作为设定点输入并使用高于 0 的最小值，您必须使用 ch_enable 开关来关闭中央供暖。在这种情况下，标志将在集线器配置中设置为 true，设定点始终大于 0，因此包含开关是关闭中央供暖的唯一方式。（这也适用于冷却和 CH2。）

二进制传感器

Section titled “二进制传感器”

组件可以在多个二进制传感器上报告锅炉状态。状态传感器在每个消息周期中更新，而其他传感器仅在初始化期间设置，因为它们不太可能在不重启锅炉的情况下更改。

  • 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 : 水过热

传感器

Section titled “传感器”

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

  • 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 热曲线比率下限

实时消息编辑

Section titled “实时消息编辑”

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

  • before_send: 在完全形成的消息发送到锅炉之前触发。当您使用 lambda 时，消息通过引用作为 x 传递。

  • before_process_response: 当从锅炉接收到响应消息并即将处理时触发。当您使用 lambda 时，消息通过引用作为 x 传递。

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

opentherm:
    # 常规集线器配置
    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 Reference: OpenthermData 以获取所有可用字段的列表。

示例

Section titled “示例”

带数值输入的最小示例

Section titled “带数值输入的最小示例”
# 一个极其简单的配置，仅允许您将锅炉的
# 水温设定点设置为数值。


opentherm:
  in_pin: GPIOXX
  out_pin: GPIOXX
  ch_enable: true


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

基本 PID 恒温器

Section titled “基本 PID 恒温器”
# 一个用于具有单个中央供暖回路和生活热水的锅炉的基本恒温器。
# 它报告火焰、CH 和 DHW 状态，类似于您在恒温器上看到的，
# 还报告锅炉内部温度和当前调制级别。温度通过 PID Climate 控制器调节，
# 当前室温从 Home Assistant 中的传感器获取。


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


opentherm:
  in_pin: GPIOXX
  out_pin: GPIOXX
  dhw_enable: true    # 请注意，当我们在集线器配置中使用静态值指定输入时，无法
                      # 在不上传新固件的情况下更改它。如果您想能够打开或关闭某些东西，
                      # 请使用开关（参见下面的 ch_enable 开关）。
                      # 另请注意，当我们将输入定义为开关（或使用其他平台）时，不需要
                      # 在集线器级别设置它。


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

另请参阅

Section titled “另请参阅”