From 458823b2979fbe912aad79fc176a21350560c159 Mon Sep 17 00:00:00 2001 From: Lukas Barth Date: Sat, 13 Jan 2018 12:35:36 +0100 Subject: [PATCH 1/3] document templates --- source/_components/climate.mqtt.markdown | 55 ++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/source/_components/climate.mqtt.markdown b/source/_components/climate.mqtt.markdown index 03c5808ceb69..d9ffe9f98ebd 100644 --- a/source/_components/climate.mqtt.markdown +++ b/source/_components/climate.mqtt.markdown @@ -78,6 +78,10 @@ payload_not_available: required: false type: string default: offline +value_template: + description: Default template to render the payloads on *all* `*_state_topic`s with. + type: template + required: false current_temperature_topic: description: The MQTT topic on which to listen for the current temperature. required: false @@ -94,6 +98,10 @@ mode_state_topic: description: The MQTT topic to subscribe for changes of the HVAC operation mode. If this is not set, the operation mode works in optimistic mode (see below). required: false type: string +mode_state_template: + description: A template to render the value received on the `mode_state_topic` with. + required: false + type: template temperature_command_topic: description: The MQTT topic to publish commands to change the target temperature. required: false @@ -102,6 +110,10 @@ temperature_state_topic: description: The MQTT topic to subscribe for changes in the target temperature. If this is not set, the target temperature works in optimistic mode (see below). required: false type: string +temperature_state_template: + description: A template to render the value received on the `temperature_state_topic` with. + required: false + type: template fan_mode_command_topic: description: The MQTT topic to publish commands to change the fan mode. required: false @@ -110,6 +122,10 @@ fan_mode_state_topic: description: The MQTT topic to subscribe for changes of the HVAC fan mode. If this is not set, the fan mode works in optimistic mode (see below). required: false type: string +fan_mode_state_template: + description: A template to render the value received on the `fan_mode_state_topic` with. + required: false + type: template swing_mode_command_topic: description: The MQTT topic to publish commands to change the swing mode. required: false @@ -118,6 +134,10 @@ swing_mode_state_topic: description: The MQTT topic to subscribe for changes of the HVAC swing mode. If this is not set, the swing mode works in optimistic mode (see below). required: false type: string +swing_mode_state_template: + description: A template to render the value received on the `swing_mode_state_topic` with. + required: false + type: template away_mode_command_topic: description: The MQTT topic to publish commands to change the away mode. required: false @@ -126,6 +146,10 @@ away_mode_state_topic: description: The MQTT topic to subscribe for changes of the HVAC away mode. If this is not set, the away mode works in optimistic mode (see below). required: false type: string +away_mode_state_template: + description: A template to render the value received on the `away_mode_state_topic` with. + required: false + type: template hold_command_topic: description: The MQTT topic to publish commands to change the hold mode. required: false @@ -134,6 +158,10 @@ hold_state_topic: description: The MQTT topic to subscribe for changes of the HVAC hold mode. If this is not set, the hold mode works in optimistic mode (see below). required: false type: string +hold_state_template: + description: A template to render the value received on the `hold_state_topic` with. + required: false + type: template aux_command_topic: description: The MQTT topic to publish commands to switch auxiliary heat. required: false @@ -142,12 +170,39 @@ aux_state_topic: description: The MQTT topic to subscribe for changes of the auxiliary heat mode. If this is not set, the auxiliary heat mode works in optimistic mode (see below). required: false type: string +aux_state_template: + description: A template to render the value received on the `aux_state_topic` with. + required: false + type: template {% endconfiguration %} #### Optimistic mode If a property works in *optimistic mode* (when the corresponding state topic is not set), home assistant will assume that any state changes published to the command topics did work and change the internal state of the entity immediately after publishing to the command topic. If it does not work in optimistic mode, the internal state of the entity is only updated when the requested update is confirmed by the device through the state topic. +#### Using Templates + +For all `*_state_topic`s, a template can be specified that will be used to render the incoming payloads on these topics. Also, a default template that applies to all state topis can be specified as `value_template`. This can be useful if you received payloads are e.g. in JSON format. Since in JSON, a quoted string (e.g. `"foo"`) is just a string, this can also be used for unquoting. + +Say you receive the operation mode `"auto"` via your `mode_state_topic`, but the mode is actually called just `auto`, here's what you could do: + +```yaml +# Full example configuration.yaml entry +climate: + - platform: mqtt + name: Study + modes: + - off + - on + - auto + mode_command_topic: "study/ac/mode/set" + mode_state_topic: "study/ac/mode/state" + mode_state_template: "{{ value_json }}" +``` + +This will parse the incoming `"auto"` as JSON, resulting in `auto`. Obvisouly, in this case you could also just set `value_template: "{{ value_json }}"`. + + ### {% linkable_title Example %} A full configuration example looks like the one below. From e25e553befd42a57193b092c6811dedb1c8006ab Mon Sep 17 00:00:00 2001 From: Lukas Barth Date: Sat, 13 Jan 2018 12:44:24 +0100 Subject: [PATCH 2/3] Remove stale comment --- source/_components/climate.mqtt.markdown | 1 - 1 file changed, 1 deletion(-) diff --git a/source/_components/climate.mqtt.markdown b/source/_components/climate.mqtt.markdown index d9ffe9f98ebd..8569080f4fec 100644 --- a/source/_components/climate.mqtt.markdown +++ b/source/_components/climate.mqtt.markdown @@ -187,7 +187,6 @@ For all `*_state_topic`s, a template can be specified that will be used to rende Say you receive the operation mode `"auto"` via your `mode_state_topic`, but the mode is actually called just `auto`, here's what you could do: ```yaml -# Full example configuration.yaml entry climate: - platform: mqtt name: Study From 848b687f8cc9a6939215df8762edb3e583ca6318 Mon Sep 17 00:00:00 2001 From: Fabian Affolter Date: Sun, 14 Jan 2018 13:52:39 +0100 Subject: [PATCH 3/3] Fix template --- source/_components/climate.mqtt.markdown | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/source/_components/climate.mqtt.markdown b/source/_components/climate.mqtt.markdown index 8569080f4fec..85675df1f624 100644 --- a/source/_components/climate.mqtt.markdown +++ b/source/_components/climate.mqtt.markdown @@ -176,16 +176,17 @@ aux_state_template: type: template {% endconfiguration %} -#### Optimistic mode +#### {% linkable_title Optimistic mode %} If a property works in *optimistic mode* (when the corresponding state topic is not set), home assistant will assume that any state changes published to the command topics did work and change the internal state of the entity immediately after publishing to the command topic. If it does not work in optimistic mode, the internal state of the entity is only updated when the requested update is confirmed by the device through the state topic. -#### Using Templates +#### {% linkable_title Using Templates %} For all `*_state_topic`s, a template can be specified that will be used to render the incoming payloads on these topics. Also, a default template that applies to all state topis can be specified as `value_template`. This can be useful if you received payloads are e.g. in JSON format. Since in JSON, a quoted string (e.g. `"foo"`) is just a string, this can also be used for unquoting. Say you receive the operation mode `"auto"` via your `mode_state_topic`, but the mode is actually called just `auto`, here's what you could do: +{% raw %} ```yaml climate: - platform: mqtt @@ -198,8 +199,9 @@ climate: mode_state_topic: "study/ac/mode/state" mode_state_template: "{{ value_json }}" ``` +{% endraw %} -This will parse the incoming `"auto"` as JSON, resulting in `auto`. Obvisouly, in this case you could also just set `value_template: "{{ value_json }}"`. +This will parse the incoming `"auto"` as JSON, resulting in `auto`. Obvisouly, in this case you could also just set `value_template: {% raw %}"{{ value_json }}"{% endraw %}`. ### {% linkable_title Example %}