Base class for all switches. More...

#include <switch.h>

Inheritance diagram for esphome::switch_::Switch:

Public Member Functions
	Switch ()

void	publish_state (bool state)
	Publish a state to the front-end from the back-end.

void	control (bool target_state)
	Control this switch using a boolean state value.

void	turn_on ()
	Turn this switch on.

void	turn_off ()
	Turn this switch off.

void	toggle ()
	Toggle this switch.

void	set_inverted (bool inverted)
	Set whether the state should be treated as inverted.

template<typename F >
void	add_on_state_callback (F &&callback)
	Set callback for state changes.

optional< bool >	get_initial_state ()
	Returns the initial state of the switch, as persisted previously, or empty if never persisted.

optional< bool >	get_initial_state_with_restore_mode ()
	Returns the initial state of the switch, after applying restore mode rules.

void	restore ()
	Drive the switch to the state its restore mode yields, through control(), so inversion and write_state() apply; a disabled restore mode drives `when_disabled`, or nothing without one.

void	restore (bool when_disabled)

virtual bool	assumed_state ()
	Return whether this switch uses an assumed state - i.e.

bool	is_inverted () const

void	set_restore_mode (SwitchRestoreMode restore_mode)

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
SwitchRestoreMode	restore_mode {SWITCH_RESTORE_DEFAULT_OFF}
	Indicates whether or not state is to be retrieved from flash and how.

bool	state
	The current reported state of the binary sensor.

Protected Member Functions
virtual void	write_state (bool state)=0
	Write the given state to hardware.

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
ESPPreferenceObject	rtc_

LazyCallbackManager< void(bool)>	state_callback_ {}

Deduplicator< bool >	publish_dedup_

bool	inverted_ {false}

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

Base class for all switches.

A switch is basically just a combination of a binary sensor (for reporting switch values) and a write_state method that writes a state to the hardware.

Definition at line 43 of file switch.h.

Constructor & Destructor Documentation

◆ Switch()

esphome::switch_::Switch::Switch ( )

explicit

Definition at line 10 of file switch.cpp.

Member Function Documentation

◆ add_on_state_callback()

template<typename F >

void esphome::switch_::Switch::add_on_state_callback ( F && callback )

inline

Set callback for state changes.

Parameters

callback The void(bool) callback.

Definition at line 101 of file switch.h.

◆ assumed_state()

bool esphome::switch_::Switch::assumed_state ( )

virtual

Return whether this switch uses an assumed state - i.e.

if both the ON/OFF actions should be displayed in Home Assistant because the real state is unknown.

Defaults to false.

Reimplemented in esphome::modbus_controller::ModbusSwitch, and esphome::template_::TemplateSwitch.

Definition at line 85 of file switch.cpp.

◆ control()

void esphome::switch_::Switch::control ( bool target_state )

Control this switch using a boolean state value.

This method provides a unified interface for setting the switch state based on a boolean parameter. It automatically calls turn_on() when state is true or turn_off() when state is false.

Parameters

target_state The desired state: true to turn the switch ON, false to turn it OFF.

Definition at line 12 of file switch.cpp.

◆ get_initial_state()

optional< bool > esphome::switch_::Switch::get_initial_state ( )

Returns the initial state of the switch, as persisted previously, or empty if never persisted.

Definition at line 32 of file switch.cpp.

◆ get_initial_state_with_restore_mode()

optional< bool > esphome::switch_::Switch::get_initial_state_with_restore_mode ( )

Returns the initial state of the switch, after applying restore mode rules.

If restore mode is disabled, this function will return an optional with no value (.has_value() is false), leaving it up to the component to decide the state. For example, the component could read the state from hardware and determine the current state.

Definition at line 49 of file switch.cpp.

◆ is_inverted()

bool esphome::switch_::Switch::is_inverted ( ) const

inline

Definition at line 130 of file switch.h.

◆ publish_state()

void esphome::switch_::Switch::publish_state ( bool state )

Publish a state to the front-end from the back-end.

The input value is inverted if applicable. Then the internal value member is set and finally the callbacks are called.

Parameters

state The new state.

Definition at line 70 of file switch.cpp.

◆ restore() [1/2]

void esphome::switch_::Switch::restore ( )

Drive the switch to the state its restore mode yields, through control(), so inversion and write_state() apply; a disabled restore mode drives when_disabled, or nothing without one.

Definition at line 63 of file switch.cpp.

◆ restore() [2/2]

void esphome::switch_::Switch::restore ( bool when_disabled )

Definition at line 67 of file switch.cpp.

◆ set_inverted()

void esphome::switch_::Switch::set_inverted ( bool inverted )

inline

Set whether the state should be treated as inverted.

To the developer and user an inverted switch will act just like a non-inverted one. In particular, the only thing that's changed by this is the value passed to write_state and the state in publish_state. The .state member variable and turn_on/turn_off/toggle remain unaffected.

Parameters

inverted Whether to invert this switch.

Definition at line 95 of file switch.h.

◆ set_restore_mode()

