Fans in esphomelib are implemented like lights. Both the hardware and the MQTT frontend access a combined FanState object and use only that to set state and receive state updates.

Example Usage

// Basic
auto fan = App.make_fan("Fan");
// Speed
auto speed_fan = App.make_fan("Speed Fan");
// Oscillation
auto oscillating_fan = App.make_fan("Oscillating Fan");

See Application::make_fan().

API Reference


class fan::FanState

This class is shared between the hardware backend and the MQTT frontend to share state.

A fan state has several variables that determine the current state: state (ON/OFF), speed (OFF, LOW, MEDIUM, HIGH), oscillating (ON/OFF) and traits (what features are supported). Both the frontend and the backend can register callbacks whenever a state is changed from the frontend and whenever a state is actually changed and should be pushed to the frontend

Inherits from Nameable

Public Functions

fan::FanStateFanState(const std::string &name)

Construct the fan state with name.

void fan::FanStateadd_on_state_change_callback(std::function<void()> &&update_callback)

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

bool fan::FanStateget_state() const

Get the current ON/OFF state of this fan.

void fan::FanStateset_state(bool state)

Set the current ON/OFF state of this fan.

bool fan::FanStateis_oscillating() const

Get the current oscillating state of this fan.

void fan::FanStateset_oscillating(bool oscillating)

Set the current oscillating state of this fan.

FanSpeed fan::FanStateget_speed() const

Get the current speed of this fan.

void fan::FanStateset_speed(FanSpeed speed)

Set the current speed of this fan.

bool fan::FanStateset_speed(const char *speed)
const FanTraits &fan::FanStateget_traits() const

Get the traits of this fan (i.e. what features it supports).

void fan::FanStateset_traits(const FanTraits &traits)

Set the traits of this fan (i.e. what features it supports).

void fan::FanStateload_from_preferences()

Load a fan state from the preferences into this object.

void fan::FanStatesave_to_preferences()

Save the fan state from this object into the preferences.

template <typename T>
TurnOnAction<T> *fan::FanStatemake_turn_on_action()
template <typename T>
TurnOffAction<T> *fan::FanStatemake_turn_off_action()
template <typename T>
ToggleAction<T> *fan::FanStatemake_toggle_action()

Protected Attributes

bool fan::FanStatestate_ = {false}
bool fan::FanStateoscillating_ = {false}
FanSpeed fan::FanStatespeed_ = {FAN_SPEED_HIGH}
FanTraits fan::FanStatetraits_ = {}
CallbackManager<void()> fan::FanStatestate_callback_ = {}


class fan::FanTraits

This class represents the capabilities/feature set of a fan.

Public Functions


Construct an empty FanTraits object. All features will be marked unsupported.

fan::FanTraitsFanTraits(bool oscillation, bool speed)

Construct a FanTraits object with the provided oscillation and speed support.

bool fan::FanTraitssupports_oscillation() const

Return if this fan supports oscillation.

void fan::FanTraitsset_oscillation(bool oscillation)

Set whether this fan supports oscillation.

bool fan::FanTraitssupports_speed() const

Return if this fan supports speed modes.

void fan::FanTraitsset_speed(bool speed)

Set whether this fan supports speed modes.

Protected Attributes

bool fan::FanTraitsoscillation_
bool fan::FanTraitsspeed_


class fan::BasicFanComponent

Simple fan helper that pushes the states to BinaryOutput/FloatOutput devices.

Inherits from Component

Public Functions

void fan::BasicFanComponentset_binary(output::BinaryOutput *output)

Create a fan that supports binary state operation (ON/OFF).

Can’t be mixed with set_speed.

  • output: The binary output where all binary commands should land.

void fan::BasicFanComponentset_speed(output::FloatOutput *output, float off_speed = 0.0, float low_speed = 0.33, float medium_speed = 0.66, float high_speed = 1.0)

Create a fan that supports speed operation (OFF/LOW/MEDIUM/HIGH SPEED).

Can’t be mixed with set_binary.

  • output: The FloatOutput where all speed/state commands should land.
  • off_speed: The speed that should be sent to the output if the fan is OFF.
  • low_speed: The speed that should be sent to the output if the fan is in LOW speed mode.
  • medium_speed: The speed that should be sent to the output if the fan is in MEDIUM speed mode.
  • high_speed: The speed that should be sent to the output if the fan is in HIGH speed mode.

void fan::BasicFanComponentset_oscillation(output::BinaryOutput *oscillating_output)

Set an oscillation output for this fan.

  • oscillating_output: The binary output where all oscillation commands should land.

FanState *fan::BasicFanComponentget_state() const
void fan::BasicFanComponentset_state(FanState *state)
void fan::BasicFanComponentsetup()

Where the component’s initialization should happen.

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

void fan::BasicFanComponentloop()

This method will be called repeatedly.

Analogous to Arduino’s loop(). setup() is guaranteed to be called before this. Defaults to doing nothing.

float fan::BasicFanComponentget_setup_priority() const

priority of setup().

higher -> executed earlier

Defaults to 0.

The setup priority of this component

Protected Attributes

FanState *fan::BasicFanComponentstate_ = {nullptr}
output::BinaryOutput *fan::BasicFanComponentbinary_output_ = {nullptr}
output::FloatOutput *fan::BasicFanComponentspeed_output_ = {nullptr}
float fan::BasicFanComponentoff_speed_ = {}
float fan::BasicFanComponentlow_speed_ = {}
float fan::BasicFanComponentmedium_speed_ = {}
float fan::BasicFanComponenthigh_speed_ = {}
output::BinaryOutput *fan::BasicFanComponentoscillating_output_ = {nullptr}
bool fan::BasicFanComponentnext_update_ = {true}


class fan::MQTTFanComponent

Inherits from mqtt::MQTTComponent

Public Functions

fan::MQTTFanComponentMQTTFanComponent(FanState *state)
void fan::MQTTFanComponentset_custom_oscillation_command_topic(const std::string &topic)

Set a custom oscillation command topic. Defaults to “<base>/oscillation/command”.

void fan::MQTTFanComponentset_custom_oscillation_state_topic(const std::string &topic)

Set a custom oscillation state topic. Defaults to “<base>/oscillation/state”.

void fan::MQTTFanComponentset_custom_speed_command_topic(const std::string &topic)

Set a custom speed command topic. Defaults to “<base>/speed/command”.

void fan::MQTTFanComponentset_custom_speed_state_topic(const std::string &topic)

Set a custom speed state topic. Defaults to “<base>/speed/state”.

void fan::MQTTFanComponentsend_discovery(JsonBuffer &buffer, JsonObject &root, mqtt::SendDiscoveryConfig &config)

Send discovery info the Home Assistant, override this.

void fan::MQTTFanComponentsetup()

Setup the fan subscriptions and discovery.

void fan::MQTTFanComponentsend_initial_state()

Send the full current state to MQTT.

void fan::MQTTFanComponentpublish_state()
std::string fan::MQTTFanComponentcomponent_type() const

‘fan’ component type for discovery.

const std::string fan::MQTTFanComponentget_oscillation_command_topic() const
const std::string fan::MQTTFanComponentget_oscillation_state_topic() const
const std::string fan::MQTTFanComponentget_speed_command_topic() const
const std::string fan::MQTTFanComponentget_speed_state_topic() const
FanState *fan::MQTTFanComponentget_state() const
bool fan::MQTTFanComponentis_internal()

Protected Functions

std::string fan::MQTTFanComponentfriendly_name() const

Get the friendly name of this MQTT component.

Protected Attributes

FanState *fan::MQTTFanComponentstate_