MQTT

MQTT (aka MQ Telemetry Transport) is a machine-to-machine or “Internet of Things” connectivity protocol on top of TCP/IP. It allows extremely lightweight publish/subscribe messaging transport.

The MQTT component needs an MQTT broker like Mosquitto or Mosca. The Eclipse Foundation is running a public MQTT broker at iot.eclipse.org or the Mosquitto Project under test.mosquitto.org. If you prefer to use a public, keep in mind to adjust the topic and that your messages may be publicly accessible.

To integrate MQTT into Home Assistant, add the following section to your configuration.yaml file:

1
2
3
4
5
6
7
8
9

# Example configuration.yaml entry
mqtt:
  broker: IP_ADDRESS_BROKER
  # All the other options are optional:
  port: 1883
  keepalive: 60
  qos: 0
  username: your_username
  password: your_secret_password

The MQTT component has no TLS support at the moment. This means that only plain-text communication is possible.

Building on top of MQTT

There are two ways to integrate MQTT into your process. One is by using the MQTT-automation rule. The other one is by integrating it into a component. See the MQTT example component how to do this.

Testing

For debugging purposes mosquitto is shipping commandline tools to send and recieve MQTT messages. For sending test messages to a broker running on localhost:

1

mosquitto_pub -h 127.0.0.1 -t home-assistant/switch/1/on -m "Switch is ON"

Another way to send MQTT messages by hand is to use the “Developer Tools” in the Frontend. Choose “Call Service” and then mqtt/mqtt_send under “Available Services”. Enter something similar to the example below into the “Service Data” field.

1
2
3
4

{
   "topic":"home-assistant/switch/1/on",
   "payload":"Switch is ON"
}

The message should appear on the bus:

1

... [homeassistant] Bus:Handling <Event MQTT_MESSAGE_RECEIVED[L]: topic=home-assistant/switch/1/on, qos=0, payload=Switch is ON>

For reading all messages sent on the topic home-assistant to a broker running on localhost:

1

mosquitto_sub -h 127.0.0.1 -v -t "home-assistant/#"