ESPHome 2026.11.0-dev
Loading...
Searching...
No Matches
esphome::climate::Climate Class Referenceabstract

ClimateDevice - This is the base class for all climate integrations. More...

#include <climate.h>

Inheritance diagram for esphome::climate::Climate:
esphome::EntityBase esphome::anova::Anova esphome::bang_bang::BangBangClimate esphome::bedjet::BedJetClimate esphome::climate_ir::ClimateIR esphome::demo::DemoClimate esphome::haier::HaierClimateBase esphome::midea::ac::AirConditioner esphome::midea_portasplit::PortaSplitClimate esphome::mitsubishi_cn105::MitsubishiCN105Climate esphome::pid::PIDClimate esphome::template_::TemplateClimate esphome::thermostat::ThermostatClimate esphome::tuya::TuyaClimate esphome::uponor_smatrix::UponorSmatrixClimate esphome::yashima::YashimaClimate

Public Member Functions

 Climate ()
 
template<typename F >
void add_on_state_callback (F &&callback)
 Add a callback for the climate device state, each time the state of the climate device is updated (using publish_state), this callback will be called.
 
template<typename F >
void add_on_control_callback (F &&callback)
 Add a callback for the climate device configuration; each time the configuration parameters of a climate device is updated (using perform() of a ClimateCall), this callback will be called, before any on_state callback.
 
ClimateCall make_call ()
 Make a climate device control call, this is used to control the climate device, see the ClimateCall description for more info.
 
void publish_state ()
 Publish the state of the climate device, to be called from integrations.
 
ClimateTraits get_traits ()
 Get the traits of this climate device with all overrides applied.
 
void set_visual_min_temperature_override (float visual_min_temperature_override)
 
void set_visual_max_temperature_override (float visual_max_temperature_override)
 
void set_visual_temperature_step_override (float target, float current)
 
void set_visual_min_humidity_override (float visual_min_humidity_override)
 
void set_visual_max_humidity_override (float visual_max_humidity_override)
 
void set_supported_custom_fan_modes (std::initializer_list< const char * > modes)
 Set the supported custom fan modes; the list is copied (stored on Climate, referenced by ClimateTraits).
 
void set_supported_custom_fan_modes (const std::vector< const char * > &modes)
 
template<size_t N>
void set_supported_custom_fan_modes (const char *const (&modes)[N])
 
void set_supported_custom_fan_modes_static (const char *const *modes, size_t count)
 Points at a static table that outlives the climate (codegen); call before any runtime copy.
 
void set_supported_custom_presets (std::initializer_list< const char * > presets)
 Set the supported custom presets; the list is copied (stored on Climate, referenced by ClimateTraits).
 
void set_supported_custom_presets (const std::vector< const char * > &presets)
 
template<size_t N>
void set_supported_custom_presets (const char *const (&presets)[N])
 
void set_supported_custom_presets_static (const char *const *presets, size_t count)
 Points at a static table that outlives the climate (codegen); call before any runtime copy.
 
bool has_custom_fan_mode () const
 Check if a custom fan mode is currently active.
 
bool has_custom_preset () const
 Check if a custom preset is currently active.
 
StringRef get_custom_fan_mode () const
 Get the active custom fan mode (read-only access). Returns StringRef.
 
StringRef get_custom_preset () const
 Get the active custom preset (read-only access). Returns StringRef.
 
- Public Member Functions inherited from esphome::EntityBase
 ESPDEPRECATED ("Use get_name_to() or get_log_name() instead. Will be removed in ESPHome 2027.5.0", "2026.11.0") const StringRef &get_name() const
 The name is in flash here; the first call makes a RAM copy that is kept for the life of the device.
 
StringRef get_name_to (std::span< char, ENTITY_NAME_BUF_SIZE > buffer) const
 Get the name of this Entity, copied out of flash into buffer.
 
 ESPDEPRECATED ("Use get_name_to() or get_log_name() instead. Will be removed in ESPHome 2027.5.0", "2026.11.0") const StringRef &get_name() const
 
const StringRef & get_name_to (std::span< char, ENTITY_NAME_BUF_SIZE >) const
 
