Water Heater Component

The water_heater component is a generic representation of water heaters (boilers) in ESPHome. A water heater handles a target temperature setpoint and an operation mode (like Eco, Electric, or Performance).

ℹ️ Note
To use a water heater in Home Assistant requires Home Assistant 2024.5 or later.

Base Water Heater Configuration

All water heater config schemas inherit from this schema - you can set these keys for water heaters.

water_heater:
  - platform: ...
    min_temperature: 10 °C
    max_temperature: 80 °C

Configuration variables:

id (Optional, string): Manually specify the ID for code generation. At least one of id and name must be specified.
name (Optional, string): The name for the water heater. At least one of id and name must be specified.

ℹ️ Note
If you have a friendly_name set for your device and you want the water heater to use that name, you can set name: None.

min_temperature (Optional, float): The minimum temperature that can be set. Defaults to 10°C (varies by platform).
max_temperature (Optional, float): The maximum temperature that can be set. Defaults to 80°C (varies by platform).
target_temperature (Optional, float): The initial target temperature to set on boot.
icon (Optional, icon): Manually set the icon to use for the water heater in the frontend.

Advanced options:

visual (Optional): Configuration for the frontend representation.
- min_temperature (Optional, float): Override the minimum temperature shown in the frontend.
- max_temperature (Optional, float): Override the maximum temperature shown in the frontend.
internal (Optional, boolean): Mark this component as internal. Internal components will not be exposed to the frontend (like Home Assistant). Only specifying an id without a name will implicitly set this to true.
disabled_by_default (Optional, boolean): If true, this entity should not be added to any client’s frontend, (usually Home Assistant) without the user manually enabling it (via the Home Assistant UI). Defaults to false.
entity_category (Optional, string): The category of the entity. See https://developers.home-assistant.io/docs/core/entity/#generic-properties for a list of available options. Set to "" to remove the default entity category.
If Webserver enabled and version 3 is selected, All other options from Webserver Component.. See Webserver Version 3.

MQTT options:

mode_command_topic (Optional, string): The topic to receive mode commands on.
mode_state_topic (Optional, string): The topic to publish mode state changes to.
target_temperature_command_topic (Optional, string): The topic to receive target temperature commands on.
target_temperature_state_topic (Optional, string): The topic to publish target temperature state changes to.
All other options from MQTT Component.

`water_heater.control` Action

This action allows you to set the operation mode and/or target temperature of the water heater.

on_...:
  then:
    - water_heater.control:
        id: boiler_1
        mode: ECO
        target_temperature: 55.0

Configuration variables:

id (Required, ID): The water heater to control.
mode (Optional, string): The operation mode to set. See Modes for available options.
target_temperature (Optional, float): The target temperature to set (e.g., 60.0).

ℹ️ Note

This action can also be expressed in lambdas:

auto call = id(boiler_1).make_call();
call.set_mode("PERFORMANCE");
call.set_target_temperature(65.0);
call.perform();

Water Heater Modes

The following modes are available for water heaters. Note that not all platforms support all modes.

OFF
ECO
ELECTRIC
PERFORMANCE
HIGH_DEMAND
HEAT_PUMP
GAS

Lambdas

From lambdas, you can access the current state of the water heater.

current_temperature : Retrieve the current measured temperature of the water (float).

    if (id(my_boiler).current_temperature < 40.0) {
      // Water is cold
    }

target_temperature : Retrieve the target setpoint temperature (float).
mode : Retrieve the current operation mode.

    if (id(my_boiler).mode == water_heater::WATER_HEATER_MODE_ECO) {
      // Boiler is in ECO mode
    } else if (id(my_boiler).mode == water_heater::WATER_HEATER_MODE_PERFORMANCE) {
      // Boiler is in PERFORMANCE mode
    }

Available C++ enums for modes:

water_heater::WATER_HEATER_MODE_OFF
water_heater::WATER_HEATER_MODE_ECO
water_heater::WATER_HEATER_MODE_ELECTRIC
water_heater::WATER_HEATER_MODE_PERFORMANCE
water_heater::WATER_HEATER_MODE_HIGH_DEMAND
water_heater::WATER_HEATER_MODE_HEAT_PUMP
water_heater::WATER_HEATER_MODE_GAS