Update MQTT documentation

source/components/automation.markdown

@@ -29,9 +29,9 @@ automation:
   service_data: {"message":"The sun has set"}
 ```
 
-## Setting up triggers
+## {% linkable_title Setting up triggers %}
 
-#### Time-based automation
+#### {% linkable_title Time-based automation %}
 This allows you to trigger actions whenever the time matches your filter. You can setup filters to match on hours, minutes and seconds. Any filter that you omit will match all values.
 
 Here are some example values:
@@ -49,7 +49,7 @@ Here are some example values:
   time_seconds: 0
 ```
 
-#### State-based automation
+#### {% linkable_title State-based automation %}
 This allows you to trigger actions based on state changes of any entity within Home Assistant. You can omit the `state_from` and `state_to` to match all.
 
 ```
@@ -76,7 +76,21 @@ This allows you to trigger actions based on state changes of any entity within H
   Use quotes around your values for <code>state_from</code> and <code>state_to</code> to avoid the YAML parser interpreting some values as booleans.
 </p>
 
-## Setting up the action
+#### {% linkable_title MQTT-based automation %}
+This allows you to trigger actions based on messages on an MQTT topic. You can specify an optional payload to match as well.
+
+```
+  # Match any changes to bathroom light
+  platform: mqtt
+  mqtt_topic: home/bathroom/light
+
+  # Match only if bathroom light is turned on
+  platform: mqtt
+  mqtt_topic: home/bathroom/light
+  mqtt_payload: 'on'
+```
+
+## {% linkable_title Setting up the action %}
 
 Currently the only supported action is calling a service. Services are what devices expose to be controlled, so this will allow us to control anything that Home Assistant can control.
 
@@ -95,7 +109,7 @@ Currently the only supported action is calling a service. Services are what devi
   service_data: {"message":"YAY"}
 ```
 
-## Putting it all together
+## {% linkable_title Putting it all together %}
 For every combination of a trigger and an action we will have to combine the configuration lines and add it to an `automation` component entry in `configuration.yaml`. You can add an optional `alias` key to the configuration to make the logs more understandable. To setup multiple entries, append 2, 3 etc to the section name. An example of a `configuration.yaml` file:
 
 ```

source/components/index.markdown

@@ -371,7 +371,7 @@ the manufacturers of these devices.
 </tr>
 
 <tr>
-  <td><a href='/components/mqtt.html'><img src='/images/supported_brands/preferences-system-sharing.png' class='brand overview' /></a></td>
+  <td><a href='/components/mqtt.html'><img src='/images/supported_brands/mqtt.png' class='brand overview' /></a></td>
   <td><a href='/components/mqtt.html'>MQTT</a></td>
   <td>Allow sending and recieving MQTT messages.</td>
 </tr>

source/components/mqtt.markdown

@@ -8,6 +8,7 @@ comments: false
 sharing: true
 footer: true
 ---
+<img src='/images/supported_brands/mqtt.png' class='brand pull-right' />
 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](http://mosquitto.org/) or [Mosca](http://www.mosca.io/). The Eclipse Foundation is running a public MQTT broker at [iot.eclipse.org](iot.eclipse.org) or the Mosquitto Project under [test.mosquitto.org](http://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.
@@ -18,21 +19,24 @@ To integrate MQTT into Home Assistant, add the following section to your `config
 # Example configuration.yaml entry
 mqtt:
   broker: IP_ADDRESS_BROKER
-```
-There are more optional entries available if your broker is using different settings or you have a special need.
-
-```yaml
-# Example configuration.yaml entry
-mqtt:
-  broker: 127.0.0.1
+  # All the other options are optional:
   port: 1883
-  topic: home-assistant
   keepalive: 60
   qos: 0
   username: your_username
   password: your_secret_password
 ```
-<img src='/images/supported_brands/preferences-system-sharing.png' class='brand pull-right' />
+
+<p class='note'>
+The MQTT component has no TLS support at the moment. This means that only plain-text communication is possible.
+</p>
+
+## Building on top of MQTT
+
+There are two ways to integrate MQTT into your process. One is by using the [MQTT-automation rule](/components/automation.html#mqtt-based-automation). The other one is by integrating it into a component. See the [MQTT example component](https://github.com/balloob/home-assistant/blob/dev/config/custom_components/mqtt_example.py) 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:
 
 ```bash
@@ -59,7 +63,3 @@ For reading all messages sent on the topic `home-assistant` to a broker running
 ```bash
 mosquitto_sub -h 127.0.0.1 -v -t "home-assistant/#"
 ```
-
-<p class='note'>
-The MQTT component has no TLS support at the moment. This means that only plain-text communication is possible.
-</p>