bool name_equals (const StringRef &other) const
 
const ProgmemStringRef & get_name_progmem () const
 The name as stored, for consumers that read flash themselves (e.g. API progmem fields).
 
size_t write_name_to (char *buf, size_t buf_size) const
 Copy the name into buf (null terminated), returns its length.
 
const LogString * get_log_name () const
 Get the name for a "%s" log argument (LOG_STR_ARG).
 
bool has_own_name () const
 
uint32_t get_object_id_hash () const
 
StringRef get_object_id_to (std::span< char, OBJECT_ID_MAX_LEN > buf) const
 Get object_id with zero heap allocation For static case: returns StringRef to internal storage (buffer unused) For dynamic case: formats into buffer and returns StringRef to buffer.
 
size_t write_object_id_to (char *buf, size_t buf_size) const
 Write object_id directly to buffer, returns length written (excluding null) Useful for building compound strings without intermediate buffer.
 
bool is_internal () const
 
void set_internal (bool internal)
 
bool is_disabled_by_default () const
 
EntityCategory get_entity_category () const
 
const char * get_device_class_to (std::span< char, MAX_DEVICE_CLASS_LENGTH > buffer) const
 
ProgmemStringRef get_device_class_progmem () const
 The device class as stored (in flash on ESP8266), for consumers that read flash themselves.
 
StringRef get_unit_of_measurement_ref () const
 
const char * get_icon_to (std::span< char, MAX_ICON_LENGTH > buffer) const
 
ProgmemStringRef get_icon_progmem () const
 The icon as stored (in flash on ESP8266), for consumers that read flash themselves.
 
uint32_t get_device_id () const
 
Device * get_device () const
 
bool has_state () const
 
void set_has_state (bool state)
 
 ESPDEPRECATED ("Use make_entity_preference<T>() instead, or preferences won't be migrated. " "See https://github.com/esphome/backlog/issues/85. Will be removed in 2027.1.0.", "2026.7.0") uint32_t get_preference_hash()
 Get a unique hash for storing preferences/settings for this entity.
 
template<typename T >
ESPPreferenceObject make_entity_preference (uint32_t version=0)
 Create a preference object for storing this entity's state/settings.
 
template<typename T >
ESPPreferenceObject make_entity_preference (uint32_t version, bool in_flash)
 As make_entity_preference(), stored in flash or RTC memory where the backend supports the choice.
 

Data Fields

float current_temperature {NAN}
 The current temperature of the climate device, as reported from the integration.
 
float current_humidity {NAN}
 The current humidity of the climate device, as reported from the integration.
 
union { 
 
   float   target_temperature 
 The target temperature of the climate device. More...
 
   struct { 
 
      float   target_temperature_low {NAN} 
 The minimum target temperature of the climate device, for climate devices with split target temperature. More...
 
      float   target_temperature_high {NAN} 
 The maximum target temperature of the climate device, for climate devices with split target temperature. More...
 
   }  
 
};  
 
float target_humidity
 The target humidity of the climate device.
 
optional< ClimateFanMode > fan_mode
 The active fan mode of the climate device.
 
optional< ClimatePreset > preset
 The active preset of the climate device.
 
ClimateMode mode {CLIMATE_MODE_OFF}
 The active mode of the climate device.
 
ClimateAction action {CLIMATE_ACTION_OFF}
 The active state of the climate device.
 
ClimateSwingMode swing_mode {CLIMATE_SWING_OFF}
 The active swing mode of the climate device.
 

Protected Member Functions

bool set_fan_mode_ (ClimateFanMode mode)
 Set fan mode. Reset custom fan mode. Return true if fan mode has been changed.
 
bool set_custom_fan_mode_ (const char *mode)
 Set custom fan mode. Reset primary fan mode. Return true if fan mode has been changed.
 
bool set_custom_fan_mode_ (const char *mode, size_t len)
 
bool set_custom_fan_mode_ (StringRef mode)
 
void clear_custom_fan_mode_ ()
 Clear custom fan mode.
 
bool set_preset_ (ClimatePreset preset)
 Set preset. Reset custom preset. Return true if preset has been changed.
 
