ESPHome 2026.11.0-dev
Loading...
Searching...
No Matches
esphome::fan::Fan Class Referenceabstract

#include <fan.h>

Inheritance diagram for esphome::fan::Fan:
esphome::EntityBase esphome::bedjet::BedJetFan esphome::binary::BinaryFan esphome::copy::CopyFan esphome::demo::DemoFan esphome::ecocomfort2::Ecocomfort2Fan esphome::hbridge::HBridgeFan esphome::speed::SpeedFan esphome::template_::TemplateFan esphome::tuya::TuyaFan

Public Member Functions

FanCall turn_on ()
 
FanCall turn_off ()
 
FanCall toggle ()
 
FanCall make_call ()
 
template<typename F >
void add_on_state_callback (F &&callback)
 Register a callback that will be called each time the state changes.
 
void publish_state ()
 
virtual FanTraits get_traits ()=0
 
void set_supported_preset_modes (std::initializer_list< const char * > preset_modes)
 Set the supported preset modes; the list is copied (stored on Fan, referenced by FanTraits).
 
void set_supported_preset_modes (const std::vector< const char * > &preset_modes)
 
void set_supported_preset_modes (const FanPresetModes &preset_modes)
 
void set_supported_preset_modes_static (const char *const *preset_modes, size_t count)
 Points at a static table that outlives the fan (codegen); call before any runtime copy.
 
void set_restore_mode (FanRestoreMode restore_mode)
 Set the restore mode of this fan.
 
StringRef get_preset_mode () const
 Get the current preset mode.
 
bool has_preset_mode () const
 Check if a preset mode is currently active.
 
- 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

bool state {false}
 The current on/off state of the fan.
 
bool oscillating {false}
 The current oscillation state of the fan.
 
int speed {0}
 The current fan speed level.
 
FanDirection direction {FanDirection::FORWARD}
 The current direction of the fan.
 

Protected Member Functions

virtual void control (const FanCall &call)=0
 
optional< FanRestoreState > restore_state_ ()
 
void save_state_ ()
 
void dump_traits_ (const char *tag, const char *prefix)
 
bool set_preset_mode_ (const char *preset_mode, size_t len)
 Set the preset mode (finds and stores pointer from traits).
 
bool set_preset_mode_ (const char *preset_mode)
 
bool set_preset_mode_ (const std::string &preset_mode)
 
bool set_preset_mode_ (StringRef preset_mode)
 
void clear_preset_mode_ ()
 Clear the preset mode.
 
void apply_preset_mode_ (const FanCall &call)
 Apply preset mode from a FanCall (handles speed-clears-preset convention)
 
const char * find_preset_mode_ (const char *preset_mode)
 Find and return the matching preset mode pointer from traits, or nullptr if not found.
 
const char * find_preset_mode_ (const char *preset_mode, size_t len)
 
void wire_preset_modes_ (FanTraits &traits)
 Wire the Fan-owned preset modes pointer into the given traits object.
 
- 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 FanCall
 
LazyCallbackManager< void()> state_callback_ {}
 
ESPPreferenceObject rtc_
 
FanRestoreMode restore_mode_ {FanRestoreMode::NO_RESTORE}
 
- 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

Definition at line 108 of file fan.h.

Member Function Documentation

◆ add_on_state_callback()

template<typename F >
void esphome::fan::Fan::add_on_state_callback ( F && callback)
inline

Register a callback that will be called each time the state changes.

Definition at line 125 of file fan.h.

◆ apply_preset_mode_()

void esphome::fan::Fan::apply_preset_mode_ ( const FanCall & call)
protected

Apply preset mode from a FanCall (handles speed-clears-preset convention)

Definition at line 196 of file fan.cpp.

◆ clear_preset_mode_()

void esphome::fan::Fan::clear_preset_mode_ ( )
protected

Clear the preset mode.

Definition at line 194 of file fan.cpp.

◆ control()

◆ dump_traits_()

void esphome::fan::Fan::dump_traits_ ( const char * tag,
const char * prefix )
protected

Definition at line 292 of file fan.cpp.

◆ find_preset_mode_() [1/2]

const char * esphome::fan::Fan::find_preset_mode_ ( const char * preset_mode)
protected

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

Definition at line 147 of file fan.cpp.

◆ find_preset_mode_() [2/2]

const char * esphome::fan::Fan::find_preset_mode_ ( const char * preset_mode,
size_t len )
protected

Definition at line 151 of file fan.cpp.

◆ get_preset_mode()

StringRef esphome::fan::Fan::get_preset_mode ( ) const
inline

Get the current preset mode.

