Switch

The switch_ namespace contains all switch helpers.

API Reference

Switch

class Switch : public Nameable

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.

Subclassed by remote::RemoteTransmitter, switch_::GPIOSwitch, switch_::OutputSwitch, switch_::RestartSwitch, switch_::ShutdownSwitch, switch_::TemplateSwitch, switch_::UARTSwitch

Public Functions

Switch(const std::string &name)
void 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.

void turn_on()

Turn this switch on.

This is called by the front-end.

For implementing switches, please override write_state.

void turn_off()

Turn this switch off.

This is called by the front-end.

For implementing switches, please override write_state.

void toggle()

Toggle this switch.

This is called by the front-end.

For implementing switches, please override write_state.

void set_inverted(bool inverted)

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.

void set_icon(const std::string &icon)

Set the icon for this switch. “” for no icon.

std::string get_icon()

Get the icon for this switch. Using icon() if not manually set.

template <typename T>
ToggleAction<T> *make_toggle_action()
template <typename T>
TurnOffAction<T> *make_turn_off_action()
template <typename T>
TurnOnAction<T> *make_turn_on_action()
void add_on_state_callback(std::function<void(bool)> &&callback)

Set callback for state changes.

Parameters
  • callback: The void(bool) callback.

optional<bool> get_initial_state()
bool optimistic()

Return whether this switch is optimistic - i.e.

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

Defaults to false.

Public Members

bool state

The current reported state of the binary sensor.

union switch_::Switch::[anonymous] [anonymous]

Protected Functions

virtual void write_state(bool state) = 0

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.

std::string icon()

Override this to set the Home Assistant icon for this switch.

Return “” to disable this feature.

Return
The icon of this switch, for example “mdi:fan”.

Protected Attributes

optional<std::string> icon_ = {}

The icon shown here. Not set means use default from switch. Empty means no icon.

CallbackManager<void(bool)> state_callback_ = {}
bool inverted_ = {false}
ESPPreferenceObject rtc_

OutputSwitch

class OutputSwitch : public switch_::Switch, public Component

A simple switch that exposes a binary output as a switch.

Public Functions

OutputSwitch(const std::string &name, output::BinaryOutput *output)

Construct this SimpleSwitch with the provided BinaryOutput.

void setup()

Where the component’s initialization should happen.

Analogous to Arduino’s setup(). This method is guaranteed to only be called once. Defaults to doing nothing.

float get_setup_priority() const

priority of setup().

higher -> executed earlier

Defaults to 0.

Return
The setup priority of this component

Protected Functions

void write_state(bool state)

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.

Protected Attributes

output::BinaryOutput *output_

GPIOSwitch

class GPIOSwitch : public switch_::Switch, public Component

Public Functions

GPIOSwitch(const std::string &name, GPIOPin *pin)
float get_setup_priority() const

priority of setup().

higher -> executed earlier

Defaults to 0.

Return
The setup priority of this component

void setup()

Where the component’s initialization should happen.

Analogous to Arduino’s setup(). This method is guaranteed to only be called once. Defaults to doing nothing.

void dump_config()

Protected Functions

void write_state(bool state)

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.

Protected Attributes

GPIOPin *const pin_

MQTTSwitchComponent

class MQTTSwitchComponent : public mqtt::MQTTComponent

MQTT representation of switches.

Overrides MQTTBinarySensorComponent with a callback that can write values to hardware.

Public Functions

MQTTSwitchComponent(switch_::Switch *switch_)
void setup()

Where the component’s initialization should happen.

Analogous to Arduino’s setup(). This method is guaranteed to only be called once. Defaults to doing nothing.

void dump_config()
void send_discovery(JsonObject &root, mqtt::SendDiscoveryConfig &config)

Send discovery info the Home Assistant, override this.

void send_initial_state()
bool is_internal()
void publish_state(bool state)

Protected Functions

std::string friendly_name() const

Get the friendly name of this MQTT component.

std::string component_type() const

“switch” component type.

Protected Attributes

Switch *switch_