bool set_custom_preset_ (const char *preset)
 Set custom preset. Reset primary preset. Return true if preset has been changed.
 
bool set_custom_preset_ (const char *preset, size_t len)
 
bool set_custom_preset_ (StringRef preset)
 
void clear_custom_preset_ ()
 Clear custom preset.
 
const char * find_custom_fan_mode_ (const char *custom_fan_mode)
 Find and return the matching custom fan mode pointer from traits, or nullptr if not found.
 
const char * find_custom_fan_mode_ (const char *custom_fan_mode, size_t len)
 
const char * find_custom_preset_ (const char *custom_preset)
 Find and return the matching custom preset pointer from traits, or nullptr if not found.
 
const char * find_custom_preset_ (const char *custom_preset, size_t len)
 
virtual ClimateTraits traits ()=0
 Get the default traits of this climate device.
 
virtual void control (const ClimateCall &call)=0
 Control the climate device, this is a virtual method that each climate integration must implement.
 
optional< ClimateDeviceRestoreState > restore_state_ ()
 Restore the state of the climate device, call this from your setup() method.
 
void save_state_ (const ClimateTraits &traits)
 Internal method to save the state of the climate device to recover memory.
 
void save_state_ ()
 
void dump_traits_ (const char *tag)
 
- Protected Member Functions inherited from esphome::EntityBase
friend void::setup ()
 
friend void::original_setup ()
 
void configure_entity_ (const char *name, uint32_t object_id_hash, uint32_t entity_fields)
 Combined entity setup from codegen: set name, object_id hash, entity string indices, and flags.
 
void set_device_ (Device *device)
 
ESPPreferenceObject make_entity_preference_ (size_t size, uint32_t version)
 Non-template helpers for make_entity_preference() to avoid code bloat.
 
ESPPreferenceObject make_entity_preference_ (size_t size, uint32_t version, bool in_flash)
 
uint32_t entity_preference_key_ (uint32_t version)
 Key for both helpers; preference hash migration goes here.
 

Protected Attributes

friend ClimateCall
 
LazyCallbackManager< void(Climate &)> state_callback_ {}
 
LazyCallbackManager< void(ClimateCall &)> control_callback_ {}
 
ESPPreferenceObject rtc_
 
float visual_min_temperature_override_ {NAN}
 
float visual_max_temperature_override_ {NAN}
 
float visual_target_temperature_step_override_ {NAN}
 
float visual_current_temperature_step_override_ {NAN}
 
float visual_min_humidity_override_ {NAN}
 
float visual_max_humidity_override_ {NAN}
 
- Protected Attributes inherited from esphome::EntityBase
ProgmemStringRef name_
 
uint32_t object_id_hash_ {}
 
Device * device_ {}
 
struct esphome::EntityBase::EntityFlags flags_
 
uint8_t device_class_idx_ {}
 
uint8_t uom_idx_ {}
 
uint8_t icon_idx_ {}
 

Detailed Description

ClimateDevice - This is the base class for all climate integrations.

Each integration needs to extend this class and implement two functions:

  • get_traits() - return the static traits of the climate device
  • control(ClimateDeviceCall call) - Apply the given changes from call.

To write data to the frontend, the integration must first set the properties using this->property = value; (for example this->current_temperature = 42.0;); then the integration must call this->publish_state(); to send the entire state to the frontend.

The entire state of the climate device is encoded in public properties of the base class (current_temperature, mode etc). These are read-only for the user and rw for integrations. The reason these are public is for simple access to them from lambdas if (id(my_climate).mode == climate::CLIMATE_MODE_HEAT_COOL) ...

Definition at line 192 of file climate.h.

Constructor & Destructor Documentation

◆ Climate()

esphome::climate::Climate::Climate ( )
inline

Definition at line 194 of file climate.h.

Member Function Documentation

◆ add_on_control_callback()

template<typename F >
void esphome::climate::Climate::add_on_control_callback ( F && callback)
inline

Add a callback for the climate device configuration; each time the configuration parameters of a climate device is updated (using perform() of a ClimateCall), this callback will be called, before any on_state callback.

Parameters
callbackThe callback to call.

Definition at line 211 of file climate.h.

