From 9e5d1835cb47638694ecb913a0c71b374625905c Mon Sep 17 00:00:00 2001 From: Jan Bouwhuis Date: Mon, 29 Mar 2021 09:37:16 +0200 Subject: [PATCH] Support preset modes and percentage for mqtt fan (#17048) --- source/_docs/mqtt/discovery.markdown | 9 +++ source/_integrations/fan.mqtt.markdown | 92 ++++++++++++++------------ 2 files changed, 60 insertions(+), 41 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index bd40db3fe5b..25834c0f317 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -156,6 +156,9 @@ Supported abbreviations: 'osc_cmd_t': 'oscillation_command_topic', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', + 'pct_cmd_t': 'percentage_command_topic', + 'pct_stat_t': 'percentage_state_topic', + 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', 'pl_arm_away': 'payload_arm_away', 'pl_arm_home': 'payload_arm_home', @@ -192,6 +195,10 @@ Supported abbreviations: 'pow_cmd_t': 'power_command_topic', 'pow_stat_t': 'power_state_topic', 'pow_stat_tpl': 'power_state_template', + 'pr_mode_cmd_t': 'preset_mode_command_topic', + 'pr_mode_stat_t': 'preset_mode_state_topic', + 'pr_mode_val_tpl': 'preset_mode_value_template', + 'pr_modes': 'preset_modes', 'r_tpl': 'red_template', 'ret': 'retain', 'rgb_cmd_tpl': 'rgb_command_template', @@ -207,6 +214,8 @@ Supported abbreviations: 'pos_tpl': 'position_template', 'spd_cmd_t': 'speed_command_topic', 'spd_stat_t': 'speed_state_topic', + 'spd_rng_min': 'speed_range_min', + 'spd_rng_max': 'speed_range_max', 'spd_val_tpl': 'speed_value_template', 'spds': 'speeds', 'src_type': 'source_type', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index cd43ae5c1ad..01263e366ab 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -128,21 +128,6 @@ payload_available: required: false type: string default: online -payload_high_speed: - description: The payload that represents the fan's high speed. - required: false - type: string - default: high -payload_low_speed: - description: The payload that represents the fan's low speed. - required: false - type: string - default: low -payload_medium_speed: - description: The payload that represents the fan's medium speed. - required: false - type: string - default: medium payload_not_available: description: The payload that represents the unavailable state. required: false @@ -168,6 +153,35 @@ payload_oscillation_on: required: false type: string default: oscillate_on +percentage_command_topic: + description: The MQTT topic to publish commands to change the fan speed state based on a percentage. + required: false + type: string +percentage_state_topic: + description: The MQTT topic subscribed to receive fan speed based on percentage. + required: false + type: string +percentage_value_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from fan percentage speed. + required: false + type: string +preset_mode_command_topic: + description: The MQTT topic to publish commands to change the preset mode. + required: false + type: string +preset_mode_state_topic: + description: The MQTT topic to publish commands to change the preset mode. + required: false + type: string +preset_mode_value_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the preset_mode payload. + required: false + type: string +preset_modes: + description: List of preset modes this fan is capable of running at. Common examples include `auto`, `smart`, `whoosh`, `eco` and `breeze`. + required: false + type: [list] + default: [] qos: description: The maximum QoS level of the state topic. required: false @@ -178,22 +192,16 @@ retain: required: false type: boolean default: true -speed_command_topic: - description: The MQTT topic to publish commands to change speed state. +speed_range_min: + description: The minimum of numeric output range (`off` not included, so `speed_range_min` - 1 represents 0%). required: false - type: string -speed_state_topic: - description: The MQTT topic subscribed to receive speed state updates. + type: integer + default: 1 +speed_range_max: + description: The maximum of numeric output range (representing 100%). required: false - type: string -speed_value_template: - description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." - required: false - type: string -speeds: - description: "List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." - required: false - type: [string, list] + type: integer + default: 100 state_topic: description: The MQTT topic subscribed to receive state updates. required: false @@ -220,10 +228,10 @@ In this section you find some real-life examples of how to use this fan. ### Full configuration -The example below shows a full configuration for a MQTT fan. +The example below shows a full configuration for a MQTT fan using percentage and preset modes. ```yaml -# Example configuration.yaml entry +# Example using percentage based speeds with preset modes configuration.yaml fan: - platform: mqtt name: "Bedroom Fan" @@ -231,19 +239,21 @@ fan: 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" + percentage_state_topic: "bedroom_fan/speed/percentage_state" + percentage_command_topic: "bedroom_fan/speed/percentage" + preset_mode_state_topic: "bedroom_fan/speed/preset_mode_state" + preset_mode_command_topic: "bedroom_fan/speed/preset_mode" + preset_modes: + - "auto" + - "smart" + - "whoosh" + - "eco" + - "breeze" 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: - - "off" - - low - - medium - - high + speed_range_min: 1 + speed_range_max: 100 ```