Home ▸ Integrations

Water heater

The Water heater integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] lets you monitor and control supported hot water heaters in Home Assistant. You can use it to check whether a water heater is on or off, adjust the target temperature, change the operation mode, and build automations around those changes.

To enable this integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more], pick one of the platforms, and add it to your configuration.yamlThe configuration.yaml file is the main configuration file for Home Assistant. It lists the integrations to be loaded and their specific configurations. In some cases, the configuration needs to be edited manually directly in the configuration.yaml file. Most integrations can be configured in the UI. [Learn more]:

# Example configuration.yaml entry
water_heater:
  platform: demo

Warning

Misconfiguring Water Heater automations may allow water temperatures to drop into ranges between 25°C to 45°C (77°F and 113°F) which allows for Legionella bacteria growth. This can pose serious health risks, including death from Legionnaires’ disease. Maintain water temperature ≥ 60°C (140°F) for bacterial safety.

The state of a water heater entity

A water heater entity state reflects the current operation of the device. Common states include:

On: The water heater is on.
Off: The water heater is off.
Eco: Energy efficient mode, provides energy savings and fast heating.
Electric: Electric only mode. This mode uses the most energy.
Performance: High performance mode.
High demand: Meet high demands when the water heater is undersized.
Heat pump: Heat pump is the slowest to heat, but it uses less energy.
Gas: Gas only mode. This mode uses the most energy.

The exact states depend on the platform and the water heater model.

In addition, the entity can have the following states:

Unavailable: The entity is currently unavailable.
Unknown: The state is not yet known.

List of triggers

The Water heater integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following triggers. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.

Water heater operation mode changed (water_heater.operation_mode_changed) Triggers after the operation mode of one or more water heaters changes to a specific mode.
Water heater target temperature changed (water_heater.target_temperature_changed) Triggers after the temperature setpoint of one or more water heaters changes.
Water heater target temperature crossed threshold (water_heater.target_temperature_crossed_threshold) Triggers after the temperature setpoint of one or more water heaters crosses a threshold.
Water heater turned off (water_heater.turned_off) Triggers after one or more water heaters turn off.
Water heater turned on (water_heater.turned_on) Triggers after one or more water heaters turn on, regardless of the operation mode.

For an overview of every trigger across all integrations, see the triggers reference.

List of conditions

The Water heater integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] provides the following conditions. Each link below opens a dedicated page with examples, fields, and a step-by-step UI walkthrough.

Water heater is off (water_heater.is_off) Tests if one or more water heaters are off.
Water heater is on (water_heater.is_on) Tests if one or more water heaters are on.
Water heater operation mode (water_heater.is_operation_mode) Tests if one or more water heaters are set to a specific operation mode.
Water heater target temperature (water_heater.is_target_temperature) Tests the temperature setpoint of one or more water heaters.

For an overview of every condition across all integrations, see the conditions reference.

Actions

Water heater control actions

Available actions: water_heater.set_temperature, water_heater.set_operation_mode, water_heater.set_away_mode, water_heater.turn_on, water_heater.turn_off

Tip

Not all water heater actions may be available for your platform. Be sure to check the available actions Home Assistant has enabled by checking Settings > Developer tools > Actions.

Action: Set temperature

The water_heater.set_temperature action sets the target temperature of the water heater device.

Data attribute	Optional	Description
`target`	yes	A target selector for the water heater device or devices to control. You can target entities, devices, areas, floors, or labels.
`temperature`	no	New target temperature for water heater
`operation_mode`	yes	Operation mode to use while setting the target temperature. For a list of possible modes, refer to the integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] documentation.

Automation example

automation:
  triggers:
    - trigger: time
      at: "07:15:00"
  actions:
    - action: water_heater.set_temperature
      target:
        entity_id: water_heater.demo
      data:
        temperature: 24
        operation_mode: eco

Action: Set operation mode

The water_heater.set_operation_mode action sets the operation mode for the water heater device.

Data attribute	Optional	Description
`target`	yes	A target selector for the water heater device or devices to control. You can target entities, devices, areas, floors, or labels.
`operation_mode`	no	New value of operation mode. For a list of possible modes, refer to the integration documentation.

Automation example

automation:
  triggers:
    - trigger: time
      at: "07:15:00"
  actions:
    - action: water_heater.set_operation_mode
      target:
        entity_id: water_heater.demo
      data:
        operation_mode: eco

Action: Set away mode

The water_heater.set_away_mode action turns away mode on or off for the water heater device.

Data attribute	Optional	Description
`target`	yes	A target selector for the water heater device or devices to control. You can target entities, devices, areas, floors, or labels.
`away_mode`	no	New value of away mode. Use `true` to enable away mode or `false` to disable it.

Automation example

automation:
  triggers:
    - trigger: time
      at: "07:15:00"
  actions:
    - action: water_heater.set_away_mode
      target:
        entity_id: water_heater.demo
      data:
        away_mode: true

Action: Turn on

The water_heater.turn_on action turns the water heater device on.

Data attribute	Optional	Description
`target`	yes	A target selector for the water heater device or devices to control. You can target entities, devices, areas, floors, or labels.

Action: Turn off

The water_heater.turn_off action turns the water heater device off.

Data attribute	Optional	Description
`target`	yes	A target selector for the water heater device or devices to control. You can target entities, devices, areas, floors, or labels.

Water heater automation examples

You can use water heater triggers and conditions in automations to keep hot water ready when you need it, while still using less energy the rest of the day.

Tip

You don’t need to edit YAML to use these examples. Copy a YAML snippet from this page, open the automation editor in Home Assistant, and press Ctrl+V (or Cmd+V on Mac). Home Assistant automatically converts the pasted YAML into the visual editor format, whether it’s a full automation, a single trigger, a condition, or an action.

Automation: lower the recirculation pump when the water heater enters Eco mode

When the water heater changes to Eco mode, lower the recirculation pump speed to match the lower-demand schedule.

Trigger: Water heater operation mode changed
- Target: Utility room water heater
- Operation mode: Eco
Action: Turn on switch

YAML example for lowering the recirculation pump in Eco mode

Automation

alias: "Lower recirculation pump in Eco mode"
triggers:
  - trigger: water_heater.operation_mode_changed
    target:
      entity_id: water_heater.utility_room
    options:
      operation_mode: eco
actions:
  - action: switch.turn_on
    target:
      entity_id: switch.recirculation_pump_low_speed

Automation: enable away mode only when the target temperature is already low

When everybody leaves home, enable away mode only if the target temperature is already below your normal daytime setting.

Trigger: State: Person changes to not_home
Condition: Water heater target temperature
- Target: Utility room water heater
- Threshold type: Below (50°C)
Action: Set water heater away mode

YAML example for enabling away mode from a lower setpoint

Automation

alias: "Enable away mode when the setpoint is already low"
triggers:
  - trigger: state
    entity_id: person.alex
    to: "not_home"
conditions:
  - condition: water_heater.is_target_temperature
    target:
      entity_id: water_heater.utility_room
    options:
      threshold:
        type: below
        value:
          number: 50
          unit_of_measurement: "°C"
actions:
  - action: water_heater.set_away_mode
    target:
      entity_id: water_heater.utility_room
    data:
      away_mode: true

Help us improve our documentation

Suggest an edit to this page, or provide/view feedback for this page.