温控器控制器

thermostat 温控平台允许您以与物理温控器非常相似的方式控制温控系统。其操作类似于 Bang-Bang 控制器；传感器测量一个值（空气温度），控制器将尝试使此值保持在由设定点定义的范围内。为此，控制器可以激活如加热单元和/或制冷单元等设备来改变传感器观测到的值。当配置为既可加热又可制冷时，它本质上是两个 Bang-Bang 控制器合二为一；然而，它的不同之处在于与温控器组件的交互几乎与真正的温控器相同。

此组件可以以两种方式之一运行：

• 单点模式：定义单个阈值（设定点）；当观测温度超过设定点时可以激活制冷，或者当观测温度低于设定点时可以激活加热；也就是说，控制器只能升高温度或降低温度。在此模式下不能同时做这两件事。

• 双点模式：定义两个阈值（设定点）；当观测温度超过较高设定点时激活制冷，而当观测温度低于较低设定点时激活加热；换句话说，控制器可以根据需要同时升高和降低温度。

此组件/控制器根据配置的动作自动确定应该以哪种模式运行——稍后详细介绍。两个参数定义设定点；它们是 target_temperature_low 和 target_temperature_high。然而，在单点模式下，只使用其中一个。设定点可以通过前端用户界面调整。下面的截图展示了一个双点模式下的温控器控制器，其中有两个设定点可用。

双设定点温控界面

此组件通过根据需要触发多个动作来工作，以使观测温度保持在由设定点定义的目标范围之上/之下/之内。一般来说，当观测温度低于 target_temperature_low 时，控制器将触发 heat_action 激活加热。当观测温度超过 target_temperature_high 时，控制器将触发 cool_action 或 fan_only_action（由温控模式确定）激活制冷。当温度达到所需范围内的某一点时，控制器将触发 idle_action 停止加热/制冷。请参阅下一节了解更多详情。

Home Assistant 中的温控/温控器界面内置了多种风扇控制模式；此组件也可以配置为根据 Home Assistant 提供的整个范围（在编写本文档时）的风扇模式触发动作。

# 双点模式示例配置条目
climate:
  - platform: thermostat
    name: "Thermostat Climate Controller"
    sensor: my_temperature_sensor
    min_cooling_off_time: 300s
    min_cooling_run_time: 300s
    min_heating_off_time: 300s
    min_heating_run_time: 300s
    min_idle_time: 30s
    cool_action:
      - switch.turn_on: air_cond
    heat_action:
      - switch.turn_on: heater
    idle_action:
      - switch.turn_off: air_cond
      - switch.turn_off: heater
    default_preset: Home
    preset:
      - name: Home
        default_target_temperature_low: 20 °C
        default_target_temperature_high: 22 °C

# 单点模式示例配置条目（仅加热）
climate:
  - platform: thermostat
    name: "Thermostat Climate Controller"
    sensor: my_temperature_sensor
    min_heating_off_time: 300s
    min_heating_run_time: 300s
    min_idle_time: 30s
    heat_action:
      - switch.turn_on: heater
    idle_action:
      - switch.turn_off: heater
    default_preset: Home
    preset:
      - name: Home
        default_target_temperature_low: 20 °C

# 单点模式示例配置条目（仅制冷）
climate:
  - platform: thermostat
    name: "Thermostat Climate Controller"
    sensor: my_temperature_sensor
    min_cooling_off_time: 300s
    min_cooling_run_time: 300s
    min_idle_time: 30s
    cool_action:
      - switch.turn_on: air_cond
    idle_action:
      - switch.turn_off: air_cond
    default_preset: Home
    preset:
      - name: Home
        default_target_temperature_high: 22 °C

控制器行为和滞回

除了设定点外，滞回值决定温度可以从设定点值变化多远才会触发动作（制冷、加热等）。它们各自默认为 0.5 °C。它们是：

• cool_deadband：启动制冷前的最小温度差（高于设定点的温度）
• cool_overrun：停止制冷前的最小温度差（制冷超过设定点）
• heat_deadband：启动加热前的最小温度差（低于设定点的温度）
• heat_overrun：停止加热前的最小温度差（加热超过设定点）

关于此组件经常出现的一个问题是，“预期的行为是什么？“让我们快速讨论配置的动作确切何时被控制器调用。

