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:
Fabian Affolter 2017-06-03 09:37:04 +02:00
commit 89237a4b2a
No known key found for this signature in database
GPG key ID: E23CD2DD36A4397F
58 changed files with 652 additions and 360 deletions
Download patch file Download diff file Expand all files Collapse all files

10
source/_docs/automation/editor.markdown
View file

@ -69,15 +69,15 @@ If you want to migrate your old automations to use the editor, you'll have to co
- id: my_unique_id # <-- Required for editor to work.
alias: Hello world
trigger:
- entity_id: sun.sun
- platform: state
entity_id: sun.sun
from: below_horizon
platform: state
to: above_horizon
condition:
- above: 17
below: 25
condition: numeric_state
- condition: numeric state
entity_id: sensor.temperature
above: 17
below: 25
value_template: '{% raw %}{{ float(state.state) + 2 }}{% endraw %}'
action:
- service: light.turn_on

2
source/_docs/configuration/securing.markdown
View file

@ -22,7 +22,7 @@ One major advantage of Home Assistant is that it's not dependent on cloud servic
If you want to allow remote access, consider these additional points:
- Protect your communication with [TLS](/blog/2015/12/13/setup-encryption-using-lets-encrypt/)
- Protect your communication with [TLS/SSL](/ecosystem/certificates/lets_encrypt/)
- Protect your communication with [Tor](/cookbook/tor_configuration/)
- Protect your communication with a [self-signed certificate](/cookbook/tls_self_signed_certificate/)
- Use a [proxy](/cookbook/apache_configuration/)

50
source/_docs/configuration/templating.markdown
View file

@ -12,12 +12,8 @@ redirect_from: /topics/templating/
This is an advanced feature of Home Assistant. You'll need a basic understanding of the following things:
- [Home Assistant architecture], especially states.
- [State object]
[Home Assistant architecture]: /developers/architecture/
[State object]: /topics/state_object/
- [Home Assistant architecture](/developers/architecture/), especially states.
- [State object](/topics/state_object/)
Templating is a powerful feature in Home Assistant that allows the user control over information that is going into and out of the system. It is used for:
@ -195,6 +191,45 @@ It depends per component or platform, but it is common to be able to define a te
| `value` | The incoming value. |
| `value_json` | The incoming value parsed as JSON. |
This means that if the incoming values looks like the sample below:
```json
{
"on": "true",
"temp": 21
}
```
The template for `on` would be:
```yaml
'{% raw %}{{value_json.on}}{% endraw %}'
```
Nested JSON in a response is supported as well
```json
{
"sensor": {
"type": "air",
"id": "12345"
},
"values": {
"temp": 26.09,
"hum": 56.73,
}
}
```
Just use the "Square bracket notation" to get the value.
```yaml
'{% raw %}{{ value_json["values"]["temp"] }}{% endraw %}'
```
The following overview contains a couple of options to get the needed values:
```text
# Incoming value:
{"primes": [2, 3, 5, 7, 11, 13]}
@ -213,7 +248,4 @@ It depends per component or platform, but it is common to be able to define a te
{% raw %}{{ value_json.tst | timestamp_local }}{% endraw %}
{% raw %}{{ value_json.tst | timestamp_utc }}{% endraw %}
{% raw %}{{ value_json.tst | timestamp_custom('%Y' True) }}{% endraw %}
# Square bracket notation
{% raw %}{{ value_json["001"] }}{% endraw %}
```

115
source/_docs/ecosystem/nginx.markdown
View file

