Merge branch 'current' into next

_config.yml

@@ -73,11 +73,7 @@ collections:
     output: true
   cookbook:
     output: true
-  ecosystem:
-    output: true
-  details:
-    output: true
-  topics:
+  docs:
     output: true
 
 # ----------------------- #

source/_components/mqtt.markdown

@@ -16,295 +16,30 @@ ha_iot_class: depends
 
 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.
 
-To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file:
+Your first step to get MQTT and Home Assistant working is the choose a [broker](/docs/mqtt/broker).
+
+To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file. Keep in mind that the minimal setup will run with [an embedded MQTT broker](/docs/mqtt/broker#embedded-broker):
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+```
+
+To connect to your [own MQTT broker](/docs/mqtt/broker#run-your-own):
 
 ```yaml
 # Example configuration.yaml entry
 mqtt:
   broker: IP_ADDRESS_BROKER
-  port: 1883
-  client_id: home-assistant-1
-  keepalive: 60
-  username: USERNAME
-  password: PASSWORD
-  certificate: /home/paulus/dev/addtrustexternalcaroot.crt
-  protocol: 3.1
-  discovery: "discovery/#"
-  birth_message:
-    topic: 'hass/status'
-    payload: 'online'
-    qos: 1
-    retain: true
-  will_message:
-    topic: 'hass/status'
-    payload: 'offline'
-    qos: 1
-    retain: true
 ```
 
-Configuration variables:
+## {% linkable_title Additional features %}
 
-- **broker** (*Required*): The IP address or hostname of your MQTT broker, e.g. 192.168.1.32.
-- **port** (*Optional*): The network port to connect to. Default is 1883.
-- **client_id** (*Optional*): The client ID that Home Assistant will use. Has to be unique on the server. Default is a randomly generated one.
-- **keepalive** (*Optional*): The time in seconds between sending keep alive messages 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.
-- **certificate** (*Optional*): The certificate authority certificate file that is to be treated as trusted by this client. This file should contain the root certificate of the certificate authority that signed your broker's certificate, but may contain multiple certificates. Example: `/home/user/identrust-root.pem`
-- **client_key** (*Optional*): Client key (example: `/home/user/owntracks/cookie.key`)
-- **client_cert** (*Optional*): Client certificate (example: `/home/user/owntracks/cookie.crt`)
-- **protocol** (*Optional*): Protocol to use: 3.1 or 3.1.1. By default it connects with 3.1.1 and falls back to 3.1 if server does not support 3.1.
-- **discovery** (*Optional*): The MQTT topic subscribed to use for discovery of MQTT devices.
-- **birth_message** (*Optional*):
-  - **topic** (*Required*): The MQTT topic to publish the message.
-  - **payload** (*Required*): The message content.
-  - **qos** (*Optional*): The maximum QoS level of the topic. Default is 0.
-  - **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `True`.
-- **will_message** (*Optional*):
-  - **topic** (*Required*): The MQTT topic to publish the message.
-  - **payload** (*Required*): The message content.
-  - **qos** (*Optional*): The maximum QoS level of the topic. Default is 0.
-  - **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `True`.
+- [Certificate](/docs/mqtt/certificate/)
+- [Discovery](/docs/mqtt/discovery/)
+- [Publish service](/docs/mqtt/service/)
+- [Birth and last will messages](/docs/mqtt/birth_will/)
+- [Testing your setup](/docs/mqtt/testing/)
+- [Logging](/docs/mqtt/logging/)
+- [Processing JSON](/docs/mqtt/processing_json/)
 
-## {% linkable_title Picking a broker %}
-
-The MQTT component needs you to run an MQTT broker for Home Assistant to connect to. There are four options, each with various degrees of ease of setup and privacy.
-
-### {% linkable_title Embedded broker %}
-
-Home Assistant contains an embedded MQTT broker. If no broker configuration is given, the [HBMQTT broker](https://pypi.python.org/pypi/hbmqtt) is started and Home Assistant connects to it. Embedded broker default configuration:
-
-| Setting | Value |
-| ------- | ----- |
-| Host | localhost
-| Port | 1883
-| Protocol | 3.1.1
-| User | homeassistant
-| Password | Your API [password](/components/http/)
-| Websocket port | 8080
-
-```yaml
-# Example configuration.yaml entry
-mqtt:
-```
-
-<p class='note'>
-This broker does not currently work with OwnTracks because of a protocol version issue.
-</p>
-
-If you want to customize the settings of the embedded broker, use `embedded:` and the values shown in the [HBMQTT Broker configuration](http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration). This will replace the default configuration.
-
-```yaml
-# Example configuration.yaml entry
-mqtt:
-  embedded:
-    # Your HBMQTT config here. Example at:
-    # http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration
-```
-
-### {% linkable_title Run your own %}
-
-This is the most private option but requires a bit more work. There are two free and open-source brokers to pick from: [Mosquitto](http://mosquitto.org/) and [Mosca](http://www.mosca.io/).
-
-```yaml
-# Example configuration.yaml entry
-mqtt:
-  broker: 192.168.1.100
-  port: 1883
-  client_id: home-assistant-1
-  keepalive: 60
-  username: USERNAME
-  password: PASSWORD
-```
-
-<p class='note warning'>
-There is an issue with the Mosquitto package included in Ubuntu 14.04 LTS. Specify `protocol: 3.1` in your MQTT configuration to work around this issue.
-</p>
-
-<p class='note'>
-If you are running a mosquitto instance on a different server with proper SSL encryption using a service like letsencrypt you may have to set the certificate to the operating systems own `.crt` certificates file. In the instance of ubuntu this would be `certificate: /etc/ssl/certs/ca-certificates.crt`
-</p>
-
-### {% linkable_title Public broker %}
-
-The Mosquitto project runs a [public broker](http://test.mosquitto.org). This is the easiest to set up, but there is no privacy as all messages are public. Use this only for testing purposes and not for real tracking of your devices.
-
-```yaml
-mqtt:
-  broker: test.mosquitto.org
-  port: 1883
-
-  # Optional, replace port 1883 with following if you want encryption
-  # (doesn't really matter because broker is public)
-  port: 8883
-  # Download certificate from http://test.mosquitto.org/ssl/mosquitto.org.crt
-  certificate: /home/paulus/downloads/mosquitto.org.crt
-```
-
-### {% linkable_title CloudMQTT %}
-
-[CloudMQTT](https://www.cloudmqtt.com) is a hosted private MQTT instance that is free for up to 10 connected devices. This is enough to get started with for example [OwnTracks](/components/device_tracker.owntracks/) and give you a taste of what is possible.
-
-<p class='note'>
-Home Assistant is not affiliated with CloudMQTT nor will receive any kickbacks.
-</p>
-
- 1. [Create an account](https://customer.cloudmqtt.com/login) (no payment details needed)
- 2. [Create a new CloudMQTT instance](https://customer.cloudmqtt.com/subscription/create)
-    (Cute Cat is the free plan)
- 3. From the control panel, click on the _Details_ button.
- 4. Create unique users for Home Assistant and each phone to connect<br>(CloudMQTT does not allow two
-    connections from the same user)
-      1. Under manage users, fill in username, password and click add
-      2. Under ACLs, select user, topic `#`, check 'read access' and 'write access'
- 5. Copy the instance info to your configuration.yaml:
-
-```yaml
-mqtt:
-  broker: <Server>
-  port: <SSL Port>
-  username: <User>
-  password: <Password>
-```
-
-<p class='note'>
-Home Assistant will automatically load the correct certificate if you connect to an encrypted channel of CloudMQTT (port range 20 000 - 30 000).
-</p>
-
-## {% linkable_title Building on top of MQTT %}
-
- - [MQTT Alarm control panel](/components/alarm_control_panel.mqtt/)
- - [MQTT Binary sensor](/components/binary_sensor.mqtt/)
- - [MQTT Sensor](/components/sensor.mqtt/)
- - [MQTT Switch](/components/switch.mqtt/)
- - [MQTT Light](/components/light.mqtt/)
- - [MQTT Lock](/components/lock.mqtt/)
- - [MQTT Device Tracker](/components/device_tracker.mqtt/)
- - [OwnTracks Device Tracker](/components/device_tracker.owntracks/)
- - [MQTT automation rule](/getting-started/automation-trigger/#mqtt-trigger)
-
- - Integrating it into own component. See the [MQTT example component](/cookbook/python_component_mqtt_basic/) how to do this.
-
-## {% linkable_title Publish service %}
-
-The MQTT component will register the service `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](/topics/templating/) that will be rendered to generate the payload.
-
-```json
-{
-  "topic": "home-assistant/light/1/command",
-  "payload": "on"
-}
-```
-
-```json
-{
-  "topic": "home-assistant/light/1/state",
-  "payload_template": "{% raw %}{{ states('device_tracker.paulus') }}{% endraw %}"
-}
-```
-
-## {% linkable_title Discovery %}
-
-The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](/components/binary_sensor.http/) and the [HTTP sensor](/components/sensor.http/). Only support for binary sensor is available at the moment.
-
-To enable MQTT discovery, add the following to your `configuration.yaml` file:
-
-```yaml
-# Example configuration.yaml entry
-mqtt:
-  discovery: true
-  # Optional
-  discovery_prefix: homeassistant
-```
-
-A motion detection device for your garden would sent its configuration as JSON payload `{"name": "garden", "device_class": "motion"}` to the topic `homeassistant/binary_sensor/garden/config`. After the first message to `config`, then the MQTT messages sent to `state`, eg. `homeassistant/binary_sensor/garden/state`, will update the state in Home Assistant.
-
-## {% linkable_title Logging %}
-
-The [logger](/components/logger/) component allow the logging of received MQTT messages.
-
-```yaml
-# Example configuration.yaml entry
-logger:
-  default: warning
-  logs:
-    homeassistant.components.device_tracker.mqtt: debug
-```
-
-## {% linkable_title Testing your setup %}
-
-The `mosquitto` broker package ships commandline tools to send and receive MQTT messages. As an alternative have a look at [hbmqtt_pub](http://hbmqtt.readthedocs.org/en/latest/references/hbmqtt_pub.html) and [hbmqtt_sub](http://hbmqtt.readthedocs.org/en/latest/references/hbmqtt_sub.html) which are provided by HBMQTT. For sending test messages to a broker running on localhost check the example below:
-
-```bash
-$ mosquitto_pub -h 127.0.0.1 -t home-assistant/switch/1/on -m "Switch is ON"
-```
-
-If you are using the embedded MQTT broker, the command looks a little different because you need to add the MQTT protocol version.
-
-```bash
-$ mosquitto_pub -V mqttv311 -t "hello" -m world
-```
-
-or if you are using a API password:
-
-```bash
-$ mosquitto_pub -V mqttv311 -u homeassistant -P <your api password> -t "hello" -m world
-```
-
-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.
-
-```json
-{
-   "topic":"home-assistant/switch/1/on",
-   "payload":"Switch is ON"
-}
-```
-
-The message should appear on the bus:
-
-```bash
-... [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:
-
-```bash
-$ mosquitto_sub -h 127.0.0.1 -v -t "home-assistant/#"
-```
-
-For the embedded MQTT broker the command looks like:
-
-```bash
-$ mosquitto_sub -v -V mqttv311 -t "#"
-```
-
-Add the username `homeassistant` and your API password if needed.
-
-## {% linkable_title Processing JSON %}
-
-The MQTT switch and sensor platforms support processing JSON over MQTT messages and parsing them using JSONPath. JSONPath allows you to specify where in the JSON the value resides that you want to use. The following examples will always return the value `100`.
-
-| JSONPath query | JSON |
-| -------------- | ---- |
-| `somekey` | `{ 'somekey': 100 }`
-| `somekey[0]` | `{ 'somekey': [100] }`
-| `somekey[0].value` | `{ 'somekey': [ { value: 100 } ] }`
-
-To use this, add the following key to your `configuration.yaml`:
-
-```yaml
-switch:
-  platform: mqtt
-  state_format: 'json:somekey[0].value'
-```
-It is also possible to extract JSON values by using a value template:
-
-```yaml
-switch:
-  platform: mqtt
-  value_template: '{% raw %}{{ value_json.somekey[0].value }}{% endraw %}'
-```
-
-More information about the full JSONPath syntax can be found [here][JSONPath syntax].
-
-[JSONPath syntax]: https://github.com/kennknowles/python-jsonpath-rw#jsonpath-syntax

source/_components/zwave.markdown

@@ -12,6 +12,11 @@ ha_category: Hub
 featured: true
 ---
 
-Please see the [getting started section] for in-depth documentation on how to use the Z-Wave component.
+The [Z-Wave](http://www.z-wave.com/) integration for Home Assistant allows you to observe and control connected Z-Wave devices. Please see the [Z-Wave getting started section](/docs/z-wave/) for in-depth documentation on how to use and setup the Z-Wave component.
 
-[getting started section]: /getting-started/z-wave/
+If you have setup the requirements, then add the following entry `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+zwave:
+```

source/_docs/automation.markdown

@@ -0,0 +1,49 @@
+---
+layout: page
+title: "Automating Home Assistant"
+description: "Steps to help you get automation setup in Home Assistant."
+date: 2015-09-19 09:40
+sidebar: true
+comments: false
+sharing: true
+footer: true
+---
+
+Home Assistant offers a wide range of automation configurations. In this section, we'll try to guide you through all the different possibilities and options. Besides this documentation, there are also a couple of people who have made their automations [publicly available][/cookbook/#example-configurationyaml].
+
+### {% linkable_title Automation basics %}
+
+Before you can go ahead and create your own automations, it's important to learn the basics. To explore these, let's have a look at the following example home automation rule:
+
+```text
+(trigger)    When Paulus arrives home
+(condition)  and it is after sunset:
+(action)     Turn the lights in the living room on
+```
+
+The example consists of three different parts: a [trigger](/docs/automation/trigger/), a [condition](/docs/automation/condition/) and an [action](/docs/automation/action/).
+
+The first line is the **trigger** of the automation rule. Triggers describe events that should trigger the automation rule. In this case, it is a person arriving home, which can be observed in Home Assistant by observing the state of Paulus changing from 'not_home' to 'home'.
+
+The second line is the **condition**. Conditions are optional tests that can limit an automation rule to only work in your specific use cases. A condition will test against the current state of the system. This includes the current time, devices, people and other things like the sun. In this case, we only want to act when the sun has set.
+
+The third part is the **action**, which will be performed when a rule is triggered and all conditions are met. For example, it can turn a light on, set the temperature on your thermostat or activate a scene.
+
+<p class='note'>
+The difference between a condition and a trigger can be confusing as they are very similar. Triggers look at the actions, while conditions look at the results: turning a light on versus a light being on.
+</p>
+
+### {% linkable_title Exploring the internal state %}
+
+Automation rules interact directly with the internal state of Home Assistant, so you'll need to familiarize yourself with it. Home Assistant exposes its current state via the developer tools. These are available at the bottom of the sidebar in the frontend. The <img src='/images/screenshots/developer-tool-states-icon.png' class='no-shadow' height='38' /> icon will show all currently available states. An entity can be anything. A light, a switch, a person and even the sun. A state consists of the following parts:
+
+| Name | Description | Example |
+| ---- | ----- | ---- |
+| Entity ID | Unique identifier for the entity. | `light.kitchen`
+| State | The current state of the device. | `home`
+| Attributes | Extra data related to the device and/or current state. | `brightness`
+
+State changes can be used as the source of triggers and the current state can be used in conditions.
+
+Actions are all about calling services. To explore the available services open the <img src='/images/screenshots/developer-tool-services-icon.png' class='no-shadow' height='38' /> Services developer tool. Services allow to change anything. For example turn on a light, run a script or enable a scene. Each service has a domain and a name. For example the service `light.turn_on` is capable of turning on any light in your system. Services can be passed parameters to for example tell which device to turn on or what color to use.
+

source/_docs/automation/action.markdown

@@ -7,14 +7,12 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/automation-action/
 ---
 
-The action of an automation rule is what is being executed when a rule fires. The action part follows the [script syntax] which can be used to interact with anything via services or events. For services you can specify the entity_id that it should apply to and optional service parameters (to specify for example the brightness).
+The action of an automation rule is what is being executed when a rule fires. The action part follows the [script syntax](/docs/scripts/) which can be used to interact with anything via services or events. For services you can specify the entity_id that it should apply to and optional service parameters (to specify for example the brightness).
 
-You can also call the service to activate [a scene] which will allow you to define how you want your devices to be and have Home Assistant call the right services.
-
-[script syntax]: /getting-started/scripts/
-[a scene]: /components/scene/
+You can also call the service to activate [a scene](/components/scene/) which will allow you to define how you want your devices to be and have Home Assistant call the right services.
 
 ```yaml
 automation:
@@ -69,4 +67,4 @@ automation:
           value_template: '{% raw %}{{ states.sensor.sensorluz_7_0.state < 10 }}{% endraw %}'
     - service: scene.turn_on
       entity_id: scene.DespiertaDespacho
-```
+```

source/_docs/automation/condition.markdown

@@ -7,11 +7,12 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/automation-condition/
 ---
 
 Conditions are an optional part of an automation rule and can be used to prevent an action from happening when triggered. Conditions look very similar to triggers but are very different. A trigger will look at events happening in the system while a condition only looks at how the system looks right now. A trigger can observe that a switch is being turned on. A condition can only see if a switch is currently on or off.
 
-The available conditions for an automation are the same as for the script syntax so see that page for a [full list of available conditions][script-condition].
+The available conditions for an automation are the same as for the script syntax so see that page for a [full list of available conditions](/docs/scripts/conditions/).
 
 Example of using condition:
 
@@ -33,4 +34,3 @@ Example of using condition:
       entity_id: scene.DespiertaDespacho
 ```
 
-[script-condition]: /getting-started/scripts-conditions/

source/_docs/automation/examples.markdown

@@ -7,8 +7,11 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/automation-examples/
 ---
 
+Just some sample automation rules to get you started.
+
 ```yaml
 # Example of entry in configuration.yaml
 automation:

source/_docs/automation/templating.markdown

@@ -7,11 +7,12 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/automation-templating/
 ---
 
 In Home Assistant 0.19 we introduced a new powerful feature: variables in scripts and automations. This makes it possible to adjust your condition and action based on the information of the trigger.
 
-The trigger data made is available during [template](/topics/templating/) rendering as the `trigger` variable.
+The trigger data made is available during [template](/configuration/templating/) rendering as the `trigger` variable.
 
 ```yaml
 # Example configuration.yaml entries
@@ -127,4 +128,4 @@ The following tables show the available trigger data per platform.
 | `trigger.zone` | State object of zone
 | `trigger.event` | Event that trigger observed: `enter` or `leave`.
 
-[state object]: /topics/state_object/
+[state object]: /configuration/state_object/

source/_docs/automation/trigger.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/automation-trigger/
 ---
 
 Triggers are what starts the processing of an automation rule. It is possible to specify multiple triggers for the same rule. Once a trigger starts, Home Assistant will validate the conditions, if any, and call the action.

source/_docs/automation/troubleshooting.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/automation-troubleshooting/
 ---
 
 You can verify that your automation rules are being initialized correctly by watching both the realtime logs (`homeassistant.log` in the configuration directory) and also the [Logbook](/components/logbook/). The realtime logs will show the rules being initialized (once for each trigger), example:

source/_docs/autostart.markdown

@@ -7,11 +7,13 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/autostart/
 ---
 
 Once you get started with Home Assistant you want it to start automatically when you launch your machine. To help you get started we've compiled a few guides for different systems.
 
- - [Linux - systemd](/getting-started/autostart-systemd/)
- - [Linux - Upstart](/getting-started/autostart-upstart/)
- - [macOS](/getting-started/autostart-macos/)
- - [Synology NAS](/getting-started/autostart-synology/)
+ - [systemd (Linux)](/docs/autostart/systemd/)
+ - [Upstart (Linux)](/docs/autostart/upstart/)
+ - [init.d (Linux)](/docs/autostart/init.d/)
+ - [macOS](/docs/autostart/macos/)
+ - [Synology NAS](/docs/autostart/synology/)

source/_docs/autostart/init.d.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/autostart-init.d/
 ---
 
 Home Assistant can run as a daemon within init.d with the script below.
@@ -17,8 +18,8 @@ Copy the script at the end of this page to `/etc/init.d/hass-daemon`.
 
 After that, set the script to be executable:
 
-```
-sudo chmod +x /etc/init.d/hass-daemon
+```bash
+$ sudo chmod +x /etc/init.d/hass-daemon
 ```
 
 ### {% linkable_title 2. Select a user. %}
@@ -27,14 +28,14 @@ Create or pick a user that the Home Assistant daemon will run under. Update scri
 
 ### {% linkable_title 3. Register the daemon with Linux %}
 
-```
-sudo update-rc.d hass-daemon defaults
+```bash
+$ sudo update-rc.d hass-daemon defaults
 ```
 
 ### {% linkable_title 4. Install this service %}
 
-```
-sudo service hass-daemon install
+```bash
+$ sudo service hass-daemon install
 ```
 
 ### {% linkable_title 5. Restart Machine %}
@@ -49,7 +50,7 @@ If any commands need to run before executing hass (like loading a virutal enviro
 
 ### {% linkable_title Daemon script %}
 
-```
+```bash
 #!/bin/sh
 ### BEGIN INIT INFO
 # Provides:          hass
@@ -134,4 +135,4 @@ case "$1" in
   *)
     echo "Usage: $0 {start|stop|restart|install|uninstall}"
 esac
-```
+```

source/_docs/autostart/macos.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/autostart-macos/
 ---
 
 Setting up Home Assistant to run as a background service is simple; macOS will start Home Assistant on boot and make sure it's always running.

source/_docs/autostart/synology.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/autostart-synology/
 ---
 
 To get Home Assistant to automatically start when you boot your Synology NAS:

source/_docs/autostart/systemd.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/autostart-systemd/
 ---
 
 Newer linux distributions are trending towards using `systemd` for managing daemons. Typically, systems based on Fedora, ArchLinux, or Debian (8 or later) use `systemd`. This includes Ubuntu releases including and after 15.04, CentOS, and Red Hat. If you are unsure if your system is using `systemd`, you may check with the following command:
@@ -20,7 +21,7 @@ If the preceding command returns the string `systemd`, you are likely using `sys
 If you want Home Assistant to be launched automatically, an extra step is needed to setup `systemd`. You need a service file to control Home Assistant with `systemd`. If you are using a Raspberry Pi with Raspbian then replace the `[your user]` with `pi` otherwise use your user you want to run Home Assistant. `ExecStart` contains the path to `hass` and this may vary. Check with `whereis hass` for the location.
 
 ```bash
-$ su -c 'cat <<EOF >> /etc/systemd/system/home-assistant@[your user].service
+$ su -c 'cat <<EOF >> /etc/systemd/system/home-assistant@.service
 [Unit]
 Description=Home Assistant
 After=network.target
@@ -45,7 +46,7 @@ After=network.target
 [Service]
 Type=simple
 User=homeassistant
-#make sure the virtualenv python binary is used
+# Make sure the virtualenv Python binary is used
 Environment=VIRTUAL_ENV="/srv/homeassistant"
 Environment=PATH="$VIRTUAL_ENV/bin:$PATH"
 ExecStart=/srv/homeassistant/bin/hass -c "/home/homeassistant/.homeassistant"

source/_docs/backend.markdown

@@ -0,0 +1,17 @@
+---
+layout: page
+title: "Backend of Home Assistant"
+description: "Backend of Home Assistant."
+date: 2017-02-14 12:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+---
+
+The frontend of Home Assistant is running with [Python 3](https://www.python.org/). 
+
+The [Architecture page](/developers/architecture/) show the details about the elements running in the background of Home Assistant.
+
+To implement a new platform or component, please refer to the [Development documentation](/developers/development/).
+

source/_docs/backend/database.markdown

@@ -3,10 +3,11 @@ layout: page
 title: "Database"
 description: "Details about the database which Home Assistant is using."
 date: 2016-10-10 10:00
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /details/database/
 ---
 
 The default database that is used for Home Assistant is [SQLite](https://www.sqlite.org/) and is stored in your [configuration directory](/getting-started/configuration/), eg. `<path to config dir>/.homeassistant/home-assistant_v2.db`. You will need an installation of `sqlite3`, the command-line for SQLite database, or [DB Browser for SQLite](http://sqlitebrowser.org/) which provide an editor for executing SQL commands.

source/_docs/backend/updater.markdown

@@ -3,10 +3,11 @@ layout: page
 title: "Updater"
 description: "Details what the updater component is reporting about your Home Assistant instance."
 date: 2016-10-22 08:00
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /details/updater/
 ---
 
 Starting with 0.31 the [updater component](/components/updater/) sends an optional report about Home Assistant instance.

source/_docs/configuration.markdown

@@ -0,0 +1,35 @@
+---
+layout: page
+title: "Configuring Home Assistant"
+description: "Configuring Home Assistant."
+date: 2015-03-23 12:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+---
+
+When launched for the first time, Home Assistant will write a default configuration file enabling the web interface and device discovery. It can take up to a minute for your devices to be discovered and appear in the user interface.
+
+The location of the folder differs between operating systems:
+
+| OS | Path |
+| -- | ---- |
+| macOS | `~/.homeassistant` |
+| Linux | `~/.homeassistant` |
+| Windows | `%APPDATA%/.homeassistant` |
+
+If you want to use a different folder for configuration, use the config command line parameter: `hass --config path/to/config`.
+
+Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains components to be loaded with their configurations. Throughout the documentation you will find snippets that you can add to your configuration file to enable functionality.
+
+<p class='note'>
+  You will have to restart Home Assistant for changes to `configuration.yaml` to take effect.
+</p>
+
+If you run into trouble while configuring Home Assistant, have a look at the [configuration troubleshooting page](/getting-started/troubleshooting-configuration/) and at the [configuration.yaml examples](/cookbook/#example-configurationyaml).
+
+<p class='note tip'>
+  Test any changes to your configuration files from the command line with `hass --script check_config`. This script allows you to test changes without the need to restart Home Assistant.
+</p>
+

source/_docs/configuration/basic.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/basic/
 ---
 
 By default, Home Assistant will try to detect your location from IP address geolocation. Home Assistant will automatically select a temperature unit and time zone based on this location. You can overwrite this by adding the following information to your `configuration.yaml`:
@@ -48,19 +49,3 @@ If you decide to expose your Home Assistant instance to the internet and forget
 
 See the [HTTP component documentation](/components/http/) for more options, such as the use of HTTPS encryption.
 
-### {% linkable_title Setting up your phone or tablet %}
-
-Home Assistant runs as a self-hosted web application and can be pinned to your home screen (with the new W3C standard). If you're on Android, follow [the visual guide]({{site_root}}/getting-started/android/). For other devices, open Home Assistant on your mobile browser and tap the "Add to Home Screen" (or similar) option.
-### {% linkable_title Remote access %}
-
-If you're interested in logging in to Home Assistant while away, you'll have to make your instance remotely accessible.
-
-The most common approach is to set up port forwarding from your router to port 8123 on the computer that is hosting Home Assistant. General instructions on how to do this can be found by searching `<router model> port forwarding instructions`.
-
-A problem with making a port accessible is that some Internet Service Providers only offer dynamic IPs. This can cause you to lose access to Home Assistant while away. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/).
-
-Remember: just putting a port up is not secure. You should definitely consider encrypting your traffic if you are accessing your Home Assistant installation remotely. For details please check the [set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post.
-
-If you want the very best security, check out [the instructions how to use Tor to access your home](/cookbook/tor_configuration/).
-
-### [Next step: Setting up devices &raquo;](/getting-started/devices/)

source/_docs/configuration/customizing-devices.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/customizing-devices/
 ---
 
 By default, all of your devices will be visible and have a default icon determined by their domain. You can customize the look and feel of your front page by altering some of these parameters. This can be done by overriding attributes of specific entities.
@@ -52,6 +53,12 @@ Device class is currently supported by the following platforms:
 * [Binary Sensor](/components/binary_sensor/)
 * [Cover](/components/cover/)
 
+### {% linkable_title Device Class %}
+
+Device class is currently supported by the following platforms:
+
+* [Binary Sensor](/components/binary_sensor/)
+* [Cover](/components/cover/)
 
 ### {% linkable_title Reloading customize %}
 
@@ -61,4 +68,3 @@ Home Assistant offers a service to reload the core configuration while Home Assi
 New customize information will be applied the next time the state of the entity gets updated.
 </p>
 
-### [Next step: Setting up presence detection &raquo;](/getting-started/presence-detection/)

source/_docs/configuration/devices.markdown

@@ -7,9 +7,10 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/devices/
 ---
 
-Home Assistant will be able to automatically discover many devices and services available on your network if you have [the discovery component]({{site_root}}/components/discovery/) enabled (the default setting).
+Home Assistant will be able to automatically discover many devices and services available on your network if you have [the discovery component](/components/discovery/) enabled (the default setting).
 
 See the [components overview page](/components/) to find installation instructions for your devices and services. If you can't find support for your favorite device or service, [consider adding support](/developers/add_new_platform/).
 
@@ -53,8 +54,8 @@ camera 2:
 
 ### {% linkable_title Grouping devices %}
 
-Once you have several devices set up, it is time to organize them into groups.  
-Each group consists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface by using the Set State page in the Developer Tools (![<>](https://cdn.rawgit.com/Templarian/MaterialDesign/master/icons/svg/code-tags.svg)).
+Once you have several devices set up, it is time to organize them into groups.
+Each group consists of a name and a list of entity IDs. Entity IDs can be retrieved from the web interface by using the Set State page in the Developer Tools (<img src='/images/screenshots/developer-tool-states-icon.png' alt='service developer tool icon' class="no-shadow" height="38" />).
 
 ```yaml
 # Example configuration.yaml entry showing two styles
@@ -65,6 +66,5 @@ group:
     - media_player.nexus_player
 ```
 
-For more details please check the [Group](https://home-assistant.io/components/group/) page.
+For more details please check the [Group](/components/group/) page.
 
-### [Next step: Customizing devices and services &raquo;](/getting-started/customizing-devices/)

source/_docs/configuration/events.markdown

@@ -3,10 +3,11 @@ layout: page
 title: "Events"
 description: "Describes all there is to know about events in Home Assistant."
 date: 2016-03-12 12:00 -0800
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /topics/events/
 ---
 
 The core of Home Assistant is the event bus. The event bus allows any component to fire or listen for events. It is the core of everything. For example, any state change will be announced on the event bus as a `state_changed` event containing the previous and the new state of an entity.

source/_docs/configuration/group_visibility.markdown

@@ -3,10 +3,11 @@ layout: page
 title: "Group Visibility"
 description: "Instructions how to change group visibility using automations."
 date: 2016-10-29 13:00
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /topics/group_visibility/
 ---
 
 After filling Home Assistant with all your precious home automation devices, you usually end up with a cluttered interface and lots of groups that are not interesting in your current context. What if you just want to show groups that are interesting _now_ and hide the rest? That's when group visibility comes to play.

source/_docs/configuration/packages.markdown

@@ -3,13 +3,14 @@ layout: page
 title: "Packages"
 description: "Describes all there is to know about configuration packages in Home Assistant."
 date: 2017-01-10 20:00 +0200
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /topics/packages/
 ---
 
-Packages in Home Assistant provides a way to bundle different component's configuration together. We were already introduced to the two configuration styles (specifying platforms entries together or individually) on the [adding devices](/getting-started/devices/) page. Both of these configuration methods require you to create the component key in the main `configuration.yaml` file. With packages we have a way to include different components, or parts of configuration using any of the `!include` directives introduced in [splitting the configuration](/topics/splitting_configuration).
+Packages in Home Assistant provides a way to bundle different component's configuration together. We were already introduced to the two configuration styles (specifying platforms entries together or individually) on the [adding devices](/docs/configuration/devices/) page. Both of these configuration methods require you to create the component key in the main `configuration.yaml` file. With packages we have a way to include different components, or parts of configuration using any of the `!include` directives introduced in [splitting the configuration](/docs/configuration/splitting_configuration).
 
 Packages are configured under the core `homeassistant/packages` in the configuration and take the format of a packages name (no spaces, all lower case) followed by a dictionary with the package config. For example, package `pack_1` would be created as:
 
@@ -88,4 +89,4 @@ homeassistant:
 ```
 
 This uses the concept splitting the configuration and will include all files in a directory with the keys representing the filenames.
-See the documentation about [splitting the configuration](/topics/splitting_configuration/) for more information about `!include_dir_named` and other include statements that might be helpful.
+See the documentation about [splitting the configuration](/docs/configuration/splitting_configuration/) for more information about `!include_dir_named` and other include statements that might be helpful.

source/_docs/configuration/platform_options.markdown

@@ -3,10 +3,11 @@ layout: page
 title: "Entity component platform options"
 description: "Shows how to customize polling interval for any component via configuration.yaml."
 date: 2016-02-12 23:17 -0800
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /topics/platform_options/
 ---
 
 Any component that is based on the entity component allows various extra options to be set per platform.

source/_docs/configuration/remote.markdown

@@ -0,0 +1,24 @@
+---
+layout: page
+title: "Remote access"
+description: "Setting up remote access for Home Assistant."
+date: 2015-03-23 12:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/basic/#remote-access
+---
+
+If you're interested in logging in to Home Assistant while away, you'll have to make your instance remotely accessible.
+
+The most common approach is to set up port forwarding from your router to port 8123 on the computer that is hosting Home Assistant. General instructions on how to do this can be found by searching `<router model> port forwarding instructions`.
+
+A problem with making a port accessible is that some Internet Service Providers only offer dynamic IPs. This can cause you to lose access to Home Assistant while away. You can solve this by using a free Dynamic DNS service like [DuckDNS](https://www.duckdns.org/).
+
+Remember: Just putting a port up is not secure. You should definitely consider encrypting your traffic if you are accessing your Home Assistant installation remotely. For details please check the [set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post.
+
+Protect your communication with a [self-signed certificate](/cookbook/tls_self_signed_certificate/) between your client and the Home Assistant instance.
+
+For another way to access your Home Assistant frontend, check out [the instructions how to use Tor](/cookbook/tor_configuration/).
+

source/_docs/configuration/secrets.markdown

@@ -3,10 +3,11 @@ layout: page
 title: "Storing secrets"
 description: "Storing secrets outside of your configuration.yaml."
 date: 2016-07-01 08:30
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /topics/secrets/
 ---
 
 The `configuration.yaml` file is a plain-text file, thus it is readable by anyone who has access to the file. The file contains passwords and API tokens which need to be redacted if you want to share your configuration. By using `!secrets` you can remove any private information from you configuration files. This separation can also help you to keep easier track of your passwords and API keys. As they are all stored at one place and no longer spread across the `configuration.yaml` file or even multiple yaml files if you [split up your configuration](/topics/splitting_configuration/).

source/_docs/configuration/securing.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/securing/
 ---
 
 One major advantage of Home Assistant is that it's not dependent on cloud services. Even if you're only using Home Assistant on a local network, you should take steps to secure your instance.

source/_docs/configuration/splitting_configuration.markdown

@@ -3,10 +3,11 @@ layout: page
 title: "Splitting up the configuration"
 description: "Splitting the configuration.yaml into several files."
 date: 2016-03-25 23:30
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/yaml/
 ---
 
 So you've been using Home Assistant for a while now and your [configuration.yaml file brings people to tears](https://home-assistant.io/cookbook/configuration_yaml_from_bassclarinetl2/) or you simply want to start off with the distributed approach, here's how to "split the configuration.yaml" into more manageable (read: humanly readable) pieces.

source/_docs/configuration/state_object.markdown

@@ -3,10 +3,11 @@ layout: page
 title: "State Objects"
 description: "Describes all there is to know about state objects in Home Assistant."
 date: 2016-03-12 12:00 -0800
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /topics/state_object/
 ---
 
 Your devices are represented in Home Assistant as entities. The entities will write their current state to the state machine for other entities/templates/frontend to access. States are a current representation of the entity.

source/_docs/configuration/templating.markdown

@@ -3,10 +3,11 @@ layout: page
 title: "Templating"
 description: "Instructions how to use the templating feature of Home Assistant."
 date: 2015-12-12 12:00
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /topics/templating/
 ---
 
 This is an advanced feature of Home Assistant. You'll need a basic understanding of the following things:

source/_docs/configuration/troubleshooting.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/troubleshooting-configuration/
 ---
 
 It can happen that you run into trouble while configuring Home Assistant. Perhaps a component is not showing up or is acting strangely. This page will discuss a few of the most common problems.

source/_docs/configuration/yaml.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/yaml/
 ---
 
 Home Assistant uses the [YAML](http://yaml.org/) syntax for configuration. YAML might take a while to get used to but is really powerful in allowing you to express complex configurations.
@@ -60,4 +61,3 @@ sensor:
     state_topic: sensor2/topic
 ```
 
-### [Next step: Setting up the basics »](/getting-started/basic/)

source/_docs/ecosystem.markdowm

@@ -7,7 +7,8 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/
 ---
 
-Ecosystem includes documentation for related tools and projects that extend Home Assistant to new platforms and systems. Use the sidebar to discover documentation for projects.
+Ecosystem includes documentation for related tools and projects that extend Home Assistant to new platforms and systems.
+

source/_docs/ecosystem/appdaemon.markdown

@@ -1,14 +1,13 @@
 ---
 layout: page
 title: "AppDaemon"
-description: "AppDaemon is a loosely coupled, multithreaded, sandboxed python execution environment for writing automation apps for Home Assistant"
+description: "AppDaemon is a loosely coupled, multithreaded, sandboxed Python execution environment for writing automation apps for Home Assistant"
 release_date: 2016-11-27 08:00:00 -0500
 sidebar: true
 comments: false
 sharing: true
 footer: true
-regenerate: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/
 ---
 
-AppDaemon is a loosely coupled, multithreaded, sandboxed python execution environment for writing automation apps for Home Assistant.
+AppDaemon is a loosely coupled, multithreaded, sandboxed python execution environment for writing automation apps for Home Assistant.

source/_docs/ecosystem/appdaemon/api.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/api/
 ---
 
 ## {% linkable_title Anatomy of an App %}

source/_docs/ecosystem/appdaemon/configuration.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/configuration/
 ---
 
 When you have appdaemon installed by either method, copy the `conf/appdaemon.cfg.example` file to `conf/appdaemon.cfg`, then edit the `[AppDaemon]` section to reflect your environment:

source/_docs/ecosystem/appdaemon/example_apps.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/example_apps/
 ---
 
-There are a number of example apps under conf/examples, and the `conf/examples.cfg` file gives sample parameters for them.
+There are a number of example apps under conf/examples, and the `conf/examples.cfg` file gives sample parameters for them.

source/_docs/ecosystem/appdaemon/installation.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/installation/
 ---
 
 Installation is either by `pip3` or Docker.

source/_docs/ecosystem/appdaemon/operation.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/tutorial/
 ---
 
 Since `AppDaemon` under the covers uses the exact same APIs as the frontend UI, you typically see it react at about the same time to a given event. Calling back to Home Assistant is also pretty fast especially if they are running on the same machine. In action, observed latency above the built in automation component is usually sub-second.

source/_docs/ecosystem/appdaemon/reboot.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/reboot/
 ---
 
 To run `AppDaemon` at reboot, I have provided a sample init script in the `./scripts` directory. These have been tested on a Raspberry PI - your mileage may vary on other systems. There is also a sample Systemd script.

source/_docs/ecosystem/appdaemon/running.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/running/
 ---
 
 As configured, `AppDaemon` comes with a single HelloWorld App that will send a greeting to the logfile to show that everything is working correctly.

source/_docs/ecosystem/appdaemon/tutorial.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/tutorial/
 ---
 
 ## {% linkable_title Another Take on Automation %}

source/_docs/ecosystem/appdaemon/updating.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/updating/
 ---
 
 To update AppDaemon after I have released new code, just run the following command to update your copy:

source/_docs/ecosystem/appdaemon/windows.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-hide_github_edit: true
+redirect_from: /ecosystem/appdaemon/windows/
 ---
 
 AppDaemon runs under windows and has been tested with the official 3.5.2 release of Python. There are a couple of caveats however:

source/_docs/ecosystem/hadashboard.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/hadashboard/
 ---
 
 HADashboard is a dashboard for [Home Assistant](https://home-assistant.io/) that is intended to be wall mounted, and is optimized for distance viewing.

source/_docs/ecosystem/hadashboard/dash_config.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/hadashboard/dash_config/
 ---
 
 (All installations)

source/_docs/ecosystem/hadashboard/hapush.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/hadashboard/hapush/
 ---
 
 # Installing hapush (Manual install only)

source/_docs/ecosystem/hadashboard/installation.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/hadashboard/installation/
 ---
 
 Installation can be performed using Docker (Contributed by [marijngiesen](https://github.com/marijngiesen)) or manually if Docker doesn't work for you. We also have a Raspberry PI version of Docker contributed by [snizzleorg](https://community.home-assistant.io/users/snizzleorg/activity)

source/_docs/ecosystem/hadashboard/reboot.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/hadashboard/reboot/
 ---
 
 To run Dashing and `hapush` at reboot, I have provided sample init scripts in the `./init` directory. These have been tested on a Raspberry Pi - your mileage may vary on other systems.

source/_docs/ecosystem/hadashboard/updating.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/hadashboard/updating/
 ---
 
 To update the dashboard after new code has been released, just run the following command to update your copy:

source/_docs/ecosystem/ios.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/
 ---
 
 The Home Assistant for iOS app offers a companion app for iOS which is deeply integrated into both Home Assistant and iOS. Its basic features include:

source/_docs/ecosystem/ios/integration.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/integration/
 ---
 
 Home Assistant for iOS supports opening from other apps via URL.

source/_docs/ecosystem/ios/location.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/location/
 ---
 
 ## {% linkable_title Location tracking when outside a Home Assistant zone %}

source/_docs/ecosystem/ios/notifications.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/notifications/
 ---
 
 The `ios` notify platform enables sending push notifications to the Home Assistant iOS app.

source/_docs/ecosystem/ios/notifications/actions.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/notifications/actions/
 ---
 
 Actionable notifications allow you to attach 1-4 custom buttons to a notification. When one of the actions is selected Home Assistant will be notified which action was chosen. This allows you to build complex automations.
@@ -22,7 +23,7 @@ Examples of actionable notifications:
   Actionable notifications allow the user to send a command back to Home Assistant.
 </p>
 
-## Overview of how actionable notifications work
+## {% linkable_title Overview of how actionable notifications work %}
 
 In advance of sending a notification:
 
@@ -42,7 +43,7 @@ When sending a notification:
   How the iOS device and Home Assistant work together to enable actionable notifications.
 </p>
 
-## Definitions
+## {% linkable_title Definitions %}
 - Category - A category represents a type of notification that the app might receive. Think of it as a unique group of actions. A categories parameters include:
 - Action - An action consists of a button title and the information that iOS needs to notify the app when the action is selected. You create separate action objects for distinct action your app supports. An actions parameters include:
 

source/_docs/ecosystem/ios/notifications/architecture.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/notifications/architecture/
 ---
 
 <p class='img'>

source/_docs/ecosystem/ios/notifications/attachments.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/notifications/attachments/
 ---
 
 iOS 10 adds _attachments_ to notifications. An attachment is an image, video, or audio file which is downloaded to the device when a notification is received and shown alongside the notification. A thumbnail is shown when the notification is not expanded. The full size attachment is shown when the notification is expanded.

source/_docs/ecosystem/ios/notifications/basic.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/notifications/basic/
 ---
 
 The iOS notify platform accepts the standard `title`, `message` and `target` parameters. The iOS notify platform supports targets as services. Assuming that you did not set a `name` when configuring the platform you should find all your registered and notification-enabled iOS devices available as notify targets as services with names prefixed "notify.ios_" and then the device name you entered at setup.

source/_docs/ecosystem/ios/notifications/content_extensions.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/notifications/content_extensions/
 ---
 
 With the new Content Extension feature found in iOS 10, dynamic content can now be displayed as part of a notification without opening an app.

source/_docs/ecosystem/ios/notifications/privacy_security_rate_limits.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/notifications/privacy_security_rate_limits/
 ---
 
 ## {% linkable_title Privacy %}

source/_docs/ecosystem/ios/notifications/requesting_location_updates.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/notifications/requesting_location_updates/
 ---
 
 <p class="note warning">

source/_docs/ecosystem/ios/notifications/sounds.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/ios/notifications/sounds/
 ---
 
 Adding a custom sound to a notification allows you to easily identify the notification without even looking at your device. Home Assistant for iOS comes with some notification sounds pre-installed but you can also upload your own.

source/_docs/ecosystem/nginx.markdown

@@ -7,20 +7,21 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/nginx/
 ---
 
 Using nginx as a proxy for Home Assistant allows you to serve Home Assistant securely over standard ports. This configuration file and instructions will walk you through setting up Home Assistant over a secure connection.
 
-### {% linkable_title 1. Get a domain name forwarded to your IP. %}
+### {% linkable_title 1. Get a domain name forwarded to your IP %}
 
 Chances are, you have a dynamic IP Address (your ISP changes your address periodically). If this is true, you can use a Dynamic DNS service to obtain a domain and set it up to update with you IP. If you purchase your own domain name, you will be able to easily get a trusted SSL certificate later.
 
 
-### {% linkable_title 2 Install nginx on your server. %}
+### {% linkable_title 2 Install nginx on your server %}
 
 This will vary depending on your OS. Check out Google for this. After installing, ensure that nginx is not running.
 
-### {% linkable_title 3. Obtain an SSL certificate. %}
+### {% linkable_title 3. Obtain an SSL certificate %}
 
 There are two ways of obtaining an SSL certificate.
 

source/_docs/ecosystem/notebooks.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/notebooks/
 ---
 
 The [Jupyter Notebooks](http://jupyter.org/) allows you to create and share documents that contain live code, equations, visualizations, and explanatory text directly in your browser. The web application what is formerly known as the IPython Notebook supports over 40 programming languages.

source/_docs/ecosystem/notebooks/api.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/notebooks/api/
 ---
 
 The [Python API](/developers/python_api/) allows one to create [interactive notebooks](http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/blob/master/home-assistant-python-api.ipynb).

source/_docs/ecosystem/notebooks/database.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/notebooks/database/
 ---
 
 The [Database example](http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/blob/master/database-examples.ipynb) shows you the details about how you can work with stored values.

source/_docs/ecosystem/notebooks/graph.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/notebooks/graph/
 ---
 
 For graphing this [Jupyter notebook](ha_external_link: http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/blob/master/graph-single-sensor.ipynb) should get you started.

source/_docs/ecosystem/notebooks/installation.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/notebooks/installation/
 ---
 
 To run Jupyter Notebooks locally, an installation of [Jupyter](http://jupyter.org/) is needed. Consider to run Jupyter in a [virtualenv](/getting-started/installation-virtualenv/).

source/_docs/ecosystem/notebooks/stats.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/notebooks/stats/
 ---
 
 The [Statistics notebook](http://nbviewer.jupyter.org/github/home-assistant/home-assistant-notebooks/blob/master/database-statistics.ipynb) gets you started if you want to create statistical analysis of your data.

source/_docs/ecosystem/scenegen.markdown

@@ -7,14 +7,15 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/scenegen/
 ---
 
 Scenegen is a scene generation tool for [Home Assistant](https://home-assistant.io/) home automation software. It creates scenes by example, by reading the current states of devices and outputting a corresponding scene. Scenegen is written in python using Home Assistant's RESTFul API so can be run from anywhere. It currently supports lights and switches only.
 
-## Installation
+## {% linkable_title Installation %}
 
-### Clone the Repository
-Clone the **scenegen** repository to the current local directory on your machine.
+### {% linkable_title Clone the Repository %}
+Clone the [**scenegen**](https://github.com/home-assistant/scenegen) repository to the current local directory on your machine.
 
 ``` bash
 $ git clone https://github.com/home-assistant/scenegen.git
@@ -26,7 +27,7 @@ Change your working directory to the repository root. Moving forward, we will be
 $ cd scenegen
 ```
 
-## Install Prereqs
+## {% linkable_title Install Prerequisites %}
 
 Before running `SceneGen` you will need to add some python prerequisites:
 
@@ -36,7 +37,7 @@ $ sudo pip3 install configparser
 
 You should now be ready to run `scenegen`
 
-## Basic Operation
+## {% linkable_title Basic Operation %}
 
 ```
 usage: scenegen [-h] [-k KEY] [-s SCENENAME] [-m MAPFILE] [-f FILTER]
@@ -91,7 +92,7 @@ Scenegen supports all documented effects for lights including transitions and fl
 
 Note that depending on the type of light there may be a delay in actually setting up its parameters and Home Assistant actually recieving that state. For instance, if you set a scene up with the Hue App, Home Assistant won't see those changes for up to 10 seconds. Turning on a ZWave light might not be seen for an entire poll interval. For this reason, its good practice to wait for a while after the scene is setup before running scenegen. Alternatively, perform all setup using the Home Assistant frontend and it will instantly have the required state for capture.
 
-## Advanced Usage
+## {% linkable_title Advanced Usage %}
 
 For a more advanced way to use the output try the following. In configuration.yaml add the following line:
 
@@ -107,11 +108,11 @@ $ ./scenegen.py https://<some url> -k <some api key> > scenes/my_new_scene.yaml
 
 This will create a new scene called `my_new_scene` which will automatically be picked up by Home Assistant on the next restart.
 
-## Colors
+## {% linkable_title Colors %}
 
 Scenegen allows colors to be captured, and in fact Home Assistant light entities store up to 4 different ways of specifying the colors. This is redundant for creating scenes so Scenegen picks 1 and goes with it. The default is `color_temp` but you can change this with the `--colortype` flag, supported options are `xy_color`, `rgb_color`, `color_temp` and `color_name`.
 
-## Types
+## {% linkable_title Types %}
 
 By default, Scenegen will list all lights and switches. To restrict the device type use the `--types` option and supply a comma separated list (no spaces) of types to output. e.g.:
 
@@ -127,7 +128,7 @@ or:
 
 This will make more sense as and when more types are added.
 
-## Maps and Filters
+## {% linkable_title Maps and Filters %}
 
 Maps allow you to specify and label various subsets of devices that you want to work on together. A mapfile is specified using the `--mapfile` option and is a `.ini` style file consisting of section headers and entries. The section headers specify a region or zone or otherwise organized selection of entities you want to filter on, and it is mandatory to have at least one. If you create a map file like this:
 
@@ -160,23 +161,10 @@ Again, if you run with that map file it will output all of the entities listed,
 
 The intended use of the mapfile and filter is that you create a map of all your devices and organize them into zones that you are interested in creating scenes for and use the filter to limit output to that zone. For instance you might want to create 3 or 4 scenes for your living room, and once the map is set up you can easily do so without the addition of unwanted devices.
 
-## Updating SceneGen
+## {% linkable_title Updating SceneGen %}
 To update SceneGen after a new version is released, just run the following command to update your copy:
 
 ```bash
 $ git pull
 ```
 
-## Release Notes
-
-***Version 1.2***
-
-- Add installation instructions
-
-***Version 1.1***
-
-- Add better error checking for Home Assistant errors
-
-***Version 1.0***
-
-Initial Release

source/_docs/ecosystem/synology.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /ecosystem/synology/
 ---
 
 Synology NAS are the perfect companion to running Home Assistant.

source/_docs/frontend.markdown

@@ -0,0 +1,21 @@
+---
+layout: page
+title: "Frontend of Home Assistant"
+description: "Frontend of Home Assistant."
+date: 2017-02-13 12:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+---
+
+The frontend of Home Assistant is built with [Polymer](https://www.polymer-project.org/).
+
+<p class='img'>
+  <img src='{{site_root}}/images/screenshots/ui2015.png' />
+</p>
+
+The [User Interface section](/cookbook/#user-interface) can give you some starting points to expand the frontend.
+
+If you want to work on the frontend, please refer to the [Frontend Development documentation](/developers/frontend/).
+

source/_docs/frontend/browsers.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/browsers/
 ---
 
 Home Assistant requires a web browser to show the frontend and supports all major modern browsers. We don't test the web interface against all available browsers but this page tracks different browsers on various operating systems and should help you to pick a browser which works.

source/_docs/frontend/mobile.markdown

@@ -7,7 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
-redirect_from: /getting-started/android/
+redirect_from: /getting-started/mobile/
 ---
 
 Home Assistant is not available on the Play Store or App Store. Instead, Home Assistant leverages the new W3C [manifest.json](https://w3c.github.io/manifest/) support, allowing mobile devices to add the "web app" to your homescreen as if it was native.

source/_docs/frontend/webserver.markdown

@@ -1,12 +1,13 @@
 ---
 layout: page
-title: "Web server"
+title: "Web server fingerprint"
 description: "Use nmap to scan your Home Assistant instance."
 date: 2016-10-06 08:00
-sidebar: false
+sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /details/webserver/
 ---
 
 It was only a matter of time till the first queries for tools like [https://www.shodan.io](https://www.shodan.io/search?query=Home+Assistant) to search for Home Assistant instances showed up.

source/_docs/hassbian.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/hassbian/
 ---
 
 Hassbian is our customized operating system for the Raspberry Pi 3. It is the easiest way of installing Home Assistant.
@@ -16,7 +17,7 @@ Hassbian is our customized operating system for the Raspberry Pi 3. It is the ea
  - [Pi specific integrations][integrations]
  - [Learn how to perform common tasks][common]
 
-[install]: /getting-started/hassbian-installation/
-[customize]: /getting-started/hassbian-customization/
-[common]: /getting-started/hassbian-common-tasks/
-[integrations]: /getting-started/hassbian-integrations/
+[install]: /docs/hassbian/installation/
+[customize]: /docs/hassbian/customization/
+[common]: /docs/hassbian/common-tasks/
+[integrations]: /docs/hassbian/integrations/

source/_docs/hassbian/common-tasks.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/hassbian-common-tasks/
 ---
 
 ### {% linkable_title Login to the Raspberry Pi %}

source/_docs/hassbian/customization.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/hassbian-customization/
 ---
 
 To allow you to customize your installation further, we have included a set of Hassbian scripts.

source/_docs/hassbian/installation.markdown

@@ -12,7 +12,7 @@ redirect_from: /getting-started/installation-raspberry-pi-image/
 
 The easiest way to install Home Assistant on your Raspberry Pi is by using HASSbian: a Raspberry Pi image with Home Assistant built-in. The image will install the latest version of Home Assistant on initial boot (~10 minutes).
 
- 1. [Download the Hassbian 1.1 image][image-download] (359MB)
+ 1. [Download the Hassbian 1.1 image][image-download] (359 MB)
  2. Use [Etcher][etcher] to flash the image to your SD card
  3. Ensure your Raspberry Pi has access to the internet.
  4. Insert SD card to Raspberry Pi and turn it on. Initial installation of Home Assistant will take about 5 minutes.
@@ -32,20 +32,6 @@ The following extras are included on the image:
  - Home Assistant will be started as a service run by the user `homeassistant`
  - The configuration is located at `/home/homeassistant/.homeassistant`
 
-
-### {% linkable_title Troubleshooting %}
-
-If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
-
-In addition to this site, check out these sources for additional help:
-
- - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- - [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant.
- - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
-
-### [Learn how to configure Home Assistant »](/getting-started/configuration/)
-### [Learn common tasks in Hassbian »](/getting-started/hassbian-common-tasks/)
-
 [image-download]: https://github.com/home-assistant/pi-gen/releases/download/v1.1/image_2017-02-03-HASSbian.zip
 [etcher]: https://etcher.io/
 [http://hassbian.local:8123]: http://hassbian.local:8123

source/_docs/hassbian/integrations.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/hassbian-installation/
 ---
 
 Some components that are specific for the Raspberry Pi can require some further configuration outside of Home Assistant. All commands below are assumed to be executed with the `pi` account. For full documentation of these components refer to the [components](/components) page.

source/_docs/hassbian/upgrading.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/hassbian-upgrading/
 ---
 
 HASSbian is based on Raspbian and uses the same repositories. Any changes to Raspbian will be reflected in HASSbian. To update and upgrade system packages and installed software (excluding Home Assistant) do the following.

source/_docs/installation.markdown

@@ -0,0 +1,18 @@
+---
+layout: page
+title: "Installation of Home Assistant"
+description: "Instructions how to install Home Assistant to launch on start."
+date: 2017-02-15 08:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/installation/
+---
+
+Home Assistant provides multiple ways to be installed. If you are a Raspberry Pi owner then the [Hassbian](/docs/hassbian/) is an easy and simple way to run home Assistant.
+
+The only requirement is that you have [Python](https://www.python.org/downloads/) installed. For Windows we require at least **Python 3.5** and for other operating systems at least **Python 3.4.2**.
+
+It may be needed that you install additional library depending on the platforms/components you want to use.
+

source/_docs/installation/docker.markdown

@@ -7,36 +7,32 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/installation-docker/
 ---
 
 Installation with Docker is straightforward. Adjust the following command so that `/path/to/your/config/` points at the folder where you want to store your config and run it:
 
+### {% linkable_title Linux %}
+
 ```bash
 $ docker run -d --name="home-assistant" -v /path/to/your/config:/config -v /etc/localtime:/etc/localtime:ro --net=host homeassistant/home-assistant
 ```
 
-This will launch Home Assistant and serve the web interface from port 8123 on your Docker host.
+### {% linkable_title macOS %}
 
-<p class='note'>
-When using boot2docker on macOS you are unable to map the local time to your Docker container. Replace `-v /etc/localtime:/etc/localtime:ro` with `-e "TZ=America/Los_Angeles"` (replacing America/Los_Angeles with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones))
+When using `boot2docker` on macOS you are unable to map the local time to your Docker container. Use `-e "TZ=America/Los_Angeles"` instead of `-v /etc/localtime:/etc/localtime:ro`. Replace "America/Los_Angeles" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
 
 Additionally, if your expectation is that you will be able to browse directly to `http://localhost:8123` on your macOS host, then you will also need to replace the `--net=host` switch with `-p 8123:8123`. This is currently the only way to forward ports on to your actual host (macOS) machine instead of the virtual machine inside `xhyve`. More detail on this can be found in [the docker forums](https://forums.docker.com/t/should-docker-run-net-host-work/14215/10).
-</p>
 
-If you change the config you have to restart the server.
-To do that you have 2 options.
+```bash
+$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -e "TZ=America/Los_Angeles" -p 8123:8123 homeassistant/home-assistant
+```
+
+### {% linkable_title Restart %}
+
+This will launch Home Assistant and serve the web interface from port 8123 on your Docker host.
+
+If you change the configuration you have to restart the server. To do that you have 2 options.
 
  1. You can go to the <img src='/images/screenshots/developer-tool-services-icon.png' alt='service developer tool icon' class="no-shadow" height="38" /> service developer tools, select the service `homeassistant/restart` and click "Call Service".
  2. Or you can restart it from an terminal by running `docker restart home-assistant`
-
-### {% linkable_title Troubleshooting %}
-
-If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
-
-In addition to this site, check out these sources for additional help:
-
- - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- - [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant.
- - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
-
-### [Next step: Configuring Home Assistant &raquo;](/getting-started/configuration/)

source/_docs/installation/python.markdown

@@ -0,0 +1,32 @@
+---
+layout: page
+title: "Installation on your computer"
+description: "Installation of Home Assistant on your computer."
+date: 2014-12-18 22:57
+sidebar: true
+comments: false
+sharing: true
+footer: true
+redirect_from: /getting-started/installation-python/
+---
+
+Once Python is installed, execute the following code in a console:
+
+```bash
+$ pip3 install homeassistant
+$ hass --open-ui
+```
+
+Running these commands will:
+
+ - Install Home Assistant
+ - Launch Home Assistant and serve the web interface on [http://localhost:8123](http://localhost:8123)
+
+If you're running a Linux-based platform, we suggest you follow the [VirtualEnv instructions](/docs/installation/virtualenv/) to avoid using `root`.
+
+Video tutorials of this process for various operating systems are available here:
+
+ - [Windows 10](https://www.youtube.com/watch?v=X27eVvuqwnY)
+ - [macOS](https://www.youtube.com/watch?v=hej6ipN86ls)
+ - [Ubuntu 14.04](https://www.youtube.com/watch?v=SXaAG1lGNH0)
+

source/_docs/installation/raspberry-pi-all-in-one.markdown

@@ -5,6 +5,7 @@ date: 2016-05-12 01:39
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/installation-raspberry-pi-all-in-one/
 ---
 
 The [Raspberry Pi All-In-One Installer](https://github.com/home-assistant/fabric-home-assistant) deploys a complete Home Assistant server including support for MQTT with websockets, Z-Wave, and the Open-Zwave Control Panel.
@@ -96,16 +97,16 @@ To launch the OZWCP web application:
 *  Specify your zwave controller, for example `/dev/ttyACM0` and hit initialize
 
 <p class='note note'>
-    If you deployed Home Assistant via the AiO installer prior to December 2016, replace `cd /srv/homeassistant/src/open-zwave-control-panel/` with `cd /srv/hass/src/open-zwave-control-panel/`
+If you deployed Home Assistant via the AiO installer prior to December 2016, replace `cd /srv/homeassistant/src/open-zwave-control-panel/` with `cd /srv/hass/src/open-zwave-control-panel/`
 </p>
 
 <p class='note warning'>
-  Don't check the USB box regardless of using a USB based device.
+Don't check the USB box regardless of using a USB based device.
 </p>
 
 ### {% linkable_title Using the GPIOs %}
 
-The (**homeassistant**)user is added to the GPIO group as part of the install now.
+The (**homeassistant**) user is added to the GPIO group as part of the install now.
 
 ### {% linkable_title WinSCP %}
 

source/_docs/installation/raspberry-pi.markdown

@@ -7,40 +7,46 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/installation-raspberry-pi/
 ---
 
-This installation of Home Assistant requires the Raspberry Pi to run [Raspbian Lite](https://www.raspberrypi.org/downloads/raspbian/).
-The installation will be installed in a [Virtual Environment](/getting-started/installation-virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspbian Lite.
+This installation of Home Assistant requires the Raspberry Pi to run [Raspbian Lite](https://www.raspberrypi.org/downloads/raspbian/). The installation will be installed in a [Virtual Environment](/docs/installation/virtualenv) with minimal overhead. Instructions assume this is a new installation of Raspbian Lite.
+
+Connect to the Raspberry Pi over SSH. Default password is `raspberry`.
+You will need to enable SSH access. The Raspberry Pi website has instructions [here](https://www.raspberrypi.org/documentation/remote-access/ssh/).
 
-Connect to the Raspberry Pi over ssh. Default password is `raspberry`.
-You will need to enable ssh access. The raspberry pi website has instructions [here](https://www.raspberrypi.org/documentation/remote-access/ssh/).
 ```bash
 $ ssh pi@ipadress
 ```
 
 Changing the default password is encouraged.
+
 ```bash
 $ passwd
 ```
 
 Update the system.
+
 ```bash
 $ sudo apt-get update
 $ sudo apt-get upgrade -y
 ```
 
 Install the dependencies.
+
 ```bash
 $ sudo apt-get install python3 python3-venv python3-pip
 ```
 
-Add an account for Home Assistant called `homeassistant`.  
+Add an account for Home Assistant called `homeassistant`.
 Since this account is only for running Home Assistant the extra arguments of `-rm` is added to create a system account and create a home directory.
+
 ```bash
 $ sudo useradd -rm homeassistant
 ```
 
 Next we will create a directory for the installation of Home Assistant and change the owner to the `homeassistant` account.
+
 ```bash
 $ cd /srv
 $ sudo mkdir homeassistant
@@ -48,6 +54,7 @@ $ sudo chown homeassistant:homeassistant homeassistant
 ```
 
 Next up is to create and change to a virtual environment for Home Assistant. This will be done as the `homeassistant` account.
+
 ```bash
 $ sudo su -s /bin/bash homeassistant
 $ cd /srv/homeassistant
@@ -55,33 +62,16 @@ $ python3 -m venv .
 $ source bin/activate
 ```
 Once you have activated the virtual environment you will notice the prompt change and then you can install Home Assistant.
+
 ```bash
 (homeassistant) homeassistant@raspberrypi:/srv/homeassistant $ pip3 install homeassistant
 ```
 
 Start Home Assistant for the first time. This will complete the installation, create the `.homeasssistant` configuration directory in the `/home/homeassistant` directory and install any basic dependencies.
+
 ```bash
 (homeassistant) $ hass
 ```
 
-You can now reach your installation on your raspberry pi over the web interface on [http://ipaddress:8123](http://ipaddress:8123).
+You can now reach your installation on your Raspberry Pi over the web interface on [http://ipaddress:8123](http://ipaddress:8123).
 
-For instruction on how to configure Home Assistant continue on with [Configuring Home Assistant](/getting-started/configuration/).
-
-### {% linkable_title Troubleshooting %}
-
-If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
-
-In addition to this site, check out these sources for additional help:
-
- - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- - [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant.
- - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
-
-### {% linkable_title What's next %}
-
-If you want to have Home Assistant start on boot, [autostart instructions can be found here](/getting-started/autostart-systemd/).
-
-To see what Home Assistant can do, launch demo mode: `hass --demo-mode` or visit the [demo page](/demo).
-
-### [Next step: Configuring Home Assistant »](/getting-started/configuration/)

source/_docs/installation/synology.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/installation-synology/
 ---
 
 The following configuration has been tested on Synology 413j running DSM 6.0-7321 Update 1.
@@ -225,20 +226,3 @@ $ sudo /volume1/homeassistant/hass-daemon restart
 $  /volume1/@appstore/py3k/usr/local/bin/python3 -m pip install --upgrade homeassistant
 ```
 
-### {% linkable_title Troubleshooting %}
-
-If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
-
-In addition to this site, check out these sources for additional help:
-
- - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- - [Gitter Chat Room](https://gitter.im/balloob/home-assistant) for real-time chat about Home Assistant.
- - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
-
-### {% linkable_title What's next %}
-
-If you want to have Home Assistant start on boot, [autostart instructions can be found here](/getting-started/autostart-synology/).
-
-To see what Home Assistant can do, launch demo mode: `hass --demo-mode` or visit the [demo page](/demo).
-
-### [Next step: Configuring Home Assistant »](/getting-started/configuration/)

source/_docs/installation/troubleshooting.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/troubleshooting/
 ---
 
 It can happen that you run into trouble while installing Home Assistant. This page is here to help you solve the most common problems.
@@ -41,12 +42,12 @@ This is a known issue if you're on a Mac using Homebrew to install Python. Pleas
 To run Python 3.x on [CentOS](https://www.centos.org/) or RHEL, [Software Collections](https://www.softwarecollections.org/en/scls/rhscl/rh-python34/) needs to be activated.
 
 #### {% linkable_title No access to the frontend %}
-In newer Linux distributions (at least Fedora 22/CentOS 7) the access to a host is very limited. This means that you can't access the Home Assistant frontend that is running on a host outside of the host machine. Windows and OSX machines may also have issues with this.
+In newer Linux distributions (at least Fedora > 22/CentOS 7) the access to a host is very limited. This means that you can't access the Home Assistant frontend that is running on a host outside of the host machine. Windows and macOS machines may also have issues with this.
 
-To fix this you will need to open your machine's firewall for TCP traffic over port 8123. The method for doing this will vary depending on your operating system and the firewall you have installed. Below are some suggestions to try. Google is your friend here.
+To fix this you will need to open your machine's firewall for TCP traffic to port 8123. The method for doing this will vary depending on your operating system and the firewall you have installed. Below are some suggestions to try. Google is your friend here.
 
 - [Windows instructions](http://windows.microsoft.com/en-us/windows/open-port-windows-firewall#1TC=windows-7)
-- [Mac OSX instructions](https://support.apple.com/en-us/HT201642)
+- [macOS instructions](https://support.apple.com/en-us/HT201642)
 
 For systems with **firewalld** (Fedora, CentOS/RHEL, etc.):
 
@@ -74,5 +75,3 @@ After upgrading to a new version, you may notice your browser gets stuck at the
 Android Chrome 
 chrome -> settings -> site settings -> storage -> search for your URL for home assistant-> "clear & reset"
 
-
-### [« Back to Getting Started](/getting-started/)

source/_docs/installation/updating.markdown

@@ -7,10 +7,11 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/hassbian-upgrading/
 ---
 
 <p class='note warning'>
-The upgrade process differs depending on the installation you have, so please review the documentation that is specific to your install [HASSbian](/getting-started/hassbian-common-tasks/#update-home-assistant), [Raspberry Pi All-In-One Installer](/getting-started/installation-raspberry-pi-all-in-one/#upgrading), [Vagrant](/getting-started/installation-vagrant/), or [Virtualenv](/getting-started/installation-virtualenv/#upgrading-home-assistant).
+The upgrade process differs depending on the installation you have, so please review the documentation that is specific to your install [HASSbian](/docs/hassbian/common-tasks/#update-home-assistant), [Raspberry Pi All-In-One Installer](/docs/installation/raspberry-pi-all-in-one/#upgrading), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/installation/virtualenv/#upgrading-home-assistant).
 </p>
 
 The default way to update Home Assistant to the latest release, when available, is:
@@ -19,10 +20,10 @@ The default way to update Home Assistant to the latest release, when available,
 $ pip3 install --upgrade homeassistant
 ```
 
-After updating, you must restart Home Assistant for the changes to take effect. This means that you will have to restart `hass` itself or the [autostarting](/getting-started/autostart/) daemon (if applicable)
+After updating, you must restart Home Assistant for the changes to take effect. This means that you will have to restart `hass` itself or the [autostarting](/docs/autostart/) daemon (if applicable)
 
 <p class='note'>
-  To avoid permission errors, the upgrade must be run as the same user as the installation was completed, again review the documentation specific to your install [HASSbian](/getting-started/installation-raspberry-pi-image/), [Raspberry Pi All-In-One Installer](/getting-started/installation-raspberry-pi-all-in-one/), [Vagrant](/getting-started/installation-vagrant/), or [Virtualenv](/getting-started/installation-virtualenv)t.
+  To avoid permission errors, the upgrade must be run as the same user as the installation was completed, again review the documentation specific to your install [HASSbian](/docs/hassbian/installation/), [Raspberry Pi All-In-One Installer](/docs/installation/raspberry-pi-all-in-one/), [Vagrant](/docs/installation/vagrant/), or [Virtualenv](/docs/installation/virtualenv).
 </p>
 
 [BRUH automation](http://www.bruhautomation.com) has created [a tutorial video](https://www.youtube.com/watch?v=tuG2rs1Cl2Y) explaining how to upgrade Home Assistant.

source/_docs/installation/vagrant.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/installation-vagrant/
 ---
 
 A `Vagrantfile` is available into `virtualization/vagrant` folder for quickly spinning up a Linux virtual machine running Home Assistant. This can be beneficial for those who want to experiment with Home Assistant and/or developers willing to easily test local changes and run test suite against them.
@@ -60,7 +61,7 @@ To start it again, just run `vagrant up`
 
 ## {% linkable_title Restarting Home Assistant process to test changes %}
 
-The root `home-assistant` directory on your workstation will be mirrored with `/home-assistant` inside the VM. In `virtualization/vagrant` there's also a `config` folder that you can use to drop configuration files (Check the [Getting started section](https://home-assistant.io/getting-started/configuration/) for more information about how to configure Home Assistant).
+The root `home-assistant` directory on your workstation will be mirrored with `/home-assistant` inside the VM. In `virtualization/vagrant` there's also a `config` folder that you can use to drop configuration files (Check the [Configuration section](/docs/configuration/) in the docmentation for more information about how to configure Home Assistant).
 
 Any changes made to the local directory on your workstation will be available from the Vagrant host, so to apply your changes to the Home Assistant process, just restart it:
 
@@ -86,15 +87,3 @@ $ rm setup_done ; vagrant destroy -f
 
 You can now recreate a completely new Vagrant host with `vagrant up`
 
-
-### {% linkable_title Troubleshooting %}
-
-If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many of the more commonly encountered issues.
-
-In addition to this site, check out these sources for additional help:
-
- - [Forum](https://community.home-assistant.io) for Home Assistant discussions and questions.
- - [Gitter Chat Room](https://gitter.im/home-assistant/home-assistant) for real-time chat about Home Assistant.
- - [GitHub Page](https://github.com/home-assistant/home-assistant/issues) for issue reporting.
-
-### [Next step: Configuring Home Assistant »](/getting-started/configuration/)

source/_docs/installation/virtualenv.markdown

@@ -7,6 +7,7 @@ sidebar: true
 comments: false
 sharing: true
 footer: true
+redirect_from: /getting-started/installation-virtualenv/
 ---
 
 There are several reasons why it makes sense to run Home Assistant in a virtual environment. A [virtualenv](https://virtualenv.pypa.io/en/latest/) encapsulates all aspect of a Python environment within a single directory tree. That means the Python packages you install for Home Assistant won't interact with the rest of your system and vice-versa. It means a random upgrade for some other program on your computer won't break Home Assistant, and it means you don't need to install Python packages as root.

source/_docs/mqtt.markdown

@@ -0,0 +1,33 @@
+---
+layout: page
+title: "MQTT"
+description: "Details about the MQTT support of Home Assistant."
+date: 2017-02-15 08:00
+sidebar: true
+comments: false
+sharing: true
+footer: 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.
+
+To integrate MQTT into Home Assistant, add the following section to your `configuration.yaml` file. Keep in mind that the minimal setup will run with [an embedded MQTT broker](/docs/mqtt/broker#embedded-broker):
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+```
+
+For other setup methods, please refer to the [MQTT broker](/docs/mqtt/broker) documentation.
+
+## {% linkable_title Additional features %}
+
+- [Certificate](/docs/mqtt/certificate/)
+- [Discovery](/docs/mqtt/discovery/)
+- [Publish service](/docs/mqtt/service/)
+- [Birth and last will messages](/docs/mqtt/birth_will/)
+- [Testing your setup](/docs/mqtt/testing/)
+- [Logging](/docs/mqtt/logging/)
+- [Processing JSON](/docs/mqtt/processing_json/)
+
+See the [MQTT example component](/cookbook/python_component_mqtt_basic/) how to integrate your own component.

source/_docs/mqtt/birth_will.markdown

@@ -0,0 +1,40 @@
+---
+layout: page
+title: "MQTT Birth and Last will"
+description: "Instructions how to setup MQTT birth and last will messages within Home Assistant."
+date: 2015-08-07 18:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: mqtt.png
+---
+
+MQTT support so-called Birth and Last Will and Testament (LWT) messages. The former is used to sned a message after the service has started. the latter is here to notify other clients about an ungracefully disconnected client or alike.
+
+To integrate MQTT Birth and Last Will messages into Home Assistant, add the following section to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+  birth_message:
+    topic: 'hass/status'
+    payload: 'online'
+  will_message:
+    topic: 'hass/status'
+    payload: 'offline'
+```
+
+Configuration variables:
+
+- **birth_message** (*Optional*):
+  - **topic** (*Required*): The MQTT topic to publish the message.
+  - **payload** (*Required*): The message content.
+  - **qos** (*Optional*): The maximum QoS level of the topic. Default is 0.
+  - **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `True`.
+- **will_message** (*Optional*):
+  - **topic** (*Required*): The MQTT topic to publish the message.
+  - **payload** (*Required*): The message content.
+  - **qos** (*Optional*): The maximum QoS level of the topic. Default is 0.
+  - **retain** (*Optional*): If the published message should have the retain flag on or not. Defaults to `True`.
+

source/_docs/mqtt/broker.markdown

@@ -0,0 +1,126 @@
+---
+layout: page
+title: "MQTT Brokers"
+description: "Instructions how to setup MQTT brokers for Home Assistant."
+date: 2015-08-07 18:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: mqtt.png
+redirect_from: /components/mqtt/#picking-a-broker
+---
+
+The MQTT component needs you to run an MQTT broker for Home Assistant to connect to. There are four options, each with various degrees of ease of setup and privacy.
+
+### {% linkable_title Embedded broker %}
+
+Home Assistant contains an embedded MQTT broker. If no broker configuration is given, the [HBMQTT broker](https://pypi.python.org/pypi/hbmqtt) is started and Home Assistant connects to it. Embedded broker default configuration:
+
+| Setting | Value |
+| ------- | ----- |
+| Host | localhost
+| Port | 1883
+| Protocol | 3.1.1
+| User | homeassistant
+| Password | Your API [password](/components/http/)
+| Websocket port | 8080
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+```
+
+<p class='note'>
+This broker does not currently work with OwnTracks because of a protocol version issue.
+</p>
+
+If you want to customize the settings of the embedded broker, use `embedded:` and the values shown in the [HBMQTT Broker configuration](http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration). This will replace the default configuration.
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+  embedded:
+    # Your HBMQTT config here. Example at:
+    # http://hbmqtt.readthedocs.org/en/latest/references/broker.html#broker-configuration
+```
+
+### {% linkable_title Run your own %}
+
+This is the most private option but requires a bit more work. There are multiple free and open-source brokers to pick from: eg. [Mosquitto](http://mosquitto.org/), [EMQ](http://emqtt.io/), or [Mosca](http://www.mosca.io/).
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+  broker: 192.168.1.100
+  port: 1883
+  client_id: home-assistant-1
+  keepalive: 60
+  username: USERNAME
+  password: PASSWORD
+  protocol: 3.1 
+```
+
+Configuration variables:
+
+- **broker** (*Optional*): The IP address or hostname of your MQTT broker, e.g. 192.168.1.32.
+- **port** (*Optional*): The network port to connect to. Default is 1883.
+- **client_id** (*Optional*): The client ID that Home Assistant will use. Has to be unique on the server. Default is a randomly generated one.
+- **keepalive** (*Optional*): The time in seconds between sending keep alive messages 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.
+- **protocol** (*Optional*): Protocol to use: 3.1 or 3.1.1. By default it connects with 3.1.1 and falls back to 3.1 if server does not support 3.1.1.
+
+<p class='note warning'>
+There is an issue with the Mosquitto package included in Ubuntu 14.04 LTS. Specify `protocol: 3.1` in your MQTT configuration to work around this issue.
+</p>
+
+<p class='note'>
+If you are running a mosquitto instance on a different server with proper SSL encryption using a service like letsencrypt you may have to set the certificate to the operating systems own `.crt` certificates file. In the instance of ubuntu this would be `certificate: /etc/ssl/certs/ca-certificates.crt`
+</p>
+
+### {% linkable_title Public broker %}
+
+The Mosquitto project runs a [public broker](http://test.mosquitto.org). This is the easiest to set up, but there is no privacy as all messages are public. Use this only for testing purposes and not for real tracking of your devices or controlling your home.
+
+```yaml
+mqtt:
+  broker: test.mosquitto.org
+  port: 1883 or 8883
+
+  # Optional, replace port 1883 with following if you want encryption
+  # (doesn't really matter because broker is public)
+  port: 8883
+  # Download certificate from http://test.mosquitto.org/ssl/mosquitto.org.crt
+  certificate: /home/paulus/downloads/mosquitto.org.crt
+```
+
+### {% linkable_title CloudMQTT %}
+
+[CloudMQTT](https://www.cloudmqtt.com) is a hosted private MQTT instance that is free for up to 10 connected devices. This is enough to get started with for example [OwnTracks](/components/device_tracker.owntracks/) and give you a taste of what is possible.
+
+<p class='note'>
+Home Assistant is not affiliated with CloudMQTT nor will receive any kickbacks.
+</p>
+
+ 1. [Create an account](https://customer.cloudmqtt.com/login) (no payment details needed)
+ 2. [Create a new CloudMQTT instance](https://customer.cloudmqtt.com/subscription/create)
+    (Cute Cat is the free plan)
+ 3. From the control panel, click on the _Details_ button.
+ 4. Create unique users for Home Assistant and each phone to connect<br>(CloudMQTT does not allow two connections from the same user)
+      1. Under manage users, fill in username, password and click add
+      2. Under ACLs, select user, topic `#`, check 'read access' and 'write access'
+ 5. Copy the instance info to your configuration.yaml:
+
+```yaml
+mqtt:
+  broker: CLOUTMQTT_SERVER
+  port: CLOUDMQTT_PORT
+  username: CLOUDMQTT_USER
+  password: CLOUDMQTT_PASSWORD
+```
+
+<p class='note'>
+Home Assistant will automatically load the correct certificate if you connect to an encrypted channel of CloudMQTT (port range 20000-30000).
+</p>
+

source/_docs/mqtt/certificate.markdown

@@ -0,0 +1,28 @@
+---
+layout: page
+title: "MQTT Certificate"
+description: "Instructions how to setup MQTT with a certificate in Home Assistant."
+date: 2015-08-07 18:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: mqtt.png
+---
+
+Using certificates will give you an additional layer of security for your MQTT communication. 
+
+To integrate MQTT with certificate into Home Assistant, add the following section to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+  certificate: /home/paulus/dev/addtrustexternalcaroot.crt
+```
+
+Configuration variables:
+
+- **certificate** (*Optional*): The certificate authority certificate file that is to be treated as trusted by this client. This file should contain the root certificate of the certificate authority that signed your broker's certificate, but may contain multiple certificates. Example: `/home/user/identrust-root.pem`
+- **client_key** (*Optional*): Client key, eg. `/home/user/owntracks/cookie.key`.
+- **client_cert** (*Optional*): Client certificate, eg. `/home/user/owntracks/cookie.crt`.
+

source/_docs/mqtt/discovery.markdown

@@ -0,0 +1,59 @@
+---
+layout: page
+title: "MQTT Discovery"
+description: "Instructions how to setup MQTT Discovery within Home Assistant."
+date: 2015-08-07 18:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: mqtt.png
+redirect_from: /components/mqtt/#discovery
+---
+
+The discovery of MQTT devices will enable one to use MQTT devices with only minimal configuration effort on the side of Home Assistant. The configuration is done on the device itself and the topic used by the device. Similar to the [HTTP binary sensor](/components/binary_sensor.http/) and the [HTTP sensor](/components/sensor.http/). Only support for binary sensor is available at the moment.
+
+To enable MQTT discovery, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+mqtt:
+  discovery: true
+  discovery_prefix: homeassistant
+```
+Configuration variables:
+
+- **discovery** (*Optional*): If the MQTT discovery should be enabled or not. Defaults to `False`.
+- **discovery_prefix** (*Optional*): The prefix for the discovery topic. Defaults  to `homeassistant`.
+
+The discovery topic need to follow a specific format:
+
+```text
+<discovery_prefix>/<component>/<object_id>/<>
+```
+
+- `<component>`: One of the supported components, eg. `binary_sensor`.
+- `<object_id>`: The ID of the device. This will become the `entity_id` in Home Assistant.
+- `<config>`: The topic `config` or `state` which defines the current action.
+
+The payload will be checked like an entry in your `configuration.yaml` file if a new device is added. This means that missing variables will be filled with the platform's default values.
+
+### {% linkable_title Example %}
+
+A motion detection device which can be represented by a [binary sensor](/components/binary_sensor.mqtt/) for your garden would sent its configuration as JSON payload to the Configuration topic. After the first message to `config`, then the MQTT messages sent to the State topic will update the state in Home Assistant.
+
+- Configuration topic: `homeassistant/binary_sensor/garden/config`
+- State topic: `homeassistant/binary_sensor/garden/state`
+- Payload:  `{"name": "garden", "sensor_class": "motion"}`
+
+To create a new sensor manually. For more details please refer to the [MQTT testing section](/component/mqtt_testing).
+
+```bash
+$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/config" -m '{"name": "garden", "sensor_class": "motion"}'
+```
+Update the state.
+
+```bash
+$ mosquitto_pub -h 127.0.0.1 -p 1883 -t "homeassistant/binary_sensor/garden/state" -m ON
+```
+