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, public Component

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_callback(std::function<void()> &&callback)

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

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).

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()
FanState::StateCall turn_on()
FanState::StateCall turn_off()
FanState::StateCall toggle()
FanState::StateCall make_call()
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

Public Members

bool state = {false}

The current ON/OFF state of the fan.

bool oscillating = {false}

The current oscillation state of the fan.

FanSpeed speed = {FAN_SPEED_HIGH}

The current fan speed.

Protected Attributes

FanTraits traits_ = {}
CallbackManager<void()> state_callback_ = {}
ESPPreferenceObject rtc_
class StateCall

Public Functions

StateCall(FanState *state)
FanState::StateCall &set_state(bool state)
FanState::StateCall &set_oscillating(bool oscillating)
FanState::StateCall &set_speed(FanSpeed speed)
FanState::StateCall &set_speed(const char *speed)
void perform() const

Protected Attributes

FanState *const state_
optional<bool> binary_state_
optional<bool> oscillating_ = {}
optional<FanSpeed> speed_ = {}

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 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.
  • 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 nothing.

void dump_config()
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 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(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

std::string custom_oscillation_command_topic_
std::string custom_oscillation_state_topic_
std::string custom_speed_command_topic_
std::string custom_speed_state_topic_
FanState *state_
template <typename T>
class ToggleAction : public Action<T>

Public Functions

ToggleAction(FanState *state)
void play(T x)

Protected Attributes

FanState *state_
template <typename T>
class TurnOnAction : public Action<T>

Public Functions

TurnOnAction(FanState *state)
void set_oscillating(std::function<bool(T)> &&oscillating)
void set_oscillating(bool oscillating)
void set_speed(std::function<FanSpeed(T)> &&speed)
void set_speed(FanSpeed speed)
void play(T x)

Protected Attributes

FanState *state_
TemplatableValue<bool, T> oscillating_
TemplatableValue<FanSpeed, T> speed_
template <typename T>
class TurnOffAction : public Action<T>

Public Functions

TurnOffAction(FanState *state)
void play(T x)

Protected Attributes

FanState *state_