◆ add_on_state_callback()

template<typename F >
void esphome::climate::Climate::add_on_state_callback ( F && callback)
inline

Add a callback for the climate device state, each time the state of the climate device is updated (using publish_state), this callback will be called.

Parameters
callbackThe callback to call.

Definition at line 201 of file climate.h.

◆ clear_custom_fan_mode_()

void esphome::climate::Climate::clear_custom_fan_mode_ ( )
protected

Clear custom fan mode.

Definition at line 672 of file climate.cpp.

◆ clear_custom_preset_()

void esphome::climate::Climate::clear_custom_preset_ ( )
protected

Clear custom preset.

Definition at line 681 of file climate.cpp.

◆ control()

◆ dump_traits_()

void esphome::climate::Climate::dump_traits_ ( const char * tag)
protected

Definition at line 699 of file climate.cpp.

◆ find_custom_fan_mode_() [1/2]

const char * esphome::climate::Climate::find_custom_fan_mode_ ( const char * custom_fan_mode)
protected

Find and return the matching custom fan mode pointer from traits, or nullptr if not found.

Definition at line 683 of file climate.cpp.

◆ find_custom_fan_mode_() [2/2]

const char * esphome::climate::Climate::find_custom_fan_mode_ ( const char * custom_fan_mode,
size_t len )
protected

Definition at line 687 of file climate.cpp.

◆ find_custom_preset_() [1/2]

const char * esphome::climate::Climate::find_custom_preset_ ( const char * custom_preset)
protected

Find and return the matching custom preset pointer from traits, or nullptr if not found.

Definition at line 691 of file climate.cpp.

◆ find_custom_preset_() [2/2]

const char * esphome::climate::Climate::find_custom_preset_ ( const char * custom_preset,
size_t len )
protected

Definition at line 695 of file climate.cpp.

◆ get_custom_fan_mode()

StringRef esphome::climate::Climate::get_custom_fan_mode ( ) const
inline

Get the active custom fan mode (read-only access). Returns StringRef.

Definition at line 326 of file climate.h.

◆ get_custom_preset()

StringRef esphome::climate::Climate::get_custom_preset ( ) const
inline

Get the active custom preset (read-only access). Returns StringRef.

Definition at line 329 of file climate.h.

◆ get_traits()

ClimateTraits esphome::climate::Climate::get_traits ( )

Get the traits of this climate device with all overrides applied.

Traits are static data that encode the capabilities and static data for a climate device such as supported modes, temperature range etc.

Definition at line 482 of file climate.cpp.

◆ has_custom_fan_mode()

bool esphome::climate::Climate::has_custom_fan_mode ( ) const
inline

Check if a custom fan mode is currently active.

Definition at line 285 of file climate.h.

◆ has_custom_preset()

bool esphome::climate::Climate::has_custom_preset ( ) const
inline

Check if a custom preset is currently active.

Definition at line 288 of file climate.h.

◆ make_call()

ClimateCall esphome::climate::Climate::make_call ( )

Make a climate device control call, this is used to control the climate device, see the ClimateCall description for more info.

Returns
A new ClimateCall instance targeting this climate device.

Definition at line 508 of file climate.cpp.

◆ publish_state()

void esphome::climate::Climate::publish_state ( )

Publish the state of the climate device, to be called from integrations.

This will schedule the climate device to publish its state to all listeners and save the current state to recover memory.

Definition at line 432 of file climate.cpp.

◆ restore_state_()

optional< ClimateDeviceRestoreState > esphome::climate::Climate::restore_state_ ( )
protected

Restore the state of the climate device, call this from your setup() method.

Definition at line 365 of file climate.cpp.

◆ save_state_() [1/2]

void esphome::climate::Climate::save_state_ ( )
inlineprotected

Definition at line 386 of file climate.h.

◆ save_state_() [2/2]

void esphome::climate::Climate::save_state_ ( const ClimateTraits & traits)
protected

Internal method to save the state of the climate device to recover memory.

This is automatically called from publish_state()

Definition at line 373 of file climate.cpp.

◆ set_custom_fan_mode_() [1/3]

