home-assistant.io/source/_docs/mqtt/service.markdown
Martin Eberhardt 0660f3b349 Improve mqtt.publish service documentation (#8562)
Current documentation doesn't mention the qos or retain attributes.
2019-02-14 10:16:12 +01:00

1.7 KiB

layout, title, description, date, sidebar, comments, sharing, footer, logo
layout title description date sidebar comments sharing footer logo
page MQTT Publish service Instructions on how to setup the MQTT Publish service within Home Assistant. 2015-08-07 18:00 true false true true mqtt.png

The MQTT component will register the service mqtt.publish which allows publishing messages to MQTT topics. There are two ways of specifying your payload. You can either use payload to hard-code a payload or use payload_template to specify a template that will be rendered to generate the payload.

{% linkable_title Service mqtt.publish %}

Service data attribute Optional Description
topic no Topic to publish payload to.
payload yes Payload to publish.
payload_template yes Template to render as payload value. Ignored if payload given.
qos yes Quality of Service to use.
retain yes If message should have the retain flag set. (default: false)

You need to include either payload or payload_template, but not both.

{
  "topic": "home-assistant/light/1/command",
  "payload": "on"
}

{% raw %}

{
  "topic": "home-assistant/light/1/state",
  "payload_template": "{{ states('device_tracker.paulus') }}"
}

{% endraw %}

payload must be a string. If you want to send JSON then you need to format/escape it properly. Like:

{
  "topic": "home-assistant/light/1/state",
  "payload":"{\"Status\":\"off\", \"Data\":\"something\"}"
}

Example of how to use qos and retain:

{
  "topic": "home-assistant/light/1/command",
  "payload": "on",
  "qos": 2,
  "retain": true
}