@ -10,7 +10,7 @@ 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.
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 %}
@ -19,7 +19,7 @@ Chances are, you have a dynamic IP Address (your ISP changes your address period
### {% 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.
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 %}
@ -29,7 +29,7 @@ There are two ways of obtaining an SSL certificate.
If you purchased your own domain, you can use https://letsencrypt.org/ to obtain a free, publicly trusted SSL certificate. This will allow you to work with services like IFTTT. Download and install per the instructions online and get a certificate using the following command.
```
./letsencrypt-auto certonly --standalone -d example.com -d www.example.com
$ sudo ./letsencrypt-auto certonly --standalone -d example.com -d www.example.com
```
Instead of example.com, use your domain. You will need to renew this certificate every 90 days.
@ -38,32 +38,37 @@ Instead of example.com, use your domain. You will need to renew this certificate
If you do not own your own domain, you may generate a self-signed certificate. This will not work with IFTTT, but it will encrypt all of your Home Assistant traffic.
```
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 9999
sudo cp key.pem cert.pem /etc/nginx/ssl
sudo chmod 600 /etc/nginx/ssl/key.pem /etc/nginx/ssl/cert.pem
sudo chown root:root /etc/nginx/ssl/key.pem /etc/nginx/ssl/cert.pem
```bash
$ openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 9999
$ openssl rsa -in key.pem -out key.pem
$ sudo cp key.pem cert.pem /etc/nginx/ssl
$ sudo chmod 600 /etc/nginx/ssl/key.pem /etc/nginx/ssl/cert.pem
$ sudo chown root:root /etc/nginx/ssl/key.pem /etc/nginx/ssl/cert.pem
```
### {% linkable_title 4. Create dhparams file %}
As a fair warning, this file will take a while to generate.
```
cd /etc/nginx/ssl
sudo openssl dhparam -out dhparams.pem 2048
```bash
$ cd /etc/nginx/ssl
$ sudo openssl dhparam -out dhparams.pem 2048
```
### {% linkable_title 5. Install configuration file in nginx. %}
Create a new file `/etc/nginx/sites-available/hass` and copy the configuration file at the bottom of the page into it.
<p class='note'>
Some Linux distributions (including CentOS and Fedora) will not have the `/etc/nginx/sites-available/` directory. In this case, remove the default server {} block from the `/etc/nginx/nginx.conf` file and paste the contents from the bottom of the page in its place. If doing this, proceed to step 7.
</p>
### {% linkable_title 6. Enable the Home Assistant configuration. %}
```
cd /etc/nginx/sites-enabled
sudo unlink default
sudo ln ../sites-available/hass default
```bash
$ cd /etc/nginx/sites-enabled
$ sudo unlink default
$ sudo ln ../sites-available/hass default
```
### {% linkable_title 7. Start NGINX. %}
@ -78,56 +83,54 @@ Forward ports 443 and 80 to your server on your router. Do not forward port 8123
### {% linkable_title NGINX Config %}
```
http {
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
server {
# Update this line to be your domain
server_name example.com;
server {
# Update this line to be your domain
server_name example.com;
# These shouldn't need to be changed
listen [::]:80 default_server ipv6only=off;
return 301 https://$host$request_uri;
}
# These shouldn't need to be changed
listen [::]:80 default_server ipv6only=off;
return 301 https://$host$request_uri;
}
server {
# Update this line to be your domain
server_name example.com;
server {
# Update this line to be your domain
server_name example.com;
# Ensure these lines point to your SSL certificate and key
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# Use these lines instead if you created a self-signed certificate
# ssl_certificate /etc/nginx/ssl/cert.pem;
# ssl_certificate_key /etc/nginx/ssl/key.pem;
# Ensure these lines point to your SSL certificate and key
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
# Use these lines instead if you created a self-signed certificate
# ssl_certificate /etc/nginx/ssl/cert.pem;
# ssl_certificate_key /etc/nginx/ssl/key.pem;
# Ensure this line points to your dhparams file
ssl_dhparam /etc/nginx/ssl/dhparams.pem;
# Ensure this line points to your dhparams file
ssl_dhparam /etc/nginx/ssl/dhparams.pem;
# These shouldn't need to be changed
listen [::]:443 default_server ipv6only=off; # if your nginx version is >= 1.9.5 you can also add the "http2" flag here
add_header Strict-Transport-Security "max-age=31536000; includeSubdomains";
ssl on;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
# These shouldn't need to be changed
listen [::]:443 default_server ipv6only=off; # if your nginx version is >= 1.9.5 you can also add the "http2" flag here
add_header Strict-Transport-Security "max-age=31536000; includeSubdomains";
ssl on;
ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
ssl_ciphers "EECDH+AESGCM:EDH+AESGCM:AES256+EECDH:AES256+EDH:!aNULL:!eNULL:!EXPORT:!DES:!MD5:!PSK:!RC4";
ssl_prefer_server_ciphers on;
ssl_session_cache shared:SSL:10m;
proxy_buffering off;
proxy_buffering off;
location / {
proxy_pass http://localhost:8123;
proxy_set_header Host $host;
proxy_redirect http:// https://;
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
location / {
proxy_pass http://localhost:8123;
proxy_set_header Host $host;
proxy_redirect http:// https://;
proxy_http_version 1.1;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
}
}
```

116
source/_docs/ecosystem/nginx_subdomain.markdown Normal file
View file

@ -0,0 +1,116 @@
---
layout: page
title: "NGINX Configuration"
description: "Configure Nginx to work with Home Assistant as a subdomain"
date: 2016-06-20 13:05
sidebar: true
comments: false
sharing: true
footer: true
---
This example demonstrates how you can configure NGINX to act as a proxy for Home Assistant.
This is useful if you want to have:
* a subdomain redirecting to your home assistant instance
* several subdomain for several instance
* HTTPS redirection
#### {% linkable_title Subdomain %}
So you already have a working NGINX server available at example.org. Your Home Assistant is correctly working on this web server and available at http://localhost:8123
To be able to access to your Home Assistant instance by using https://home.example.org, create file `/etc/nginx/sites-enabled/homeassistant` (or symlink via `/etc/nginx/sites-available`) and add the following:
```nginx
server {
listen 443 ssl;
server_name home.example.org;
ssl on;
ssl_certificate /etc/nginx/ssl/home.example.org/home.example.org-bundle.crt;
ssl_certificate_key /etc/nginx/ssl/home.example.org/home.example.org.key;
ssl_prefer_server_ciphers on;
location / {
proxy_pass http://localhost:8123/;
proxy_set_header Host $host;
}
location /api/websocket {
proxy_pass http://localhost:8123/api/websocket;
proxy_set_header Host $host;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
If you don't want HTTPS, you can change `listen 443 ssl` to `listen 80` or better, consider redirecting all HTTP to HTTPS. See further down.
#### {% linkable_title Multiple Instance %}
You already have Home Assistant running on http://localhost:8123 and available at home.example.org as describe before. The configuration file for this Home Assistant is available in `/home/alice/.homeassistant/configuration.yaml`.
You want another instance available at https://countryside.example.org
You can either :
* Create a new user, `bob`, to hold the configuration file in `/home/bob/.homeassistant/configuration.yaml` and run home assistant as this new user
* Create another configuration directory in `/home/alice/.homeassistan2/configuration.yaml` and run home assistant using `hass --config /home/alice/.homeassistant2/`
In both solution, change port number used by modifying `configuration.yaml` file.
```yaml
http:
server_port: 8124
...
```
Start Home Assistant: Now, you have another instance running on http://localhost:8124
To access this instance by using https://countryside.example.org create the file `/etc/nginx/sites-enabled/countryside.example.org` (or symlink via `/etc/nginx/sites-available`) and add the following:
```bash
server {
listen 443 ssl;
server_name countryside.example.org;
ssl on;
ssl_certificate /etc/nginx/ssl/countryside.example.org/countryside.example.org-bundle.crt;
ssl_certificate_key /etc/nginx/ssl/countryside.example.org/countryside.example.org.key;
ssl_prefer_server_ciphers on;
location / {
proxy_pass http://localhost:8124/;
proxy_set_header Host $host;
}
location /api/websocket {
proxy_pass http://localhost:8124/api/websocket;
proxy_set_header Host $host;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}
}
```
#### {% linkable_title HTTP to HTTPS redirection %}
Add to your `/etc/nginx/sites-enabled/default`
```bash
server {
listen 80 default_server;
server_name example.tld;
return 301 https://$host$request_uri;
}
```

2
source/_docs/hassbian/common-tasks.markdown
View file

@ -11,7 +11,7 @@ redirect_from: /getting-started/hassbian-common-tasks/
---
### {% linkable_title Login to 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].
To login to your Raspberry Pi running HASSbian you're 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].
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.

3
source/_docs/installation/fedora.markdown
View file

@ -23,10 +23,11 @@ and Home Assistant itself.
$ pip3 install homeassistant
```
To isolate the Home Assistant installation a [venv](https://docs.python.org/3/library/venv.html) is handy. First create a new directory to store the installation.
To isolate the Home Assistant installation a [venv](https://docs.python.org/3/library/venv.html) is handy. First create a new directory to store the installation and adjust the permissions.
```bash
$ sudo mkdir -p /opt/homeassistant
$ sudo chown -R user:group /opt/homeassistant
```
Now switch to the new directory, setup the venv, and activate it.

8
source/_docs/mqtt/broker.markdown
View file

@ -58,7 +58,9 @@ mqtt:
keepalive: 60
username: USERNAME
password: PASSWORD
protocol: 3.1
protocol: 3.1
tls_insecure: True
tls_version: 1.2
```
Configuration variables:
@ -70,9 +72,13 @@ Configuration variables:
- **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.
- **tls_insecure** (*Optional*): Set the verification of the server hostname in the server certificate.
- **tls_version** (*Optional*): TLS/SSL protocol version to use. Available options are: `auto`, `1.0`, `1.1`, `1.2`. Defaults to `auto`.
<p class='note warning'>
There is an issue with the Mosquitto package included in Ubuntu 14.04 LTS. Specify `protocol: 3.1` in your MQTT configuration to work around this issue.
If you get this error `AttributeError: module 'ssl' has no attribute 'PROTOCOL_TLS'` then you need to set `tls_version: 1.2`.
</p>
<p class='note'>

5
source/_docs/z-wave.markdown
View file

@ -52,6 +52,11 @@ To find the path of your Z-Wave USB stick or module, run:
$ ls /dev/ttyUSB*
```
Or, if there is no result try to find detailed USB connection info with:
```bash
$ dmesg | grep USB
```
Or, on some other systems (such as Raspberry Pi), use:
```bash