bool esphome::climate::Climate::set_custom_fan_mode_ ( const char * mode)
inlineprotected

Set custom fan mode. Reset primary fan mode. Return true if fan mode has been changed.

Definition at line 339 of file climate.h.

◆ set_custom_fan_mode_() [2/3]

bool esphome::climate::Climate::set_custom_fan_mode_ ( const char * mode,
size_t len )
protected

Definition at line 667 of file climate.cpp.

◆ set_custom_fan_mode_() [3/3]

bool esphome::climate::Climate::set_custom_fan_mode_ ( StringRef mode)
inlineprotected

Definition at line 341 of file climate.h.

◆ set_custom_preset_() [1/3]

bool esphome::climate::Climate::set_custom_preset_ ( const char * preset)
inlineprotected

Set custom preset. Reset primary preset. Return true if preset has been changed.

Definition at line 349 of file climate.h.

◆ set_custom_preset_() [2/3]

bool esphome::climate::Climate::set_custom_preset_ ( const char * preset,
size_t len )
protected

Definition at line 676 of file climate.cpp.

◆ set_custom_preset_() [3/3]

bool esphome::climate::Climate::set_custom_preset_ ( StringRef preset)
inlineprotected

Definition at line 351 of file climate.h.

◆ set_fan_mode_()

bool esphome::climate::Climate::set_fan_mode_ ( ClimateFanMode mode)
protected

Set fan mode. Reset custom fan mode. Return true if fan mode has been changed.

Definition at line 663 of file climate.cpp.

◆ set_preset_()

bool esphome::climate::Climate::set_preset_ ( ClimatePreset preset)
protected

Set preset. Reset custom preset. Return true if preset has been changed.

Definition at line 674 of file climate.cpp.

◆ set_supported_custom_fan_modes() [1/3]

template<size_t N>
void esphome::climate::Climate::set_supported_custom_fan_modes ( const char *const (&) modes[N])
inline

Definition at line 261 of file climate.h.

◆ set_supported_custom_fan_modes() [2/3]

void esphome::climate::Climate::set_supported_custom_fan_modes ( const std::vector< const char * > & modes)
inline

Definition at line 258 of file climate.h.

◆ set_supported_custom_fan_modes() [3/3]

void esphome::climate::Climate::set_supported_custom_fan_modes ( std::initializer_list< const char * > modes)
inline

Set the supported custom fan modes; the list is copied (stored on Climate, referenced by ClimateTraits).

Definition at line 255 of file climate.h.

◆ set_supported_custom_fan_modes_static()

void esphome::climate::Climate::set_supported_custom_fan_modes_static ( const char *const * modes,
size_t count )
inline

Points at a static table that outlives the climate (codegen); call before any runtime copy.

Definition at line 265 of file climate.h.

◆ set_supported_custom_presets() [1/3]

template<size_t N>
void esphome::climate::Climate::set_supported_custom_presets ( const char *const (&) presets[N])
inline

Definition at line 276 of file climate.h.

◆ set_supported_custom_presets() [2/3]

void esphome::climate::Climate::set_supported_custom_presets ( const std::vector< const char * > & presets)
inline

Definition at line 273 of file climate.h.

◆ set_supported_custom_presets() [3/3]

void esphome::climate::Climate::set_supported_custom_presets ( std::initializer_list< const char * > presets)
inline

Set the supported custom presets; the list is copied (stored on Climate, referenced by ClimateTraits).

Definition at line 270 of file climate.h.

◆ set_supported_custom_presets_static()

void esphome::climate::Climate::set_supported_custom_presets_static ( const char *const * presets,
size_t count )
inline

Points at a static table that outlives the climate (codegen); call before any runtime copy.

Definition at line 280 of file climate.h.

◆ set_visual_max_humidity_override()

void esphome::climate::Climate::set_visual_max_humidity_override ( float visual_max_humidity_override)
inline

Definition at line 249 of file climate.h.

◆ set_visual_max_temperature_override()

void esphome::climate::Climate::set_visual_max_temperature_override ( float visual_max_temperature_override)
inline

Definition at line 239 of file climate.h.

◆ set_visual_min_humidity_override()

