Template Water Heater

The template water heater platform allows you to create simple water heaters out of just a few actions and lambdas. Once defined, it will automatically appear in Home Assistant as a water heater entity and can be controlled through the frontend.

# Example configuration entry
water_heater:
  - platform: template
    name: "Template Boiler"
    id: my_boiler

    # Lambda to read the current temperature (e.g. from a sensor)
    current_temperature: !lambda 'return id(my_sensor).state;'

    # Lambda to read the target temperature (optional)
    target_temperature: !lambda 'return id(my_target_temp_sensor).state;'

    # Lambda to read the current operation mode (optional)
    mode: !lambda 'return water_heater::WATER_HEATER_MODE_ECO;'

    # Lambda to read the away mode state (optional)
    away: !lambda "return id(vacation_mode).state;"

    # Lambda to read the current On/Off state (optional)
    is_on: !lambda 'return id(my_relay).state;'

    optimistic: true

    # List of modes to show in the UI (optional)
    supported_modes:
      - "OFF"
      - ECO
      - GAS

    visual:
      min_temperature: 10.0
      max_temperature: 85.0
      target_temperature_step: 0.5

    set_action:
      - lambda: |-
          ESP_LOGI("boiler", "New mode: %d", id(my_boiler).get_mode());
          ESP_LOGI("boiler", "New target temperature: %.1f", id(my_boiler).get_target_temperature());
          ESP_LOGI("boiler", "On: %s, Away: %s", YESNO(id(my_boiler).is_on()), YESNO(id(my_boiler).is_away()));

Possible return values for the lambdas:

current_temperature: Returns a float (e.g. 42.5).
target_temperature: Returns a float (e.g. 60.0).
mode: Returns a WaterHeaterMode enum (e.g. water_heater::WATER_HEATER_MODE_ECO).
away: Returns a bool (e.g. false).
is_on: Returns a bool (e.g. true).

Configuration variables

current_temperature (Optional, lambda): Lambda to be evaluated repeatedly to get the current temperature of the water. Expects a float return value.
target_temperature (Optional, lambda): Lambda to be evaluated repeatedly to get the target temperature of the water. Expects a float return value.
mode (Optional, lambda): Lambda to be evaluated repeatedly to get the current operation mode. Expects a WaterHeaterMode enum return value.
away (Optional, lambda): Lambda to be evaluated repeatedly to get the current away mode state. Expects a boolean return value.
is_on (Optional, lambda): Lambda to be evaluated repeatedly to get the current On/Off state. Expects a boolean return value.
optimistic (Optional, boolean): Whether to operate in optimistic mode - when in this mode, any command sent to the template water heater will immediately update the reported state. Defaults to true.
set_action (Optional, Action): The action to perform when the water heater receives a command (mode change, target temperature change, away, on/off, etc.). This is where you implement the actual control logic for your water heater.
supported_modes (Optional, list): Static list of operation modes that will be exposed to the frontend (for example Home Assistant). This controls the operation_list reported to Home Assistant and affects only the UI and available service calls. It does not change runtime behavior or control logic. When not specified, all supported water heater modes are shown by default.
ℹ️ Note
The list of supported_modes is static and evaluated at startup. It cannot be changed dynamically and does not support templates or lambdas.
restore_mode (Optional, enum): Control how the water heater attempts to restore state on bootup.
- NO_RESTORE (Default): Do not save or restore state.
- RESTORE : Attempts to restore the state (target temp & mode) on startup, but doesn’t perform the set_action.
- RESTORE_AND_CALL : Attempts to restore the state on startup and immediately executes the set_action.
All other options from Water Heater.

`water_heater.template.publish` Action

You can also publish state to a template water heater from elsewhere in your YAML file with the water_heater.template.publish action.

# Example action
- water_heater.template.publish:
    id: my_boiler
    current_temperature: 55.0
    target_temperature: 60.0
    mode: ECO
    away: false
    is_on: true

Configuration options:

id (Required, ID): The ID of the template water heater.
current_temperature (Optional, templatable, float): The current measured temperature to publish.
target_temperature (Optional, templatable, float): The target setpoint temperature to publish.
mode (Optional, templatable, string): The operation mode to publish. See Water Heater Modes for options.
away (Optional, templatable, boolean): The away mode state to publish.
is_on (Optional, templatable, boolean): The boolean On/Off state to publish.

ℹ️ Note
This action can also be written in lambdas:
id(my_boiler).set_current_temperature(55.0);
id(my_boiler).publish_state();

Template Water Heater

Template Water Heater

Configuration variables

water_heater.template.publish Action

See Also

Template Water Heater

`water_heater.template.publish` Action