diff --git a/source/_docs/configuration/templating.markdown b/source/_docs/configuration/templating.markdown index bfa929f53f2..ae43aeed336 100644 --- a/source/_docs/configuration/templating.markdown +++ b/source/_docs/configuration/templating.markdown @@ -1284,7 +1284,7 @@ For actions, command templates are defined to format the outgoing MQTT payload t {% note %} -Example command template: +**Example command template with JSON data:** With given value `21.9` template {% raw %}`{"temperature": {{ value }} }`{% endraw %} renders to: @@ -1298,6 +1298,14 @@ Additional the MQTT entity attributes `entity_id`, `name` and `this` can be used {% endnote %} +**Example command template with raw data:** + +When a command template renders to a valid `bytes` literal, then MQTT will publish this data as raw data. In other cases, a string representation will be published. So: + +- Template {% raw %}`{{ "16" }}`{% endraw %} renders to payload encoded string `"16"`. +- Template {% raw %}`{{ 16 }}`{% endraw %} renders to payload encoded string `"16"`. +- Template {% raw %}`{{ pack(0x10, ">B") }}`{% endraw %} renders to a raw 1 byte payload `0x10`. + ## Some more things to keep in mind ### `entity_id` that begins with a number diff --git a/source/_integrations/mqtt.markdown b/source/_integrations/mqtt.markdown index 139e0e52bb1..975196aa93d 100644 --- a/source/_integrations/mqtt.markdown +++ b/source/_integrations/mqtt.markdown @@ -1110,9 +1110,13 @@ The MQTT integration will register the `mqtt.publish` action, which allows publi | ---------------------- | -------- | ------------------------------------------------------------ | | `topic` | no | Topic to publish payload to. | | `payload` | no | Payload to publish. | +| `evaluate_payload` | yes | If a `bytes` literal in `payload` should be evaluated to publish raw data. (default: false)| | `qos` | yes | Quality of Service to use. (default: 0) | | `retain` | yes | If message should have the retain flag set. (default: false) | +{% note %} +When `payload` is rendered from [template](/docs/configuration/templating/#using-templates-with-the-mqtt-integration) in a YAML script or automation, and the template renders to a `bytes` literal, the outgoing MQTT payload will only be sent as `raw` data, if the `evaluate_payload` option flag is set to `true`. +{% endnote %} {% important %} You must include either `topic` or `topic_template`, but not both. If providing a payload, you need to include either `payload` or `payload_template`, but not both.