考虑一下较低设定点（通常激活加热的那个），假设它设置为常见的室温 22 °C。让我们假设 heat_deadband 设置为 0.4 °C，而 heat_overrun 设置为 0.6 °C。在这种情况下，控制器将允许温度下降到设定点的值（22 °C）减去 heat_deadband 值（0.4 °C），即 21.6 °C，然后调用 heat_action 激活加热。

加热激活后，它将保持活动状态，直到观测温度达到设定点（22 °C）加上 heat_overrun 值（0.6 °C），即 22.6 °C。一旦达到此温度，将调用 idle_action 停用加热。

相同的行为适用于较高设定点，尽管行为在某种意义上是相反的；给定较高设定点 23 °C，cool_deadband 设置为 0.3 °C，cool_overrun 设置为 0.7 °C，cool_action 将在 23.3 °C 时被调用，而 idle_action 直到温度降低到 22.3 °C 才会被调用。

重要术语

在我们进入更多配置细节之前，让我们退一步谈谈”action”这个词；我们需要在接下来的部分仔细考虑这个词的上下文，因为它有双重含义，否则会导致一些歧义。

• ESPHome Action（动作）：ESPHome 应用程序按要求执行的任务，例如打开开关。请参阅 Action。

• Climate Action（温控动作）：温控设备正在主动做什么

• Climate Mode（温控模式）：温控设备应该（或不应该）做什么

我们将在下面描述时指出我们指的是哪种定义的”action”——请仔细阅读！

关于温控控制，理解”action”和”mode”这两个术语之间的微妙区别很重要，因为它们不是同一回事：

示例：

• Heat Mode（加热模式）：温控设备可以加热但不能制冷。
• Heat Action（加热动作）：温控设备正在主动将加热的空气分配到房间中。

都明白了吗？很好。让我们仔细看看一些配置。

配置变量

温控器控制器使用传感器来确定是否应该加热或制冷。

• sensor (必填, ID): 用于测量当前温度的传感器。
• humidity_sensor (可选, ID): 如果指定，此传感器用于测量当前湿度。这可用于湿度控制；请参阅 湿度控制动作。

加热和制冷动作

当温控控制器更改温控控制动作时触发这些。这里，“action”具有上述两种含义，因为它们既是温控动作也是 ESPHome 动作。这些应用于激活加热、制冷等设备。

• idle_action (必填, 动作): 当温控设备应进入空闲状态（不制冷、不加热）时调用的动作。

• heat_action (可选, 动作): 当温控设备应进入加热模式以增加当前温度时调用的动作。

• supplemental_heating_action (可选, 动作): 当温控设备应激活辅助加热以（更积极地）增加当前温度时调用的动作。此动作会按 max_heating_run_time 定义的间隔重复调用（见下文）。

• cool_action (可选, 动作): 当温控设备应进入制冷模式以降低当前温度时调用的动作。

• supplemental_cooling_action (可选, 动作): 当温控设备应激活辅助制冷以（更积极地）降低当前温度时调用的动作。此动作会按 max_cooling_run_time 定义的间隔重复调用（见下文）。

• dry_action (可选, 动作): 当温控设备应执行其干燥（除湿）动作时调用的动作。温控控制器不触发此动作；它由 dry_mode 调用（见下文）。

• fan_only_action (可选, 动作): 当温控设备应仅激活其风扇（但不加热或制冷）时调用的动作。当 fan_only_cooling 设置为 false 时，设置为 fan_only_mode 时温控控制器立即触发此动作；然而，当 fan_only_cooling 设置为 true 时，此动作根据较高目标温度调用（类似于上面的 cool_action）。

• Climate 的所有其他选项。

cool_action、fan_only_action、heat_action 和 dry_action 中至少必须指定一个。

如果只指定了 cool_action、fan_only_action、heat_action 和 dry_action 中的一个，控制器将配置为以单点模式运行，因此 Home Assistant 将为设备显示单点温控用户界面。

加热和制冷模式

当温控控制模式更改时触发这些。注意参数名称中没有”action”——这些仍然是 ESPHome 动作，但它们不是温控动作。相反，它们是温控模式。这些动作很有用，例如可以用于打开和/或关闭一组 LED 以提供当前温控模式的视觉指示。

• heat_mode (可选, 动作): 当温控设备进入加热模式时调用的动作（可以根据需要加热，但不能制冷）。

