3.2 KiB
layout, title, description, date, sidebar, comments, sharing, footer
| layout | title | description | date | sidebar | comments | sharing | footer |
|---|---|---|---|---|---|---|---|
| page | MQTT | Instructions how to setup MQTT within Home Assistant. | 2015-08-07 18:00 | false | false | true | true |
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:
# Example configuration.yaml entry
mqtt:
broker: IP_ADDRESS_BROKER
port: 1883
client_id: home-assistant-1
keepalive: 60
username: USERNAME
password: PASSWORD
Configuration variables:
- broker (Required): The IP address of your MQTT broker, e.g. 192.168.1.32.
- port (Optional): The network port to connect to. Default is 1883.
- client_id (Optional): Client ID that Home Assistant will use. Has to be unique on the server. Default is a random generated one.
- keepalive (Optional): The keep alive in seconds for this client. Default is 60.
- username (Optional): The username to use with your MQTT broker.
- password (Optional): The corresponding password for the username to use with your MQTT broker.
The MQTT component has no TLS support at the moment. This means that only plain-text communication is possible.
Building on top of MQTT
- MQTT Sensor
- MQTT Switch
- MQTT Device Tracker
- MQTT-automation rule
- 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:
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.
{
"topic":"home-assistant/switch/1/on",
"payload":"Switch is ON"
}
The message should appear on the bus:
... [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:
mosquitto_sub -h 127.0.0.1 -v -t "home-assistant/#"