Template Climate

The template climate platform lets you create a climate entity backed by lambda expressions and automation actions. It is useful for wrapping custom UART/I²C climate controllers, integrating hardware that lacks a dedicated ESPHome component, or prototyping climate integrations.

Read lambdas (current_temperature, mode, target_temperature, etc.) are polled each loop() iteration to populate the entity with the device’s current state. Set actions (set_mode_action, set_target_temperature_action, etc.) are fired when the frontend or an automation sends a command to the device.

Once defined, the entity will automatically appear in Home Assistant and can be controlled through the frontend.

Simple example

A minimal setup with no read lambdas. The entity state is updated immediately when set actions fire (optimistic: true, the default).

climate:
  - platform: template
    name: "Living Room Climate"
    supported_modes:
      - "OFF"
      - HEAT
      - COOL
    set_mode_action:
      - logger.log:
          format: "Mode: %d"
          args: ["(int) x"]
    set_target_temperature_action:
      - logger.log:
          format: "Target temperature: %.1f"
          args: ["x"]
    visual:
      min_temperature: 16.0
      max_temperature: 30.0
      temperature_step: 0.5

External device example

A full example showing both read lambdas and set actions. The read lambdas poll the device state each loop; the set actions send new settings to the device. In a real scenario the actions would write over UART or I²C. The globals here simulate that external device.

globals:
  - id: ext_mode
    type: int
    initial_value: "0"   # CLIMATE_MODE_OFF
  - id: ext_target_temp
    type: float
    initial_value: "21.0"
  - id: ext_fan_mode
    type: int
    initial_value: "2"   # CLIMATE_FAN_AUTO
  - id: ext_swing_mode
    type: int
    initial_value: "0"   # CLIMATE_SWING_OFF
  - id: ext_preset
    type: int
    initial_value: "5"   # CLIMATE_PRESET_ECO

climate:
  - platform: template
    name: "External Heatpump"
    current_temperature: !lambda "return id(temp_sensor).state;"
    target_temperature: !lambda "return id(ext_target_temp);"
    mode: !lambda "return static_cast<climate::ClimateMode>(id(ext_mode));"
    fan_mode: !lambda "return static_cast<climate::ClimateFanMode>(id(ext_fan_mode));"
    swing_mode: !lambda "return static_cast<climate::ClimateSwingMode>(id(ext_swing_mode));"
    preset: !lambda "return static_cast<climate::ClimatePreset>(id(ext_preset));"
    optimistic: true
    supported_modes:
      - "OFF"
      - HEAT
      - COOL
      - FAN_ONLY
    supported_fan_modes:
      - AUTO
      - LOW
      - HIGH
    supported_swing_modes:
      - "OFF"
      - VERTICAL
    supported_presets:
      - NONE
      - ECO
      - AWAY
    set_mode_action:
      - lambda: "id(ext_mode) = (int) x;"
    set_target_temperature_action:
      - lambda: "id(ext_target_temp) = x;"
    set_fan_mode_action:
      - lambda: "id(ext_fan_mode) = (int) x;"
    set_swing_mode_action:
      - lambda: "id(ext_swing_mode) = (int) x;"
    set_preset_action:
      - lambda: "id(ext_preset) = (int) x;"
    visual:
      min_temperature: 16.0
      max_temperature: 30.0
      temperature_step: 0.5

Configuration variables

current_temperature (Optional, lambda): Lambda evaluated on every loop to get the measured (ambient) temperature. Return a float value, or {} to leave the current temperature unchanged.
target_temperature (Optional, lambda): Lambda evaluated on every loop to read the target (setpoint) temperature from the device. Return a float value, or {} to leave the target temperature unchanged.
mode (Optional, lambda): Lambda evaluated on every loop to read the current operating mode from the device. Return a ClimateMode value (e.g. climate::CLIMATE_MODE_HEAT), or {} to leave the mode unchanged.
fan_mode (Optional, lambda): Lambda evaluated on every loop to read the current fan mode from the device. Return a ClimateFanMode value (e.g. climate::CLIMATE_FAN_AUTO), or {} to leave the fan mode unchanged.
swing_mode (Optional, lambda): Lambda evaluated on every loop to read the current swing mode from the device. Return a ClimateSwingMode value (e.g. climate::CLIMATE_SWING_OFF), or {} to leave the swing mode unchanged.
preset (Optional, lambda): Lambda evaluated on every loop to read the current preset from the device. Return a ClimatePreset value (e.g. climate::CLIMATE_PRESET_ECO), or {} to leave the preset unchanged.
optimistic (Optional, boolean): Controls whether the entity state is updated immediately after a set action fires (true, default) or only after the next read-lambda poll reflects the device’s actual state (false).
- true (default): Entity state updates immediately after a set action so the UI shows the new value right away. If the device does not accept the command, the read lambdas will correct it on the next loop.
- false: Entity state does not update after a set action. The UI only updates when the read lambdas detect a change in the device state.
When no read lambdas are configured, entity state always updates immediately (there is nothing polling the device).
supported_modes (Optional, list): List of operating modes to expose to the frontend. Valid values: OFF, HEAT, COOL, AUTO, HEAT_COOL, FAN_ONLY, DRY.

NOTE

supported_modes is evaluated at compile time. It cannot be changed at runtime.
supported_fan_modes (Optional, list): List of fan modes to expose to the frontend. Valid values: ON, OFF, AUTO, LOW, MEDIUM, HIGH, MIDDLE, FOCUS, DIFFUSE, QUIET.
supported_swing_modes (Optional, list): List of swing modes to expose to the frontend. Valid values: OFF, BOTH, VERTICAL, HORIZONTAL.
supported_presets (Optional, list): List of presets to expose to the frontend. Valid values: NONE, ECO, AWAY, BOOST, COMFORT, HOME, SLEEP, ACTIVITY.
set_mode_action (Optional, Action): Action executed when a mode command is received. The requested mode is available as x of type ClimateMode.
set_target_temperature_action (Optional, Action): Action executed when a target temperature command is received. The requested temperature is available as x of type float.
set_fan_mode_action (Optional, Action): Action executed when a fan mode command is received. The requested fan mode is available as x of type ClimateFanMode.
set_swing_mode_action (Optional, Action): Action executed when a swing mode command is received. The requested swing mode is available as x of type ClimateSwingMode.
set_preset_action (Optional, Action): Action executed when a preset command is received. The requested preset is available as x of type ClimatePreset.
All other options from Climate.

NOTE

Climate state (mode, target temperature, fan mode, swing mode, and preset) is automatically persisted to flash and restored on reboot via the standard ESPHome climate restore mechanism.

Template Climate

Simple example

External device example

Configuration variables

See Also