Rephrase MQTT template documentation (#35727)

This commit is contained in:
Erik Montnemery 2024-11-13 18:20:42 +01:00 committed by GitHub
parent ed149d216a
commit 4f2a793eaa
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194

View File

@ -1463,12 +1463,14 @@ To evaluate a response, go to **{% my developer_template title="Developer Tools
### Using templates with the MQTT integration
The [MQTT integration](/integrations/mqtt/) relies heavily on templates. Templates are used to transform incoming payloads (value templates) to status updates or incoming actions (command templates) to payloads that configure the MQTT device.
The [MQTT integration](/integrations/mqtt/) relies heavily on templates. Templates are used to transform incoming payloads (value templates) to state updates or incoming actions (command templates) to payloads that configure the MQTT device.
#### Using value templates with MQTT
For incoming data a value template translates incoming JSON or raw data to a valid payload.
Incoming payloads are rendered with possible JSON values, so when rendering the `value_json` can be used access the attributes in a JSON based payload.
Value templates translate received MQTT payload to a valid state or attribute.
The received MQTT is available in the `value` template variable, and in the `value_json` template variable if the received MQTT payload is valid JSON.
In addition, the template variables `entity_id`, `name` and `this` are available for MQTT entity value templates. The `this` attribute refers to the [entity state](/docs/configuration/state_object) of the MQTT item.
{% note %}
@ -1482,13 +1484,13 @@ With given payload:
Template {% raw %}`{{ value_json.temperature | round(1) }}`{% endraw %} renders to `21.9`.
Additional the MQTT entity attributes `entity_id`, `name` and `this` can be used as variables in the template. The `this` attribute refers to the [entity state](/docs/configuration/state_object) of the MQTT item.
{% endnote %}
#### Using command templates with MQTT
For actions, command templates are defined to format the outgoing MQTT payload to the device. When an action is executed, `value` can be used to generate the correct payload to the device.
For actions, command templates are defined to format the outgoing MQTT payload to a format supported by the remote device. When an action is executed, the template variable `value` has the action data in most cases unless otherwise specified in the documentation.
In addition, the template variables `entity_id`, `name` and `this` are available for MQTT entity command templates. The `this` attribute refers to the [entity state](/docs/configuration/state_object) of the MQTT item.
{% note %}
@ -1502,8 +1504,6 @@ With given value `21.9` template {% raw %}`{"temperature": {{ value }} }`{% endr
}
```
Additional the MQTT entity attributes `entity_id`, `name` and `this` can be used as variables in the template. The `this` attribute refers to the [entity state](/docs/configuration/state_object) of the MQTT item.
{% endnote %}
**Example command template with raw data:**