From ffe95a0214d090573fd355f53583da1f48f63757 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Thu, 18 Mar 2021 10:56:21 +0100 Subject: [PATCH 1/3] Update to new entity model introducing percentage and preset modes --- source/_docs/mqtt/discovery.markdown | 9 +++ source/_integrations/fan.mqtt.markdown | 79 +++++++++++++++++++------- 2 files changed, 69 insertions(+), 19 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index bd40db3fe5bc..85f38a6dc1d0 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_value_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 cd43ae5c1ad1..581966855f2a 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -129,17 +129,17 @@ payload_available: type: string default: online payload_high_speed: - description: The payload that represents the fan's high speed. + description: DEPRECATED - 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. + description: DEPRECATED - 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. + description: DEPRECATED - The payload that represents the fan's medium speed. required: false type: string default: medium @@ -168,6 +168,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 @@ -179,19 +208,29 @@ retain: type: boolean default: true speed_command_topic: - description: The MQTT topic to publish commands to change speed state. + description: DEPRECATED - The MQTT topic to publish commands to change speed state. required: false type: string +speed_range_min: + description: The minimum of numeric output range (`off` not included). + required: false + type: integer + default: 1 +speed_range_max: + description: The maximum of numeric output range (representing 100%). + required: false + type: integer + default: 100 speed_state_topic: - description: The MQTT topic subscribed to receive speed state updates. + description: DEPRECATED - The MQTT topic subscribed to receive speed state updates. 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." + description: "DEPRECATED - 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`." + description: "DEPRECATED - List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." required: false type: [string, list] state_topic: @@ -220,10 +259,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 +270,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 ``` From 3ca3a44751ece4a17cb2319eb119d48c36aaafb9 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Thu, 18 Mar 2021 11:26:32 +0100 Subject: [PATCH 2/3] Support preset modes and percentage for mqtt fan --- source/_docs/mqtt/discovery.markdown | 9 +++ source/_integrations/fan.mqtt.markdown | 79 +++++++++++++++++++------- 2 files changed, 69 insertions(+), 19 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index bd40db3fe5bc..85f38a6dc1d0 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_value_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 cd43ae5c1ad1..581966855f2a 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -129,17 +129,17 @@ payload_available: type: string default: online payload_high_speed: - description: The payload that represents the fan's high speed. + description: DEPRECATED - 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. + description: DEPRECATED - 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. + description: DEPRECATED - The payload that represents the fan's medium speed. required: false type: string default: medium @@ -168,6 +168,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 @@ -179,19 +208,29 @@ retain: type: boolean default: true speed_command_topic: - description: The MQTT topic to publish commands to change speed state. + description: DEPRECATED - The MQTT topic to publish commands to change speed state. required: false type: string +speed_range_min: + description: The minimum of numeric output range (`off` not included). + required: false + type: integer + default: 1 +speed_range_max: + description: The maximum of numeric output range (representing 100%). + required: false + type: integer + default: 100 speed_state_topic: - description: The MQTT topic subscribed to receive speed state updates. + description: DEPRECATED - The MQTT topic subscribed to receive speed state updates. 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." + description: "DEPRECATED - 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`." + description: "DEPRECATED - List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." required: false type: [string, list] state_topic: @@ -220,10 +259,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 +270,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 ``` From 782092ae35132bd479d0c8d1c99ba318dbf573b3 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Fri, 26 Mar 2021 10:02:29 +0100 Subject: [PATCH 3/3] Remove deprecated items, fix typo --- source/_docs/mqtt/discovery.markdown | 2 +- source/_integrations/fan.mqtt.markdown | 33 +------------------------- 2 files changed, 2 insertions(+), 33 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 85f38a6dc1d0..25834c0f317d 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -197,7 +197,7 @@ Supported abbreviations: 'pow_stat_tpl': 'power_state_template', 'pr_mode_cmd_t': 'preset_mode_command_topic', 'pr_mode_stat_t': 'preset_mode_state_topic', - 'pr_mode_value_tpl': 'preset_mode_value_template', + 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', 'r_tpl': 'red_template', 'ret': 'retain', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 581966855f2a..01263e366ab5 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: DEPRECATED - The payload that represents the fan's high speed. - required: false - type: string - default: high -payload_low_speed: - description: DEPRECATED - The payload that represents the fan's low speed. - required: false - type: string - default: low -payload_medium_speed: - description: DEPRECATED - 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 @@ -207,12 +192,8 @@ retain: required: false type: boolean default: true -speed_command_topic: - description: DEPRECATED - The MQTT topic to publish commands to change speed state. - required: false - type: string speed_range_min: - description: The minimum of numeric output range (`off` not included). + description: The minimum of numeric output range (`off` not included, so `speed_range_min` - 1 represents 0%). required: false type: integer default: 1 @@ -221,18 +202,6 @@ speed_range_max: required: false type: integer default: 100 -speed_state_topic: - description: DEPRECATED - The MQTT topic subscribed to receive speed state updates. - required: false - type: string -speed_value_template: - description: "DEPRECATED - Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload." - required: false - type: string -speeds: - description: "DEPRECATED - List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium` and `high`." - required: false - type: [string, list] state_topic: description: The MQTT topic subscribed to receive state updates. required: false