void esphome::switch_::Switch::set_restore_mode ( SwitchRestoreMode restore_mode )

inline

Definition at line 132 of file switch.h.

◆ toggle()

void esphome::switch_::Switch::toggle ( )

Toggle this switch.

This is called by the front-end.

For implementing switches, please override write_state.

Definition at line 27 of file switch.cpp.

◆ turn_off()

void esphome::switch_::Switch::turn_off ( )

Turn this switch off.

This is called by the front-end.

For implementing switches, please override write_state.

Definition at line 23 of file switch.cpp.

◆ turn_on()

void esphome::switch_::Switch::turn_on ( )

Turn this switch on.

This is called by the front-end.

For implementing switches, please override write_state.

Definition at line 19 of file switch.cpp.

◆ write_state()

virtual void esphome::switch_::Switch::write_state ( bool state )

protectedpure virtual

Write the given state to hardware.

You should implement this abstract method if you want to create your own switch.

In the implementation of this method, you should also call publish_state to acknowledge that the state was written to the hardware.

Parameters

state The state to write. Inversion is already applied if user specified it.

Implemented in esphome::at581x::RFSwitch, esphome::ble_client::BLEClientSwitch, esphome::bq25186::BQ25186PgGpoSwitch, esphome::copy::CopySwitch, esphome::demo::DemoSwitch, esphome::dfrobot_sen0395::Sen0395LedSwitch, esphome::dfrobot_sen0395::Sen0395PowerSwitch, esphome::dfrobot_sen0395::Sen0395StartAfterBootSwitch, esphome::dfrobot_sen0395::Sen0395UartPresenceSwitch, esphome::factory_reset::FactoryResetSwitch, esphome::gpio::GPIOSwitch, esphome::gree::GreeModeBitSwitch, esphome::haier::BeeperSwitch, esphome::haier::DisplaySwitch, esphome::haier::HealthModeSwitch, esphome::haier::QuietModeSwitch, esphome::haier_tundra::HaierTundraSwitch, esphome::hbridge::HBridgeSwitch, esphome::homeassistant::HomeassistantSwitch, esphome::ld2410::BluetoothSwitch, esphome::ld2410::EngineeringModeSwitch, esphome::ld2412::BluetoothSwitch, esphome::ld2412::EngineeringModeSwitch, esphome::ld2450::BluetoothSwitch, esphome::ld2450::MultiTargetSwitch, esphome::ld6002b::LD6002BSwitch, esphome::lvgl::LVGLSwitch, esphome::micronova::MicroNovaSwitch, esphome::modbus_controller::ModbusSwitch, esphome::nextion::NextionSwitch, esphome::opentherm::OpenthermSwitch, esphome::output::OutputSwitch, esphome::pcm5122::PCM5122PowerSwitch, esphome::pipsolar::PipsolarSwitch, esphome::restart::RestartSwitch, esphome::safe_mode::SafeModeSwitch, esphome::seeed_mr24hpc1::UnderlyOpenFunctionSwitch, esphome::sendspin_::SendspinEnabledSwitch, esphome::sendspin_::SendspinUnpairedAccessSwitch, esphome::shutdown::ShutdownSwitch, esphome::sprinkler::SprinklerControllerSwitch, esphome::switch_::ApplySwitch< Fn >, esphome::template_::TemplateSwitch, esphome::tuya::TuyaSwitch, and esphome::uart::UARTSwitch.

Field Documentation

◆ inverted_

bool esphome::switch_::Switch::inverted_ {false}

protected

Definition at line 153 of file switch.h.

◆ publish_dedup_

Deduplicator<bool> esphome::switch_::Switch::publish_dedup_

protected

Definition at line 152 of file switch.h.

◆ restore_mode

SwitchRestoreMode esphome::switch_::Switch::restore_mode {SWITCH_RESTORE_DEFAULT_OFF}

Indicates whether or not state is to be retrieved from flash and how.

Definition at line 57 of file switch.h.

◆ rtc_

ESPPreferenceObject esphome::switch_::Switch::rtc_

protected

Definition at line 146 of file switch.h.

◆ state

bool esphome::switch_::Switch::state

The current reported state of the binary sensor.

Definition at line 60 of file switch.h.

◆ state_callback_

LazyCallbackManager<void(bool)> esphome::switch_::Switch::state_callback_ {}

protected

Definition at line 149 of file switch.h.

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

esphome/components/switch/switch.h
esphome/components/switch/switch.cpp

Public Member Functions

Data Fields

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ Switch()

Member Function Documentation

◆ add_on_state_callback()

◆ assumed_state()

◆ control()

◆ get_initial_state()

◆ get_initial_state_with_restore_mode()

◆ is_inverted()

◆ publish_state()

◆ restore() [1/2]

◆ restore() [2/2]

◆ set_inverted()

◆ set_restore_mode()

◆ toggle()

◆ turn_off()

◆ turn_on()

◆ write_state()

Field Documentation

◆ inverted_

◆ publish_dedup_

◆ restore_mode

◆ rtc_

◆ state

◆ state_callback_