Returns a StringRef of the string stored in traits, or empty ref if not set. The returned ref points to string literals from codegen (static storage). Traits are set once at startup and valid for the lifetime of the program.

Definition at line 155 of file fan.h.

◆ get_traits()

◆ has_preset_mode()

bool esphome::fan::Fan::has_preset_mode ( ) const
inline

Check if a preset mode is currently active.

Definition at line 158 of file fan.h.

◆ make_call()

FanCall esphome::fan::Fan::make_call ( )
inline

Definition at line 122 of file fan.h.

◆ publish_state()

void esphome::fan::Fan::publish_state ( )

Definition at line 205 of file fan.cpp.

◆ restore_state_()

optional< FanRestoreState > esphome::fan::Fan::restore_state_ ( )
protected

Definition at line 233 of file fan.cpp.

◆ save_state_()

void esphome::fan::Fan::save_state_ ( )
protected

Definition at line 268 of file fan.cpp.

◆ set_preset_mode_() [1/4]

bool esphome::fan::Fan::set_preset_mode_ ( const char * preset_mode)
protected

Definition at line 180 of file fan.cpp.

◆ set_preset_mode_() [2/4]

bool esphome::fan::Fan::set_preset_mode_ ( const char * preset_mode,
size_t len )
protected

Set the preset mode (finds and stores pointer from traits).

Returns true if changed. Passing nullptr or empty string clears the preset mode.

Definition at line 163 of file fan.cpp.

◆ set_preset_mode_() [3/4]

bool esphome::fan::Fan::set_preset_mode_ ( const std::string & preset_mode)
protected

Definition at line 184 of file fan.cpp.

◆ set_preset_mode_() [4/4]

bool esphome::fan::Fan::set_preset_mode_ ( StringRef preset_mode)
protected

Definition at line 188 of file fan.cpp.

◆ set_restore_mode()

void esphome::fan::Fan::set_restore_mode ( FanRestoreMode restore_mode)
inline

Set the restore mode of this fan.

Definition at line 149 of file fan.h.

◆ set_supported_preset_modes() [1/3]

void esphome::fan::Fan::set_supported_preset_modes ( const FanPresetModes & preset_modes)
inline

Definition at line 140 of file fan.h.

◆ set_supported_preset_modes() [2/3]

void esphome::fan::Fan::set_supported_preset_modes ( const std::vector< const char * > & preset_modes)
inline

Definition at line 137 of file fan.h.

◆ set_supported_preset_modes() [3/3]

void esphome::fan::Fan::set_supported_preset_modes ( std::initializer_list< const char * > preset_modes)
inline

Set the supported preset modes; the list is copied (stored on Fan, referenced by FanTraits).

Definition at line 134 of file fan.h.

◆ set_supported_preset_modes_static()

void esphome::fan::Fan::set_supported_preset_modes_static ( const char *const * preset_modes,
size_t count )
inline

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

Definition at line 144 of file fan.h.

◆ toggle()

FanCall esphome::fan::Fan::toggle ( )
inline

Definition at line 121 of file fan.h.

◆ turn_off()

FanCall esphome::fan::Fan::turn_off ( )
inline

Definition at line 120 of file fan.h.

◆ turn_on()

FanCall esphome::fan::Fan::turn_on ( )
inline

Definition at line 119 of file fan.h.

◆ wire_preset_modes_()

void esphome::fan::Fan::wire_preset_modes_ ( FanTraits & traits)
inlineprotected

Wire the Fan-owned preset modes pointer into the given traits object.

Definition at line 186 of file fan.h.

Field Documentation

◆ direction

FanDirection esphome::fan::Fan::direction {FanDirection::FORWARD}

The current direction of the fan.

Definition at line 117 of file fan.h.

◆ FanCall

friend esphome::fan::Fan::FanCall
protected

Definition at line 161 of file fan.h.

◆ oscillating

bool esphome::fan::Fan::oscillating {false}

The current oscillation state of the fan.

Definition at line 113 of file fan.h.

◆ restore_mode_

FanRestoreMode esphome::fan::Fan::restore_mode_ {FanRestoreMode::NO_RESTORE}
protected

Definition at line 190 of file fan.h.

◆ rtc_

ESPPreferenceObject esphome::fan::Fan::rtc_
protected

Definition at line 189 of file fan.h.

◆ speed

int esphome::fan::Fan::speed {0}

The current fan speed level.

Definition at line 115 of file fan.h.

◆ state

bool esphome::fan::Fan::state {false}

The current on/off state of the fan.

Definition at line 111 of file fan.h.

◆ state_callback_

LazyCallbackManager<void()> esphome::fan::Fan::state_callback_ {}
protected

Definition at line 188 of file fan.h.


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