Skip to content

Update the MQTT fan documentation #1345

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed

Update the MQTT fan documentation #1345

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 38 additions & 8 deletions source/_components/fan.mqtt.markdown
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,31 +17,61 @@ The `mqtt` fan platform let you control your MQTT enabled fans.

In an ideal scenario, the MQTT device will have a `state_topic` to publish state changes. If these messages are published with `RETAIN` flag, the MQTT fan will receive an instant state update after subscription and will start with correct state. Otherwise, the initial state of the fan will be `false`.

When a `state_topic` is not available, the fan will work in optimistic mode. In this mode, the fan will immediately change state after every command. Otherwise, the fan will wait for state confirmation from device (message from `state_topic`).
When a `state_topic` is not available, the fan will work in optimistic mode. In this mode, the fan will immediately change state after every command. Otherwise, the fan will wait for state confirmation from the device (message from `state_topic`).

Optimistic mode can be forced, even if state topic is available. Try to enable it, if experiencing incorrect fan operation.
Optimistic mode can be forced even if a `state_topic` is available. Try to enable it if you are experiencing incorrect fan operation.

To enable MQTT fans in your installation, add the following to your `configuration.yaml` file:

```yaml
# Example configuration.yml entry
fan:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a great addition but the example code should always try to be minimized.
Feel free to have a fully fleshed out example also but avoid having the Optional variables in the minimized one.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So happy to make the change but the way the original author defined the component would mean the minimal version would ONLY be the command topic. Would you be ok with some kind of happy medium?

platform: mqtt
command_topic: "home/living-room/fan/set"
- platform: mqtt
name: "Bedroom Fan"
state_topic: "bedroom_fan/on/state"
command_topic: "bedroom_fan/on/set"
oscillation_state_topic: "bedroom_fan/oscillation/state"
oscillation_command_topic: "bedroom_fan/oscillation/set"
speed_state_topic: "bedroom_fan/speed/state"
speed_command_topic: "bedroom_fan/speed/set"
qos: 0
payload_on: "true"
payload_off: "false"
payload_oscillation_on: "true"
payload_oscillation_off: "false"
payload_low_speed: "low"
payload_medium_speed: "medium"
payload_high_speed: "high"
speeds:
- low
- medium
- high
```

Configuration variables:

- **name** (*Optional*): The name of the lock. Default is 'MQTT Lock'.
- **name** (*Optional*): The name of the fan. Default is 'MQTT Fan'.
- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates.
- **command_topic** (*Required*): The MQTT topic to publish commands to change the lock state.
- **oscillation_state_topic** (*Optional*): The MQTT topic subscribed to receive oscillation state updates.
- **oscillation_command_topic** (*Optional*): The MQTT topic to publish commands to change the oscillation state.
- **speed_state_topic** (*Optional*): The MQTT topic subscribed to receive speed state updates.
- **speed_command_topic** (*Optional*): The MQTT topic to publish commands to change speed state.
- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.
- **payload_on** (*Optional*): The payload that represents the running state. Default is "ON".
- **payload_off** (*Optional*): The payload that represents the stop state. Default is "OFF".
- **payload_oscillation_on** (*Optional*): The payload that represents the oscillation on state. Default is "oscillate_on".
- **payload_oscillation_off** (*Optional*): The payload that presents the oscillation off state. Default is "oscillate_off"
- **payload_low_speed** (*Optional*): The payload that represents the fan's low speed.
- **payload_medium_speed** (*Optional*): The payload that represents the fan's medium speed.
- **payload_high_speed** (*Optional*): The payload that represents the fan's high speed.
- **speeds** (*Optional*): List of available speeds on the fan. Default is "off", "low", "med", and "high".
- **optimistic** (*Optional*): Flag that defines if lock works in optimistic mode. Default is `true` if no state topic defined, else `false`.
- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.
- **retain** (*Optional*): If the published message should have the retain flag on or not.
- **value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the payload.
- **state_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the state payload.
- **oscillation_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the oscillation payload.
- **speed_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract a value from the speed payload.

<p class='note warning'>
Make sure that your topic match exact. `some-topic/` and `some-topic` are different topics.
Make sure that your topic is an exact match. `some-topic/` and `some-topic` are different topics.
</p>