diff --git a/_config.yml b/_config.yml index 2704d4cca9dc..233124d6ce05 100644 --- a/_config.yml +++ b/_config.yml @@ -73,12 +73,6 @@ collections: output: true cookbook: output: true - ecosystem: - output: true - details: - output: true - topics: - output: true # ----------------------- # # 3rd Party Settings # diff --git a/source/_components/mqtt.markdown b/source/_components/mqtt.markdown index f0d6cdb249f2..e4d77f8121e4 100644 --- a/source/_components/mqtt.markdown +++ b/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). -```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: - -- **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`. - -## {% 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 +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: ``` -

-This broker does not currently work with OwnTracks because of a protocol version issue. -

- -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/). +To connect to your [own MQTT broker](/docs/mqtt/broker#run-your-own): ```yaml # Example configuration.yaml entry mqtt: - broker: 192.168.1.100 - port: 1883 - client_id: home-assistant-1 - keepalive: 60 - username: USERNAME - password: PASSWORD -``` - -

-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. -

- -

-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` -

- -### {% 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. - -

-Home Assistant is not affiliated with CloudMQTT nor will receive any kickbacks. -

- - 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
(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: - port: - username: - password: -``` - -

-Home Assistant will automatically load the correct certificate if you connect to an encrypted channel of CloudMQTT (port range 20 000 - 30 000). -

- -## {% 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", "sensor_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 -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 -``` - -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' + broker: IP_ADDRESS_BROKER ``` -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 %}' -``` +## {% linkable_title Additional features %} -More information about the full JSONPath syntax can be found [here][JSONPath syntax]. +- [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/) -[JSONPath syntax]: https://github.com/kennknowles/python-jsonpath-rw#jsonpath-syntax diff --git a/source/_components/zwave.markdown b/source/_components/zwave.markdown index 5615187a21f9..dd7ba38a0ce0 100644 --- a/source/_components/zwave.markdown +++ b/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: +``` diff --git a/source/_docs/automation.markdown b/source/_docs/automation.markdown new file mode 100644 index 000000000000..ceb424df6643 --- /dev/null +++ b/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. + +

+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. +

+ +### {% 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 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 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. + diff --git a/source/getting-started/automation-action.markdown b/source/_docs/automation/action.markdown similarity index 78% rename from source/getting-started/automation-action.markdown rename to source/_docs/automation/action.markdown index 485e3514f422..87295918ac52 100644 --- a/source/getting-started/automation-action.markdown +++ b/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 -``` \ No newline at end of file +``` diff --git a/source/getting-started/automation-condition.markdown b/source/_docs/automation/condition.markdown similarity index 93% rename from source/getting-started/automation-condition.markdown rename to source/_docs/automation/condition.markdown index 5105ff7e94f0..78f396fa670f 100644 --- a/source/getting-started/automation-condition.markdown +++ b/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/ diff --git a/source/getting-started/automation-examples.markdown b/source/_docs/automation/examples.markdown similarity index 93% rename from source/getting-started/automation-examples.markdown rename to source/_docs/automation/examples.markdown index ef7eea40ca7a..941e7a978956 100644 --- a/source/getting-started/automation-examples.markdown +++ b/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: diff --git a/source/getting-started/automation-templating.markdown b/source/_docs/automation/templating.markdown similarity index 95% rename from source/getting-started/automation-templating.markdown rename to source/_docs/automation/templating.markdown index 5e30fe2bdeb3..e1c085ea738b 100644 --- a/source/getting-started/automation-templating.markdown +++ b/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/ diff --git a/source/getting-started/automation-trigger.markdown b/source/_docs/automation/trigger.markdown similarity index 99% rename from source/getting-started/automation-trigger.markdown rename to source/_docs/automation/trigger.markdown index d6e15fa263a9..0f5b73551393 100644 --- a/source/getting-started/automation-trigger.markdown +++ b/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. diff --git a/source/getting-started/automation-troubleshooting.markdown b/source/_docs/automation/troubleshooting.markdown similarity index 94% rename from source/getting-started/automation-troubleshooting.markdown rename to source/_docs/automation/troubleshooting.markdown index feb82dab9f64..5207175e2583 100644 --- a/source/getting-started/automation-troubleshooting.markdown +++ b/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: diff --git a/source/getting-started/autostart.markdown b/source/_docs/autostart.markdown similarity index 59% rename from source/getting-started/autostart.markdown rename to source/_docs/autostart.markdown index 34951c2c957b..95e9608adc8f 100644 --- a/source/getting-started/autostart.markdown +++ b/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/) diff --git a/source/getting-started/autostart-init.d.markdown b/source/_docs/autostart/init.d.markdown similarity index 94% rename from source/getting-started/autostart-init.d.markdown rename to source/_docs/autostart/init.d.markdown index 27bd44f8d413..abe1ccb6ff14 100644 --- a/source/getting-started/autostart-init.d.markdown +++ b/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 -``` \ No newline at end of file +``` diff --git a/source/getting-started/autostart-macos.markdown b/source/_docs/autostart/macos.markdown similarity index 93% rename from source/getting-started/autostart-macos.markdown rename to source/_docs/autostart/macos.markdown index d0c5798665e0..0a1b6ea13488 100644 --- a/source/getting-started/autostart-macos.markdown +++ b/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. diff --git a/source/getting-started/autostart-synology.markdown b/source/_docs/autostart/synology.markdown similarity index 95% rename from source/getting-started/autostart-synology.markdown rename to source/_docs/autostart/synology.markdown index f41bd1277f06..38dfded8ece9 100644 --- a/source/getting-started/autostart-synology.markdown +++ b/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: diff --git a/source/getting-started/autostart-systemd.markdown b/source/_docs/autostart/systemd.markdown similarity index 95% rename from source/getting-started/autostart-systemd.markdown rename to source/_docs/autostart/systemd.markdown index c9a94abbbcc4..ff3289246264 100644 --- a/source/getting-started/autostart-systemd.markdown +++ b/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 <> /etc/systemd/system/home-assistant@[your user].service +$ su -c 'cat <> /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" diff --git a/source/getting-started/autostart-upstart.markdown b/source/_docs/autostart/upstart.markdown similarity index 100% rename from source/getting-started/autostart-upstart.markdown rename to source/_docs/autostart/upstart.markdown diff --git a/source/_docs/backend.markdown b/source/_docs/backend.markdown new file mode 100644 index 000000000000..23659871a0e7 --- /dev/null +++ b/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/). + diff --git a/source/_details/database.markdown b/source/_docs/backend/database.markdown similarity index 98% rename from source/_details/database.markdown rename to source/_docs/backend/database.markdown index a4c7ec00acb0..9fe42de98663 100644 --- a/source/_details/database.markdown +++ b/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. `/.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. diff --git a/source/_details/updater.markdown b/source/_docs/backend/updater.markdown similarity index 99% rename from source/_details/updater.markdown rename to source/_docs/backend/updater.markdown index ccf13eb8116d..dcdb3cb54331 100644 --- a/source/_details/updater.markdown +++ b/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. diff --git a/source/_docs/configuration.markdown b/source/_docs/configuration.markdown new file mode 100644 index 000000000000..0b7a7138ca51 --- /dev/null +++ b/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. + +

+ You will have to restart Home Assistant for changes to `configuration.yaml` to take effect. +

+ +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). + +

+ 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. +

+ diff --git a/source/getting-started/basic.markdown b/source/_docs/configuration/basic.markdown similarity index 50% rename from source/getting-started/basic.markdown rename to source/_docs/configuration/basic.markdown index f8cb5b33cc6b..4af7df1a3501 100644 --- a/source/getting-started/basic.markdown +++ b/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 ` 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 »](/getting-started/devices/) diff --git a/source/getting-started/customizing-devices.markdown b/source/_docs/configuration/customizing-devices.markdown similarity index 59% rename from source/getting-started/customizing-devices.markdown rename to source/_docs/configuration/customizing-devices.markdown index 1fb92f1b2a74..e1b65217fd89 100644 --- a/source/getting-started/customizing-devices.markdown +++ b/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. @@ -45,6 +46,60 @@ homeassistant: | `assumed_state` | For switches with an assumed state two buttons are shown (turn off, turn on) instead of a switch. By setting `assumed_state` to `false` you will get the default switch icon. | `sensor_class` | Sets the [class of the sensor](/components/binary_sensor/), changing the device state and icon that is displayed on the UI (see below). +### {% linkable_title Advanced example %} + +You can also specify attributes for all devices in a domain, use wildcards, use several entity IDs as a list or comma separated list. + +```yaml +homeassistant: + customize: + - entity_id: sensor + icon: mdi:kettle # Give all sensor the kettle icon + - entity_id: light.family* + hidden: true # Hide all lights that have an ID starting with 'family' + - entity_id: switch.wemo_switch_1,switch.wemo_switch_2,switch.wemo_switch_3 + entity_picture: /local/toaster.jpg # Set picture on multiple devices +``` + +Either `entity_id` must be present in each customization block. + +### {% linkable_title Older format %} + +In the previous version of customize format the keys were the IDs: + +```yaml +homeassistant: + name: Home + unit_system: metric + # etc + + customize: + # Only the 'entity_id' is required. All other options are optional. + sensor.living_room_motion: + hidden: true + thermostat.family_roomfamily_room: + entity_picture: https://example.com/images/nest.jpg + friendly_name: Nest + switch.wemo_switch_1: + friendly_name: Toaster + entity_picture: /local/toaster.jpg + switch.wemo_switch_2: + friendly_name: Kitchen kettle + icon: mdi:kettle + - entity_id: switch.rfxtrx_switch: + assumed_state: false +``` +This format doesn't support comma-separated IDs, wildcards or domain matching. + +The formats can't be mixed +```yaml + # NOT A VALID CONFIGURATION + customize: + sensor.living_room_motion: + hidden: true + - entity_id: thermostat.family_roomfamily_room + friendly_name: Nest +``` ### {% linkable_title Reloading customize %} @@ -54,4 +109,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.

