Document publishing raw data in mqtt command templates and publish action (#34312)

* Document mqtt command template behavior

* Add `evalute_bytes` option to mqtt publish action

* rephrase

* Follow up on review

* Rename new option to evaluate_payload

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

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.