HAFan class¶

class HAFan : public HABaseDeviceType ¶

HAFan allows adding a controllable fan in the Home Assistant panel. The library supports only the state and speed of the fan. If you want more features please open a new GitHub issue.

Note

You can find more information about this entity in the Home Assistant documentation: https://www.home-assistant.io/integrations/fan.mqtt/

Public Types

enum Features¶

Values:

enumerator DefaultFeatures¶

enumerator SpeedsFeature¶

Public Functions

HAFan(const char *uniqueId, const uint8_t features = DefaultFeatures)¶

Parameters

uniqueId – The unique ID of the fan. It needs to be unique in a scope of your device.
features – Features that should be enabled for the fan.

bool setState(const bool state, const bool force = false)¶

Changes state of the fan and publishes MQTT message. Please note that if a new value is the same as previous one, the MQTT message won’t be published.

Parameters

state – New state of the fan.
force – Forces to update state without comparing it to previous known state.

Returns

Returns true if MQTT message has been published successfully.

bool setSpeed(const uint16_t speed, const bool force = false)¶

Changes the speed of the fan and publishes MQTT message. Please note that if a new value is the same as previous one, the MQTT message won’t be published.

Parameters

speed – The new speed of the fan. It should be in range of min and max value.
force – Forces to update the value without comparing it to a previous known value.

Returns

Returns true if MQTT message has been published successfully.

inline bool turnOn()¶: Alias for setState(true).

inline bool turnOff()¶: Alias for setState(false).

inline void setCurrentState(const bool state)¶

Sets current state of the fan without publishing it to Home Assistant. This method may be useful if you want to change state before connection with MQTT broker is acquired.

Parameters: state – New state of the fan.

inline bool getCurrentState() const¶: Returns last known state of the fan. By default it’s false.

inline void setCurrentSpeed(const uint16_t speed)¶

Sets the current speed of the fan without pushing the value to Home Assistant. This method may be useful if you want to change the speed before the connection with the MQTT broker is acquired.

Parameters: speed – The new speed of the fan. It should be in range of min and max value.

inline uint16_t getCurrentSpeed() const¶: Returns the last known speed of the fan. By default speed is set to 0.

inline void setIcon(const char *icon)¶

Sets icon of the fan. Any icon from MaterialDesignIcons.com (for example: mdi:home).

Parameters: icon – The icon name.

inline void setRetain(const bool retain)¶

Sets retain flag for the fan’s command. If set to true the command produced by Home Assistant will be retained.

Parameters: retain –

inline void setOptimistic(const bool optimistic)¶

Sets optimistic flag for the fan state. In this mode the fan state doesn’t need to be reported back to the HA panel when a command is received. By default the optimistic mode is disabled.

Parameters: optimistic – The optimistic mode (true - enabled, false - disabled).

inline void setSpeedRangeMax(const uint16_t max)¶

Sets the maximum of numeric output range (representing 100%). The number of speeds within the speed_range / 100 will determine the percentage step. By default the maximum range is 100.

Parameters: max – The maximum of numeric output range.

inline void setSpeedRangeMin(const uint16_t min)¶

Sets the minimum of numeric output range (off is not included, so speed_range_min - 1 represents 0 %). The number of speeds within the speed_range / 100 will determine the percentage step. By default the minimum range is 1.

Parameters: min – The minimum of numeric output range.

inline void onStateCommand(void (*callback)(bool state, HAFan *sender))¶

Registers callback that will be called each time the state command from HA is received. Please note that it’s not possible to register multiple callbacks for the same fan.

Note

In non-optimistic mode, the state must be reported back to HA using the HAFan::setState method.

Parameters: callback –

inline void onSpeedCommand(void (*callback)(uint16_t speed, HAFan *sender))¶

Registers callback that will be called each time the speed command from HA is received. Please note that it’s not possible to register multiple callbacks for the same fan.

Note

In non-optimistic mode, the speed must be reported back to HA using the HAFan::setSpeed method.

Parameters: callback –

Protected Functions

virtual void buildSerializer() override¶

virtual void onMqttConnected() override¶

virtual void onMqttMessage(const char *topic, const uint8_t *payload, const uint16_t length) override¶

Private Functions

bool publishState(const bool state)¶

Publishes the MQTT message with the given state.

Parameters: state – The state to publish.
Returns: Returns true if the MQTT message has been published successfully.

bool publishSpeed(const uint16_t speed)¶

Publishes the MQTT message with the given speed.

Parameters: speed – The speed to publish. It should be in range of min and max value.
Returns: Returns true if the MQTT message has been published successfully.

void handleStateCommand(const uint8_t *cmd, const uint16_t length)¶

Parses the given state command and executes the callback with proper value.

Parameters

cmd – The data of the command.
length – Length of the command.

void handleSpeedCommand(const uint8_t *cmd, const uint16_t length)¶

Parses the given speed command and executes the callback with proper value.

Parameters

cmd – The data of the command.
length – Length of the command.

Private Members

const uint8_t _features¶: Features enabled for the fan.

const char *_icon¶: The icon of the button. It can be nullptr.

bool _retain¶: The retain flag for the HA commands.

bool _optimistic¶: The optimistic mode of the fan (true - enabled, false - disabled).

HANumeric _speedRangeMax¶: The maximum of numeric output range.

HANumeric _speedRangeMin¶: The minimum of numeric output range.

bool _currentState¶: The current state of the fan. By default it’s false.

uint16_t _currentSpeed¶: The current speed of the fan. By default it’s 0.

void (*_stateCallback)(bool state, HAFan *sender)¶: The callback that will be called when the state command is received from the HA.

void (*_speedCallback)(uint16_t speed, HAFan *sender)¶: The callback that will be called when the speed command is received from the HA.