-### [Next step: Setting up presence detection »](/getting-started/presence-detection/) diff --git a/source/getting-started/devices.markdown b/source/_docs/configuration/devices.markdown similarity index 87% rename from source/getting-started/devices.markdown rename to source/_docs/configuration/devices.markdown index a7eb3e82eff1..76b4f82447e2 100644 --- a/source/getting-started/devices.markdown +++ b/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,7 +54,7 @@ camera 2: ### {% linkable_title Grouping devices %} -Once you have several devices set up, it is time to organize them into groups. +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)). ```yaml @@ -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 »](/getting-started/customizing-devices/) diff --git a/source/_topics/events.markdown b/source/_docs/configuration/events.markdown similarity index 98% rename from source/_topics/events.markdown rename to source/_docs/configuration/events.markdown index f3d5d8b4e7f1..48cb5df1af0c 100644 --- a/source/_topics/events.markdown +++ b/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. diff --git a/source/_topics/group_visibility.markdown b/source/_docs/configuration/group_visibility.markdown similarity index 99% rename from source/_topics/group_visibility.markdown rename to source/_docs/configuration/group_visibility.markdown index a312ced75885..13c5cf9d7bef 100644 --- a/source/_topics/group_visibility.markdown +++ b/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. diff --git a/source/_topics/packages.markdown b/source/_docs/configuration/packages.markdown similarity index 81% rename from source/_topics/packages.markdown rename to source/_docs/configuration/packages.markdown index 369ba6d3443a..39f231e832d5 100644 --- a/source/_topics/packages.markdown +++ b/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. diff --git a/source/_topics/platform_options.markdown b/source/_docs/configuration/platform_options.markdown similarity index 95% rename from source/_topics/platform_options.markdown rename to source/_docs/configuration/platform_options.markdown index f8cd217c687c..0d7945d3d10d 100644 --- a/source/_topics/platform_options.markdown +++ b/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. diff --git a/source/_docs/configuration/remote.markdown b/source/_docs/configuration/remote.markdown new file mode 100644 index 000000000000..273d92c2f959 --- /dev/null +++ b/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 ` 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/). + diff --git a/source/_topics/secrets.markdown b/source/_docs/configuration/secrets.markdown similarity index 98% rename from source/_topics/secrets.markdown rename to source/_docs/configuration/secrets.markdown index 60129c98ab59..e3531c2db8ca 100644 --- a/source/_topics/secrets.markdown +++ b/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/). diff --git a/source/getting-started/securing.markdown b/source/_docs/configuration/securing.markdown similarity index 97% rename from source/getting-started/securing.markdown rename to source/_docs/configuration/securing.markdown index 9ed36dc13f77..31e3a1fbca7f 100644 --- a/source/getting-started/securing.markdown +++ b/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. diff --git a/source/_topics/splitting_configuration.markdown b/source/_docs/configuration/splitting_configuration.markdown similarity index 99% rename from source/_topics/splitting_configuration.markdown rename to source/_docs/configuration/splitting_configuration.markdown index 5a0d63ac791c..a13b5db7e2e4 100644 --- a/source/_topics/splitting_configuration.markdown +++ b/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. diff --git a/source/_topics/state_object.markdown b/source/_docs/configuration/state_object.markdown similarity index 98% rename from source/_topics/state_object.markdown rename to source/_docs/configuration/state_object.markdown index ca4f6827bfa6..9659e255241b 100644 --- a/source/_topics/state_object.markdown +++ b/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. diff --git a/source/_topics/templating.markdown b/source/_docs/configuration/templating.markdown similarity index 99% rename from source/_topics/templating.markdown rename to source/_docs/configuration/templating.markdown index e2f06762bdd6..bb94a2c912ed 100644 --- a/source/_topics/templating.markdown +++ b/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: diff --git a/source/getting-started/troubleshooting-configuration.markdown b/source/_docs/configuration/troubleshooting.markdown similarity index 98% rename from source/getting-started/troubleshooting-configuration.markdown rename to source/_docs/configuration/troubleshooting.markdown index f06c7e17cc85..f16cdb7ab857 100644 --- a/source/getting-started/troubleshooting-configuration.markdown +++ b/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. diff --git a/source/getting-started/yaml.markdown b/source/_docs/configuration/yaml.markdown similarity index 97% rename from source/getting-started/yaml.markdown rename to source/_docs/configuration/yaml.markdown index 7a5fb2cb7dba..7ce62138fa73 100644 --- a/source/getting-started/yaml.markdown +++ b/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/) diff --git a/source/ecosystem/index.markdown b/source/_docs/ecosystem.markdowm similarity index 63% rename from source/ecosystem/index.markdown rename to source/_docs/ecosystem.markdowm index 0af82796dab7..2d221faf0072 100644 --- a/source/ecosystem/index.markdown +++ b/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. + diff --git a/source/_ecosystem/appdaemon.markdown b/source/_docs/ecosystem/appdaemon.markdown old mode 100755 new mode 100644 similarity index 76% rename from source/_ecosystem/appdaemon.markdown rename to source/_docs/ecosystem/appdaemon.markdown index 9ec0e87f8e3f..43094211190f --- a/source/_ecosystem/appdaemon.markdown +++ b/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. \ No newline at end of file +AppDaemon is a loosely coupled, multithreaded, sandboxed python execution environment for writing automation apps for Home Assistant. diff --git a/source/_ecosystem/appdaemon/api.markdown b/source/_docs/ecosystem/appdaemon/api.markdown similarity index 99% rename from source/_ecosystem/appdaemon/api.markdown rename to source/_docs/ecosystem/appdaemon/api.markdown index 891ef1dec870..5ebe762f1bef 100755 --- a/source/_ecosystem/appdaemon/api.markdown +++ b/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 %} diff --git a/source/_ecosystem/appdaemon/configuration.markdown b/source/_docs/ecosystem/appdaemon/configuration.markdown similarity index 98% rename from source/_ecosystem/appdaemon/configuration.markdown rename to source/_docs/ecosystem/appdaemon/configuration.markdown index ec955aff6221..ee497f2d4dda 100644 --- a/source/_ecosystem/appdaemon/configuration.markdown +++ b/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: diff --git a/source/_ecosystem/appdaemon/example_apps.markdown b/source/_docs/ecosystem/appdaemon/example_apps.markdown similarity index 69% rename from source/_ecosystem/appdaemon/example_apps.markdown rename to source/_docs/ecosystem/appdaemon/example_apps.markdown index 2d7b659ad797..bf696f634c49 100644 --- a/source/_ecosystem/appdaemon/example_apps.markdown +++ b/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. \ No newline at end of file +There are a number of example apps under conf/examples, and the `conf/examples.cfg` file gives sample parameters for them. diff --git a/source/_ecosystem/appdaemon/installation.markdown b/source/_docs/ecosystem/appdaemon/installation.markdown similarity index 94% rename from source/_ecosystem/appdaemon/installation.markdown rename to source/_docs/ecosystem/appdaemon/installation.markdown index 6eb9f1f16c50..cd6d1cf4cd99 100644 --- a/source/_ecosystem/appdaemon/installation.markdown +++ b/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. diff --git a/source/_ecosystem/appdaemon/operation.markdown b/source/_docs/ecosystem/appdaemon/operation.markdown similarity index 91% rename from source/_ecosystem/appdaemon/operation.markdown rename to source/_docs/ecosystem/appdaemon/operation.markdown index 9f643719a614..536f474aee03 100644 --- a/source/_ecosystem/appdaemon/operation.markdown +++ b/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. diff --git a/source/_ecosystem/appdaemon/reboot.markdown b/source/_docs/ecosystem/appdaemon/reboot.markdown similarity index 90% rename from source/_ecosystem/appdaemon/reboot.markdown rename to source/_docs/ecosystem/appdaemon/reboot.markdown index 96d7b9552b89..1ccdd8773a99 100644 --- a/source/_ecosystem/appdaemon/reboot.markdown +++ b/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. diff --git a/source/_ecosystem/appdaemon/running.markdown b/source/_docs/ecosystem/appdaemon/running.markdown similarity index 98% rename from source/_ecosystem/appdaemon/running.markdown rename to source/_docs/ecosystem/appdaemon/running.markdown index 78e5cf3976e6..d4006526d6f6 100755 --- a/source/_ecosystem/appdaemon/running.markdown +++ b/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. diff --git a/source/_ecosystem/appdaemon/tutorial.markdown b/source/_docs/ecosystem/appdaemon/tutorial.markdown similarity index 99% rename from source/_ecosystem/appdaemon/tutorial.markdown rename to source/_docs/ecosystem/appdaemon/tutorial.markdown index bec655b90746..18f25c5b1b6b 100755 --- a/source/_ecosystem/appdaemon/tutorial.markdown +++ b/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 %} diff --git a/source/_ecosystem/appdaemon/updating.markdown b/source/_docs/ecosystem/appdaemon/updating.markdown similarity index 91% rename from source/_ecosystem/appdaemon/updating.markdown rename to source/_docs/ecosystem/appdaemon/updating.markdown index 20a5ebef141a..8b39e9ccf8bd 100644 --- a/source/_ecosystem/appdaemon/updating.markdown +++ b/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: diff --git a/source/_ecosystem/appdaemon/windows.markdown b/source/_docs/ecosystem/appdaemon/windows.markdown similarity index 96% rename from source/_ecosystem/appdaemon/windows.markdown rename to source/_docs/ecosystem/appdaemon/windows.markdown index 360bf975a122..a903f37f4243 100755 --- a/source/_ecosystem/appdaemon/windows.markdown +++ b/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: diff --git a/source/_ecosystem/hadashboard.markdown b/source/_docs/ecosystem/hadashboard.markdown similarity index 96% rename from source/_ecosystem/hadashboard.markdown rename to source/_docs/ecosystem/hadashboard.markdown index 799468d0e6a6..871ec17cda69 100644 --- a/source/_ecosystem/hadashboard.markdown +++ b/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. diff --git a/source/_ecosystem/hadashboard/dash_config.markdown b/source/_docs/ecosystem/hadashboard/dash_config.markdown similarity index 99% rename from source/_ecosystem/hadashboard/dash_config.markdown rename to source/_docs/ecosystem/hadashboard/dash_config.markdown index 4abc93d3fd88..1436f3fd981d 100755 --- a/source/_ecosystem/hadashboard/dash_config.markdown +++ b/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) diff --git a/source/_ecosystem/hadashboard/hapush.markdown b/source/_docs/ecosystem/hadashboard/hapush.markdown similarity index 99% rename from source/_ecosystem/hadashboard/hapush.markdown rename to source/_docs/ecosystem/hadashboard/hapush.markdown index d390f22f3fc9..6445a12ae3ea 100755 --- a/source/_ecosystem/hadashboard/hapush.markdown +++ b/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) diff --git a/source/_ecosystem/hadashboard/installation.markdown b/source/_docs/ecosystem/hadashboard/installation.markdown similarity index 99% rename from source/_ecosystem/hadashboard/installation.markdown rename to source/_docs/ecosystem/hadashboard/installation.markdown index ecce1549c1b0..0fd3df48efc1 100755 --- a/source/_ecosystem/hadashboard/installation.markdown +++ b/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) diff --git a/source/_ecosystem/hadashboard/reboot.markdown b/source/_docs/ecosystem/hadashboard/reboot.markdown similarity index 92% rename from source/_ecosystem/hadashboard/reboot.markdown rename to source/_docs/ecosystem/hadashboard/reboot.markdown index 0d87ef287250..3f912b0268f9 100755 --- a/source/_ecosystem/hadashboard/reboot.markdown +++ b/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. diff --git a/source/_ecosystem/hadashboard/updating.markdown b/source/_docs/ecosystem/hadashboard/updating.markdown similarity index 91% rename from source/_ecosystem/hadashboard/updating.markdown rename to source/_docs/ecosystem/hadashboard/updating.markdown index 96d6f9731bd2..6854a5541511 100755 --- a/source/_ecosystem/hadashboard/updating.markdown +++ b/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: diff --git a/source/_ecosystem/ios.markdown b/source/_docs/ecosystem/ios.markdown similarity index 98% rename from source/_ecosystem/ios.markdown rename to source/_docs/ecosystem/ios.markdown index 862fce661c42..9a176f006bdf 100644 --- a/source/_ecosystem/ios.markdown +++ b/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: diff --git a/source/_ecosystem/ios/devices_file.markdown b/source/_docs/ecosystem/ios/devices_file.markdown similarity index 100% rename from source/_ecosystem/ios/devices_file.markdown rename to source/_docs/ecosystem/ios/devices_file.markdown diff --git a/source/_ecosystem/ios/integration.markdown b/source/_docs/ecosystem/ios/integration.markdown similarity index 93% rename from source/_ecosystem/ios/integration.markdown rename to source/_docs/ecosystem/ios/integration.markdown index e9db1dd875e9..c37e3342458f 100644 --- a/source/_ecosystem/ios/integration.markdown +++ b/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. diff --git a/source/_ecosystem/ios/location.markdown b/source/_docs/ecosystem/ios/location.markdown similarity index 98% rename from source/_ecosystem/ios/location.markdown rename to source/_docs/ecosystem/ios/location.markdown index f9bd14bf0a54..ac344227c2b1 100644 --- a/source/_ecosystem/ios/location.markdown +++ b/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 %} diff --git a/source/_ecosystem/ios/notifications.markdown b/source/_docs/ecosystem/ios/notifications.markdown similarity index 90% rename from source/_ecosystem/ios/notifications.markdown rename to source/_docs/ecosystem/ios/notifications.markdown index 49490161de0f..21e393687739 100644 --- a/source/_ecosystem/ios/notifications.markdown +++ b/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. diff --git a/source/_ecosystem/ios/notifications/actions.markdown b/source/_docs/ecosystem/ios/notifications/actions.markdown similarity index 97% rename from source/_ecosystem/ios/notifications/actions.markdown rename to source/_docs/ecosystem/ios/notifications/actions.markdown index 9749cfec8aee..5e2f49f3e45e 100644 --- a/source/_ecosystem/ios/notifications/actions.markdown +++ b/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.