• cool_mode (可选, 动作): 当温控设备进入制冷模式时调用的动作（可以根据需要制冷，但不能加热）。

• dry_mode (可选, 动作): 当温控设备进入干燥模式时调用的动作（用于除湿）。

• fan_only_mode (可选, 动作): 当温控设备进入仅风扇模式时调用的动作（不能加热或制冷，但会立即激活其风扇，或者当 fan_only_cooling 为 true 时根据较高目标温度值需要时激活）。

• heat_cool_mode (可选, 动作 或 boolean): 当温控设备进入”加热/制冷”模式时调用的动作（可以根据需要制冷和加热）。如果不需要动作，可以设置为 true 以启用模式而不需要相关自动化。请注意，必须定义 heat_action 和 cool_action（见上文）才能启用此模式。

• auto_mode (可选, 动作): 当温控设备进入”自动”模式时调用的动作（可以根据需要制冷和加热）。此模式与 heat_cool_mode（上文）的不同之处在于它从用户手中夺走设定点的控制权；通常专供自动化使用。

• off_mode (可选, 动作): 当温控设备进入”关闭”模式时调用的动作（完全禁用）。

上述动作不应用于激活制冷或加热设备！ 请参阅上一节了解那些动作。

风扇模式动作

当温控控制风扇模式更改时触发这些。这些是 ESPHome 动作。这些应用于仅控制风扇（如果可用）。

• fan_mode_auto_action (可选, 动作): 当风扇应设置为”自动”模式时调用的动作（风扇根据需要由温控系统控制）。

• fan_mode_on_action (可选, 动作): 当风扇应连续运行时调用的动作。

• fan_mode_off_action (可选, 动作): 当风扇应永不运行时调用的动作。

• fan_mode_low_action (可选, 动作): 当风扇应以最低速度运行时调用的动作。

• fan_mode_medium_action (可选, 动作): 当风扇应以中等速度运行时调用的动作。

• fan_mode_high_action (可选, 动作): 当风扇应以最高速度运行时调用的动作。

• fan_mode_middle_action (可选, 动作): 当风扇应将其气流导向中间区域时调用的动作。

• fan_mode_focus_action (可选, 动作): 当风扇应将其气流导向特定区域时调用的动作。

• fan_mode_diffuse_action (可选, 动作): 当风扇应将其气流导向广泛区域时调用的动作。

• fan_mode_quiet_action (可选, 动作): 当风扇应以静音速度运行时调用的动作。

摆风模式动作

当温控控制摆风模式更改时触发这些。这些是 ESPHome 动作。这些应用于仅控制风扇（如果可用）。

• swing_off_action (可选, 动作): 当风扇应保持静止位置时调用的动作。

• swing_horizontal_action (可选, 动作): 当风扇应水平摆动时调用的动作。

• swing_vertical_action (可选, 动作): 当风扇应垂直摆动时调用的动作。

• swing_both_action (可选, 动作): 当风扇应水平和垂直摆动时调用的动作。

湿度控制动作

当温控控制器更改湿度控制动作时触发这些。它可以触发动作以激活加湿或除湿。

• humidity_control_dehumidify_action (可选, 动作): 当需要除湿时调用的动作。

• humidity_control_humidify_action (可选, 动作): 当需要加湿时调用的动作。

• humidity_control_off_action (可选, 动作): 当（除）加湿应停止时调用的动作。当配置了上述任一动作时，此动作是必需的。

高级配置/行为

设定点选项/行为

• set_point_minimum_differential (可选, float): 对于双点/双功能系统，加热和制冷设定点之间所需的最小温度差。默认为 0.5 °C。

• supplemental_cooling_delta (有 supplemental_cooling_action 时必填, float): 当较高设定点与当前温度之间的温度差超过此值时，将立即调用 supplemental_cooling_action。

• supplemental_heating_delta (有 supplemental_heating_action 时必填, float): 当较低设定点与当前温度之间的温度差超过此值时，将立即调用 supplemental_heating_action。

预设模式

预设模式允许您定义一组设定点、温控模式、风扇模式和摆风模式的组合，可以从前端（Home Assistant）作为单个操作快速轻松地调用。这可以简化用户体验和自动化。

