From 466967d46f8fdbbb70a72ba237cd4559a6b90e3f Mon Sep 17 00:00:00 2001 From: jbouwh Date: Mon, 29 Mar 2021 20:11:18 +0200 Subject: [PATCH 1/7] Command templates - cleanup speeds --- source/_docs/mqtt/discovery.markdown | 18 +++--------- source/_integrations/fan.mqtt.markdown | 40 ++++++++++++++++++++++++++ 2 files changed, 44 insertions(+), 14 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index ecd61b01e647..1959c28b54df 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -45,8 +45,6 @@ discovery_prefix: type: string {% endconfiguration %} -### Discovery topic - The discovery topic need to follow a specific format: ```text @@ -57,11 +55,9 @@ The discovery topic need to follow a specific format: - `` (*Optional*): ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic. The ID of the node must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen). - ``: The ID of the device. This is only to allow for separate topics for each device and is not used for the `entity_id`. The ID of the device must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen). -Best practice for entities with a `unique_id` is to set `` to `unique_id` and omit the ``. - The payload must be a JSON dictionary and will be checked like an entry in your `configuration.yaml` file if a new device is added. This means that missing variables will be filled with the platform's default values. All configuration variables which are *required* must be present in the initial payload send to `/config`. -Subsequent messages on a topic where a valid payload has been received will be handled as a configuration update, and a configuration update with an empty payload will cause a previously discovered device to be deleted. +An empty payload will cause a previously discovered device to be deleted. The `` level can be used by clients to only subscribe to their own (command) topics by using one wildcard topic like `/+//+/set`. @@ -158,9 +154,11 @@ Supported abbreviations: 'on_cmd_type': 'on_command_type', 'opt': 'optimistic', 'osc_cmd_t': 'oscillation_command_topic', + 'osc_cmd_tpl': 'oscillation_command_template', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', 'pct_cmd_t': 'percentage_command_topic', + 'pct_cmd_tpl': 'percentage_command_template', 'pct_stat_t': 'percentage_state_topic', 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', @@ -172,16 +170,12 @@ Supported abbreviations: 'pl_cln_sp': 'payload_clean_spot', 'pl_cls': 'payload_close', 'pl_disarm': 'payload_disarm', - 'pl_hi_spd': 'payload_high_speed', 'pl_home': 'payload_home', 'pl_lock': 'payload_lock', 'pl_loc': 'payload_locate', - 'pl_lo_spd': 'payload_low_speed', - 'pl_med_spd': 'payload_medium_speed', 'pl_not_avail': 'payload_not_available', 'pl_not_home': 'payload_not_home', 'pl_off': 'payload_off', - 'pl_off_spd': 'payload_off_speed', 'pl_on': 'payload_on', 'pl_open': 'payload_open', 'pl_osc_off': 'payload_oscillation_off', @@ -200,6 +194,7 @@ Supported abbreviations: 'pow_stat_t': 'power_state_topic', 'pow_stat_tpl': 'power_state_template', 'pr_mode_cmd_t': 'preset_mode_command_topic', + 'pr_mode_cmd_tpl': 'preset_mode_command_template', 'pr_mode_stat_t': 'preset_mode_state_topic', 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', @@ -216,12 +211,8 @@ Supported abbreviations: 'set_pos_t': 'set_position_topic', 'pos_t': 'position_topic', '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', 'stat_clsd': 'state_closed', 'stat_closing': 'state_closing', @@ -286,7 +277,6 @@ Supported abbreviations for device registry configuration: 'mf': 'manufacturer', 'mdl': 'model', 'sw': 'sw_version', - 'sa': 'suggested_area', ``` ## Support by third-party tools diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 96a0078e134e..79b289ff10e8 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -56,6 +56,10 @@ availability_topic: description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. required: false type: string +command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `command_topic`. + required: false + type: template command_topic: description: The MQTT topic to publish commands to change the fan state. required: true @@ -115,6 +119,10 @@ optimistic: required: false type: boolean default: "`true` if no state topic defined, else `false`." +oscillation_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `oscillation_command_topic`. + required: false + type: template oscillation_command_topic: description: The MQTT topic to publish commands to change the oscillation state. required: false @@ -157,6 +165,10 @@ payload_oscillation_on: required: false type: string default: oscillate_on +percentage_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `percentage_command_topic`. + required: false + type: template percentage_command_topic: description: The MQTT topic to publish commands to change the fan speed state based on a percentage. required: false @@ -169,6 +181,10 @@ 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_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `preset_mode_command_topic`. + required: false + type: template preset_mode_command_topic: description: The MQTT topic to publish commands to change the preset mode. required: false @@ -261,3 +277,27 @@ fan: speed_range_min: 1 speed_range_max: 100 ``` + +This example demonstrates how to use command templates with json output. + +```yaml +# Example configuration.yaml +# Example using command templates +fan: + - platform: mqtt + name: "Bedroom Fan" + command_topic: "bedroom_fan/on/set" + command_template: "{ state: '{{ value }}'}" + oscillation_command_topic: "bedroom_fan/oscillation/set" + oscillation_command_template: "{ oscillation: '{{ value }}'}" + percentage_command_topic: "bedroom_fan/speed/percentage" + percentage_command_template: "{ percentage: {{ value }}}" + preset_mode_command_topic: "bedroom_fan/speed/preset_mode" + preset_mode_command_template: "{ preset_mode: '{{ value }}'}" + preset_modes: + - "auto" + - "smart" + - "whoosh" + - "eco" + - "breeze" +``` From 05dad0d6f296a237fef18182e0d867f4b97782ef Mon Sep 17 00:00:00 2001 From: jbouwh Date: Mon, 29 Mar 2021 22:04:32 +0200 Subject: [PATCH 2/7] correct unwanted discovery.markdown changes --- source/_docs/mqtt/discovery.markdown | 11 ++----- source/_integrations/fan.mqtt.markdown | 40 ++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 8 deletions(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index ecd61b01e647..471ec71cd742 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -158,9 +158,11 @@ Supported abbreviations: 'on_cmd_type': 'on_command_type', 'opt': 'optimistic', 'osc_cmd_t': 'oscillation_command_topic', + 'osc_cmd_tpl': 'oscillation_command_template', 'osc_stat_t': 'oscillation_state_topic', 'osc_val_tpl': 'oscillation_value_template', 'pct_cmd_t': 'percentage_command_topic', + 'pct_cmd_tpl': 'percentage_command_template', 'pct_stat_t': 'percentage_state_topic', 'pct_val_tpl': 'percentage_value_template', 'pl': 'payload', @@ -172,16 +174,12 @@ Supported abbreviations: 'pl_cln_sp': 'payload_clean_spot', 'pl_cls': 'payload_close', 'pl_disarm': 'payload_disarm', - 'pl_hi_spd': 'payload_high_speed', 'pl_home': 'payload_home', 'pl_lock': 'payload_lock', 'pl_loc': 'payload_locate', - 'pl_lo_spd': 'payload_low_speed', - 'pl_med_spd': 'payload_medium_speed', 'pl_not_avail': 'payload_not_available', 'pl_not_home': 'payload_not_home', 'pl_off': 'payload_off', - 'pl_off_spd': 'payload_off_speed', 'pl_on': 'payload_on', 'pl_open': 'payload_open', 'pl_osc_off': 'payload_oscillation_off', @@ -200,6 +198,7 @@ Supported abbreviations: 'pow_stat_t': 'power_state_topic', 'pow_stat_tpl': 'power_state_template', 'pr_mode_cmd_t': 'preset_mode_command_topic', + 'pr_mode_cmd_tpl': 'preset_mode_command_template', 'pr_mode_stat_t': 'preset_mode_state_topic', 'pr_mode_val_tpl': 'preset_mode_value_template', 'pr_modes': 'preset_modes', @@ -216,12 +215,8 @@ Supported abbreviations: 'set_pos_t': 'set_position_topic', 'pos_t': 'position_topic', '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', 'stat_clsd': 'state_closed', 'stat_closing': 'state_closing', diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 96a0078e134e..79b289ff10e8 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -56,6 +56,10 @@ availability_topic: description: The MQTT topic subscribed to receive availability (online/offline) updates. Must not be used together with `availability`. required: false type: string +command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `command_topic`. + required: false + type: template command_topic: description: The MQTT topic to publish commands to change the fan state. required: true @@ -115,6 +119,10 @@ optimistic: required: false type: boolean default: "`true` if no state topic defined, else `false`." +oscillation_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `oscillation_command_topic`. + required: false + type: template oscillation_command_topic: description: The MQTT topic to publish commands to change the oscillation state. required: false @@ -157,6 +165,10 @@ payload_oscillation_on: required: false type: string default: oscillate_on +percentage_command_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `percentage_command_topic`. + required: false + type: template percentage_command_topic: description: The MQTT topic to publish commands to change the fan speed state based on a percentage. required: false @@ -169,6 +181,10 @@ 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_template: + description: Defines a [template](/docs/configuration/templating/#processing-incoming-data) to generate the payload to send to `preset_mode_command_topic`. + required: false + type: template preset_mode_command_topic: description: The MQTT topic to publish commands to change the preset mode. required: false @@ -261,3 +277,27 @@ fan: speed_range_min: 1 speed_range_max: 100 ``` + +This example demonstrates how to use command templates with json output. + +```yaml +# Example configuration.yaml +# Example using command templates +fan: + - platform: mqtt + name: "Bedroom Fan" + command_topic: "bedroom_fan/on/set" + command_template: "{ state: '{{ value }}'}" + oscillation_command_topic: "bedroom_fan/oscillation/set" + oscillation_command_template: "{ oscillation: '{{ value }}'}" + percentage_command_topic: "bedroom_fan/speed/percentage" + percentage_command_template: "{ percentage: {{ value }}}" + preset_mode_command_topic: "bedroom_fan/speed/preset_mode" + preset_mode_command_template: "{ preset_mode: '{{ value }}'}" + preset_modes: + - "auto" + - "smart" + - "whoosh" + - "eco" + - "breeze" +``` From 767a338d36ec154851f67cad0b9cf4fb0f23e179 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Mon, 29 Mar 2021 22:12:21 +0200 Subject: [PATCH 3/7] Repair content --- source/_docs/mqtt/discovery.markdown | 1 - 1 file changed, 1 deletion(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 471ec71cd742..aac94fde2783 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -281,7 +281,6 @@ Supported abbreviations for device registry configuration: 'mf': 'manufacturer', 'mdl': 'model', 'sw': 'sw_version', - 'sa': 'suggested_area', ``` ## Support by third-party tools From 60e4c0e72a3eba1541469692fc6242ec07402de6 Mon Sep 17 00:00:00 2001 From: jbouwh Date: Mon, 29 Mar 2021 22:15:53 +0200 Subject: [PATCH 4/7] Repair content --- source/_docs/mqtt/discovery.markdown | 1 - 1 file changed, 1 deletion(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 471ec71cd742..aac94fde2783 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -281,7 +281,6 @@ Supported abbreviations for device registry configuration: 'mf': 'manufacturer', 'mdl': 'model', 'sw': 'sw_version', - 'sa': 'suggested_area', ``` ## Support by third-party tools From 76d32814fb31c9a2e8b4f09a36db840a700aba6a Mon Sep 17 00:00:00 2001 From: jbouwh Date: Mon, 29 Mar 2021 22:17:15 +0200 Subject: [PATCH 5/7] Repair retry --- source/_docs/mqtt/discovery.markdown | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index 1959c28b54df..aac94fde2783 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -45,6 +45,8 @@ discovery_prefix: type: string {% endconfiguration %} +### Discovery topic + The discovery topic need to follow a specific format: ```text @@ -55,9 +57,11 @@ The discovery topic need to follow a specific format: - `` (*Optional*): ID of the node providing the topic, this is not used by Home Assistant but may be used to structure the MQTT topic. The ID of the node must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen). - ``: The ID of the device. This is only to allow for separate topics for each device and is not used for the `entity_id`. The ID of the device must only consist of characters from the character class `[a-zA-Z0-9_-]` (alphanumerics, underscore and hyphen). +Best practice for entities with a `unique_id` is to set `` to `unique_id` and omit the ``. + The payload must be a JSON dictionary and will be checked like an entry in your `configuration.yaml` file if a new device is added. This means that missing variables will be filled with the platform's default values. All configuration variables which are *required* must be present in the initial payload send to `/config`. -An empty payload will cause a previously discovered device to be deleted. +Subsequent messages on a topic where a valid payload has been received will be handled as a configuration update, and a configuration update with an empty payload will cause a previously discovered device to be deleted. The `` level can be used by clients to only subscribe to their own (command) topics by using one wildcard topic like `/+//+/set`. From 95baa82e66f4f9f5beefb0566c5d88cac43c2acc Mon Sep 17 00:00:00 2001 From: jbouwh Date: Mon, 29 Mar 2021 22:21:15 +0200 Subject: [PATCH 6/7] pylint fix --- source/_integrations/fan.mqtt.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/_integrations/fan.mqtt.markdown b/source/_integrations/fan.mqtt.markdown index 79b289ff10e8..50eafc25bad7 100644 --- a/source/_integrations/fan.mqtt.markdown +++ b/source/_integrations/fan.mqtt.markdown @@ -278,7 +278,7 @@ fan: speed_range_max: 100 ``` -This example demonstrates how to use command templates with json output. +This example demonstrates how to use command templates with JSON output. ```yaml # Example configuration.yaml From 5aa460a08cd197518ea4b366b65623c207cdd66a Mon Sep 17 00:00:00 2001 From: jbouwh Date: Mon, 29 Mar 2021 22:26:14 +0200 Subject: [PATCH 7/7] Revert unrelated change suggested_area --- source/_docs/mqtt/discovery.markdown | 1 + 1 file changed, 1 insertion(+) diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown index aac94fde2783..471ec71cd742 100644 --- a/source/_docs/mqtt/discovery.markdown +++ b/source/_docs/mqtt/discovery.markdown @@ -281,6 +281,7 @@ Supported abbreviations for device registry configuration: 'mf': 'manufacturer', 'mdl': 'model', 'sw': 'sw_version', + 'sa': 'suggested_area', ``` ## Support by third-party tools