-## 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.

-## 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: diff --git a/source/_ecosystem/ios/notifications/architecture.markdown b/source/_docs/ecosystem/ios/notifications/architecture.markdown similarity index 84% rename from source/_ecosystem/ios/notifications/architecture.markdown rename to source/_docs/ecosystem/ios/notifications/architecture.markdown index c699e4529989..b7dac74dfb11 100644 --- a/source/_ecosystem/ios/notifications/architecture.markdown +++ b/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/ ---

diff --git a/source/_ecosystem/ios/notifications/attachments.markdown b/source/_docs/ecosystem/ios/notifications/attachments.markdown similarity index 97% rename from source/_ecosystem/ios/notifications/attachments.markdown rename to source/_docs/ecosystem/ios/notifications/attachments.markdown index 639f087b362c..2138ae602d19 100644 --- a/source/_ecosystem/ios/notifications/attachments.markdown +++ b/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. diff --git a/source/_ecosystem/ios/notifications/basic.markdown b/source/_docs/ecosystem/ios/notifications/basic.markdown similarity index 97% rename from source/_ecosystem/ios/notifications/basic.markdown rename to source/_docs/ecosystem/ios/notifications/basic.markdown index fbb217edffe8..0400888a2c68 100644 --- a/source/_ecosystem/ios/notifications/basic.markdown +++ b/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. diff --git a/source/_ecosystem/ios/notifications/content_extensions.markdown b/source/_docs/ecosystem/ios/notifications/content_extensions.markdown similarity index 96% rename from source/_ecosystem/ios/notifications/content_extensions.markdown rename to source/_docs/ecosystem/ios/notifications/content_extensions.markdown index 9279f75d5959..8b9ec5b5053a 100644 --- a/source/_ecosystem/ios/notifications/content_extensions.markdown +++ b/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. diff --git a/source/_ecosystem/ios/notifications/privacy_security_rate_limits.markdown b/source/_docs/ecosystem/ios/notifications/privacy_security_rate_limits.markdown similarity index 94% rename from source/_ecosystem/ios/notifications/privacy_security_rate_limits.markdown rename to source/_docs/ecosystem/ios/notifications/privacy_security_rate_limits.markdown index ebb0b1462674..f0a60e1af880 100644 --- a/source/_ecosystem/ios/notifications/privacy_security_rate_limits.markdown +++ b/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 %} diff --git a/source/_ecosystem/ios/notifications/requesting_location_updates.markdown b/source/_docs/ecosystem/ios/notifications/requesting_location_updates.markdown similarity index 92% rename from source/_ecosystem/ios/notifications/requesting_location_updates.markdown rename to source/_docs/ecosystem/ios/notifications/requesting_location_updates.markdown index f02f63f30e3f..a014cb5334a2 100644 --- a/source/_ecosystem/ios/notifications/requesting_location_updates.markdown +++ b/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/ ---

diff --git a/source/_ecosystem/ios/notifications/sounds.markdown b/source/_docs/ecosystem/ios/notifications/sounds.markdown similarity index 99% rename from source/_ecosystem/ios/notifications/sounds.markdown rename to source/_docs/ecosystem/ios/notifications/sounds.markdown index cbe35943ad89..7e0a96635237 100644 --- a/source/_ecosystem/ios/notifications/sounds.markdown +++ b/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. diff --git a/source/_ecosystem/nginx.markdown b/source/_docs/ecosystem/nginx.markdown similarity index 95% rename from source/_ecosystem/nginx.markdown rename to source/_docs/ecosystem/nginx.markdown index 8d657a500311..b3305a9de347 100644 --- a/source/_ecosystem/nginx.markdown +++ b/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. diff --git a/source/_ecosystem/notebooks.markdown b/source/_docs/ecosystem/notebooks.markdown similarity index 95% rename from source/_ecosystem/notebooks.markdown rename to source/_docs/ecosystem/notebooks.markdown index 6dfd9a73633a..9cde967703a9 100644 --- a/source/_ecosystem/notebooks.markdown +++ b/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. diff --git a/source/_ecosystem/notebooks/api.markdown b/source/_docs/ecosystem/notebooks/api.markdown similarity index 91% rename from source/_ecosystem/notebooks/api.markdown rename to source/_docs/ecosystem/notebooks/api.markdown index bf20faaecb37..11d01248a296 100644 --- a/source/_ecosystem/notebooks/api.markdown +++ b/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). diff --git a/source/_ecosystem/notebooks/database.markdown b/source/_docs/ecosystem/notebooks/database.markdown similarity index 90% rename from source/_ecosystem/notebooks/database.markdown rename to source/_docs/ecosystem/notebooks/database.markdown index 5b0cd3cd5569..afb900c56e86 100644 --- a/source/_ecosystem/notebooks/database.markdown +++ b/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. diff --git a/source/_ecosystem/notebooks/graph.markdown b/source/_docs/ecosystem/notebooks/graph.markdown similarity index 89% rename from source/_ecosystem/notebooks/graph.markdown rename to source/_docs/ecosystem/notebooks/graph.markdown index 257d5adf4b94..4fda74e239af 100644 --- a/source/_ecosystem/notebooks/graph.markdown +++ b/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. diff --git a/source/_ecosystem/notebooks/installation.markdown b/source/_docs/ecosystem/notebooks/installation.markdown similarity index 97% rename from source/_ecosystem/notebooks/installation.markdown rename to source/_docs/ecosystem/notebooks/installation.markdown index ffc67af78d24..96997dd06501 100644 --- a/source/_ecosystem/notebooks/installation.markdown +++ b/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/). diff --git a/source/_ecosystem/notebooks/stats.markdown b/source/_docs/ecosystem/notebooks/stats.markdown similarity index 90% rename from source/_ecosystem/notebooks/stats.markdown rename to source/_docs/ecosystem/notebooks/stats.markdown index 542d7dbb18c0..c94ccb583b88 100644 --- a/source/_ecosystem/notebooks/stats.markdown +++ b/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. diff --git a/source/_ecosystem/scenegen.markdown b/source/_docs/ecosystem/scenegen.markdown similarity index 92% rename from source/_ecosystem/scenegen.markdown rename to source/_docs/ecosystem/scenegen.markdown index 0d8a8d047a76..aa512fd18330 100644 --- a/source/_ecosystem/scenegen.markdown +++ b/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:// -k > 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 \ No newline at end of file diff --git a/source/_ecosystem/synology.markdown b/source/_docs/ecosystem/synology.markdown similarity index 95% rename from source/_ecosystem/synology.markdown rename to source/_docs/ecosystem/synology.markdown index 93002049f71e..099ea41ef084 100644 --- a/source/_ecosystem/synology.markdown +++ b/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. diff --git a/source/_docs/frontend.markdown b/source/_docs/frontend.markdown new file mode 100644 index 000000000000..4c6d26dcabf1 --- /dev/null +++ b/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/). + +

+ +

+ +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/). + diff --git a/source/getting-started/browsers.markdown b/source/_docs/frontend/browsers.markdown similarity index 99% rename from source/getting-started/browsers.markdown rename to source/_docs/frontend/browsers.markdown index f36be2f2a45f..8ddb3f805b4e 100644 --- a/source/getting-started/browsers.markdown +++ b/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. diff --git a/source/getting-started/mobile.markdown b/source/_docs/frontend/mobile.markdown similarity index 96% rename from source/getting-started/mobile.markdown rename to source/_docs/frontend/mobile.markdown index 8f3657f838c2..d5537e664b4a 100644 --- a/source/getting-started/mobile.markdown +++ b/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. diff --git a/source/_details/webserver.markdown b/source/_docs/frontend/webserver.markdown similarity index 94% rename from source/_details/webserver.markdown rename to source/_docs/frontend/webserver.markdown index f9e2f4e00312..bf4bf1b8b103 100644 --- a/source/_details/webserver.markdown +++ b/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. diff --git a/source/getting-started/hassbian.markdown b/source/_docs/hassbian.markdown similarity index 70% rename from source/getting-started/hassbian.markdown rename to source/_docs/hassbian.markdown index 969eaad57c38..a9177f3ab1d7 100644 --- a/source/getting-started/hassbian.markdown +++ b/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/ diff --git a/source/getting-started/hassbian-common-tasks.markdown b/source/_docs/hassbian/common-tasks.markdown similarity index 98% rename from source/getting-started/hassbian-common-tasks.markdown rename to source/_docs/hassbian/common-tasks.markdown index 0e5399ae9451..25104502c317 100644 --- a/source/getting-started/hassbian-common-tasks.markdown +++ b/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 %} diff --git a/source/getting-started/hassbian-customization.markdown b/source/_docs/hassbian/customization.markdown similarity index 95% rename from source/getting-started/hassbian-customization.markdown rename to source/_docs/hassbian/customization.markdown index 54a34a2c0704..2c86da09b935 100644 --- a/source/getting-started/hassbian-customization.markdown +++ b/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. diff --git a/source/getting-started/hassbian-installation.markdown b/source/_docs/hassbian/installation.markdown similarity index 68% rename from source/getting-started/hassbian-installation.markdown rename to source/_docs/hassbian/installation.markdown index 6ed77c596424..7d09be5914dc 100644 --- a/source/getting-started/hassbian-installation.markdown +++ b/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 diff --git a/source/getting-started/hassbian-integrations.markdown b/source/_docs/hassbian/integrations.markdown similarity index 98% rename from source/getting-started/hassbian-integrations.markdown rename to source/_docs/hassbian/integrations.markdown index 957b263a6303..122ae0b54eeb 100644 --- a/source/getting-started/hassbian-integrations.markdown +++ b/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. diff --git a/source/getting-started/hassbian-upgrading.markdown b/source/_docs/hassbian/upgrading.markdown similarity index 93% rename from source/getting-started/hassbian-upgrading.markdown rename to source/_docs/hassbian/upgrading.markdown index 9c353469f2ba..dff4e81e8d86 100644 --- a/source/getting-started/hassbian-upgrading.markdown +++ b/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. diff --git a/source/_docs/installation.markdown b/source/_docs/installation.markdown new file mode 100644 index 000000000000..1db05d075783 --- /dev/null +++ b/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. + diff --git a/source/getting-started/installation-docker.markdown b/source/_docs/installation/docker.markdown similarity index 58% rename from source/getting-started/installation-docker.markdown rename to source/_docs/installation/docker.markdown index d1c5221b7e64..ac3bd466f2ba 100644 --- a/source/getting-started/installation-docker.markdown +++ b/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 %} -