• preset: (可选, list)

  • name (必填, string): 预设的名称。如果这是标准预设之一（eco、away、boost、comfort、home、sleep 或 activity），则被视为标准预设。任何其他字符串将使预设成为自定义预设。标准和自定义预设功能等效，唯一的区别是通过 climate.control 动作切换模式时，需要使用 preset 或 custom_preset 属性。Home Assistant climate.set_preset_mode 服务将它们视为相同

  • default_target_temperature_low (可选, float): 切换到此预设时的默认较低目标温度

  • default_target_temperature_high (可选, float): 切换到此预设时的默认较高目标温度。

  • mode (可选, 温控模式): 激活此预设时温控器应切换到的模式。如果未指定，激活预设时温控器的模式将保持不变。可选：

    • heat_cool
    • cool
    • heat
    • dry
    • fan_only
    • auto

  • fan_mode (可选, 温控风扇模式): 激活此预设时温控器应切换到的风扇模式。如果未指定，激活预设时温控器的风扇模式将保持不变。可选：

    • on
    • off
    • auto
    • low
    • medium
    • high
    • middle
    • focus
    • diffuse
    • quiet

  • swing_mode (可选, 温控摆风模式): 激活此预设时温控器应切换到的风扇摆风模式。如果未指定，激活预设时温控器的风扇摆风模式将保持不变。可选：

    • off
    • both
    • horizontal
    • vertical

# 带预设的温控器示例
climate:
  - platform: thermostat
    name: "Thermostat with Presets"
    preset:
      # 标准预设
      - name: sleep
        default_target_temperature_low: 17
        default_target_temperature_high: 26
        fan_mode: LOW
        swing_mode: OFF
      # 自定义预设
      - name: A custom preset
        default_target_temperature_low: 21
        default_target_temperature_high: 23
        fan_mode: HIGH
        mode: HEAT_COOL

• preset_change: (可选, 动作): 当预设更改时调用的动作。这将在用户通过 Home Assistant UI 更改模式或通过调用 climate.control 时被调用

# 带预设和更改动作的温控器示例
climate:
  - platform: thermostat
    name: "Thermostat with Presets Actions"
    preset:
      - name: sleep
        default_target_temperature_low: 17
        default_target_temperature_high: 26
        fan_mode: LOW
        swing_mode: OFF
    preset_change:
      - logger.log: Preset has been changed!

默认预设

这些配置项确定温控控制器启动时应使用的默认值。

• default_preset (可选, string): 默认使用的预设名称。必须与 preset 中的预设匹配。

• on_boot_restore_from: (可选, on_boot_restore_from): 控制温控器首次启动时的行为。可选：

  • memory（默认）：温控器将恢复上次运行时的任何设置。
  • default_preset：温控器将始终切换到由 default_preset 指定的预设

NOTE

您可以指定 default_preset 并将 on_boot_restore_from 设置为 memory。在此模式下，当由于任何原因无法检索上次启动的设置时，将应用指定的 default_preset。

# 此温控控制器首次启动时将切换到"My Startup Preset"。随后的启动将恢复到重启前的模式
climate:
  - platform: thermostat
    name: "From Memory Thermostat"
    default_preset: My Startup Preset
    on_boot_restore_from: memory
    preset:
      - name: My Startup Preset
        default_target_temperature_low: 17
        default_target_temperature_high: 26
        fan_mode: OFF
        swing_mode: OFF
        mode: OFF
      # 自定义预设
      - name: A custom preset
        default_target_temperature_low: 21
        default_target_temperature_high: 23
        fan_mode: HIGH
        mode: HEAT_COOL

# 此温控控制器将始终切换到"Every Start Preset"
climate:
  - platform: thermostat
    name: "Default Preset Thermostat"
    default_preset: Every Start Preset
    on_boot_restore_from: default_preset
    preset:
      - name: Every Start Preset
        default_target_temperature_low: 17
        default_target_temperature_high: 26
        fan_mode: OFF
        swing_mode: OFF
        mode: OFF
      # 自定义预设
      - name: A custom preset
        default_target_temperature_low: 21
        default_target_temperature_high: 23
        fan_mode: HIGH
        mode: HEAT_COOL

其他动作/行为

• target_humidity_change_action (可选, 动作): 当温控器的目标湿度更改时调用的动作。

• target_temperature_change_action (可选, 动作): 当温控器的目标温度更改时调用的动作。

