Fan

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");
fan.output->set_binary(App.make_gpio_output(34));
// Speed
auto speed_fan = App.make_fan("Speed Fan");
fan.output->set_speed(App.make_ledc_output(34));
// Oscillation
auto oscillating_fan = App.make_fan("Oscillating Fan");
oscillating_fan.output->set_binary(App.make_gpio_output(34));
oscillating_fan.output->set_oscillation(App.make_gpio_output(35));

See Application::make_fan().

API Reference

FanState

class FanState : public Nameable

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

Public Functions

FanState(const std::string &name)

Construct the fan state with name.

void add_on_state_change_callback(std::function<void()> &&update_callback)

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

bool get_state() const

Get the current ON/OFF state of this fan.

void set_state(bool state)

Set the current ON/OFF state of this fan.

bool is_oscillating() const

Get the current oscillating state of this fan.

void set_oscillating(bool oscillating)

Set the current oscillating state of this fan.

FanSpeed get_speed() const

Get the current speed of this fan.

void set_speed(FanSpeed speed)

Set the current speed of this fan.

bool set_speed(const char *speed)
const FanTraits &get_traits() const

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

void set_traits(const FanTraits &traits)

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

void load_from_preferences()

Load a fan state from the preferences into this object.

void save_to_preferences()

Save the fan state from this object into the preferences.

template <typename T>
TurnOnAction<T> *make_turn_on_action()
template <typename T>
TurnOffAction<T> *make_turn_off_action()
template <typename T>
ToggleAction<T> *make_toggle_action()

Protected Attributes

bool state_ = {false}
bool oscillating_ = {false}
FanSpeed speed_ = {FAN_SPEED_HIGH}
FanTraits traits_ = {}
CallbackManager<void()> state_callback_ = {}

FanTraits

class FanTraits

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

Public Functions

FanTraits()

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

FanTraits(bool oscillation, bool speed)

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

bool supports_oscillation() const

Return if this fan supports oscillation.

void set_oscillation(bool oscillation)

Set whether this fan supports oscillation.

bool supports_speed() const

Return if this fan supports speed modes.

void set_speed(bool speed)

Set whether this fan supports speed modes.

Protected Attributes

bool oscillation_
bool speed_

BasicFanComponent

class BasicFanComponent : public Component

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

Public Functions

void set_binary(output::BinaryOutput *output)

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

Can’t be mixed with set_speed.

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

void set_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.

Parameters
  • 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 set_oscillation(output::BinaryOutput *oscillating_output)

Set an oscillation output for this fan.

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

FanState *get_state() const
void set_state(FanState *state)
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 noting.

void loop()

This method will be called repeatedly.

Analogous to Arduino’s loop(). setup() is guaranteed to be called before this. 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 Attributes

FanState *state_ = {nullptr}
output::BinaryOutput *binary_output_ = {nullptr}
output::FloatOutput *speed_output_ = {nullptr}
float off_speed_ = {}
float low_speed_ = {}
float medium_speed_ = {}
float high_speed_ = {}
output::BinaryOutput *oscillating_output_ = {nullptr}
bool next_update_ = {true}

MQTTFanComponent

class MQTTFanComponent : public mqtt::MQTTComponent

Public Functions

MQTTFanComponent(FanState *state)
void set_custom_oscillation_command_topic(const std::string &topic)

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

void set_custom_oscillation_state_topic(const std::string &topic)

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

void set_custom_speed_command_topic(const std::string &topic)

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

void set_custom_speed_state_topic(const std::string &topic)

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

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

Send discovery info the Home Assistant, override this.

void setup()

Setup the fan subscriptions and discovery.

void send_initial_state()

Send the full current state to MQTT.

void publish_state()
std::string component_type() const

‘fan’ component type for discovery.

const std::string get_oscillation_command_topic() const
const std::string get_oscillation_state_topic() const
const std::string get_speed_command_topic() const
const std::string get_speed_state_topic() const
FanState *get_state() const
bool is_internal()

Protected Functions

std::string friendly_name() const

Get the friendly name of this MQTT component.

Protected Attributes

FanState *state_