-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). -

- -If you change the config you have to restart the server. -To do that you have 2 options. - - 1. You can go to the service developer tool icon 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 %} +```bash +$ docker run -d --name="home-assistant" -v /path/to/your/config:/config -e "TZ=America/Los_Angeles" -p 8123:8123 homeassistant/home-assistant +``` -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. +### {% linkable_title Restart %} -In addition to this site, check out these sources for additional help: +This will launch Home Assistant and serve the web interface from port 8123 on your Docker host. - - [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. +If you change the configuration you have to restart the server. To do that you have 2 options. -### [Next step: Configuring Home Assistant »](/getting-started/configuration/) + 1. You can go to the service developer tool icon 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` diff --git a/source/_docs/installation/python.markdown b/source/_docs/installation/python.markdown new file mode 100644 index 000000000000..e0603a076c17 --- /dev/null +++ b/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) + diff --git a/source/getting-started/installation-raspberry-pi-all-in-one.markdown b/source/_docs/installation/raspberry-pi-all-in-one.markdown similarity index 93% rename from source/getting-started/installation-raspberry-pi-all-in-one.markdown rename to source/_docs/installation/raspberry-pi-all-in-one.markdown index 0f5ec4ca1ff6..06e03d6c3367 100644 --- a/source/getting-started/installation-raspberry-pi-all-in-one.markdown +++ b/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

- 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/`

- 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.

### {% 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 %} diff --git a/source/getting-started/installation-raspberry-pi.markdown b/source/_docs/installation/raspberry-pi.markdown similarity index 56% rename from source/getting-started/installation-raspberry-pi.markdown rename to source/_docs/installation/raspberry-pi.markdown index 5c58622a791f..bb899d6c3770 100644 --- a/source/getting-started/installation-raspberry-pi.markdown +++ b/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). - -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). +You can now reach your installation on your Raspberry Pi over the web interface on [http://ipaddress:8123](http://ipaddress:8123). -### [Next step: Configuring Home Assistant »](/getting-started/configuration/) diff --git a/source/getting-started/installation-synology.markdown b/source/_docs/installation/synology.markdown similarity index 83% rename from source/getting-started/installation-synology.markdown rename to source/_docs/installation/synology.markdown index 114d3629055e..773476f9bb3b 100644 --- a/source/getting-started/installation-synology.markdown +++ b/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/) diff --git a/source/getting-started/troubleshooting.markdown b/source/_docs/installation/troubleshooting.markdown similarity index 84% rename from source/getting-started/troubleshooting.markdown rename to source/_docs/installation/troubleshooting.markdown index 2f1bfcbeb3d0..b78544b025ad 100644 --- a/source/getting-started/troubleshooting.markdown +++ b/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/) diff --git a/source/getting-started/updating.markdown b/source/_docs/installation/updating.markdown similarity index 68% rename from source/getting-started/updating.markdown rename to source/_docs/installation/updating.markdown index a9bf836b894c..eeb83e0d5afe 100644 --- a/source/getting-started/updating.markdown +++ b/source/_docs/installation/updating.markdown @@ -7,10 +7,11 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/hassbian-upgrading/ ---

-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).

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)

- 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).

[BRUH automation](http://www.bruhautomation.com) has created [a tutorial video](https://www.youtube.com/watch?v=tuG2rs1Cl2Y) explaining how to upgrade Home Assistant. diff --git a/source/getting-started/installation-vagrant.markdown b/source/_docs/installation/vagrant.markdown similarity index 79% rename from source/getting-started/installation-vagrant.markdown rename to source/_docs/installation/vagrant.markdown index e17b06efe72b..2ab59b2019ee 100644 --- a/source/getting-started/installation-vagrant.markdown +++ b/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/) diff --git a/source/getting-started/installation-virtualenv.markdown b/source/_docs/installation/virtualenv.markdown similarity index 99% rename from source/getting-started/installation-virtualenv.markdown rename to source/_docs/installation/virtualenv.markdown index 6bedb6863793..613b3ecd7c4a 100644 --- a/source/getting-started/installation-virtualenv.markdown +++ b/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. diff --git a/source/_docs/mqtt.markdown b/source/_docs/mqtt.markdown new file mode 100644 index 000000000000..072561f99122 --- /dev/null +++ b/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. diff --git a/source/_docs/mqtt/birth_will.markdown b/source/_docs/mqtt/birth_will.markdown new file mode 100644 index 000000000000..a3caf2c466fb --- /dev/null +++ b/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`. + diff --git a/source/_docs/mqtt/broker.markdown b/source/_docs/mqtt/broker.markdown new file mode 100644 index 000000000000..ff1e873e67ac --- /dev/null +++ b/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: +``` + +

+This broker does not currently work with OwnTracks because of a protocol version issue. +

+ +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. + +

+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. +

+ +

+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` +

+ +### {% 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. + +

+Home Assistant is not affiliated with CloudMQTT nor will receive any kickbacks. +