• startup_delay (可选, boolean): 如果设置为 true，当 ESPHome 启动时，必须经过 min_cooling_off_time、min_fanning_off_time 和 min_heating_off_time 后才能调用各自的动作。此选项提供了一种防止因电源中断而损坏设备的方法。默认为 false。

• fan_only_action_uses_fan_mode_timer (可选, boolean): 如果设置为 true，fan_only_action 将与所有 fan_mode 动作使用的延迟计时器共享相同的最小风扇切换延迟。当 fan_only_action 控制与 fan_mode 动作相同的物理风扇时很有用，常见于强制送风 HVAC 系统。

• fan_only_cooling (可选, boolean): 如果设置为 true，在 fan_only_mode 温控模式下，只有当观测温度超过较高设定点加上 cool_deadband 时才会调用 fan_only_action。设置为 false（默认）时，激活 fan_only_mode 时立即调用 fan_only_action，无论当前温度或设定点如何。默认为 false。

• fan_with_cooling (可选, boolean): 如果设置为 true，每当调用 cool_action 时都会调用 fan_only_action。这对于风扇通常与制冷一起运行的强制送风系统很有用。默认为 false。

• fan_with_heating (可选, boolean): 如果设置为 true，每当调用 heat_action 时都会调用 fan_only_action。这对于风扇通常与加热一起运行的强制送风系统很有用。默认为 false。

• max_cooling_run_time (有 supplemental_cooling_action 时必填, 时间): 制冷活动时经过此持续时间后调用 supplemental_cooling_action。请注意，supplemental_cooling_action 也会按此参数定义的间隔重复调用，从而启用多级辅助（紧急）制冷。

• max_heating_run_time (有 supplemental_heating_action 时必填, 时间): 加热活动时经过此持续时间后调用 supplemental_heating_action。请注意，supplemental_heating_action 也会按此参数定义的间隔重复调用，从而启用多级辅助（紧急）加热。

• min_cooling_off_time (有 cool_action 时必填, 时间): 制冷动作必须停用后才能启用的最小持续时间。

• min_cooling_run_time (有 cool_action 时必填, 时间): 制冷动作必须启用后才能停用的最小持续时间。

• min_fanning_off_time (有 fan_only_action 时必填, 时间): 风扇动作必须停用后才能启用的最小持续时间。

• min_fanning_run_time (有 fan_only_action 时必填, 时间): 风扇动作必须启用后才能停用的最小持续时间。

• min_heating_off_time (有 heat_action 时必填, 时间): 加热动作必须停用后才能启用的最小持续时间。

• min_heating_run_time (有 heat_action 时必填, 时间): 加热动作必须启用后才能停用的最小持续时间。

• min_idle_time (必填, 时间): 空闲动作必须活动后才能调用另一个温控动作的最小持续时间。

• min_fan_mode_switching_time (有任何 fan_mode 动作时必填, 时间): 任何给定风扇模式必须活动后才能更改的最小持续时间。

请注意，基础温控组件中的 min_temperature 和 max_temperature 用于定义温控器组件中允许的温度值范围。请参阅 Climate。

滞回值

• cool_deadband (可选, float): 调用制冷动作前的最小温度差（高于设定点的温度）。默认为 0.5 °C。

• cool_overrun (可选, float): 调用空闲动作前的最小温度差（制冷超过设定点）。默认为 0.5 °C。

• heat_deadband (可选, float): 调用加热动作前的最小温度差（低于设定点的温度）。默认为 0.5 °C。

• heat_overrun (可选, float): 调用空闲动作前的最小温度差（加热超过设定点）。默认为 0.5 °C。

• humidity_hysteresis (可选, float): 调用各自湿度控制动作前的最大湿度差（高于/低于设定点）。默认为 1%。

NOTE

• 虽然此平台在各处都使用温度一词，但它也可以用于调节其他值。例如，使用此平台控制湿度也是可能的。

• 基础温控组件中的 min_temperature 和 max_temperature 用于定义可调节范围，默认值对于湿度等控制可能没有意义。请参阅 Climate。

Bang-Bang 与温控器对比

请参阅 Bang-Bang 组件的文档以获取这两个组件的详细比较。

另见

• Climate 组件
• 传感器组件
• Bang-Bang
• 所有动作