void esphome::climate::Climate::set_visual_min_humidity_override ( float visual_min_humidity_override)
inline

Definition at line 246 of file climate.h.

◆ set_visual_min_temperature_override()

void esphome::climate::Climate::set_visual_min_temperature_override ( float visual_min_temperature_override)
inline

Definition at line 236 of file climate.h.

◆ set_visual_temperature_step_override()

void esphome::climate::Climate::set_visual_temperature_step_override ( float target,
float current )
inline

Definition at line 242 of file climate.h.

◆ traits()

virtual ClimateTraits esphome::climate::Climate::traits ( )
protectedpure virtual

Field Documentation

◆ [union]

◆ action

ClimateAction esphome::climate::Climate::action {CLIMATE_ACTION_OFF}

The active state of the climate device.

Definition at line 320 of file climate.h.

◆ ClimateCall

friend esphome::climate::Climate::ClimateCall
protected

Definition at line 332 of file climate.h.

◆ control_callback_

LazyCallbackManager<void(ClimateCall &)> esphome::climate::Climate::control_callback_ {}
protected

Definition at line 391 of file climate.h.

◆ current_humidity

float esphome::climate::Climate::current_humidity {NAN}

The current humidity of the climate device, as reported from the integration.

Definition at line 294 of file climate.h.

◆ current_temperature

float esphome::climate::Climate::current_temperature {NAN}

The current temperature of the climate device, as reported from the integration.

Definition at line 291 of file climate.h.

◆ fan_mode

optional<ClimateFanMode> esphome::climate::Climate::fan_mode

The active fan mode of the climate device.

Definition at line 311 of file climate.h.

◆ mode

ClimateMode esphome::climate::Climate::mode {CLIMATE_MODE_OFF}

The active mode of the climate device.

Definition at line 317 of file climate.h.

◆ preset

optional<ClimatePreset> esphome::climate::Climate::preset

The active preset of the climate device.

Definition at line 314 of file climate.h.

◆ rtc_

ESPPreferenceObject esphome::climate::Climate::rtc_
protected

Definition at line 392 of file climate.h.

◆ state_callback_

LazyCallbackManager<void(Climate &)> esphome::climate::Climate::state_callback_ {}
protected

Definition at line 390 of file climate.h.

◆ swing_mode

ClimateSwingMode esphome::climate::Climate::swing_mode {CLIMATE_SWING_OFF}

The active swing mode of the climate device.

Definition at line 323 of file climate.h.

◆ target_humidity

float esphome::climate::Climate::target_humidity

The target humidity of the climate device.

Definition at line 308 of file climate.h.

◆ target_temperature

float esphome::climate::Climate::target_temperature

The target temperature of the climate device.

Definition at line 298 of file climate.h.

◆ target_temperature_high

float esphome::climate::Climate::target_temperature_high {NAN}

The maximum target temperature of the climate device, for climate devices with split target temperature.

Definition at line 303 of file climate.h.

◆ target_temperature_low

float esphome::climate::Climate::target_temperature_low {NAN}

The minimum target temperature of the climate device, for climate devices with split target temperature.

Definition at line 301 of file climate.h.

◆ visual_current_temperature_step_override_

float esphome::climate::Climate::visual_current_temperature_step_override_ {NAN}
protected

Definition at line 398 of file climate.h.

◆ visual_max_humidity_override_

float esphome::climate::Climate::visual_max_humidity_override_ {NAN}
protected

Definition at line 400 of file climate.h.

◆ visual_max_temperature_override_

float esphome::climate::Climate::visual_max_temperature_override_ {NAN}
protected

Definition at line 396 of file climate.h.

◆ visual_min_humidity_override_

float esphome::climate::Climate::visual_min_humidity_override_ {NAN}
protected

Definition at line 399 of file climate.h.

◆ visual_min_temperature_override_

float esphome::climate::Climate::visual_min_temperature_override_ {NAN}
protected

Definition at line 395 of file climate.h.

◆ visual_target_temperature_step_override_

float esphome::climate::Climate::visual_target_temperature_step_override_ {NAN}
protected

Definition at line 397 of file climate.h.


The documentation for this class was generated from the following files: