恒温器气候控制器

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 动作：ESPHome 应用根据请求执行的任务，例如 打开开关。请参见 Action。

• 气候动作：气候设备当前正在主动执行的操作

• 气候模式：气候设备应该（或不应该）执行的操作

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

就气候控制而言，理解”action”与”mode”两个术语之间微妙的区别很重要， 因为它们并不是同一个东西：

示例：

• 加热模式：气候设备可以加热，但不可以冷却。
• 加热动作：气候设备正在主动向室内输送热空气。

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

配置变量

恒温器控制器使用传感器来决定应该加热还是冷却。

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

加热与冷却动作

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

• idle_action (必填，Action)：当气候设备应进入 空闲状态（既不冷却也不加热）时调用的动作。

• heat_action (可选，Action)：当气候设备应进入加热模式 以提高当前温度时调用的动作。

• supplemental_heating_action (可选，Action)：当气候设备应激活辅助加热 以（更积极地）提高当前温度时调用的动作。此动作将以 max_heating_run_time 定义的间隔反复调用（见下文）。

• cool_action (可选，Action)：当气候设备应进入冷却模式 以降低当前温度时调用的动作。

• supplemental_cooling_action (可选，Action)：当气候设备应激活辅助冷却 以（更积极地）降低当前温度时调用的动作。此动作将以 max_cooling_run_time 定义的间隔反复调用（见下文）。

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

• fan_only_action (可选，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 (可选，Action)：当 气候设备被置于加热模式（可以按需加热，但不能冷却）时调用的动作。

• cool_mode (可选，Action)：当 气候设备被置于冷却模式（可以按需冷却，但不能加热）时调用的动作。

• dry_mode (可选，Action)：当 气候设备被置于干燥模式（用于除湿）时调用的动作。

• fan_only_mode (可选，Action)：当 气候设备被置于仅风扇模式（不能加热或冷却，但会根据情况立即激活其风扇， 或者当 fan_only_cooling 为 true 时根据较高目标温度值按需激活风扇）时调用的动作。

• heat_cool_mode (可选，Action 或 布尔值)：当 气候设备被置于”加热/冷却”模式（可以按需加热和冷却）时调用的动作。如果不需要动作， 可以设为 true 以在不关联自动化的情况下启用该模式。注意必须同时定义 heat_action 和 cool_action（见上文）才能启用此模式。

• auto_mode (可选，Action)：当 气候设备被置于”自动”模式（可以按需加热和冷却）时调用的动作。此模式 不同于 heat_cool_mode（上文），它接管了设定点的控制权，不再由用户设定； 通常仅供自动化脚本使用。

• off_mode (可选，Action)：当 气候设备被置于”关闭”模式（完全禁用）时调用的动作。

以上动作不应用于启动冷却或加热设备！ 请参见上一节来了解相关配置。

风扇模式动作

这些在气候控制风扇模式更改时被触发。它们是 ESPHome 动作。 如果可用，这些应被用于仅控制风扇。

• fan_mode_auto_action (可选，Action)：当风扇 应被设置为”自动”模式（风扇由气候控制系统按需控制）时调用的动作。

• fan_mode_on_action (可选，Action)：当风扇 应持续运行时调用的动作。

• fan_mode_off_action (可选，Action)：当风扇 不应运行时调用的动作。

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

• fan_mode_medium_action (可选，Action)：当风扇 应以中档速度运行时调用的动作。

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

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

• fan_mode_focus_action (可选，Action)：当风扇 应将气流集中导向特定区域时调用的动作。

• fan_mode_diffuse_action (可选，Action)：当风扇 应将气流扩散到较大区域时调用的动作。

• fan_mode_quiet_action (可选，Action)：当风扇 应以安静速度运行时调用的动作。

摆动模式动作

这些在气候控制摆动模式更改时被触发。它们是 ESPHome 动作。 如果可用，这些应被用于仅控制风扇。

• swing_off_action (可选，Action)：当风扇应 保持在固定位置时调用的动作。

• swing_horizontal_action (可选，Action)：当风扇 应沿水平方向摆动时调用的动作。

• swing_vertical_action (可选，Action)：当风扇 应沿垂直方向摆动时调用的动作。

• swing_both_action (可选，Action)：当风扇 应沿水平和垂直两个方向摆动时调用的动作。

湿度控制动作

这些在恒温器控制器更改湿度控制动作时被触发。它可以触发动作 以启动加湿或除湿。

• humidity_control_dehumidify_action (可选，Action)：需要 除湿时调用的动作。

• humidity_control_humidify_action (可选，Action)：需要 加湿时调用的动作。

• humidity_control_off_action (可选，Action)：需要 停止加湿/除湿时调用的动作。当配置了上述任一动作时，此动作为必填。

高级配置/行为

设定点选项/行为

• set_point_minimum_differential (可选，浮点数)：对于双点/双功能系统，加热和冷却设定点之间的最低 要求温度差。默认为 0.5 °C。

• supplemental_cooling_delta (配合 supplemental_cooling_action 使用必填，浮点数)：当较高设定点与当前温度之间的差值 超过此值时， supplemental_cooling_action 将立即被调用。

• supplemental_heating_delta (配合 supplemental_heating_action 使用必填，浮点数)：当较低设定点与当前温度之间的差值 超过此值时， supplemental_heating_action 将立即被调用。

预设

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

• preset：(可选，列表)

  • name (必填，字符串)：预设的名称。如果该名称是标准预设之一（eco、away、 boost、comfort、home、sleep 或 activity），则被视为标准预设。任何其他 字符串将使该预设成为自定义预设。标准预设与自定义预设在功能上等效， 唯一区别是：通过 climate.control 动作 切换模式时 需要根据情况使用 preset 或 custom_preset 属性。Home Assistant 的 climate.set_preset_mode 服务对二者处理方式完全相同。

  • default_target_temperature_low (可选，浮点数)：切换到此预设时的默认较低目标温度

  • default_target_temperature_high (可选，浮点数)：切换到此预设时的默认较高目标温度。

  • 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：(可选，Action)：预设更改时调用的动作。当用户通过 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 (可选，字符串)：默认使用的预设名称。必须与预设 名称匹配（如 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 (可选，Action)：当 恒温器的目标湿度更改时调用的动作。

• target_temperature_change_action (可选，Action)：当 恒温器的目标温度更改时调用的动作。

• startup_delay (可选，布尔值)：如果设为 true，ESPHome 启动时，min_cooling_off_time、 min_fanning_off_time 和 min_heating_off_time 必须分别经过之后，相应动作才能被调用。 此选项提供了一种方式来防止设备损坏（例如），防止因断电而中断的设备再次立即运行。 默认为 false。

• fan_only_action_uses_fan_mode_timer (可选，布尔值)：如果设为 true，fan_only_action 将 与所有 fan_mode 动作共用同一个延迟计时器。此时风扇的最小切换延迟由 min_fan_mode_switching_time 决定 （见下文）。当 fan_only_action 与 fan_mode 动作控制的是同一物理风扇时（在强制送风 HVAC 系统中很常见），此选项非常有用。

• fan_only_cooling (可选，布尔值)：如果设为 true，处于 fan_only_mode 气候模式时， fan_only_action 仅在观测温度超过较高设定点加 cool_deadband 时才被调用。设为 false（默认值）时，激活 fan_only_mode 时会立即调用 fan_only_action，无论当前温度和设定点如何。默认为 false。

• fan_with_cooling (可选，布尔值)：如果设为 true，每当调用 cool_action 时也会调用 fan_only_action。这对于强制送风系统（风扇通常与冷却一起运行）很有用。 默认为 false。

• fan_with_heating (可选，布尔值)：如果设为 true，每当调用 heat_action 时也会调用 fan_only_action。这对于强制送风系统（风扇通常与加热一起运行）很有用。 默认为 false。

• max_cooling_run_time (配合 supplemental_cooling_action 使用必填，Time)：冷却激活后经过此 时长将调用 supplemental_cooling_action。注意 supplemental_cooling_action 也将以本参数定义的间隔反复调用， 从而实现多级辅助（备用/应急）冷却。

• max_heating_run_time (配合 supplemental_heating_action 使用必填，Time)：加热激活后经过此 时长将调用 supplemental_heating_action。注意 supplemental_heating_action 也将以本参数定义的间隔反复调用， 从而实现多级辅助（备用/应急）加热。

• min_cooling_off_time (配合 cool_action 使用必填，Time)：冷却动作 必须停止的最小时长，之后才能重新启动。

• min_cooling_run_time (配合 cool_action 使用必填，Time)：冷却动作 必须运行的最小时长，之后才能停止。

• min_fanning_off_time (配合 fan_only_action 使用必填，Time)：送风 动作必须停止的最小时长，之后才能重新启动。

• min_fanning_run_time (配合 fan_only_action 使用必填，Time)：送风 动作必须运行的最小时长，之后才能停止。

• min_heating_off_time (配合 heat_action 使用必填，Time)：加热动作 必须停止的最小时长，之后才能重新启动。

• min_heating_run_time (配合 heat_action 使用必填，Time)：加热动作 必须运行的最小时长，之后才能停止。

• min_idle_time (必填，Time)：空闲动作必须处于激活状态的最小时长，之后才能调用 另一个气候动作。

• min_fan_mode_switching_time (使用任何 fan_mode 动作时必填，Time)： 任一风扇模式必须处于激活状态的最小时长，之后才能切换。

注意来自基础气候组件的 min_temperature 和 max_temperature 用于在恒温器组件中定义 允许的温度值范围。请参见 Climate。

滞后值

• cool_deadband (可选，浮点数)：调用冷却动作之前的最低温度差值（高于设定点的温度）。 默认为 0.5 °C。

• cool_overrun (可选，浮点数)：调用空闲动作之前的最低温度差值（冷却超过设定点）。 默认为 0.5 °C。

• heat_deadband (可选，浮点数)：调用加热动作之前的最低温度差值（低于设定点的温度）。 默认为 0.5 °C。

• heat_overrun (可选，浮点数)：调用空闲动作之前的最低温度差值（加热超过设定点）。 默认为 0.5 °C。

• humidity_hysteresis (可选，浮点数)：调用相应湿度控制动作之前允许的最大湿度差值（高于/低于设定点）。默认为 1%。

NOTE

• 虽然此平台在所有地方都使用”温度”这一术语，但它也可以用于调节其他值。 例如，此平台也可以用于控制湿度。

• 来自基础气候组件的 min_temperature 和 max_temperature 用于定义可调节范围， 对于控制湿度等场景，默认值可能并不适用。请参见 Climate。

Bang-Bang 与恒温器对比

请参见 Bang-Bang 组件的文档，了解这两个组件的详细对比。

另请参见

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