jeena/home-assistant.github.io
1
0
Fork 0
Code Issues Pull requests Projects Packages Wiki Activity Actions

Merge branch 'current' into next

Browse source
This commit is contained in:
Paulus Schoutsen 2016-10-21 22:52:07 -07:00
commit be8ea1aef1
77 changed files with 1151 additions and 293 deletions
Download patch file Download diff file Expand all files Collapse all files

7
source/getting-started/automation-condition.markdown
View file

@ -11,13 +11,6 @@ footer: true
Conditions are an optional part of an automation rule and 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.
If your triggers and conditions are exactly the same, you can use a shortcut to specify conditions. In this case, triggers that are not valid conditions will be ignored.
```yaml
automation:
condition: use_trigger_values
```
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].
Example of using condition:

3
source/getting-started/automation-create-first.markdown
View file

@ -17,6 +17,7 @@ In this example, we are defining a trigger to track the sunset and tell it to fi
# Example configuration.yaml entry
automation:
alias: Turn on light when sun sets
initial_state: True
hide_entity: False
trigger:
platform: sun
@ -25,7 +26,7 @@ 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 is 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`.
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 is 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`.
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.

2
source/getting-started/automation-templating.markdown
View file

@ -11,7 +11,7 @@ footer: true
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 rendering as the `trigger` variable.
The trigger data made is available during [template](/topics/templating/) rendering as the `trigger` variable.
```yaml
# Example configuration.yaml entries

2
source/getting-started/automation.markdown
View file

@ -31,7 +31,7 @@ The first line is the trigger of the automation rule. Triggers describe events t
The second line is the condition part of the automation rule. 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 third part is the action which will be performed when a rule is triggered and all conditions are met. For example, it can turn a light on, set the temperature on your thermostat or activate a scene.
<p class='note'>
The difference between a condition and a trigger can be confusing as they are very similar. Triggers look at the actions, while conditions look at the results: turning a light on vs a light being on.

2
source/getting-started/index.markdown
View file

@ -9,7 +9,7 @@ sharing: true
footer: true
---
Below you can find the standard instructions. See the sidebar for installation instructions for specific platforms. If you're running a Linux-based platform, we suggest to follow the [VirtualEnv Linux instructions] to avoid having to use root.
Below you can find the standard instructions. See the sidebar for installation instructions for specific platforms. If you're running a Linux-based platform, we suggest you to follow the [VirtualEnv Linux instructions] to avoid using root.
[Virtualenv Linux instructions]: /getting-started/installation-virtualenv/

114
source/getting-started/installation-raspberry-pi-image.markdown
View file

@ -1,7 +1,7 @@
---
layout: page
title: "Hassbian image for Raspberry Pi"
description: "Instructions to flash the Home Assistant Hassbian image on a Raspberry Pi."
title: "HASSbian image for Raspberry Pi"
description: "Instructions to flash the Home Assistant HASSbian image on a Raspberry Pi."
date: 2016-09-26 21:00
sidebar: true
comments: false
@ -9,15 +9,15 @@ sharing: true
footer: true
---
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 (~5 minutes).
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 (~5 minutes).
1. [Download the latest image][image-download]
2. Flash the image to an SD card:
- [Windows][flash-windows]
- [Linux][flash-linux]
- [Mac][flash-macos]
- [Mac OS][flash-macos]
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 5 minutes.
4. Insert SD card to Raspberry Pi and turn it on. Initial installation of Home Assistant will take about 5 minutes.
These instructions are also available as a [video](https://www.youtube.com/watch?v=iIz6XqDwHEk).
@ -36,21 +36,104 @@ Some extra tips:
### {% linkable_title Technical Details %}
- Home Assistant is installed in a virtual Python environment at `src/homeassistant`
- Home Assistant is installed in a virtual Python environment at `/src/homeassistant/`
- Home Assistant will be started as a service run by the user `homeassistant`
- The configuration is located at `/home/homeassistant/.homeassistant`
{% comment %}
### {% linkable_title Managing your HASSbian installation %}
#### {% linkable_title Login to HASSbian on the Raspberry Pi %}
To login to your Raspberry Pi running HASSbian your going to be using a ssh client. Depending on your platform there are several alternatives for doing this. Linux and Max OS generally have a ssh client installed. Windows users are recommended to download and install the ssh client [Putty][ssh-putty].
TODO:
Connect to the Raspberry Pi over ssh. Default user name is `pi` and password is `raspberry`.
Linux and Mac OS users execute the following command in a terminal.
```bash
$ ssh pi@ip-address-of-pi
```
Windows users start [Putty][ssh-putty], enter the IP address of the Raspberry Pi in the *Host name* field and port 22 in the *Port* field. Then click *Open* and a terminal window will open. Enter the credentials. Default user name is `pi` and password is `raspberry`.
Add instructions:
#### {% linkable_title Start/Stop/Restart Home Assistant on HaSSbian %}
Log in as the `pi` account account and execute the following commands:
```bash
sudo systemctl stop home-assistant@homeassistant.service
```
Replace `stop` with `start` or `restart` to get the desired functionality.
To get the current state of the `homeassistant.service` replace `stop` with `status`.
- How to login via shell (?) or at least mention how to work with a Pi
- How to restart HASS
- How to see the logs for config validation
- How to update the config
#### {% linkable_title Update Home Assistant on HASSbian %}
Log in as the `pi` account and execute the following commands:
```bash
sudo systemctl stop home-assistant@homeassistant.service
sudo su -s /bin/bash homeassistant
source /srv/homeassistant/bin/activate
pip3 install --upgrade homeassistant
exit
sudo systemctl start home-assistant@homeassistant.service
```
This will in order do the following:
- Stop the Home Assistant service running on HASSbian
- Open a shell as the `homeassistant` user running the Homeassistant service and that has ownership over the Home Assistant installation.
- Change into the virtual Python environment at `/src/homeassistant/` containing the Home Assistant installation.
- Upgrade the Home Assistant installation to the latest release.
- Exit the shell and return to the `pi` user.
- Restart the Home Assistant service.
{% endcomment %}
#### {% linkable_title Manually launch Home Assistant on HASSbian %}
Log in as the `pi` account and execute the following commands:
```bash
sudo su -s /bin/bash homeassistant
source /srv/homeassistant/bin/activate
hass
```
This will start Home Assistant in your shell and output anything that ends up in the log and more into the console. This will fail if the Home Assistant service is already running so don't forget to [stop][stop-homeassistant] it first.
#### {% linkable_title Check your configuration on HASSbian %}
Log in as the `pi` account and execute the following commands:
```bash
sudo su -s /bin/bash homeassistant
source /srv/homeassistant/bin/activate
hass --script check_config
```
This will output any errors in your configuration files to console.
#### {% linkable_title Read the Home Assistant log file on HASSbian %}
Log in as the `pi` account and execute the following commands:
```bash
sudo su -s /bin/bash homeassistant
cd /home/homeassistant/.homeassistant
nano homeassistant.log
```
This will in order do the following:
- Open a shell as the `homeassistant` user.
- Change directory to the Home Assistant configuration directory.
- Open the log file in the nano editor.
Optionaly, you can also view the log with `journalctl`.
Log in as the `pi` account and execute the following commands:
```bash
sudo journalctl -fu home-assistant@homeassistant.service
```
#### {% linkable_title Edit the Home Assistant configuration on HASSbian %}
Log in as the `pi` account and execute the following commands:
```bash
sudo su -s /bin/bash homeassistant
cd /home/homeassistant/.homeassistant
nano configuration.yaml
```
This will in order do the following:
- Open a shell as the `homeassistant` user.
- Change directory to the Home Assistant configuration directory.
- Open the configuration file in the nano editor.
It's generally recommended that you read the [Getting started][configuring-homeassistant] guide for how to configure Home Assistant.
#### {% linkable_title Upgrade and update HASSbian %}
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.
Log in as the `pi` account and execute the following commands:
```bash
sudo apt-get update
sudo apt-get upgrade
```
Press `Y` to confirm that you would like to continue.
### {% linkable_title Troubleshooting %}
@ -69,3 +152,6 @@ In addition to this site, check out these sources for additional help:
[flash-macos]: https://www.raspberrypi.org/documentation/installation/installing-images/mac.md
[flash-windows]: https://www.raspberrypi.org/documentation/installation/installing-images/windows.md
[pi-components]: /getting-started/installation-raspberry-pi/#raspberry-pi-hardware-specific-components
[ssh-putty]: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html
[stop-homeassistant]: /getting-started/installation-raspberry-pi-image/#startstoprestart-home-assistant-on-hassbian
[configuring-homeassistant]: /getting-started/configuration/

2
source/getting-started/presence-detection.markdown
View file

@ -44,7 +44,7 @@ Home Assistant will know the location of your device if you are using OwnTracks.
### [Next step: Setting up automation &raquo;](/getting-started/automation/)
[routers]: /components/#presence-detection
[nmap]: /components/device_tracker.nmap_scanner/
[nmap]: /components/device_tracker.nmap_tracker/
[ha-owntracks]: /components/device_tracker.owntracks/
[ha-locative]: /components/device_tracker.locative/
[mqtt-self]: /components/mqtt/#run-your-own

28
source/getting-started/securing.markdown Normal file
View file

@ -0,0 +1,28 @@
---
layout: page
title: "Securing"
description: "Instructions how to secure your Home Assistant installation."
date: 2016-10-06 06:00
sidebar: true
comments: false
sharing: true
footer: true
---
One of the reasons to use Home Assistant is that it's not depending on cloud services. Even if you are only using Home Assistant in your local network, you should consider securing your instance.
### {% linkable_title Checklist %}
- [Protect your web interface with a password](https://home-assistant.io/getting-started/basic/#password-protecting-the-web-interface)
- Secure your host. Sources could be [Red Hat Enterprise Linux 7 Security Guide](https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/7/pdf/Security_Guide/Red_Hat_Enterprise_Linux-7-Security_Guide-en-US.pdf), [CIS Red Hat Enterprise Linux 7 Benchmark](https://benchmarks.cisecurity.org/tools2/linux/CIS_Red_Hat_Enterprise_Linux_7_Benchmark_v1.0.0.pdf), or the [Securing Debian Manual](https://www.debian.org/doc/manuals/securing-debian-howto/index.en.html).
- Restrict network access to your device. Set `PermitRootLogin no` in your sshd config (usually `/etc/ssh/sshd_config`) and to use keys for authentication instead of passwords.
- Don't run Home Assistant as root.
- Keep your [secrets](/topics/secrets/) safe.
Additional points if you want to allow remote access:
- Protect your communication with [TLS](blog/2015/12/13/setup-encryption-using-lets-encrypt/)
- Protect your communication with [Tor](/cookbook/tor_configuration/)
- Use a [proxy](/cookbook/apache_configuration/)

2
source/getting-started/updating.markdown
View file

@ -16,7 +16,7 @@ The default way to update Home Assistant to the latest release, when available,
$ pip3 install --upgrade homeassistant
```
Different installation methods as [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) may have an alternative way for updating Home Assistant.
Different installation methods as [HASSbian](/getting-started/installation-raspberry-pi-image/#update-home-assistant-on-hassbian), [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) may have an alternative way for updating Home Assistant.
After updating, restart Home Assistant for the changes to take effect. This means that you have to restart `hass` itself or the [autostarting](/getting-started/autostart/) daemon if you use any.

4
source/getting-started/z-wave-device-specific.markdown
View file

@ -11,7 +11,7 @@ footer: true
##### {% linkable_title Motion or alarm sensors %}
In order for Home Assistant to recognize some sensors, you will need to change its configuration from `Basic Set (default)` to `Binary Sensor report` or `Alarm report`.
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.
As of version 0.30 you can set the settings of a Z-Wave device through the dev_service page of Home Assistant with the service: `zwave/set_config_parameter`.
@ -35,7 +35,7 @@ Example entry in dev-service, setting binary reports for an Aeotec Multisensor 6
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.
It is best to pair these devices in OpenZWave Control Panel or another Z-Wave tool that can show you logs while pairing. Home Assistant stores logs from Z-Wave in `OZW.log` in the Home Assistant config directory.
It is best to pair these devices in OpenZWave Control Panel or another Z-Wave tool that can show you logs while pairing. Home Assistant stores logs from Z-Wave in `OZW.log` in the Home Assistant config directory.
You should see communication from the node with lines starting with `info: NONCES` in `OZW.log` when the device is paired successfully with a secure connection. If you use OpenZWave Control Panel to pair, test the device before you save the configuration.
Make sure you copy the newly saved `zwcfg_[home_id].xml`into your Home Assistant configuration directory.

6
source/getting-started/z-wave-settings.markdown
View file

@ -9,13 +9,13 @@ sharing: true
footer: true
---
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.
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.
The reasoning for using these tools is that your Z-Wave controller stores the values and data that are used to control the network. The XML file in the `.homeassistant` configuration directory acts as a settings/values cache for the Z-Wave network, so modifying it directly won't change the network values. The [Open-Zwave Control Panel](https://github.com/OpenZWave/open-zwave-control-panel) writes values directly to the network and will provide you with an updated `.xml` file to overwrite in your `.homeassistant` configuration directory. This is the most foolproof way to make modifications to your Z-Wave devices.
Although totally normal for your Z-Wave stick (Aeon Aeotec Z-Stick Gen5 for example) to cycle through its LEDs (Yellow, Blue and Red) while plugged into your system. If you don like this behaviour then you could turn it off.
It's totally normal for your Z-Wave stick (Aeon Aeotec Z-Stick Gen5 for example) to cycle through its LEDs (Yellow, Blue and Red) while plugged into your system. If you don't like this behaviour it can be turned off.
Use the following commands from a terminal session on your Pi where your Z-Wave stick is connected as an example.
Use the following example commands from a terminal session on your Pi where your Z-Wave stick is connected.
Turn off "Disco lights":

4
source/getting-started/z-wave.markdown
View file

@ -131,7 +131,7 @@ cat /dev/urandom | tr -dc '0-9A-F' | fold -w 32 | head -n 1 | sed -e 's/\(..\)/0
#### {% linkable_title zwave.network_complete %}
Home Assistant will trigger a event when the Z-Wave network is complete. Meaning all of the nodes on the network have been queried. This can take quite som time, depending on wakeup intervals on the battery powered devices on the network.
Home Assistant will trigger a event when the Z-Wave network is complete. Meaning all of the nodes on the network have been queried. This can take quite some time, depending on wakeup intervals on the battery powered devices on the network.
```yaml
- alias: Z-Wave network is complete
@ -220,7 +220,7 @@ The `zwave` component exposes ten services to help maintain the network.
| add_node_secure | Put the Z-Wave controller in secure inclusion mode. Allows one to add a new device with secure communications to the Z-Wave network. |
| association | Add or remove an association in th Z-Wave network
| cancel_command | Cancels a running Z-Wave command. If you have started a add_node or remove_node command, and decides you are not going to do it, then this must be used to stop the inclusion/exclusion command. |
| heal_network | Tells the controller to "heal" the Z-Wave network. Bascially asks the nodes to tell the controller all of their neighbors so the controller can refigure out optimal routing. |
| heal_network | Tells the controller to "heal" the Z-Wave network. Basically asks the nodes to tell the controller all of their neighbors so the controller can refigure out optimal routing. |
| remove_node | Put the Z-Wave controller in exclusion mode. Allows one to remove a device from the Z-Wave network.|
| set_config_parameter | Let's the user set a config parameter to a node.
| soft_reset | Tells the controller to do a "soft reset". This is not supposed to lose any data, but different controllers can behave differently to a "soft reset" command.|