+ + 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
(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 +``` + +

+Home Assistant will automatically load the correct certificate if you connect to an encrypted channel of CloudMQTT (port range 20000-30000). +

+ diff --git a/source/_docs/mqtt/certificate.markdown b/source/_docs/mqtt/certificate.markdown new file mode 100644 index 000000000000..71374bc85c10 --- /dev/null +++ b/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`. + diff --git a/source/_docs/mqtt/discovery.markdown b/source/_docs/mqtt/discovery.markdown new file mode 100644 index 000000000000..12b7af279398 --- /dev/null +++ b/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 +///<> +``` + +- ``: One of the supported components, eg. `binary_sensor`. +- ``: The ID of the device. This will become the `entity_id` in Home Assistant. +- ``: 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 +``` + diff --git a/source/_docs/mqtt/logging.markdown b/source/_docs/mqtt/logging.markdown new file mode 100644 index 000000000000..d40f99cd7964 --- /dev/null +++ b/source/_docs/mqtt/logging.markdown @@ -0,0 +1,23 @@ +--- +layout: page +title: "MQTT Logging" +description: "Instructions how to setup MQTT Logging within Home Assistant." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +redirect_from: /components/mqtt/#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 +``` + diff --git a/source/_docs/mqtt/processing_json.markdown b/source/_docs/mqtt/processing_json.markdown new file mode 100644 index 000000000000..b10558655cb7 --- /dev/null +++ b/source/_docs/mqtt/processing_json.markdown @@ -0,0 +1,37 @@ +--- +layout: page +title: "Processing JSON" +description: "Instructions how to process the MQTT payload." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +redirect_from: /components/mqtt/#processing-json +--- + +The MQTT [switch](/components/switch.mqtt/) and [sensor](/components/sensor.mqtt/) 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 [in their documentation](https://github.com/kennknowles/python-jsonpath-rw#jsonpath-syntax). diff --git a/source/_docs/mqtt/service.markdown b/source/_docs/mqtt/service.markdown new file mode 100644 index 000000000000..0b3e778fdf2e --- /dev/null +++ b/source/_docs/mqtt/service.markdown @@ -0,0 +1,29 @@ +--- +layout: page +title: "MQTT Publish service" +description: "Instructions how to setup the MQTT Publish service within Home Assistant." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +redirect_from: /components/mqtt/#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 %}" +} +``` + diff --git a/source/_docs/mqtt/testing.markdown b/source/_docs/mqtt/testing.markdown new file mode 100644 index 000000000000..3cc565d05116 --- /dev/null +++ b/source/_docs/mqtt/testing.markdown @@ -0,0 +1,60 @@ +--- +layout: page +title: "MQTT Testing" +description: "Instructions how to test your MQTT setup." +date: 2015-08-07 18:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mqtt.png +redirect_from: /components/mqtt/#testing-your-setup +--- + +The `mosquitto` broker package ships commandline tools (often as `*-clients` package) 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 -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 +``` + +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. + diff --git a/source/getting-started/scripts.markdown b/source/_docs/scripts.markdown similarity index 98% rename from source/getting-started/scripts.markdown rename to source/_docs/scripts.markdown index 69441a23ab92..22e094ce445f 100644 --- a/source/getting-started/scripts.markdown +++ b/source/_docs/scripts.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/scripts/ --- Scripts are a sequence of actions that Home Assistant will execute. Scripts are available as an entity through the standalone [Script component] but can also be embedded in [automations] and [Alexa/Amazon Echo] configurations. diff --git a/source/getting-started/scripts-conditions.markdown b/source/_docs/scripts/conditions.markdown similarity index 99% rename from source/getting-started/scripts-conditions.markdown rename to source/_docs/scripts/conditions.markdown index dde7f9cf2efe..85837d5372ef 100644 --- a/source/getting-started/scripts-conditions.markdown +++ b/source/_docs/scripts/conditions.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/scripts-conditions/ --- Conditions can be used within a script or automation to prevent further execution. A condition will look at the system right now. For example a condition can test if a switch is currently turned on or off. diff --git a/source/getting-started/scripts-service-calls.markdown b/source/_docs/scripts/service-calls.markdown similarity index 98% rename from source/getting-started/scripts-service-calls.markdown rename to source/_docs/scripts/service-calls.markdown index 2f9e4b07a10c..58ee3b4b9243 100644 --- a/source/getting-started/scripts-service-calls.markdown +++ b/source/_docs/scripts/service-calls.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/scripts-service-calls/ --- Various components allow calling services when a certain event occurs. The most common one is calling a service when an automation trigger happens. But a service can also be called from a script or via the Amazon Echo. diff --git a/source/_docs/tools.markdown b/source/_docs/tools.markdown new file mode 100644 index 000000000000..a82ca8f43b1d --- /dev/null +++ b/source/_docs/tools.markdown @@ -0,0 +1,12 @@ +--- +layout: page +title: "Tools" +description: "Description of tools which helps when using Home Assistant." +release_date: 2016-11-13 15:00:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Home Assistant ships a couple of helpers for the command-line and the frontend which simplify common tasks, are helping with migrations, and ensure that Home Assistant runs properly. diff --git a/source/_docs/tools/dev-tools.markdown b/source/_docs/tools/dev-tools.markdown new file mode 100644 index 000000000000..a82ca8f43b1d --- /dev/null +++ b/source/_docs/tools/dev-tools.markdown @@ -0,0 +1,12 @@ +--- +layout: page +title: "Tools" +description: "Description of tools which helps when using Home Assistant." +release_date: 2016-11-13 15:00:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Home Assistant ships a couple of helpers for the command-line and the frontend which simplify common tasks, are helping with migrations, and ensure that Home Assistant runs properly. diff --git a/source/_docs/tools/hass.markdown b/source/_docs/tools/hass.markdown new file mode 100644 index 000000000000..a00c68c5bd66 --- /dev/null +++ b/source/_docs/tools/hass.markdown @@ -0,0 +1,43 @@ +--- +layout: page +title: "Hass" +description: "Description of tools which helps when using Home Assistant." +release_date: 2016-11-13 15:00:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +The command-line part of Home Assistant is + + +```bash +$ hass -h +usage: hass [-h] [--version] [-c path_to_config_dir] [--demo-mode] [--debug] + [--open-ui] [--skip-pip] [-v] [--pid-file path_to_pid_file] + [--log-rotate-days LOG_ROTATE_DAYS] [--runner] [--script ...] + [--daemon] + +Home Assistant: Observe, Control, Automate. + +optional arguments: + -h, --help show this help message and exit + --version show program's version number and exit + -c path_to_config_dir, --config path_to_config_dir + Directory that contains the Home Assistant + configuration + --demo-mode Start Home Assistant in demo mode + --debug Start Home Assistant in debug mode + --open-ui Open the webinterface in a browser + --skip-pip Skips pip install of required packages on startup + -v, --verbose Enable verbose logging to file. + --pid-file path_to_pid_file + Path to PID file useful for running as daemon + --log-rotate-days LOG_ROTATE_DAYS + Enables daily log rotation and keeps up to the + specified days + --runner On restart exit with code 100 + --script ... Run one of the embedded scripts + --daemon Run Home Assistant as daemon +``` diff --git a/source/_docs/tools/scripts.markdown b/source/_docs/tools/scripts.markdown new file mode 100644 index 000000000000..a82ca8f43b1d --- /dev/null +++ b/source/_docs/tools/scripts.markdown @@ -0,0 +1,12 @@ +--- +layout: page +title: "Tools" +description: "Description of tools which helps when using Home Assistant." +release_date: 2016-11-13 15:00:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Home Assistant ships a couple of helpers for the command-line and the frontend which simplify common tasks, are helping with migrations, and ensure that Home Assistant runs properly. diff --git a/source/getting-started/z-wave.markdown b/source/_docs/z-wave.markdown similarity index 99% rename from source/getting-started/z-wave.markdown rename to source/_docs/z-wave.markdown index 9e085b17da72..88eb7a3de18b 100644 --- a/source/getting-started/z-wave.markdown +++ b/source/_docs/z-wave.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/z-wave/ --- [Z-Wave](http://www.z-wave.com/) integration for Home Assistant allows you to observe and control connected Z-Wave devices. Z-Wave support requires a [supported Z-Wave USB stick or module](https://github.com/OpenZWave/open-zwave/wiki/Controller-Compatibility-List) to be plugged into the host. @@ -65,7 +66,6 @@ If you followed along with setting up a virtual environment, your path will be: /srv/homeassistant/python-openzwave/openzwave/config ``` - ### {% linkable_title Configuration %} ```yaml diff --git a/source/getting-started/z-wave-controllers.markdown b/source/_docs/z-wave/controllers.markdown similarity index 96% rename from source/getting-started/z-wave-controllers.markdown rename to source/_docs/z-wave/controllers.markdown index 694f7263d0c5..76831a22993a 100644 --- a/source/getting-started/z-wave-controllers.markdown +++ b/source/_docs/z-wave/controllers.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/z-wave-controllers/ --- Z-Wave is a popular home automation protocol that is not always straightforward to setup. This page will try to help you make sense of it all. diff --git a/source/getting-started/z-wave-device-specific.markdown b/source/_docs/z-wave/device-specific.markdown similarity index 96% rename from source/getting-started/z-wave-device-specific.markdown rename to source/_docs/z-wave/device-specific.markdown index 047fd29e67f1..5437d4b60142 100644 --- a/source/getting-started/z-wave-device-specific.markdown +++ b/source/_docs/z-wave/device-specific.markdown @@ -7,9 +7,10 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/z-wave-device-specific/ --- -##### {% linkable_title Motion or alarm sensors %} +## {% linkable_title Motion or alarm sensors %} In order for Home Assistant to recognize the sensor properly, you will need to change its configuration from `Basic Set (default)` to `Binary Sensor report` or `Alarm report`. These devices will either show as a binary sensor or a sensor called `Alarm xxxx` and will report a numeric value. Test to see what value is what. Sometimes this is noted in the device manual. @@ -21,8 +22,12 @@ The following parameters can be entered: - **parameter** (*Required*): The index number of the parameter to be set. Refer to device manual or zwcfg_[home_id].xml - **value** (*Required*): The value to set the parameter to. Refer to device manual or zwcfg_[home_id].xml - **size** (*Optional*): The size of the value. It is normally not needed to specify this parameter, but in some cases it's needed. Check OZW.log for details on this. -You should check OZW.log to see if your new setting has been set + +You should check OZW.log to see if your new setting has been set. + Example entry in dev-service, setting binary reports for an Aeotec Multisensor 6: + + ```yaml # Example entry in dev-service { @@ -32,7 +37,7 @@ Example entry in dev-service, setting binary reports for an Aeotec Multisensor 6 } ``` -##### {% linkable_title Locks and other secure devices %} +## {% linkable_title Locks and other secure devices %} These devices require a network key to be set for the Z-Wave network before they are paired. This key is set in OpenZWave's `options.xml` which is located in OpenZWave's directory. This should also be the same directory as `config_path:` in your `configuration.yaml`. If it's not, make sure you have the same values in all the files you are using. The option is commented out by default in `options.xml` and is a default key. Make your own unique key. The key is in Hexadecimals. diff --git a/source/getting-started/z-wave-settings.markdown b/source/_docs/z-wave/settings.markdown similarity index 97% rename from source/getting-started/z-wave-settings.markdown rename to source/_docs/z-wave/settings.markdown index 64102acd8f6e..fecba91fd50c 100644 --- a/source/getting-started/z-wave-settings.markdown +++ b/source/_docs/z-wave/settings.markdown @@ -7,6 +7,7 @@ sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/z-wave-settings/ --- You may wish to modify the Z-Wave settings in your `ozw*.xml` file (stored in the `.homeassistant` configuration directory), or certain situations/devices may require it (i.e. Aeon Multisensor 6). To do this, utilize [Open-Zwave Control Panel](https://github.com/OpenZWave/open-zwave-control-panel). Alternatively, use [Domoticz](https://www.domoticz.com/), which incorporates the Open-Zwave Control Panel project into an easy to use Raspberry Pi image. diff --git a/source/_ecosystem/ios/features.markdown b/source/_ecosystem/ios/features.markdown deleted file mode 100644 index 895a6a25311c..000000000000 --- a/source/_ecosystem/ios/features.markdown +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: page -title: "Features" -description: "Describes the features of Home Assistant for iOS" -date: 2016-10-25 15:00:00 -0700 -sidebar: true -comments: false -sharing: true -footer: true ---- - -Coming soon diff --git a/source/_ecosystem/ios/requirements.markdown b/source/_ecosystem/ios/requirements.markdown deleted file mode 100644 index 89e89e6dcbbf..000000000000 --- a/source/_ecosystem/ios/requirements.markdown +++ /dev/null @@ -1,14 +0,0 @@ ---- -layout: page -title: "Requirements" -description: "Basic requirements to use Home Assistant for iOS" -date: 2016-10-25 15:00:00 -0700 -sidebar: true -comments: false -sharing: true -footer: true ---- - -* iOS device running at least iOS 9, but iOS 10 is greatly preferred. -* Home Assistant 0.31.1 or higher for push notification support. -* SSL is strongly recommended. Self-signed SSL certificates will not work due to Apple's limitations. diff --git a/source/_includes/asides/docs_navigation.html b/source/_includes/asides/docs_navigation.html new file mode 100644 index 000000000000..59a3e6f813dd --- /dev/null +++ b/source/_includes/asides/docs_navigation.html @@ -0,0 +1,184 @@ +
+
+

Topics

+
    +
  • + {% active_link /docs/installation/ Installation %} +
      +
    • {% active_link /docs/installation/python/ Python %}
      • +
    • {% active_link /docs/installation/virtualenv/ Python Virtual Env %}
      • +
    • {% active_link /docs/installation/docker/ Docker %}
      • +
    • {% active_link /docs/installation/raspberry-pi/ Raspberry Pi %}
      • +
    • {% active_link /docs/installation/raspberry-pi-all-in-one/ Raspberrry Pi All-in-One %}
      • +
    • {% active_link /docs/installation/vagrant/ Vagrant %}
      • +
    • {% active_link /docs/installation/synology/ Synology %}
      • +
    • {% active_link /docs/installation/updating/ Updating %}
      • +
    • {% active_link /docs/installation/troubleshooting/ Troubleshooting %}
      • +
    +
    • +
  • + {% active_link /docs/hassbian/ Hassbian %} +
      +
    • {% active_link /docs/hassbian/installation/ Installation %}
      • +
    • {% active_link /docs/hassbian/customization/ Customization %}
      • +
    • {% active_link /docs/hassbian/common-tasks/ Common tasks %}
      • +
    • {% active_link /docs/hassbian/integrations/ Integrations %}
      • +
    • {% active_link /docs/hassbian/upgrading/ Upgrading %}
      • +
    +
    • +
  • + {% active_link /docs/configuration/ Configuration %} +
      +
    • {% active_link /docs/configuration/yaml/ YAML %}
      • +
    • {% active_link /docs/configuration/basic/ Basic information %}
      • +
    • {% active_link /docs/configuration/devices/ Setting up devices %}
      • +
    • {% active_link /docs/configuration/customizing-devices/ Customizing devices and services %}
      • +
    • {% active_link /docs/configuration/presence-detection/ Presence Detection %}
      • +
    • {% active_link /docs/configuration/troubleshooting/ Troubleshooting %}
      • +
    • {% active_link /docs/configuration/securing/ Security Check Points %}
      • +
    +
    • +
  • + Advanced Configuration +
      +
    • {% active_link /docs/configuration/remote/ Remote access %}
      • +
    • {% active_link /docs/configuration/packages/ Packages %}
      • +
    • {% active_link /docs/configuration/splitting_configuration/ Splitting up the configuration %}
      • +
    • {% active_link /docs/configuration/secrets/ Storing Secrets %}
      • +
    • {% active_link /docs/configuration/templating/ Templating %}
      • +
    • {% active_link /docs/configuration/group_visibility/ Group Visibility %}
      • +
    • {% active_link /docs/configuration/events/ Events %}
      • +
    • {% active_link /docs/configuration/state_object/ State Objects %}
      • +
    • {% active_link /docs/configuration/platform_options/ Entity component platform options %}
      • +
    +
    • +
  • + {% active_link /docs/automation/ Automation %} +
      +
    • {% active_link /docs/automation/examples/ Examples %}
      • +
    • {% active_link /docs/automation/trigger/ Triggers %}
      • +
    • {% active_link /docs/automation/condition/ Conditions %}
      • +
    • {% active_link /docs/automation/action/ Actions %}
      • +
    • {% active_link /docs/automation/templating/ Templates %}
      • +
    +
    • +
  • + {% active_link /docs/frontend/ Frontend %} +
      +
    • {% active_link /docs/frontend/mobile/ Android/iOS Homescreen %}
      • +
    • {% active_link /docs/frontend/webserver/ Web server fingerprint %}
      • +
    • {% active_link /docs/frontend/browsers/ Browser Compatibility List %}
      • +
    +
    • +
  • + {% active_link /docs/backend/ Backend %} +
      +
    • {% active_link /docs/backend/database/ Database %}
      • +
    • {% active_link /docs/backend/updater/ Updater %}
      • +
    • {% active_link /developers/api/ API %}
      • +
    +
    • +
  • + {% active_link /docs/scripts/ Scripts %} +
      +
    • {% active_link /docs/scripts/service-calls/ Service Calls %}
      • +
    • {% active_link /docs/scripts/conditions/ Conditions %}
      • +
    +
    • +
  • + {% active_link /docs/z-wave/ Z-Wave %} +
      +
    • {% active_link /docs/z-wave/controllers/ Controllers %}
      • +
    • {% active_link /docs/z-wave/settings/ Modifying Settings %}
      • +
    • {% active_link /docs/z-wave/device-specific/ Device Specific %}
      • +
    +
    • +
  • + {% active_link /docs/mqtt/ MQTT %} +
      +
    • {% active_link /docs/mqtt/broker/ Broker %}
      • +
    • {% active_link /docs/mqtt/certificate/ Certificate %}
      • +
    • {% active_link /docs/mqtt/discovery/ Discovery %}
      • +
    • {% active_link /docs/mqtt/service/ Publish service %}
      • +
    • {% active_link /docs/mqtt/birth_will/ Birth and last will messages %}
      • +
    • {% active_link /docs/mqtt/testing/ Testing your setup %}
      • +
    • {% active_link /docs/mqtt/logging/ Logging %}
      • +
    • {% active_link /docs/mqtt/processing_json/ Processing JSON %}
      • +
    +
    • +
  • + {% active_link /docs/ecosystem/ Ecosystem %} +
      +
    • + {% active_link /docs/ecosystem/autostart/ Autostart %} +
        +
      • {% active_link /docs/ecosystem/autostart/systemd/ systemd (Linux) %}
        • +
      • {% active_link /docs/ecosystem/autostart/upstart/ Upstart (Linux) %}
        • +
      • {% active_link /docs/ecosystem/autostart/init.d/ init.d (Linux) %}
        • +
      • {% active_link /docs/ecosystem/autostart/macos/ macOS %}
        • +
      • {% active_link /docs/ecosystem/autostart/synology/ Synology NAS %}
        • +
      +
      • +
    • + {% active_link /docs/ecosystem/appdaemon/ AppDaemon %} +
        +
      • {% active_link /docs/ecosystem/appdaemon/installation/ Installation %}
        • +
      • {% active_link /docs/ecosystem/appdaemon/configuration/ Configuration %}
        • +
      • {% active_link /docs/ecosystem/appdaemon/example_apps/ Example Apps %}
        • +
      • {% active_link /docs/ecosystem/appdaemon/running/ Running AppDaemon %}
        • +
      • {% active_link /docs/ecosystem/appdaemon/reboot/ Starting AppDaemon at Reboot %}
        • +
      • {% active_link /docs/ecosystem/appdaemon/operation/ Operation %}
        • +
      • {% active_link /docs/ecosystem/appdaemon/windows/ AppDaemon on Windows %}
        • +
      • {% active_link /docs/ecosystem/appdaemon/updating/ Updating AppDaemon %}
        • +
      • {% active_link /docs/ecosystem/appdaemon/tutorial/ AppDaemon Tutorial %}
        • +
      • {% active_link /docs/ecosystem/appdaemon/api/ AppDaemon API Reference %}
        • +
      +
      • + +
    • + {% active_link /docs/ecosystem/hadashboard/ HADashboard %} +
        +
      • {% active_link /docs/ecosystem/hadashboard/installation/ Installation %}
        • +
      • {% active_link /docs/ecosystem/hadashboard/dash_config/ Dashboard Configuration %}
        • +
      • {% active_link /docs/ecosystem/hadashboard/hapush/ HAPush %}
        • +
      • {% active_link /docs/ecosystem/hadashboard/reboot/ Reboot %}
        • +
      • {% active_link /docs/ecosystem/hadashboard/updating/ Updating HADashboard %}
        • +
      +
      • + +
    • + {% active_link /docs/ecosystem/notebooks/ Notebooks %} +
        +
      • {% active_link /docs/ecosystem/notebooks/ Introduction %}
        • +
      • {% active_link /docs/ecosystem/notebooks/installation/ Installation %}
        • +
      • {% active_link /docs/ecosystem/notebooks/graph/ Graph %}
        • +
      • {% active_link /docs/ecosystem/notebooks/api/ Home Assistant API %}
        • +
      • {% active_link /docs/ecosystem/notebooks/database/ Databsase %}
        • +
      • {% active_link /docs/ecosystem/notebooks/stats/ Statistics %}
        • +
      +
      • +
    • + {% active_link /docs/ecosystem/ios/notifications/ iOS %} +
        +
      • {% active_link /docs/ecosystem/ios/notifications/basic/ Basic notifications %}
        • +
          +
        • {% active_link /docs/ecosystem/ios/notifications/examples/ Examples %}
          • +
        • {% active_link /docs/ecosystem/ios/notifications/sounds/ Sounds %}
          • +
        • {% active_link /docs/ecosystem/ios/notifications/architecture/ Architecture %}
          • +
        • {% active_link /docs/ecosystem/ios/notifications/privacy_security_rate_limits/ Privacy, rate limiting and security %}
          • +
        +
      • Advanced notifications
        • +
          +
        • {% active_link /docs/ecosystem/ios/notifications/attachments/ Attachments %}
          • +
        • {% active_link /docs/ecosystem/ios/notifications/content_extensions/ Dynamic content %}
          • +
        • {% active_link /docs/ecosystem/ios/notifications/actions/ Actionable notifications %}
          • +
        • {% active_link /docs/ecosystem/ios/notifications/requesting_location_updates/ Requesting location updates %}
          • +
        +
      • {% active_link /docs/ecosystem/ios/location/ Location Tracking %}
        • +
      • {% active_link /docs/ecosystem/ios/integration/ Integration with other apps %}
        • +
      +
      • +
    +
+
+
diff --git a/source/_includes/asides/ecosystem_appdaemon_navigation.html b/source/_includes/asides/ecosystem_appdaemon_navigation.html deleted file mode 100755 index 8333511804ea..000000000000 --- a/source/_includes/asides/ecosystem_appdaemon_navigation.html +++ /dev/null @@ -1,19 +0,0 @@ -
- -
-

AppDaemon

-
    -
  • {% active_link /ecosystem/appdaemon/ General %}
    • -
  • {% active_link /ecosystem/appdaemon/installation/ Installation %}
    • -
  • {% active_link /ecosystem/appdaemon/configuration/ AppDaemon Configuration %}
    • -
  • {% active_link /ecosystem/appdaemon/example_apps/ Example Apps %}
    • -
  • {% active_link /ecosystem/appdaemon/running/ Running AppDaemon %}
    • -
  • {% active_link /ecosystem/appdaemon/reboot/ Starting AppDaemon at Reboot %}
    • -
  • {% active_link /ecosystem/appdaemon/operation/ AppDaemon Operation %}
    • -
  • {% active_link /ecosystem/appdaemon/windows/ AppDaemon on Windows %}
    • -
  • {% active_link /ecosystem/appdaemon/updating/ Updating AppDaemon %}
    • -
  • {% active_link /ecosystem/appdaemon/tutorial/ AppDaemon Tutorial %}
    • -
  • {% active_link /ecosystem/appdaemon/api/ AppDaemon API Reference %}
    • -
-
-
diff --git a/source/_includes/asides/ecosystem_hadashboard_navigation.html b/source/_includes/asides/ecosystem_hadashboard_navigation.html deleted file mode 100755 index 8053a2ff9933..000000000000 --- a/source/_includes/asides/ecosystem_hadashboard_navigation.html +++ /dev/null @@ -1,14 +0,0 @@ -
- -
-

HADashboard

-
    -
  • {% active_link /ecosystem/hadashboard/ General %}
    • -
  • {% active_link /ecosystem/hadashboard/installation/ Installation %}
    • -
  • {% active_link /ecosystem/hadashboard/dash_config/ Dashboard Configuration %}
    • -
  • {% active_link /ecosystem/hadashboard/hapush/ HAPush %}
    • -
  • {% active_link /ecosystem/hadashboard/reboot/ Reboot %}
    • -
  • {% active_link /ecosystem/hadashboard/updating/ Updating HADashboard %}
    • -
-
-
diff --git a/source/_includes/asides/ecosystem_ios_navigation.html b/source/_includes/asides/ecosystem_ios_navigation.html deleted file mode 100644 index 152b4494be54..000000000000 --- a/source/_includes/asides/ecosystem_ios_navigation.html +++ /dev/null @@ -1,39 +0,0 @@ -
- -
-

iOS Guide

-
    -
  • - {% active_link /ecosystem/ios/ General %} - {% comment %} -
      -
    • {% active_link /ecosystem/ios/requirements/ Requirements %}
      • -
    • {% active_link /ecosystem/ios/getting_started/ Getting Started %}
      • -
    • {% active_link /ecosystem/ios/features/ Features %}
      • -
    • {% active_link /ecosystem/ios/devices_file/ ios.conf %}
      • -
    - {% endcomment %} -
    • -
  • - {% active_link /ecosystem/ios/notifications/ Push Notifications %} -
      -
    • {% active_link /ecosystem/ios/notifications/basic/ Basic notifications %}
      • -
    • Advanced notifications
      • -
        -
      • {% active_link /ecosystem/ios/notifications/attachments/ Attachments %}
        • -
      • {% active_link /ecosystem/ios/notifications/content_extensions/ Dynamic content %}
        • -
      • {% active_link /ecosystem/ios/notifications/actions/ Actionable notifications %}
        • -
      • {% active_link /ecosystem/ios/notifications/requesting_location_updates/ Requesting location updates %}
        • -
      -
    • {% active_link /ecosystem/ios/notifications/examples/ Examples %}
      • -
    • {% active_link /ecosystem/ios/notifications/sounds/ Sounds %}
      • -
    • {% active_link /ecosystem/ios/notifications/architecture/ Architecture %}
      • -
    • {% active_link /ecosystem/ios/notifications/privacy_security_rate_limits/ Privacy, rate limiting and security %}
      • -
    -
    • -
  • {% active_link /ecosystem/ios/location/ Location Tracking %}
    • - {% comment %}
  • {% active_link /ecosystem/ios/sensor/ Battery Sensors %}
    • {% endcomment %} -
  • {% active_link /ecosystem/ios/integration/ Integration with other apps %}
    • -
-
-
diff --git a/source/_includes/asides/ecosystem_navigation.html b/source/_includes/asides/ecosystem_navigation.html deleted file mode 100755 index 24285c4f0bf6..000000000000 --- a/source/_includes/asides/ecosystem_navigation.html +++ /dev/null @@ -1,31 +0,0 @@ -{% assign url_parts = page.url | split: "/" %} -{% if url_parts[2] == "ios" %} - {% include asides/ecosystem_ios_navigation.html | compact_newlines %} -{% elsif url_parts[2] == "hadashboard" %} - {% include asides/ecosystem_hadashboard_navigation.html | compact_newlines %} -{% elsif url_parts[2] == "appdaemon" %} - {% include asides/ecosystem_appdaemon_navigation.html | compact_newlines %} -{% elsif url_parts[2] == "notebooks" %} - {% include asides/ecosystem_notebooks_navigation.html | compact_newlines %} -{% comment %} -{% elsif url_parts[2] == "cookbook" %} - {% include asides/cookbook_navigation.html | compact_newlines %} -{% endcomment %} -{% else %} -
- {% include edit_github.html %} - {% assign ecosystem = site.ecosystem | sort: "title" %} - -
-

Ecosystem

-
    - {% for tool in ecosystem %} - {% assign filename = tool.path | split: "/" %} - {% if filename.size == 2 %} -
  • {{tool.title}}
    • - {% endif %} - {% endfor %} -
-
-
-{% endif %} diff --git a/source/_includes/asides/ecosystem_notebooks_navigation.html b/source/_includes/asides/ecosystem_notebooks_navigation.html deleted file mode 100644 index 72415a3dd0be..000000000000 --- a/source/_includes/asides/ecosystem_notebooks_navigation.html +++ /dev/null @@ -1,15 +0,0 @@ -
- -
-

Jupyter Notebooks

-
    -
  • {% active_link /ecosystem/notebooks/ Introduction %}
    • -
  • {% active_link /ecosystem/notebooks/installation/ Installation %}
    • -
  • {% active_link /ecosystem/notebooks/graph/ Graph %}
    • -
  • {% active_link /ecosystem/notebooks/api/ Home Assistant API %}
    • -
  • {% active_link /ecosystem/notebooks/Database/ Databsase %}
    • -
  • {% active_link /ecosystem/notebooks/stats/ Statistics %}
    • -
-
-
- diff --git a/source/_includes/asides/getting_started_navigation.html b/source/_includes/asides/getting_started_navigation.html index d43017616593..9d41bb402b13 100644 --- a/source/_includes/asides/getting_started_navigation.html +++ b/source/_includes/asides/getting_started_navigation.html @@ -4,75 +4,12 @@

Getting Started Guide

    -
  • - {% active_link /getting-started/ Installation %} -
      -
    • {% active_link /getting-started/installation-python/ Python %}
      • -
    • {% active_link /getting-started/updating/ Updating %}
      • -
    • {% active_link /getting-started/troubleshooting/ Troubleshooting %}
      • -
    -
    • -
  • - {% active_link /getting-started/hassbian/ Hassbian %} -
      -
    • {% active_link /getting-started/hassbian-installation/ Installation %}
      • -
    • {% active_link /getting-started/hassbian-customization/ Customization %}
      • -
    • {% active_link /getting-started/hassbian-common-tasks/ Common tasks %}
      • -
    • {% active_link /getting-started/hassbian-integrations/ Integrations %}
      • -
    • {% active_link /getting-started/hassbian-upgrading/ Upgrading %}
      • -
    -
    • -
  • - {% active_link /getting-started/configuration/ Configuration %} -
      -
    • {% active_link /getting-started/yaml/ YAML %}
      • -
    • {% active_link /getting-started/basic/ Basic information %}
      • -
    • {% active_link /getting-started/devices/ Setting up devices %}
      • -
    • {% active_link /getting-started/customizing-devices/ Customizing devices and services %}
      • -
    • {% active_link /getting-started/presence-detection/ Presence Detection %}
      • -
    • {% active_link /getting-started/troubleshooting-configuration/ Troubleshooting %}
      • -
    • {% active_link /getting-started/securing/ Security Check Points %}
      • -
    -
    • -
  • - {% active_link /getting-started/automation/ Automation %} -
      -
    • {% active_link /getting-started/automation-create-first/ Tutorial %}
      • -
    • {% active_link /getting-started/automation-trigger/ Triggers %}
      • -
    • {% active_link /getting-started/automation-condition/ Conditions %}
      • -
    • {% active_link /getting-started/automation-action/ Actions %}
      • -
    • {% active_link /getting-started/automation-templating/ Templates %}
      • -
    -
    • -
  • - {% active_link /getting-started/scripts/ Scripts %} -
      -
    • {% active_link /getting-started/scripts-service-calls/ Service Calls %}
      • -
    • {% active_link /getting-started/scripts-conditions/ Conditions %}
      • -
    -
    • -
  • - {% active_link /getting-started/z-wave/ Z-Wave %} -
      -
    • {% active_link /getting-started/z-wave-controllers/ Controllers %}
      • -
    • {% active_link /getting-started/z-wave-settings/ Modifying Settings %}
      • -
    • {% active_link /getting-started/z-wave-device-specific/ Device Specific %}
      • -
    -
    • -
  • - {% active_link /getting-started/autostart/ Autostart %} -
      -
    • {% active_link /getting-started/autostart-systemd/ Linux - systemd %}
      • -
    • {% active_link /getting-started/autostart-upstart/ Linux - Upstart %}
      • -
    • {% active_link /getting-started/autostart-init.d/ Linux - init.d %}
      • -
    • {% active_link /getting-started/autostart-macos/ macOS %}
      • -
    • {% active_link /getting-started/autostart-synology/ Synology NAS %}
      • -
    -
    • -
  • {% active_link {{site_root}}/topics/ Advanced Topics %}
    • -
  • {% active_link {{site_root}}/details/ Details %}
    • -
  • {% active_link /getting-started/mobile/ Add to Android/iOS Homescreen %}
    • -
  • {% active_link /getting-started/browsers/ Browser Compatibility List %}
    • +
  • {% active_link /getting-started/ Installation %} +
  • {% active_link /getting-started/configuration/ Configuration %}
    • +
  • {% active_link /getting-started/automation/ Automation %}
    • +
  • {% active_link /getting-started/automation-2/ Automation 2 %}
    • +
  • {% active_link /getting-started/presence-detection/ Presence detection %}
    • +
  • {% active_link /getting-started/use/ Use it! %}
diff --git a/source/_includes/custom/navigation.html b/source/_includes/custom/navigation.html index 98337cf3137c..d6188c1408ea 100644 --- a/source/_includes/custom/navigation.html +++ b/source/_includes/custom/navigation.html @@ -11,7 +11,7 @@ {% endcomment %}
  • Getting started
  • Components
    • -
  • Ecosystem
    • +
  • Docs
  • Examples
  • Developers
  • Blog
    • diff --git a/source/_includes/site/sidebar.html b/source/_includes/site/sidebar.html index 14fdb5f499d6..dcaf694b71e5 100644 --- a/source/_includes/site/sidebar.html +++ b/source/_includes/site/sidebar.html @@ -6,10 +6,10 @@ {% include asides/cookbook_navigation.html | compact_newlines %} {% elsif url_parts[1] == 'developers' %} {% include asides/developers_navigation.html | compact_newlines %} - {% elsif url_parts[1] == 'ecosystem' %} - {% include asides/ecosystem_navigation.html | compact_newlines %} {% elsif url_parts[1] == 'getting-started' %} {% include asides/getting_started_navigation.html | compact_newlines %} + {% elsif url_parts[1] == 'docs' %} + {% include asides/docs_navigation.html | compact_newlines %} {% else %} {% include asides/about.html %} diff --git a/source/details/index.markdown b/source/details/index.markdown deleted file mode 100644 index ff2fccd135e3..000000000000 --- a/source/details/index.markdown +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: page -title: "Details Topics" -description: "Details about Home Assistant." -date: 2016-10-20 12:00 -0800 -sidebar: false -comments: false -sharing: true -footer: true -regenerate: true -hide_github_edit: true ---- - -This page is a collection of further details about Home Assistant. - -{% assign details = site.details | sort: 'title' %} - -{% for detail in details %} -* [{{detail.title}}]({{detail.url}}) -{% endfor %} diff --git a/source/docs/index.markdown b/source/docs/index.markdown new file mode 100644 index 000000000000..4c743e1b1210 --- /dev/null +++ b/source/docs/index.markdown @@ -0,0 +1,56 @@ +--- +layout: page +title: "Documentation" +description: "Documentation for Home Assistant" +date: 2016-10-26 00:46 +sidebar: true +comments: false +sharing: true +footer: true +--- + +The documentation covers from beginner to advanced topic around the installation, the setup, the configuration, and the usage of Home Assistant. + +
    + +
    + +
    +
    Hassbian
    +     + +
    + +
    +
    Configuration
    +     + +
    + +
    +
    Z-Wave
    +     + +
    + +
    +
    MQTT
    +     + +
    + +
    +
    HADashboard
    +     + +
    + +
    +
    iOS
    +     +
    + +
    + + +To see what Home Assistant can do, take a look at the [demo page](/demo). diff --git a/source/getting-started/automation-create-first.markdown b/source/getting-started/automation-2.markdown similarity index 72% rename from source/getting-started/automation-create-first.markdown rename to source/getting-started/automation-2.markdown index 9f9f4f5f1e74..71c32304f8da 100644 --- a/source/getting-started/automation-create-first.markdown +++ b/source/getting-started/automation-2.markdown @@ -1,17 +1,18 @@ --- layout: page -title: "Your First Automation" -description: "Step by step guiding through making your first automation." +title: "Your second Automation" +description: "Step by step guiding through making your second automation." date: 2016-04-24 08:30 +0100 sidebar: true comments: false sharing: true footer: true +redirect_from: /getting-started/automation-create-first/ --- -Before we dive deeper into what every piece of automation _can_ do, let's look at a simple automation rule: **Turn on the lights when the sun sets** +After the scratch on the Automation surface, let's dive deeper and create the automation rule: **Turn on the lights when the sun sets** -In this example, we are defining a trigger to track the sunset and tell it to fire when the sun is setting. When this event is triggered, the service `light.turn_on` is called without any parameters. Because we specify no parameters, it will turn on all the lights. +We are defining a [trigger](/docs/automation/trigger/) to track the sunset and tell it to fire when the sun is setting. When this event is triggered, the service `light.turn_on` is called without any parameters. Because we specify no parameters, it will turn on all the lights. ```yaml # Example configuration.yaml entry @@ -26,9 +27,9 @@ automation: service: light.turn_on ``` -Starting with 0.28 automation rules can be reloaded from the [frontend](/components/automation/) and are shown by default. With [`hide_entity:`](/components/automation/) you can control this behaviour. It's very handy if you are working on your rules but when a rule is finished and you don't want to see that rule in your frontend, you can set `hide_entity:` to `True`. To set an automation to be disabled when HASS starts set `initial_state:` to `False`. +Starting with 0.28 automation rules can be reloaded from the [frontend](/components/automation/) and are shown by default. With [`hide_entity:`](/components/automation/) you can control this behaviour. It's very handy if you are working on your rules but when a rule is finished and you don't want to see that rule in your frontend, you can set `hide_entity:` to `True`. To set an automation to be disabled when Home Assistant starts set `initial_state:` to `False`. -After a few days of running this automation rule, you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a condition to only turn on the lights if anyone is home. +After a few days of running this automation rule, you come to realize that this automation rule is not good enough. It was already dark when the lights went on and the one day you weren't home, the lights turned on anyway. Time for some tweaking. Let's add an offset to the sunset trigger and a [condition](/docs/automation/condition/) to only turn on the lights if anyone is home. ```yaml # Example configuration.yaml entry @@ -78,7 +79,7 @@ automation: Christmas is coming along and you decide to buy a remote switch to control the Christmas lights from Home Assistant. You can't claim to live in the house of the future if you're still manually turning on your Christmas lights! -We hook the switch up to Home Assistant and grab the entity ID from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our action. We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on. +We hook the switch up to Home Assistant and grab the entity ID from the developer tools: `switch.christmas_lights`. We will update the group to include the switch and will change our [action](/docs/automation/action/). We are no longer able to call `light.turn_on` because we also want to turn on a switch. This is where `homeassistant.turn_on` comes to the rescue. This service is capable of turning any entity on. ```yaml # Example configuration.yaml entry @@ -104,14 +105,5 @@ automation: entity_id: group.living_room ``` -### {% linkable_title Learn more %} +### [Next step: Presence detection »](/getting-started/presence-detection/) - - [Triggers] - - [Conditions] - - [Actions] - - [Templating] (advanced) - -[Triggers]: /getting-started/automation-trigger/ -[Conditions]: /getting-started/automation-condition/ -[Actions]: /getting-started/automation-action/ -[Templating]: /getting-started/automation-templating/ diff --git a/source/getting-started/automation.markdown b/source/getting-started/automation.markdown index 660b6772a8e6..31812056d94c 100644 --- a/source/getting-started/automation.markdown +++ b/source/getting-started/automation.markdown @@ -1,54 +1,31 @@ --- layout: page title: "Automating Home Assistant" -description: "Steps to help you get automation setup in Home Assistant." -date: 2015-09-19 09:40 +description: "Instructions to get started with Automation using Home Assistant." +date: 2016-09-26 21:00 sidebar: true comments: false sharing: true footer: true --- -When all your devices are set up, it's time to put the cherry on the pie: automation. Home Assistant offers [a few built-in automations](/components/#automation) – but you'll be using the automation component to set up your own rules, for the most part. - -Home Assistant offers a wide range of automation configurations. In the next few pages, 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-config]. - -[cookbook-config]: /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 +When your devices are set up, it's time to put the cherry on the pie: **automation**. Home Assistant offers [a few built-in automations](/components/#automation) – but you'll be using the automation component to set up your own rules, for the most part. + +If you added a random sensor in the previous step then you can use that sensor for your very first automation: + +```yaml +automation: + - alias: Check sensor value and show notification + trigger: + platform: numeric_state + entity_id: sensor.random + above: 10 + action: + service: persistent_notification.create + data: + message: "Sensor value greater than 10" ``` -The example consists of three different parts: a trigger, a condition and an 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. - -

    -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. -

    - -### {% 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 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 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. +For further details about automation, please take the next step or the [automation documentation](/docs/automation/). -### [Next step: Your First Automation »](/getting-started/automation-create-first/) +### [Next step: Home Assistant Automation Part 2 »](/getting-started/automation-2/) diff --git a/source/getting-started/configuration.markdown b/source/getting-started/configuration.markdown index ee68ebb88b2a..fa8d70c03610 100644 --- a/source/getting-started/configuration.markdown +++ b/source/getting-started/configuration.markdown @@ -1,36 +1,27 @@ --- layout: page -title: "Configuring Home Assistant" -description: "Configuring Home Assistant." -date: 2015-03-23 12:50 +title: "Configure Home Assistant" +description: "Instructions to get Home Assistant configured." +date: 2016-09-26 21:00 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. +When launched for the first time, Home Assistant will write a default configuration file, called `configuration.yaml`, enabling the web interface and [device discovery](/components/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: +The `configuration.yaml` is written in [YAML](/docs/configuration/yaml/), stored in [`.homeassistant`](/docs/configuration/), and can be modified with a text editor. -| OS | Path | -| -- | ---- | -| macOS | `~/.homeassistant` | -| Linux | `~/.homeassistant` | -| Windows | `%APPDATA%/.homeassistant` | +See the [components overview page](/components/) to find sample entries for your devices and services. For a sensor that is showing [random values](/components/sensor.random/), the entry would looks like the sample below: -If you want to use a different folder for configuration, use the config command line parameter: `hass --config path/to/config`. +```yaml +sensor: + - platform: random +``` -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. +The [Setting up devices part](/docs/configuration/devices/) contains of the documentation additional details about adding device and services and [customizization](docs/configuration/customizing-devices/). -

    - You will have to restart Home Assistant for changes to `configuration.yaml` to take effect. -

    +For further details about configuration, please take a look at the [configuration documentation](/docs/configuration/). -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). - -

    - 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. -

    - -### [Next step: Get familiar with YAML »](/getting-started/yaml/) +### [Next step: Automate Home Assistant »](/getting-started/automation/) diff --git a/source/getting-started/index.markdown b/source/getting-started/index.markdown index fd1e441c5a56..35f028591503 100644 --- a/source/getting-started/index.markdown +++ b/source/getting-started/index.markdown @@ -12,13 +12,13 @@ footer: true You will need to install Home Assistant before we can get started. You can install Home Assistant on your computer or you can turn a Raspberry Pi into a dedicated Home Assistant hub.
    - +
    Install Hassbian on your Raspberry Pi 3
     - +
    @@ -26,16 +26,8 @@ You will need to install Home Assistant before we can get started. You can insta
    -### {% linkable_title Alternative methods %} +For alternative installation methods please take a look at the [installation documentation](/docs/installation/). -For advanced users we have several alternative guides for installing Home Assistant. +If you run into any issues, please see [the troubleshooting page](/docs/installation/troubleshooting/) or [communication channels](/help/). It contains solutions to many commonly encountered issues. -- [Docker](/getting-started/installation-docker/) -- [Manual Raspberry Pi installation](/getting-started/installation-raspberry-pi/) (requires existing Raspbian installation) -- [Raspberry Pi All-In-One Installer Script](/getting-started/installation-raspberry-pi-all-in-one/) (requires existing Raspbian installation) -- [Vagrant](/getting-started/installation-vagrant/) -- [Synology NAS](/getting-started/installation-synology/) -- [Virtualenv Linux](/getting-started/installation-virtualenv/) - -[rpi]: /getting-started/installation-raspberry-pi-image/ -[python]: /getting-started/installation-python/ +### [Next step: Configuring Home Assistant »](/getting-started/configuration/) diff --git a/source/getting-started/installation-python.markdown b/source/getting-started/installation-python.markdown deleted file mode 100644 index d4ea0f5f3626..000000000000 --- a/source/getting-started/installation-python.markdown +++ /dev/null @@ -1,54 +0,0 @@ ---- -layout: page -title: "Installation on your computer" -description: "Step by step guide to install Home Assistant on your computer." -date: 2014-12-18 22:57 -sidebar: true -comments: false -sharing: true -footer: true ---- - -Installing and running Home Assistant on your local machine is easy. 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. - -Once 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 Linux instructions][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) - - [Mac OS X](https://www.youtube.com/watch?v=hej6ipN86ls) - - [Ubuntu 14.04](https://www.youtube.com/watch?v=SXaAG1lGNH0) - -### {% linkable_title Updating %} - -To update Home Assistant to the latest release check the [Updating section](/getting-started/updating/). - -### {% linkable_title Troubleshooting %} - -If you run into any issues, please see [the troubleshooting page](/getting-started/troubleshooting/). It contains solutions to many 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? %} - -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/) - -[virtualenv]: /getting-started/installation-virtualenv/ diff --git a/source/getting-started/presence-detection.markdown b/source/getting-started/presence-detection.markdown index 38cd1e5f143e..b3956b7213a9 100644 --- a/source/getting-started/presence-detection.markdown +++ b/source/getting-started/presence-detection.markdown @@ -2,7 +2,7 @@ layout: page title: "Setting up presence detection" description: "Instructions how to setup presence detection within Home Assistant." -date: 2015-10-4 12:08 +date: 2015-10-04 12:08 sidebar: true comments: false sharing: true @@ -41,8 +41,6 @@ OwnTracks communicates directly with your MQTT broker; no data will pass through Home Assistant will know the location of your device if you are using OwnTracks. By [setting up zones][zone] you will be able to add names to the locations of your devices. This way you can easily spot on the state page where the people in your house are and use it as [triggers][trigger] and [conditions][condition] for automation. -### [Next step: Setting up automation »](/getting-started/automation/) - [routers]: /components/#presence-detection [nmap]: /components/device_tracker.nmap_tracker/ [ha-owntracks]: /components/device_tracker.owntracks/ @@ -53,3 +51,5 @@ Home Assistant will know the location of your device if you are using OwnTracks. [trigger]: /getting-started/automation-trigger/#zone-trigger [condition]: /getting-started/automation-condition/#zone-condition +### [Next step: Use Home Assistant »](/getting-started/use/) + diff --git a/source/getting-started/use.markdown b/source/getting-started/use.markdown new file mode 100644 index 000000000000..75cc86d8b10c --- /dev/null +++ b/source/getting-started/use.markdown @@ -0,0 +1,26 @@ +--- +layout: page +title: "Manage Home Assistant" +description: "Instructions about how to manage Home Assistant." +date: 2016-09-26 21:00 +sidebar: true +comments: false +sharing: true +footer: true +--- + +If you are using Hassbian, browse to [http://hassbian.local:8123](http://hassbian.local:8123) to open the Home Assistant frontend. + +To reload your configuration, [login](/docs/hassbian/common-tasks/#login-to-the-raspberry-pi) your Raspberry Pi + +```bash +$ ssh pi@ip-address-of-pi +``` + +and [restart](/docs/hassbian/common-tasks/#startstoprestart-home-assistant) Home Assistant + +```bash +$ sudo systemctl restart home-assistant@homeassistant.service +``` + +For tweaking your Home Assistant setup, take a look at the [documentation](/docs/), ask your questions in our [forum](https://community.home-assistant.io/), join us for a [chat](https://gitter.im/home-assistant/home-assistant), or report your [issues](https://github.com/home-assistant/home-assistant/issues). diff --git a/source/images/supported_brands/pencil.png b/source/images/supported_brands/pencil.png new file mode 100644 index 000000000000..0d17c08ee467 Binary files /dev/null and b/source/images/supported_brands/pencil.png differ diff --git a/source/images/supported_brands/view-dashboard.png b/source/images/supported_brands/view-dashboard.png new file mode 100644 index 000000000000..33c23e2e5159 Binary files /dev/null and b/source/images/supported_brands/view-dashboard.png differ diff --git a/source/topics/index.markdown b/source/topics/index.markdown deleted file mode 100644 index 421b32150415..000000000000 --- a/source/topics/index.markdown +++ /dev/null @@ -1,20 +0,0 @@ ---- -layout: page -title: "Advanced Topics" -description: "Documentation about the more advanced features in Home Assistant." -date: 2016-03-12 12:00 -0800 -sidebar: false -comments: false -sharing: true -footer: true -regenerate: true -hide_github_edit: true ---- - -Home Assistant is built from many small building blocks that together offer a powerful and customizable system. This page is a collection of the more advanced topics. - -{% assign topics = site.topics | sort: 'title' %} - -{% for topic in topics %} -* [{{topic.title}}]({{topic.url}}) -{% endfor %}