jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-21 08:16:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

Spelling and Markdown fixes: Part 4

Browse Source
This commit is contained in:
Franck Nijhof 2020-01-29 11:57:44 +01:00
parent 76b5127904
commit 04712c4628
No known key found for this signature in database
GPG Key ID: D62583BA8AB11CA3
24 changed files with 680 additions and 638 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
source/_docs/autostart/init.d.markdown
View File

@ -6,31 +6,31 @@ redirect_from: /getting-started/autostart-init.d/
Home Assistant can run as a daemon within init.d with the script below.
### 1. Copy script
## 1. Copy script
Copy either the daemon script or the Python environment script at the end of this page to `/etc/init.d/hass-daemon` depending on your installation.
After that, set the script to be executable:
```bash
$ sudo chmod +x /etc/init.d/hass-daemon
sudo chmod +x /etc/init.d/hass-daemon
```
### 2. Select a user.
## 2. Select a user
Create or pick a user that the Home Assistant daemon will run under. Update script to set `RUN_AS` to the username that should be used to execute hass.
Create or pick a user that the Home Assistant daemon will run under. Update script to set `RUN_AS` to the username that should be used to execute Home Assistant.
### 3. Change hass executable and other variables if required.
## 3. Change `hass` executable and other variables if required
Some installation environments may require a change in the Home Assistant executable `hass`. Update script to set `HASS_BIN` to the appropriate `hass` executable path. Please also check the other variables for the appropriate value. In general the defaults should work
### 4. Install this service
## 4. Install this service
```bash
$ sudo service hass-daemon install
sudo service hass-daemon install
```
### 5. Create logrotate rule
## 5. Create logrotate rule
This logrotate script at `/etc/logrotate.d/homeassistant` will create an outage of a few seconds every week at night. If you do not want this add `--log-rotate-days 7` to the `FLAGS` variable in the init script.
@ -55,11 +55,11 @@ File `/var/log/homeassistant/home-assistant.log`:
That's it. Restart your machine and Home Assistant should start automatically.
If HA does not start, check the log file output for errors at `/var/log/homeassistant/home-assistant.log`
If Home Assistant does not start, check the log file output for errors at `/var/log/homeassistant/home-assistant.log`
### Extra: Running commands before hass executes
### Extra: Running commands before Home Assistant executes
If any commands need to run before executing hass (like loading a virtual environment), put them in PRE_EXEC. This command must end with a semicolon.
If any commands need to run before executing Home Assistant (like loading a virtual environment), put them in PRE_EXEC. This command must end with a semicolon.
### Daemon script

4
source/_docs/backend/updater.markdown
View File

@ -6,7 +6,7 @@ redirect_from: /details/updater/
Starting with 0.31 the [updater component](/integrations/updater/) sends an optional report about Home Assistant instance.
If you want to opt-in to include integration information, add `include_used_components` to your config. This will allow the Home Assistant developers to focus development efforts on the most popular components.
If you want to opt-in to include integration information, add `include_used_components` to your configuration. This will allow the Home Assistant developers to focus development efforts on the most popular components.
```yaml
updater:
@ -16,7 +16,7 @@ updater:
We are only collecting this information to better understand our user base to provide better long term support and feature development.
| Name | Description | Example | Data Source |
|-----------------------|--------------------------------------------|------------------------------------|----------------|
| --------------------- | ------------------------------------------ | ---------------------------------- | -------------- |
| `arch` | CPU Architecture | `x86_64` | Local Instance |
| `distribution` | Linux Distribution name (only Linux) | `Ubuntu` | Local Instance |
| `docker` | True if running inside Docker | `false` | Local Instance |

16
source/_docs/configuration.markdown
View File

@ -9,19 +9,19 @@ The web interface can be found at `http://ip.ad.dre.ss:8123/` - for example if y
The location of the folder differs between operating systems:
| OS | Path |
| -- | ---- |
| macOS | `~/.homeassistant` |
| Linux | `~/.homeassistant` |
| OS | Path |
| ------- | -------------------------- |
| macOS | `~/.homeassistant` |
| Linux | `~/.homeassistant` |
| Windows | `%APPDATA%/.homeassistant` |
| Hass.io | `/config` |
| Docker | `/config` |
| Hass.io | `/config` |
| Docker | `/config` |
If you want to use a different folder for configuration, use the config command line parameter: `hass --config path/to/config`.
If you want to use a different folder for configuration, use the configuration command line parameter: `hass --config path/to/config`.
Inside your configuration folder is the file `configuration.yaml`. This is the main file that contains integrations to be loaded with their configurations. Throughout the documentation you will find snippets that you can add to your configuration file to enable functionality.
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).
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).
<div class='note tip'>

166
source/_docs/ecosystem/certificates/lets_encrypt.markdown
View File

@ -11,28 +11,28 @@ If you are using Hass.io do not use this guide. Instead, use the [DuckDNS add-on
This guide was added by mf_social on 16/03/2017 and was valid at the time of writing. This guide makes the following assumptions:
* You can access your Home Assistant instance across your local network, and access the device that it is on via SSH from your local network.
* You know the internal IP address of your router and can access your router's configuration pages.
* You have already secured your Home Assistant instance, following the advice on [this page](/docs/configuration/securing/)
* You want to access your Home Assistant instance when you are away from home (ie, not connected to your local network) and secure it with a TLS/SSL certificate.
* You have a basic understanding of the phrases I have used so far.
* You are not currently running anything on port 80 on your network (you'd know if you were).
* If you are not using Home Assistant on a Debian/Raspian system you will be able to convert any of the terminology I use in to the correct syntax for your system.
* You understand that this is a 'guide' covering the general application of these things to the general masses and there are things outside of the scope of it, and it does not cover every eventuality (although I have made some notes where people may stumble). Also, I have used some turns of phrase to make it easier to understand for the novice reader which people of advanced knowledge may say is inaccurate. My goal here is to get you through this guide with a satisfactory outcome and have a decent understanding of what you are doing and why, not to teach you advanced internet communication protocols.
* Each step presumes you have fully completed the previous step successfully, so if you did an earlier step following a different guide, please ensure that you have not missed anything out that may affect the step you have jumped to, and ensure that you adapt any commands to take in to account different file placements from other guides.
- You can access your Home Assistant instance across your local network, and access the device that it is on via SSH from your local network.
- You know the internal IP address of your router and can access your router's configuration pages.
- You have already secured your Home Assistant instance, following the advice on [this page](/docs/configuration/securing/)
- You want to access your Home Assistant instance when you are away from home (ie, not connected to your local network) and secure it with a TLS/SSL certificate.
- You have a basic understanding of the phrases I have used so far.
- You are not currently running anything on port 80 on your network (you'd know if you were).
- If you are not using Home Assistant on a Debian/Raspian system you will be able to convert any of the terminology I use in to the correct syntax for your system.
- You understand that this is a 'guide' covering the general application of these things to the general masses and there are things outside of the scope of it, and it does not cover every eventuality (although I have made some notes where people may stumble). Also, I have used some turns of phrase to make it easier to understand for the novice reader which people of advanced knowledge may say is inaccurate. My goal here is to get you through this guide with a satisfactory outcome and have a decent understanding of what you are doing and why, not to teach you advanced internet communication protocols.
- Each step presumes you have fully completed the previous step successfully, so if you did an earlier step following a different guide, please ensure that you have not missed anything out that may affect the step you have jumped to, and ensure that you adapt any commands to take in to account different file placements from other guides.
Steps we will take:
- 0 - Gain a basic level of understanding around IP addresses, port numbers and port forwarding
- 1 - Set your device to have a static IP address
- 2 - Set up port forwarding without TLS/SSL and test connection
- 3 - Set up a DuckDNS account
- 4 - Obtain a TLS/SSL certificate from Let's Encrypt
- 5 - Check the incoming connection
- 6 - Clean up port forwards
- 7 - Set up a sensor to monitor the expiry date of the certificate
- 8 - Set up an automatic renewal of the TLS/SSL certificate
- 9 - Set up an alert to warn us if something went wrong
- 0 - Gain a basic level of understanding around IP addresses, port numbers and port forwarding
- 1 - Set your device to have a static IP address
- 2 - Set up port forwarding without TLS/SSL and test connection
- 3 - Set up a DuckDNS account
- 4 - Obtain a TLS/SSL certificate from Let's Encrypt
- 5 - Check the incoming connection
- 6 - Clean up port forwards
- 7 - Set up a sensor to monitor the expiry date of the certificate
- 8 - Set up an automatic renewal of the TLS/SSL certificate
- 9 - Set up an alert to warn us if something went wrong
### 0 - Gain a basic level of understanding around IP addresses, port numbers and port forwarding
@ -49,10 +49,11 @@ We will be looking for a system to run like this (in this example I will pretend
```text
Outside world -> 203.0.113.12:8123 -> your router -> 192.168.0.200:8123
```
Sounds simple? It really is except for two small, but easy to overcome, complications:
* IP addresses are often dynamically allocated, so they can change.
* Because of the way the internet works you cannot chain IP addresses together to get from where you are, to where you want to go.
- IP addresses are often dynamically allocated, so they can change.
- Because of the way the internet works you cannot chain IP addresses together to get from where you are, to where you want to go.
To get around the issue of changing IP addresses we must remember that there are two IP addresses affected. Your external one (which we will 'call' to get on to your network from the internet) and your internal one (192.168.0.200 in the example I am currently using).
@ -60,11 +61,12 @@ So, we can use a static IP to ensure that whenever our device running Home Assis
We then have no control over our external IP, as our Service Provider will give us a new one at random intervals. To fix this we will use a service called DuckDNS which will give us a name for our connection (something like examplehome.duckdns.org) and behind the scenes will continue to update your external IP. So no matter how many times the IP address changes, typing examplehome.duckdns.org in to our browser will convert to the correct, up-to-date, IP address. This is covered in step 3 below.
To get around the issue of not being able to chain the IP addresses together (I can't say I want to call 203.0.113.12 and be put through to 192.168.0.200, and then be put through to extension 8123) we use port forwarding. Port forwarding is the process of telling your router which device to allow the outside connection to speak to. In the doctors surgery example, port forwarding is the receptionist. This takes a call from outside, and forwards it to the correct extension number inside. It is important to note that port forwarding can forward an incoming request for one port to a different port on your internal network if you so choose, and we will be doing this later on. The end result being that when we have our TLS/SSL certificate our incoming call will by default be requesting port 443 (because that is the default HTTPS port, like the default SSH port is 22), our port forwarding rule can forward this to our HA instance on port 8123 (or we can specify the port number in the URL). When this guide is completed we will run something like this:
To get around the issue of not being able to chain the IP addresses together (I can't say I want to call 203.0.113.12 and be put through to 192.168.0.200, and then be put through to extension 8123) we use port forwarding. Port forwarding is the process of telling your router which device to allow the outside connection to speak to. In the doctors surgery example, port forwarding is the receptionist. This takes a call from outside, and forwards it to the correct extension number inside. It is important to note that port forwarding can forward an incoming request for one port to a different port on your internal network if you so choose, and we will be doing this later on. The end result being that when we have our TLS/SSL certificate our incoming call will by default be requesting port 443 (because that is the default HTTPS port, like the default SSH port is 22), our port forwarding rule can forward this to our Home Assistant instance on port 8123 (or we can specify the port number in the URL). When this guide is completed we will run something like this:
```text
Outside world -> https://examplehome.duckdns.org -> 203.0.113.12:443 -> your router -> 192.168.0.200:8123
```
So, let's make it happen...
### 1 - Set your device to have a static IP address
@ -136,7 +138,7 @@ All working? Hooray! You now have a static IP. This will now always be your in
### 2 - Set up port forwarding without TLS/SSL and test connection
Log in to your router's configuration pages and find the port forwarding options. This bit is hard to write a guide for because each router has a different way of presenting these options. Searching google for "port forwarding" and the name of your router may help. When you find it you will likely have options similar to:
Log in to your router's configuration pages and find the port forwarding options. This bit is hard to write a guide for because each router has a different way of presenting these options. Searching Google for "port forwarding" and the name of your router may help. When you find it you will likely have options similar to:
Service name - Port Range - Local IP - Local Port - Protocol
@ -162,7 +164,7 @@ https://whatismyipaddress.com/
This will tell you your current external IP address
Type the external IP address in to the URL bar with http:// in front and :8123 after like so (203.0.113.12 is my example!):
Type the external IP address in to the URL bar with `http://` in front and :8123 after like so (203.0.113.12 is my example!):
```text
http://203.0.113.12:8123
@ -170,7 +172,7 @@ http://203.0.113.12:8123
Can you see your Home Assistant instance? If not, your router may not support 'loopback' - try the next step anyway and if that works, and this one still doesn't, just remember that you cannot use loopback, so will have to use internal addresses when you're on your home network. More on this later on if it's relevant to you.
Just to verify this isn't some kind of witchcraft that is actually using your internal network, pick up your phone, disconnect it from your WiFi so that you are on your mobile data and not connected to the home network, put the same URL in the browser on your phone.
Just to verify this isn't some kind of witchcraft that is actually using your internal network, pick up your phone, disconnect it from your Wi-Fi so that you are on your mobile data and not connected to the home network, put the same URL in the browser on your phone.
Can you see it now, from a device that is definitely not connected to your local network? Excellent! You now have a remotely accessible Home Assistant instance.
@ -178,7 +180,7 @@ But what if your external IP changes? Plus, remembering all those numbers is pr
### 3 - Set up a DuckDNS account
Open your browser and go to https://duckdns.org.
Open your browser and go to <https://duckdns.org>.
Sign in and create an account using one of the id validation options in the top right corner.
@ -208,7 +210,7 @@ What now happens behind the scenes is this:
- DuckDNS receives the request and forwards the request to your router's external IP address (which has been kept up to date by your device running Home Assistant)
- Your router receives the request on port 8123 and checks the port forwarding rules
- It finds the rule you created in step 2 and forwards the request to your HA instance
- It finds the rule you created in step 2 and forwards the request to your Home Assistant instance
- Your browser displays your Home Assistant instance frontend.
Did it work? Super!
@ -326,7 +328,7 @@ Protocol - Both
Remember to save the rule changes.
Now edit your configuration.yaml file to reflect the SSL entries and your base URL (changing the `examplehome` subdomain to yours in all three places):
Now edit your `configuration.yaml` file to reflect the SSL entries and your base URL (changing the `examplehome` subdomain to yours in all three places):
```yaml
http:
@ -335,9 +337,9 @@ http:
base_url: examplehome.duckdns.org
```
You may wish to set up other options for the [http](/integrations/http/) integration at this point, these extra options are beyond the scope of this guide.
You may wish to set up other options for the [HTTP](/integrations/http/) integration at this point, these extra options are beyond the scope of this guide.
Save the changes to configuration.yaml. Restart Home Assistant.
Save the changes to `configuration.yaml`. Restart Home Assistant.
In step 3 we accessed our Home Assistant from the outside world with our DuckDNS URL and our port number. We are going to use a slightly different URL this time.
@ -345,7 +347,7 @@ In step 3 we accessed our Home Assistant from the outside world with our DuckDNS
https://examplehome.duckdns.org
```
Note the **S** after http, and that no port number is added. This is because https will use port 443 automatically, and we have already set up our port forward to redirect this request to our Home Assistant instance on port 8123.
Note the **S** after http, and that no port number is added. This is because HTTPS will use port 443 automatically, and we have already set up our port forward to redirect this request to our Home Assistant instance on port 8123.
You should now be able to see your Home Assistant instance via your DuckDNS URL, and importantly note that your browser shows the connection as secure.
@ -379,8 +381,8 @@ If you have any more for Home Assistant you should delete them now. If you only
You are now part of one of two groups:
* If you have BOTH rules you are able to set up auto renewals of your certificates using port 80 and the standard http challenge, as performed above.
* If you only have one, you are still able to set up auto renewals of your certificates, but will have to specify additional options when renewing that will temporarily stop Home Assistant and use port 8123 for certificate renewal.
- If you have BOTH rules you are able to set up auto renewals of your certificates using port 80 and the standard HTTP challenge, as performed above.
- If you only have one, you are still able to set up auto renewals of your certificates, but will have to specify additional options when renewing that will temporarily stop Home Assistant and use port 8123 for certificate renewal.
Please remember whether you are a ONE-RULE person or a BOTH-RULE person for step 8!
@ -392,10 +394,10 @@ Move on to step 7 to see how to monitor your certificates expiry date, and be re
Setting a sensor to read the number of days left on your TLS/SSL certificate before it expires is not required, but it has the following advantages:
* You can physically see how long you have left, pleasing your inner control freak
* You can set automations based on the number of days left
* You can set alerts to notify you if your certificate has not been renewed and is coming close to expiry.
* If you cannot set up automatic renewals due to your ISP blocking port 80, you will have timely reminders to complete the process manually.
- You can physically see how long you have left, pleasing your inner control freak
- You can set automations based on the number of days left
- You can set alerts to notify you if your certificate has not been renewed and is coming close to expiry.
- If you cannot set up automatic renewals due to your ISP blocking port 80, you will have timely reminders to complete the process manually.
If you do not wish to set up a sensor you can skip straight to step 8 to learn how to update your certificates.
@ -423,13 +425,13 @@ sensor:
command: "ssl-cert-check -b -c /etc/letsencrypt/live/examplehome.duckdns.org/cert.pem | awk '{ print $NF }'"
```
Save the configuration.yaml. Restart Home Assistant.
Save the `configuration.yaml`. Restart Home Assistant.
On your default_view you should now see a sensor badge containing your number of days until expiry. If you've been following this guide from the start and have not taken any breaks in between, this should be 89 or 90. The sensor will update every 3 hours. You can place this reading on a card using groups, or hide it using customize. These topics are outside of the scope of this guide, but information can be found on their respective integrations pages: [Group](/integrations/group/) and [Customize](/docs/configuration/customizing-devices/)
Got your sensor up and running and where you want it? Top drawer! Nearly there, now move on to the final steps to ensure that you're never without a secure connection in the future.
### 8 - Set up an automatic renewal of the TLS/SSL certificate.
### 8 - Set up an automatic renewal of the TLS/SSL certificate
The certbot program we downloaded in step 4 contains a script that will renew your certificate. The script will only obtain a new certificate if the current one has less than 30 days left on it, so running the script more often than is actually needed will not cause any harm.
@ -439,47 +441,49 @@ If you are a TWO-RULE person (from step 6), you can automatically renew your cer
There are a number of options for automating the renewal process:
#### Option 1:
#### Option 1
Your certificate can be renewed as a 'cron job' - cron jobs are background tasks run by the computer at specified intervals (and are totally independent of Home Assistant). Defining cron is outside of the scope of this guide but you will have had dealings with `crontab` when setting up DuckDNS in step 3
To set a cron job to run the script at regular intervals:
* SSH in to your device running Home Assistant.
* Change to your Home Assistant user (where `homeassistant` is the name of the user):
- SSH in to your device running Home Assistant.
- Change to your Home Assistant user (where `homeassistant` is the name of the user):
```bash
sudo -u homeassistant -H -s
```
```bash
sudo -u homeassistant -H -s
```
* Open the crontab:
- Open the crontab:
```bash
crontab -e
```
```bash
crontab -e
```
* If you are a TWO-RULE Person: Scroll to the bottom of the file and paste in the following line
- If you are a TWO-RULE Person: Scroll to the bottom of the file and paste in the following line
```text
30 2 * * 1 ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01
```
```text
30 2 * * 1 ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01
```
* If you are a ONE-RULE Person: Scroll to the bottom of the file and paste in the following line
- If you are a ONE-RULE Person: Scroll to the bottom of the file and paste in the following line
```text
30 2 * * 1 ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"
```
* Let's take a moment to look at the differences here:
1. This method uses a `tls-sni` challenge, so the Let's Encrypt CA will attempt to bind port 443 externally (which you have forwarded)
2. `--tls-sni-01-port 8123` tells certbot to bind port 8123 internally, which matches with the port forwarding rules that are already in place.
3. We define pre-hooks and post-hooks that stop our Home Assistant service before certbot runs, freeing port 8123 for certificate renewal, and restart Home Assistant after renewal is complete.
```text
30 2 * * 1 ~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"
```
* Save the file and exit
- Let's take a moment to look at the differences here:
1. This method uses a `tls-sni` challenge, so the Let's Encrypt CA will attempt to bind port 443 externally (which you have forwarded)
2. `--tls-sni-01-port 8123` tells certbot to bind port 8123 internally, which matches with the port forwarding rules that are already in place.
3. We define pre-hooks and post-hooks that stop our Home Assistant service before certbot runs, freeing port 8123 for certificate renewal, and restart Home Assistant after renewal is complete.
- Save the file and exit
#### Option 2
#### Option 2:
You can set an automation in Home Assistant to run the certbot renewal script.
Add the following sections to your configuration.yaml if you are a TWO-RULE person
Add the following sections to your `configuration.yaml` if you are a TWO-RULE person
```yaml
shell_command:
@ -494,37 +498,39 @@ automation:
action:
service: shell_command.renew_ssl
```
If you are a ONE-RULE person, replace the `certbot-auto` command above with `~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"`
#### Option 3:
#### Option 3
You can manually update the certificate when your certificate is less than 30 days to expiry.
To manually update:
* SSH in to your device running Home Assistant.
* Change to your Home Assistant user (where `homeassistant` is the name of the user):
- SSH in to your device running Home Assistant.
- Change to your Home Assistant user (where `homeassistant` is the name of the user):
```bash
sudo -u homeassistant -H -s
```
```bash
sudo -u homeassistant -H -s
```
* Change to your certbot folder
- Change to your certbot folder
```bash
cd ~/certbot/
```
```bash
cd ~/certbot/
```
* Run the renewal command
- Run the renewal command
```bash
./certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01
```
```bash
./certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges http-01
```
* If you are a ONE-RULE person, replace the `certbot-auto` command above with `~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"`
- If you are a ONE-RULE person, replace the `certbot-auto` command above with `~/certbot/certbot-auto renew --quiet --no-self-upgrade --standalone --preferred-challenges tls-sni-01 --tls-sni-01-port 8123 --pre-hook "sudo systemctl stop home-assistant@homeassistant.service" --post-hook "sudo systemctl start home-assistant@homeassistant.service"`
So, now were all set up. We have our secured, remotely accessible Home Assistant instance and we're on track for keeping our certificates up to date. But what if something goes wrong? What if the automation didn't fire? What if the cron job forgot to run? What if the dog ate my homework? Read on to set up an alert so you can be notified in plenty of time if you need to step in and sort out any failures.
### 9 - Set up an alert to warn us if something went wrong.
### 9 - Set up an alert to warn us if something went wrong
We set up our automatic renewal of our certificates and whatever method we used the certificate should be renewed on or around 30 days before it expires. But what if a week later it still hasn't been? This alert will go off if the expiry time on the certificate gets down to 21 days. This will give you 3 weeks to fix the problem, get your new certificate installed and get another 90 days of secure Home Assistant connections in play.

146
source/_docs/installation/docker.markdown
View File

@ -11,19 +11,19 @@ Installation with Docker is straightforward. Adjust the following command so tha
### Linux
```bash
$ docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/home-assistant:stable
docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/home-assistant:stable
```
### Raspberry Pi 3 (Raspbian)
```bash
$ docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/raspberrypi3-homeassistant:stable
docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/raspberrypi3-homeassistant:stable
```
You need to replace `/PATH_TO_YOUR_CONFIG` with your path to the configuration, for example if you choose your configuration path to be `/home/pi/homeassistant`, then command would be:
```bash
$ docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /home/pi/homeassistant:/config --net=host homeassistant/raspberrypi3-homeassistant:stable
docker run --init -d --name="home-assistant" -e "TZ=America/New_York" -v /home/pi/homeassistant:/config --net=host homeassistant/raspberrypi3-homeassistant:stable
```
### macOS
@ -33,7 +33,7 @@ When using `docker-ce` (or `boot2docker`) on macOS, you are unable to map the lo
If you wish to browse directly to `http://localhost:8123` from your macOS host, meaning forward ports directly to the container, replace the `--net=host` switch with `-p 8123:8123`. More detail can be found in [the docker forums](https://forums.docker.com/t/should-docker-run-net-host-work/14215/10).
```bash
$ docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v /PATH_TO_YOUR_CONFIG:/config -p 8123:8123 homeassistant/home-assistant:stable
docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v /PATH_TO_YOUR_CONFIG:/config -p 8123:8123 homeassistant/home-assistant:stable
```
Alternatively, `docker-compose` works with any recent release of `docker-ce` on macOS. Note that (further down this page) we provide an example `docker-compose.yml` however it differs from the `docker run` example above. To make the .yml directives match, you would need to make _two_ changes: first add the equivalent `ports:` directive, then _remove_ the `network_mode: host` section. This is because `Port mapping is incompatible with network_mode: host:`. More details can be found at [Docker networking docs](https://docs.docker.com/network/). Note also the `/dev/tty*` device name used by your Arduino etc. devices will differ from the Linux example, so the compose `mount:` may require updates.
@ -48,13 +48,13 @@ Before proceeding, make sure you have shared out a drive for docker to mount to.
<https://docs.docker.com/docker-for-windows/troubleshoot/#verify-domain-user-has-permissions-for-shared-drives-volumes>
```powershell
$ docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/home-assistant:stable
docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v /PATH_TO_YOUR_CONFIG:/config --net=host homeassistant/home-assistant:stable
```
It’s easier to understand the trick when put into practice. Here we would like to mount a current working directory (something like `C:\Users\<your login name>\homeassistant` make sure this exists first) into the `homeassistant/home-assistant:stable` image at the `/config` location in the container. We would do that as so:
```powershell
$ docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v //c/Users/<your login name>/homeassistant:/config --net=host homeassistant/home-assistant:stable
docker run --init -d --name="home-assistant" -e "TZ=America/Los_Angeles" -v //c/Users/<your login name>/homeassistant:/config --net=host homeassistant/home-assistant:stable
```
When running Home Assistant in Docker on Windows, you may have some difficulty getting ports to map for routing (since the `--net=host` switch actually applies to the hypervisor's network interface). To get around this, you will need to add port proxy ipv4 rules to your local Windows machine, like so (Replacing '192.168.1.10' with whatever your Windows IP is, and '10.0.50.2' with whatever your Docker container's IP is):
@ -71,23 +71,24 @@ This will let you access your Home Assistant portal from `http://localhost:8123`
As Synology within DSM now supports Docker (with a neat UI), you can simply install Home Assistant using docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see <https://www.synology.com/en-us/dsm/packages/Docker>
The steps would be:
* Install "Docker" package on your Synology NAS
* Launch Docker-app and move to "Registry"-section
* Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "latest" tag, this will make version updates easier later on.
* Wait for some time until your NAS has pulled the image
* Move to the "Image"-section of the Docker-app
* Click on "Launch"
* Choose a container-name you want (e.g., "homeassistant")
* Click on "Advanced Settings"
* Set "Enable auto-restart" if you like
* Within "Volume" click on "Add Folder" and choose either an existing folder or add a new folder. The "mount path" has to be "/config", so that Home Assistant will use it for the configs and logs. It is therefore recommended that the folder you choose should be named "config" or "homeassistant/config" to avoid confusion when referencing it within service calls.
* Within "Network" select "Use same network as Docker Host"
* To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
* Confirm the "Advanced Settings"
* Click on "Next" and then "Apply"
* Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Synology NAS IP address - for example `http://192.168.1.10:8123`)
To use a Z-Wave USB stick for Z-Wave control, the HA Docker container needs extra configuration to access to the USB stick. While there are multiple ways to do this, the least privileged way of granting access can only be performed via the Terminal, at the time of writing. See this page for configuring Terminal acces to your Synology NAS:
- Install "Docker" package on your Synology NAS
- Launch Docker-app and move to "Registry"-section
- Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "latest" tag, this will make version updates easier later on.
- Wait for some time until your NAS has pulled the image
- Move to the "Image"-section of the Docker-app
- Click on "Launch"
- Choose a container-name you want (e.g., "homeassistant")
- Click on "Advanced Settings"
- Set "Enable auto-restart" if you like
- Within "Volume" click on "Add Folder" and choose either an existing folder or add a new folder. The "mount path" has to be "/config", so that Home Assistant will use it for the configs and logs. It is therefore recommended that the folder you choose should be named "config" or "homeassistant/config" to avoid confusion when referencing it within service calls.
- Within "Network" select "Use same network as Docker Host"
- To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
- Confirm the "Advanced Settings"
- Click on "Next" and then "Apply"
- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Synology NAS IP address - for example `http://192.168.1.10:8123`)
To use a Z-Wave USB stick for Z-Wave control, the HA Docker container needs extra configuration to access to the USB stick. While there are multiple ways to do this, the least privileged way of granting access can only be performed via the Terminal, at the time of writing. See this page for configuring Terminal acces to your Synology NAS:
<https://www.synology.com/en-global/knowledgebase/DSM/help/DSM/AdminCenter/system_terminal>
@ -99,7 +100,7 @@ Adjust the following Terminal command as follows :
- Replace `/PATH_TO_YOUR_CONFIG` points at the folder where you want to store your configuration
- Replace `/PATH_TO_YOUR_USB_STICK` matches the path for your USB stick (e.g., `/dev/ttyACM0` for most Synology users)
- Replace "Australia/Melbourne" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
- Replace "Australia/Melbourne" with [your timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
Run it in Terminal.
@ -111,17 +112,18 @@ Complete the remainder of the Z-Wave configuration by [following the instruction
Remark: to update your Home Assistant on your Docker within Synology NAS, you just have to do the following:
* Go to the Docker-app and move to "Registry"-section
* Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "latest" tag, this will overwrite your current image to the latest version.
* Wait until the system-message/-notification comes up, that the download is finished (there is no progress bar)
* Move to "Container"-section
* Stop your container if it's running
* Right-click on it and select "Action"->"Clear". You won't lose any data, as all files are stored in your config-directory
* Start the container again - it will then boot up with the new Home Assistant image
- Go to the Docker-app and move to "Registry"-section
- Find "homeassistant/home-assistant" within registry and click on "Download". Choose the "latest" tag, this will overwrite your current image to the latest version.
- Wait until the system-message/-notification comes up, that the download is finished (there is no progress bar)
- Move to "Container"-section
- Stop your container if it's running
- Right-click on it and select "Action"->"Clear". You won't lose any data, as all files are stored in your config-directory
- Start the container again - it will then boot up with the new Home Assistant image
Remark: to restart your Home Assistant within Synology NAS, you just have to do the following:
* Go to the Docker-app and move to "Container"-section
* Right-click on it and select "Action"->"Restart".
- Go to the Docker-app and move to "Container"-section
- Right-click on it and select "Action"->"Restart".
<div class='note'>
If you want to use a USB Bluetooth adapter or Z-Wave USB Stick with Home Assistant on Synology Docker these instructions do not correctly configure the container to access the USB devices. To configure these devices on your Synology Docker Home Assistant you can follow the instructions provided <a href="https://philhawthorne.com/installing-home-assistant-io-on-a-synology-diskstation-nas/">here</a> by Phil Hawthorne.
@ -129,23 +131,23 @@ If you want to use a USB Bluetooth adapter or Z-Wave USB Stick with Home Assista
### QNAP NAS
As QNAP within QTS now supports Docker (with a neat UI), you can simply install Home Assistant using docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see https://www.qnap.com/solution/container_station/en/index.php
As QNAP within QTS now supports Docker (with a neat UI), you can simply install Home Assistant using docker without the need for command-line. For details about the package (including compatibility-information, if your NAS is supported), see <https://www.qnap.com/solution/container_station/en/index.php>
The steps would be:
- Install "Container Station" package on your Qnap NAS
- Launch Container Station and move to "Create Container"-section
- Search image "homeassistant/home-assistant" with Docker hub and click on "Install"
Make attention to CPU architecture of your NAS. For ARM CPU types the correct image is "homeassistant/armhf-homeassistant"
- Choose "latest" version and click next
- Choose a container-name you want (e.g., "homeassistant")
- Click on "Advanced Settings"
- Within "Shared Folders" click on "Volume from host" > "Add" and choose either an existing folder or add a new folder. The "mount point has to be `/config`, so that Home Assistant will use it for the configuration and logs.
- Within "Network" and select Network Mode to "Host"
- To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
- Click on "Create"
- Wait for some time until your NAS has created the container
- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Qnap NAS IP address - for example `http://192.xxx.xxx.xxx:8123`)
- Install "Container Station" package on your Qnap NAS
- Launch Container Station and move to "Create Container"-section
- Search image "homeassistant/home-assistant" with Docker hub and click on "Install"
Make attention to CPU architecture of your NAS. For ARM CPU types the correct image is "homeassistant/armhf-homeassistant"
- Choose "latest" version and click next
- Choose a container-name you want (e.g., "homeassistant")
- Click on "Advanced Settings"
- Within "Shared Folders" click on "Volume from host" > "Add" and choose either an existing folder or add a new folder. The "mount point has to be `/config`, so that Home Assistant will use it for the configuration and logs.
- Within "Network" and select Network Mode to "Host"
- To ensure that Home Assistant displays the correct timezone go to the "Environment" tab and click the plus sign then add `variable` = `TZ` & `value` = `Europe/London` choosing [your correct timezone](http://en.wikipedia.org/wiki/List_of_tz_database_time_zones)
- Click on "Create"
- Wait for some time until your NAS has created the container
- Your Home Assistant within Docker should now run and will serve the web interface from port 8123 on your Docker host (this will be your Qnap NAS IP address - for example `http://192.xxx.xxx.xxx:8123`)
Remark: To update your Home Assistant on your Docker within Qnap NAS, you just remove container and image and do steps again (Don't remove "config" folder).
@ -153,38 +155,38 @@ If you want to use a USB Bluetooth adapter or Z-Wave USB stick with Home Assista
#### Z-Wave
- Connect to your NAS over SSH
- Load cdc-acm kernel module(when nas restart need to run this command)
`insmod /usr/local/modules/cdc-acm.ko`
- Find USB devices attached. Type command:
`ls /dev/tty*`
The above command should show you any USB devices plugged into your NAS. If you have more than one, you may get multiple items returned. Like : `ttyACM0`
- Run Docker command:
`docker run --init --name home-assistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e variable=TZ -e value=Europe/London --device /dev/ttyACM0 homeassistant/home-assistant:stable`
`-v` is your config path
`-e` is set timezone
- Edit `configuration.yaml`
- Connect to your NAS over SSH
- Load cdc-acm kernel module(when nas restart need to run this command)
`insmod /usr/local/modules/cdc-acm.ko`
- Find USB devices attached. Type command:
`ls /dev/tty*`
The above command should show you any USB devices plugged into your NAS. If you have more than one, you may get multiple items returned. Like : `ttyACM0`
- Run Docker command:
`docker run --init --name home-assistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e variable=TZ -e value=Europe/London --device /dev/ttyACM0 homeassistant/home-assistant:stable`
`-v` is your config path
`-e` is set timezone
- Edit `configuration.yaml`
```yaml
zwave:
usb_path: /dev/ttyACM0
```
That will tell Home Assistant where to look for our Z-wave radio.
That will tell Home Assistant where to look for our Z-Wave radio.
#### Bluetooth
- Connect to your NAS over SSH
- Run Docker command:
`docker run --init --name home-assistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e variable=TZ -e value=Europe/London -v /dev/bus/usb:/dev/bus/usb -v /var/run/dbus:/var/run/dbus homeassistant/home-assistant:stable`
First `-v` is your config path
`-e` is set timezone
- Edit the `configuration.yaml` file
- Connect to your NAS over SSH
- Run Docker command:
`docker run --init --name home-assistant --net=host --privileged -itd -v /share/CACHEDEV1_DATA/Public/homeassistant/config:/config -e variable=TZ -e value=Europe/London -v /dev/bus/usb:/dev/bus/usb -v /var/run/dbus:/var/run/dbus homeassistant/home-assistant:stable`
First `-v` is your config path
`-e` is set timezone
- Edit the `configuration.yaml` file
```yaml
device_tracker:
@ -219,13 +221,13 @@ As the docker command becomes more complex, switching to `docker-compose` can be
Then start the container with:
```bash
$ docker-compose up -d
docker-compose up -d
```
To restart Home Assistant when you have changed configuration:
```bash
$ docker-compose restart
docker-compose restart
```
## Exposing Devices

46
source/_docs/installation/freenas.markdown
View File

@ -8,6 +8,7 @@ description: "Installation of Home Assistant on your FreeNAS."
This has been tested on FreeNAS 11.2 and should also work on FreeBSD 11.x as well. These instructions assume you already have a running and accessible jail. For more information on creating a jail read the official FreeNAS User Guide regarding [Jails](https://www.ixsystems.com/documentation/freenas/11.2/jails.html). Once you have the jail available, follow the steps below. Directories used follow standard BSD conventions but can be adjusted as you wish.
Enter the Home Assistant jail. If you don't know which name you have given the jail, you can use the `iocage list` command to check.
```bash
# If the jail is called 'HomeAssistant'
iocage exec HomeAssistant
@ -87,13 +88,13 @@ vi /usr/local/etc/rc.d/homeassistant
# KEYWORD: shutdown
#
# homeassistant_user: The user account used to run the homeassistant daemon.
# This is optional, however do not specifically set this to an
# empty string as this will cause the daemon to run as root.
# Default: homeassistant
# This is optional, however do not specifically set this to an
# empty string as this will cause the daemon to run as root.
# Default: homeassistant
# homeassistant_group: The group account used to run the homeassistant daemon.
# This is optional, however do not specifically set this to an
# empty string as this will cause the daemon to run with group wheel.
# Default: homeassistant
# This is optional, however do not specifically set this to an
# empty string as this will cause the daemon to run with group wheel.
# Default: homeassistant
#
# homeassistant_venv: Directory where homeassistant virtualenv is installed.
# Default: "/usr/local/share/homeassistant"
@ -217,11 +218,11 @@ You can also restart the jail to ensure that Home Assistant starts on boot.
<div class='note'>
USB Z-wave sticks may give `dmesg` warnings similar to "data interface 1, has no CM over data, has no break". This doesn't impact the function of the Z-Wave stick in Home Assistant. Just make sure the proper `/dev/cu*` is used in the Home Assistant `configuration.yaml` file.
USB Z-Wave sticks may give `dmesg` warnings similar to "data interface 1, has no CM over data, has no break". This doesn't impact the function of the Z-Wave stick in Home Assistant. Just make sure the proper `/dev/cu*` is used in the Home Assistant `configuration.yaml` file.
</div>
# Adding support for Z-wave stick
## Adding support for Z-Wave stick
The following two packages need to be installed in the jail
@ -230,7 +231,8 @@ pkg install gmake
pkg install libudev-devd
```
Then you can install the zwave package
Then you can install the Z-Wave package
```bash
su homeassistant
cd /usr/local/share/homeassistant
@ -240,36 +242,42 @@ deactivate
exit
```
Stop the hass Jail
Stop the Home Assistant Jail
```bash
sudo iocage stop HomeAssistant
```
Edit the devfs rules on the Freenas Host
Edit the devfs rules on the FreenNAS Host
```bash
vi /etc/devfs.rules
```
Add the following lines
Add the following lines
```bash
[devfsrules_jail_allow_usb=7]
add path 'cu\*' mode 0660 group 8123 unhide
```
Reload devfs
```bash
sudo service devfs restart
```
Edit the ruleset used by the jail in the Freenas GUI by going to Jails -> hass -> Edit -> Jail Properties -> devfs_ruleset
Edit the ruleset used by the jail in the FreeNAS GUI by going to Jails -> `hass` -> Edit -> Jail Properties -> devfs_ruleset
Set it to 7
Start the hass jail
Start the Home Assistant jail
```bash
sudo iocage start HomeAssistant
```
Connect to the hass jail and verify that you see the modem devices
Connect to the Home Assistant jail and verify that you see the modem devices
```bash
sudo iocage console HomeAssistant
```
@ -277,15 +285,19 @@ sudo iocage console HomeAssistant
```bash
ls /dev/cu*
```
This should output the following
```bash
/dev/cuau0 /dev/cuaU0
```
Add the zwave config to your `configuration.yaml` and restart HA
Add the Z-Wave config to your `configuration.yaml` and restart Home Assistant
```bash
vi /home/homeassistant/.homeassistant/configuration.yaml
```
```yaml
zwave:
usb_path: /dev/cuaU0
@ -296,8 +308,8 @@ zwave:
service homeassistant restart
```
## Updating
# Updating
Before updating, read the changelog to see what has changed and how it affects your Home Assistant instance. Enter the jail using `iocage exec <jailname>`. Stop the Home Assistant service:
```bash

22
source/_docs/z-wave/controllers.markdown
View File

@ -13,13 +13,13 @@ There have [been reports](https://www.raspberrypi.org/forums/viewtopic.php?f=28&
</div>
* Aeotec Z-Stick Series 5
* Everspring USB stick - Gen 5
* Sigma Designs UZB stick
* Vision USB stick - Gen5
* Zooz Z-Wave Plus S2 stick ZST10
* ZWave.me Razberry Board
* ZWave.me UZB1 stick
- Aeotec Z-Stick Series 5
- Everspring USB stick - Gen 5
- Sigma Designs UZB stick
- Vision USB stick - Gen5
- Zooz Z-Wave Plus S2 stick ZST10
- ZWave.me Razberry Board
- ZWave.me UZB1 stick
We recommend that you purchase a [Z-Wave Plus](https://z-wavealliance.org/z-wave_plus_certification/) controller, to take advantage of the improvements this provides. As OpenZWave doesn't support S2 or Smart Start, there's no need to buy one just for support of these features.
@ -31,10 +31,10 @@ We recommend that you purchase a [Z-Wave Plus](https://z-wavealliance.org/z-wave
The alternative to a stick is a hub that supports Z-Wave. Home Assistant supports the following hubs with Z-Wave support:
- [Vera](/integrations/vera/)
- [Wink](/integrations/wink/)
- [Fibaro](/integrations/fibaro/)
- [SmartThings](/integrations/smartthings/)
- [Vera](/integrations/vera/)
- [Wink](/integrations/wink/)
- [Fibaro](/integrations/fibaro/)
- [SmartThings](/integrations/smartthings/)
## Controller Notes

115
source/_docs/z-wave/entities.markdown
View File

@ -5,7 +5,7 @@ description: "A summary of common entity names."
<div class='note'>
This is a work in progress, based upon reports in the forum, the author's own devices and reading of various documentation. It will be incomplete, so if you have a device that isn't reported here or have a device that reports a different value, please provide a report in the [Z-Wave section](https://community.home-assistant.io/c/configuration/zwave) of the forum or the #zwave channel on [Discord](https://discord.gg/RkajcgS).
This is a work in progress, based upon reports in the forum, the author's own devices and reading of various documentation. It will be incomplete, so if you have a device that isn't reported here or have a device that reports a different value, please provide a report in the [Z-Wave section](https://community.home-assistant.io/c/configuration/zwave) of the forum or the `#zwave` channel on [Discord](https://discord.gg/RkajcgS).
</div>
@ -22,6 +22,7 @@ This is for a single purpose sensor, multi sensors are explained under Multi Sen
Devices (usually sensors) that support the Alarm command class will create entities starting with `sensor`, and with some generic suffixes, and a suffix that relates to the supported alarm class. For example, the smoke detector `lounge` will have an entity `sensor.lounge_smoke`, and possibly also `sensor.lounge_alarm_type` and `sensor.lounge_alarm_level`. If the device creates a `binary_sensor` entity, it is recommended to use that rather then the `sensor` entity.
Note that the older Z-Wave alarm command class version 1 didn't have standardized types, and so each manufacturer specified their own version and type info. With Version 2 the alarm type was standardized to the below list. See the [openzwave alarm command class documents](https://github.com/OpenZWave/open-zwave/wiki/Alarm-Command-Class) for more info. You can see which version your sensor supports via the zwcfg_0x\*.xml file. An example with version 2 support:
```xml
<CommandClass id="113" name="COMMAND_CLASS_ALARM" version="2" request_flags="2" innif="true">
```
@ -70,74 +71,74 @@ The meaning of the `alarm_level` entity depends on the nature of the alarm senso
#### Smoke, CO, and CO2
- **1**: Detection - will include a Node Location Report
- **2**: Detection (unknown location)
- **254**: Unknown event
- **1**: Detection - will include a Node Location Report
- **2**: Detection (unknown location)
- **254**: Unknown event
#### Heat
- **1**: Overheat detected - will include a Node Location Report
- **2**: Overheat detected (unknown location)
- **3**: Rapid temperature rise - will include a Node Location Report
- **4**: Rapid temperature rise (unknown location)
- **5**: Underheat detection - will include a Node Location Report
- **6**: Underheat detection (unknown location)
- **254**: Unknown event
- **1**: Overheat detected - will include a Node Location Report
- **2**: Overheat detected (unknown location)
- **3**: Rapid temperature rise - will include a Node Location Report
- **4**: Rapid temperature rise (unknown location)
- **5**: Underheat detection - will include a Node Location Report
- **6**: Underheat detection (unknown location)
- **254**: Unknown event
#### Water leak
- **1**: Water leak detected - will include a Node Location Report
- **2**: Water leak detected (unknown location)
- **3**: Water level dropped - will include a Node Location Report
- **4**: Water level dropped (unknown location)
- **254**: Unknown event
- **1**: Water leak detected - will include a Node Location Report
- **2**: Water leak detected (unknown location)
- **3**: Water level dropped - will include a Node Location Report
- **4**: Water level dropped (unknown location)
- **254**: Unknown event
#### Access control
- **1**: Manual lock
- **2**: Manual unlock
- **3**: RF lock
- **4**: RF unlock
- **5**: Keypad lock - will include the User Identifier of the User Code Report
- **6**: Keypad unlock - will include the User Identifier of the User Code Report
- **254**: Unknown event
- **1**: Manual lock
- **2**: Manual unlock
- **3**: RF lock
- **4**: RF unlock
- **5**: Keypad lock - will include the User Identifier of the User Code Report
- **6**: Keypad unlock - will include the User Identifier of the User Code Report
- **254**: Unknown event
#### Burglar
- **1**: Intrusion - will include a Node Location Report
- **2**: Intrusion (unknown location)
- **3**: Tampering (case opened)
- **4**: Tampering (invalid code)
- **5**: Glass break - will include a Node Location Report
- **6**: Glass break (invalid code)
- **254**: Unknown event
- **1**: Intrusion - will include a Node Location Report
- **2**: Intrusion (unknown location)
- **3**: Tampering (case opened)
- **4**: Tampering (invalid code)
- **5**: Glass break - will include a Node Location Report
- **6**: Glass break (invalid code)
- **254**: Unknown event
#### Power Management
- **1**: Power applied
- **2**: AC disconnected
- **3**: AC re-connected
- **4**: Surge detection
- **5**: Voltage drop or drift
- **254**: Unknown event
- **1**: Power applied
- **2**: AC disconnected
- **3**: AC re-connected
- **4**: Surge detection
- **5**: Voltage drop or drift
- **254**: Unknown event
#### System Alarm
- **1**: System hardware failure
- **2**: System software failure
- **254**: Unknown event
- **1**: System hardware failure
- **2**: System software failure
- **254**: Unknown event
#### Emergency Alarm
- **1**: Contact Police
- **2**: Contact Fire Service
- **3**: Contact Medical Service
- **254**: Unknown event
- **1**: Contact Police
- **2**: Contact Fire Service
- **3**: Contact Medical Service
- **254**: Unknown event
#### Alarm Clock
- **1**: Wake up
- **254**: Unknown event
- **1**: Wake up
- **254**: Unknown event
### Access Control Entity
@ -150,41 +151,45 @@ The meaning of the `alarm_level` entity depends on the nature of the alarm senso
If your device has an `access_control` entity, but not a `binary_sensor` equivalent, you can use a [template binary sensor](/integrations/binary_sensor.template/) to create one (here we've defined it as a door, but you can use [any relevant device class](/integrations/binary_sensor/#device-class):
{% raw %}
```yaml
binary_sensor:
- platform: template
sensors:
sensors:
YOUR_SENSOR:
friendly_name: "Friendly name here"
device_class: door
value_template: "{{ is_state('sensor.YOUR_ORIGINAL_SENSOR_access_control', '22') }}"
```
{% endraw %}
### Burglar Entity
- **burglar**: These *may* vary between brands
- **0**: Not active
- **2**: Smoke (?)
- **3**: Tamper
- **8**: Motion
- **22**: Open
- **23**: Closed
- **254**: Deep sleep
- **255**: Case open
- **0**: Not active
- **2**: Smoke (?)
- **3**: Tamper
- **8**: Motion
- **22**: Open
- **23**: Closed
- **254**: Deep sleep
- **255**: Case open
If your device has a `burglar` entity, but not a `binary_sensor` equivalent, you can use a [template binary sensor](/integrations/binary_sensor.template/) to create one (here we've defined it as a motion sensor, but you can use [any relevant device class](/integrations/binary_sensor/#device-class):
{% raw %}
```yaml
binary_sensor:
- platform: template
sensors:
sensors:
YOUR_SENSOR:
friendly_name: "Friendly name here"
device_class: motion
value_template: "{{ is_state('sensor.YOUR_SENSOR_burglar', '8') }}"
```
{% endraw %}
### Source Node ID Entity

6
source/_docs/z-wave/installation.markdown
View File

@ -15,7 +15,7 @@ zwave:
device_config: !include zwave_device_config.yaml
```
{% configuration zwave %}
{% configuration Z-Wave %}
usb_path:
description: The port where your device is connected to your Home Assistant host. Z-Wave sticks will generally be `/dev/ttyACM0` and GPIO hats will generally be `/dev/ttyAMA0`.
required: false
@ -32,12 +32,12 @@ config_path:
type: string
default: the 'config' that is installed by python-openzwave
polling_interval:
description: The time period in milliseconds between polls of a nodes value. Be careful about using polling values below 30000 (30 seconds) as polling can flood the zwave network and cause problems.
description: The time period in milliseconds between polls of a nodes value. Be careful about using polling values below 30000 (30 seconds) as polling can flood the Z-Wave network and cause problems.
required: false
type: integer
default: 60000
debug:
description: Print verbose z-wave info to log.
description: Print verbose Z-Wave info to log.
required: false
type: boolean
default: false

42
source/_docs/z-wave/query-stage.markdown
View File

@ -7,24 +7,24 @@ When the Z-Wave mesh is first started, the controller will go through all the fo
Your devices will still function normally while marked as `Initializing`.
| Stage | Description |
|------------------------|--------------------------------------------------------------------|
| None | Query process hasn't started for this node |
| ProtocolInfo | Retrieve protocol information |
| Probe | Ping device to see if alive |
| WakeUp | Start wake up process if a sleeping node |
| ManufacturerSpecific1 | Retrieve manufacturer name and product ids if ProtocolInfo lets us |
| NodeInfo | Retrieve info about supported, controlled command classes |
| NodePlusInfo | Retrieve Z-Wave+ info and update device classes |
| SecurityReport | Retrieve a list of Command Classes that require Security |
| ManufacturerSpecific2 | Retrieve manufacturer name and product ids |
| Versions | Retrieve version information |
| Instances | Retrieve information about multiple command class instances |
| Static | Retrieve static information (doesn't change) |
| CacheLoad | Ping a device upon restarting with cached config for the device |
| Associations | Retrieve information about associations |
| Neighbors | Retrieve node neighbor list |
| Session | Retrieve session information (changes infrequently) |
| Dynamic | Retrieve dynamic information (changes frequently) |
| Configuration | Retrieve configurable parameter information (only done on request) |
| Complete | Query process is completed for this node |
| Stage | Description |
| --------------------- | ---------------------------------------------------------------------- |
| None | Query process hasn't started for this node |
| ProtocolInfo | Retrieve protocol information |
| Probe | Ping device to see if alive |
| WakeUp | Start wake up process if a sleeping node |
| ManufacturerSpecific1 | Retrieve manufacturer name and product ids if ProtocolInfo lets us |
| NodeInfo | Retrieve info about supported, controlled command classes |
| NodePlusInfo | Retrieve Z-Wave+ info and update device classes |
| SecurityReport | Retrieve a list of Command Classes that require Security |
| ManufacturerSpecific2 | Retrieve manufacturer name and product ids |
| Versions | Retrieve version information |
| Instances | Retrieve information about multiple command class instances |
| Static | Retrieve static information (doesn't change) |
| CacheLoad | Ping a device upon restarting with cached configuration for the device |
| Associations | Retrieve information about associations |
| Neighbors | Retrieve node neighbor list |
| Session | Retrieve session information (changes infrequently) |
| Dynamic | Retrieve dynamic information (changes frequently) |
| Configuration | Retrieve configurable parameter information (only done on request) |
| Complete | Query process is completed for this node |

52
source/_docs/z-wave/services.markdown
View File

@ -5,32 +5,32 @@ description: "Services exposed by the Z-Wave component."
The `zwave` integration exposes multiple services to help maintain the network. All of these are available through the Z-Wave control panel.
| Service | Description |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| add_node | Put the Z-Wave controller in inclusion mode. Allows you to add a new device to the Z-Wave network. |
| add_node_secure | Put the Z-Wave controller in secure inclusion mode. Allows you to add a new device with secure communications to the Z-Wave network. |
| cancel_command | Cancels a running Z-Wave command. If you have started an add_node or remove_node command, and decide you are not going to do it, then this must be used to stop the inclusion/exclusion command. |
| change_association | Add or remove an association in the Z-Wave network |
| 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 re-figure out optimal routing. |
| heal_node | Tells the controller to "heal" a specific node on the network. Requires `node_id` field. You can also force return route update with `return_routes` field.
| print_config_parameter | Prints Z-Wave node's config parameter value to the (console) log. |
| print_node | Print all states of Z-Wave node. |
| refresh_entity | Refresh the Z-Wave entity by refreshing dependent values. |
| refresh_node | Refresh the Z-Wave node. |
| refresh_node_value | Refresh the specified value of a Z-Wave node. |
| remove_node | Put the Z-Wave controller in exclusion mode. Allows you to remove a device from the Z-Wave network. |
| rename_node | Sets a node's name. Requires a `node_id` and `name` field. |
| rename_value | Sets a value's name. Requires a `node_id`, `value_id`, and `name` field. |
| remove_failed_node | Remove a failed node from the network. The Node should be on the controller's Failed Node List, otherwise this command will fail. |
| replace_failed_node | Replace a failed device with another. If the node is not in the controller's Failed Node List, or the node responds, this command will fail. |
| reset_node_meters | Reset a node's meter values. Only works if the node supports this. |
| set_config_parameter | Lets the user set a config parameter to a node. NOTE: Use the parameter option's `label` string as the `value` for list parameters (e.g., `"value": "Off"`). For all other parameters use the relevant integer `value` (e.g., `"value": 1`). |
| set_node_value | Set the specified value of a Z-Wave 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. |
| start_network | Starts the Z-Wave network. |
| stop_network | Stops the Z-Wave network. |
| test_network | Tells the controller to send no-op commands to each node and measure the time for a response. In theory, this can also bring back nodes which have been marked "presumed dead." |
| test_node | Tells the controller to send no-op command(s) to a specific node. Requires `node_id` field. You can specify amount of test_messages to send by specifying it with `messages` field. In theory, this could bring back nodes marked as "presumed dead"
| Service | Description |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| add_node | Put the Z-Wave controller in inclusion mode. Allows you to add a new device to the Z-Wave network. |
| add_node_secure | Put the Z-Wave controller in secure inclusion mode. Allows you to add a new device with secure communications to the Z-Wave network. |
| cancel_command | Cancels a running Z-Wave command. If you have started an add_node or remove_node command, and decide you are not going to do it, then this must be used to stop the inclusion/exclusion command. |
| change_association | Add or remove an association in the Z-Wave network |
| 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 re-figure out optimal routing. |
| heal_node | Tells the controller to "heal" a specific node on the network. Requires `node_id` field. You can also force return route update with `return_routes` field. |
| print_config_parameter | Prints Z-Wave node's configuration parameter value to the (console) log. |
| print_node | Print all states of Z-Wave node. |
| refresh_entity | Refresh the Z-Wave entity by refreshing dependent values. |
| refresh_node | Refresh the Z-Wave node. |
| refresh_node_value | Refresh the specified value of a Z-Wave node. |
| remove_node | Put the Z-Wave controller in exclusion mode. Allows you to remove a device from the Z-Wave network. |
| rename_node | Sets a node's name. Requires a `node_id` and `name` field. |
| rename_value | Sets a value's name. Requires a `node_id`, `value_id`, and `name` field. |
| remove_failed_node | Remove a failed node from the network. The Node should be on the controller's Failed Node List, otherwise this command will fail. |
| replace_failed_node | Replace a failed device with another. If the node is not in the controller's Failed Node List, or the node responds, this command will fail. |
| reset_node_meters | Reset a node's meter values. Only works if the node supports this. |
| set_config_parameter | Lets the user set a configuration parameter to a node. NOTE: Use the parameter option's `label` string as the `value` for list parameters (e.g., `"value": "Off"`). For all other parameters use the relevant integer `value` (e.g., `"value": 1`). |
| set_node_value | Set the specified value of a Z-Wave 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. |
| start_network | Starts the Z-Wave network. |
| stop_network | Stops the Z-Wave network. |
| test_network | Tells the controller to send no-op commands to each node and measure the time for a response. In theory, this can also bring back nodes which have been marked "presumed dead." |
| test_node | Tells the controller to send no-op command(s) to a specific node. Requires `node_id` field. You can specify amount of test_messages to send by specifying it with `messages` field. In theory, this could bring back nodes marked as "presumed dead" |
The `soft_reset` and `heal_network` commands can be used to help keep a Z-Wave network running reliably. This is a configuration option for the `zwave` component. The option defaults to `false` but can be enabled by setting `autoheal` to true. This, however, is bad practice since it introduces overhead that can be avoided since you only need to do a `heal_network` whenever one of the following actions are done:

52
source/_integrations/alexa.intent.markdown
View File

@ -28,7 +28,7 @@ The built-in Alexa integration allows you to integrate Home Assistant into Alexa
- Click the yellow "Add a new skill" button in the top right
- Skill Type: Custom Interaction Model (default)
- Name: Home Assistant
- Invocation name: home assistant (or be creative, up to you)
- Invocation name: `home assistant` (or be creative, up to you)
- Version: 1.0
- Endpoint: This will be the ARN for the Lambda Function you will create next.
@ -40,7 +40,7 @@ The Alexa Custom skill will trigger a AWS Lambda function to process the request
OK, let's go. You first need sign in your [AWS console](https://console.aws.amazon.com/), if you don't have an AWS account yet, you can create a new user [here](https://aws.amazon.com/free/) with 12-month free tier benefit. You don't need worry the cost if your account has already passed the first 12 months, AWS provides up to 1 million Lambda requests, 1GB of outbound data and unlimited inbound data for free every month for all users. See [Lambda pricing](https://aws.amazon.com/lambda/pricing/) for details.
#### Create an IAM Role for Lambda
#### Create an IAM Role for Lambda
The first thing you need to do after you sign in to the [AWS console](https://console.aws.amazon.com/) is to create an IAM Role for Lambda execution. AWS has very strict access control, you have to explicitly define and assign the permissions.
@ -61,9 +61,9 @@ Next you need to create a Lambda function.
- Click `Service` in top navigation bar, expand the menu to display all AWS services, click `Lambda` under `Compute` section to navigate to Lambda console. Or you may use this [link](https://console.aws.amazon.com/lambda/home)
- **IMPORTANT** Your current region will be displayed on the top right corner, make sure you select right region base on your Amazon account's country:
* **US East (N.Virginia)** region for English (US) or English (CA) skills
* **EU (Ireland)** region for English (UK), English (IN), German (DE), Spanish (ES) or French (FR) skills
* **US West (Oregon)** region for Japanese and English (AU) skills.
- **US East (N.Virginia)** region for English (US) or English (CA) skills
- **EU (Ireland)** region for English (UK), English (IN), German (DE), Spanish (ES) or French (FR) skills
- **US West (Oregon)** region for Japanese and English (AU) skills.
- Click `Functions` in the left navigation bar, display list of your Lambda functions.
- Click `Create function`, select `Author from scratch`, then input a `Function name`.
- Select *Python 3.6* or *Python 3.7* as `Runtime`.
@ -74,10 +74,10 @@ Next you need to create a Lambda function.
- Click your Lambda Function icon in the middle of the diagram and scroll down, you will see a `Function code` window.
- Clear the example code and copy the Python script from: [https://gist.github.com/lpomfrey/97381cf4316553b03622c665ae3a47da](https://gist.github.com/lpomfrey/97381cf4316553b03622c665ae3a47da)
- Scroll down again and you will find `Environment variables`, add the following environment variables as needed:
* BASE_URL *(required)*: your Home Assistant instance's Internet accessible URL with port if needed. *Do not include the trailing `/`*.
* NOT_VERIFY_SSL *(optional)*: set to *True* to ignore the SSL issue, if you don't have a valid SSL certificate or you are using self-signed certificate.
* DEBUG *(optional)*: set to *True* to log debugging messages.
* LONG_LIVED_ACCESS_TOKEN *(optional, not recommended)*: you will connect your Alexa Custom skill with your Home Assistant user account in the later steps, so that you don't need to use long-lived access token here. However, the access token you got from login flow is only valid for 30 minutes. It will be hard for you to test lambda function with the access token in test data. So for your convinces, you can remove the access token from the test data, [generate a long-lived access token][generate-long-lived-access-token] put here, then the function will fall back to reading the token from environment variables. (tips: You did not enable the security storage for your environment variables, so your token saved here is not that safe. You should only use it for debugging and testing purpose. You should remove and delete the long-lived access token after you finish the debugging.)
- BASE_URL *(required)*: your Home Assistant instance's Internet accessible URL with port if needed. *Do not include the trailing `/`*.
- NOT_VERIFY_SSL *(optional)*: set to *True* to ignore the SSL issue, if you don't have a valid SSL certificate or you are using self-signed certificate.
- DEBUG *(optional)*: set to *True* to log debugging messages.
- LONG_LIVED_ACCESS_TOKEN *(optional, not recommended)*: you will connect your Alexa Custom skill with your Home Assistant user account in the later steps, so that you don't need to use long-lived access token here. However, the access token you got from login flow is only valid for 30 minutes. It will be hard for you to test lambda function with the access token in test data. So for your convinces, you can remove the access token from the test data, [generate a long-lived access token][generate-long-lived-access-token] put here, then the function will fall back to reading the token from environment variables. (tips: You did not enable the security storage for your environment variables, so your token saved here is not that safe. You should only use it for debugging and testing purpose. You should remove and delete the long-lived access token after you finish the debugging.)
<p class='img'>
<img src='/images/integrations/alexa/lambda_function_env_var.png' alt='Screenshot: Environment variables in Lambda function'>
@ -93,20 +93,20 @@ Alexa can link your Amazon account to your Home Assistant account. Therefore Hom
- Sign in to the [Alexa Developer Console][alexa-dev-console] and go to the `Alexa Skills` page.
- Find the skill you just created and click `Edit` in the `Actions` column.
- Click `ACCOUNT LINKING` in the left navigation bar of build page
- Input all information required. Assuming your Home Assistant can be accessed by https://[YOUR HOME ASSISTANT URL:PORT]
* `Authorization URI`: https://[YOUR HOME ASSISTANT URL]/auth/authorize
* `Access Token URI`: https://[YOUR HOME ASSISTANT URL]/auth/token
- Input all information required. Assuming your Home Assistant can be accessed by `https://[YOUR HOME ASSISTANT URL:PORT]`
- `Authorization URI`: `https://[YOUR HOME ASSISTANT URL]/auth/authorize`
- `Access Token URI`: `https://[YOUR HOME ASSISTANT URL]/auth/token`
- Note: you must use a valid/trusted SSL Certificate and port 443 for account linking to work
* `Client ID`:
- https://pitangui.amazon.com/ if you are in US
- https://layla.amazon.com/ if you are in EU
- https://alexa.amazon.co.jp/ if you are in JP or AU
- `Client ID`:
- `https://pitangui.amazon.com/` if you are in US
- `https://layla.amazon.com/` if you are in EU
- `https://alexa.amazon.co.jp/` if you are in JP or AU
The trailing slash is important here.
* `Client Secret`: input anything you like, Home Assistant does not check this field
* `Client Authentication Scheme`: make sure you selected *Credentials in request body*. Home Assistant does not support *HTTP Basic*.
* `Scope`: input `intent`. Home Assistant doesn't use this yet, we may use it in the future when we allow more fine-grained access control.
- `Client Secret`: input anything you like, Home Assistant does not check this field
- `Client Authentication Scheme`: make sure you selected *Credentials in request body*. Home Assistant does not support *HTTP Basic*.
- `Scope`: input `intent`. Home Assistant doesn't use this yet, we may use it in the future when we allow more fine-grained access control.
- You can leave `Domain List` and `Default Access Token Expiration Time` as empty.
<p class='img'>
@ -115,11 +115,11 @@ Alexa can link your Amazon account to your Home Assistant account. Therefore Hom
- Click `Save` button in the top right corner.
- Next, you will use the Alexa Mobile App or [Alexa web-based app](#alexa-web-based-app) to link your account.
* Open the Alexa app, navigate to `Skills` -> `Your Skills` -> `Dev Skills`
* Click the Custom skill you just created.
* Click `Enable`.
* A new window will open to direct you to your Home Assistant's login screen.
* After you successfully login, you will be redirected back to Alexa app.
- Open the Alexa app, navigate to `Skills` -> `Your Skills` -> `Dev Skills`
- Click the Custom skill you just created.
- Click `Enable`.
- A new window will open to direct you to your Home Assistant's login screen.
- After you successfully login, you will be redirected back to Alexa app.
### Configuring your Amazon Alexa skill
@ -288,6 +288,7 @@ To start, you need to get the skill id:
- Click the "View Skill ID" link and copy the ID
The configuration is the same as an intent with the exception being you will use your skill ID instead of the intent name.
```yaml
intent_script:
amzn1.ask.skill.08888888-7777-6666-5555-444444444444:
@ -340,7 +341,6 @@ text: !include alexa_confirm.yaml
Alexa will now respond with a random phrase each time. You can use the include for as many different intents as you like so you only need to create the list once.
[amazon-dev-console]: https://developer.amazon.com
[large-icon]: /images/integrations/alexa/alexa-512x512.png
[small-icon]: /images/integrations/alexa/alexa-108x108.png

324
source/_integrations/alexa.smart_home.markdown
View File

@ -12,10 +12,10 @@ ha_codeowners:
Amazon Alexa provides a Smart Home API for richer home automation control without requiring the user to say the skill name, such as:
* _"Alexa, turn off the light."_
* _"Alexa, set the thermostat to cool."_
* _"Alexa, is the garage door open?"_
- _"Alexa, turn off the light."_
- _"Alexa, set the thermostat to cool."_
- _"Alexa, is the garage door open?"_
It takes considerable effort to configure. Your Home Assistant instance must be accessible from the Internet, and you need to create an Amazon Developer account and an Amazon Web Services (AWS) account. An easier solution is to use [Home Assistant Cloud](/integrations/cloud/).
The [Emulated Hue integration][emulated-hue-component] provides a simpler alternative to use utterances such as _"Alexa, turn on the kitchen light"_. However, it has some limitations since everything looks like a light bulb.
@ -29,7 +29,7 @@ For Home Assistant Cloud Users, documentation can be found [here](https://www.na
</div>
**Steps to Integrate an Amazon Alexa Smart Home Skill with Home Assistant**
Steps to Integrate an Amazon Alexa Smart Home Skill with Home Assistant:
- [Requirements](#requirements)
- [Create an Amazon Alexa Smart Home Skill](#create-an-amazon-alexa-smart-home-skill)
@ -102,9 +102,9 @@ Next you need create a Lambda function.
- Click `Service` in top navigation bar, expand the menu to display all AWS services, click `Lambda` under `Compute` section to navigate to Lambda console. Or you may use this [link](https://console.aws.amazon.com/lambda/home)
- **IMPORTANT** Your current region will be displayed on the top right corner, make sure you select right region base on your Amazon account's country:
* **US East (N.Virginia)** region for English (US) or English (CA) skills
* **EU (Ireland)** region for English (UK), English (IN), German (DE), Spanish (ES) or French (FR) skills
* **US West (Oregon)** region for Japanese and English (AU) skills.
- **US East (N.Virginia)** region for English (US) or English (CA) skills
- **EU (Ireland)** region for English (UK), English (IN), German (DE), Spanish (ES) or French (FR) skills
- **US West (Oregon)** region for Japanese and English (AU) skills.
- Click `Functions` in the left navigation bar, display list of your Lambda functions.
- Click `Create function`, select `Author from scratch`, then input a `Function name`.
- Select *Python 3.6* or *Python 3.7* as `Runtime`.
@ -115,10 +115,10 @@ Next you need create a Lambda function.
- Click your Lambda function icon in the middle of the diagram, scroll down you will see a `Function code` window.
- Clear the example code, copy the Python script from: [https://gist.github.com/matt2005/744b5ef548cc13d88d0569eea65f5e5b](https://gist.github.com/matt2005/744b5ef548cc13d88d0569eea65f5e5b) (modified code to support Alexa's proactive mode, see details below)
- Scroll down a little bit, you will find `Environment variables`, you need add 4 environment variables:
* BASE_URL *(required)*: your Home Assistant instance's Internet accessible URL with port if needed. *Do not include the trailing `/`*.
* NOT_VERIFY_SSL *(optional)*: you can set it to *True* to ignore the SSL issue, if you don't have a valid SSL certificate or you are using self-signed certificate.
* DEBUG *(optional)*: set to *True* to log the debug message
* LONG_LIVED_ACCESS_TOKEN *(optional, not recommend)*: you will connect your Alexa Smart Home skill with your Home Assistant user account in the later steps, so that you don't need to use long-lived access token here. However, the access token you got from login flow is only valid for 30 minutes. It will be hard for you to test lambda function with the access token in test data. So for your convinces, you can remove the access token from the test data, [generate a long-lived access token][generate-long-lived-access-token] put here, then the function will fall back to read token from environment variables. (tips: You did not enable the security storage for your environment variables, so your token saved here is not that safe. You should only use it for debugging and testing purpose. You should remove and delete the long-lived access token after you finish the debugging.)
- BASE_URL *(required)*: your Home Assistant instance's Internet accessible URL with port if needed. *Do not include the trailing `/`*.
- NOT_VERIFY_SSL *(optional)*: you can set it to *True* to ignore the SSL issue, if you don't have a valid SSL certificate or you are using self-signed certificate.
- DEBUG *(optional)*: set to *True* to log the debug message
- LONG_LIVED_ACCESS_TOKEN *(optional, not recommend)*: you will connect your Alexa Smart Home skill with your Home Assistant user account in the later steps, so that you don't need to use long-lived access token here. However, the access token you got from login flow is only valid for 30 minutes. It will be hard for you to test lambda function with the access token in test data. So for your convinces, you can remove the access token from the test data, [generate a long-lived access token][generate-long-lived-access-token] put here, then the function will fall back to read token from environment variables. (tips: You did not enable the security storage for your environment variables, so your token saved here is not that safe. You should only use it for debugging and testing purpose. You should remove and delete the long-lived access token after you finish the debugging.)
<p class='img'>
<img src='/images/integrations/alexa/lambda_function_env_var.png' alt='Screenshot: Environment variables in Lambda function'>
@ -182,20 +182,20 @@ Alexa can link your Amazon account to your Home Assistant account. Therefore Hom
- Sign in [Alexa Developer Console][alexa-dev-console], go to `Alexa Skills` page if you are not.
- Find the skill you just created, click `Edit` link in the `Actions` column.
- Click `ACCOUNT LINKING` in the left navigation bar of build page
- Input all information required. Assuming your Home Assistant can be accessed by https://[YOUR HOME ASSISTANT URL:PORT]
* `Authorization URI`: https://[YOUR HOME ASSISTANT URL]/auth/authorize
* `Access Token URI`: https://[YOUR HOME ASSISTANT URL]/auth/token
- Input all information required. Assuming your Home Assistant can be accessed by `https://[YOUR HOME ASSISTANT URL:PORT]`
- `Authorization URI`: `https://[YOUR HOME ASSISTANT URL]/auth/authorize`
- `Access Token URI`: `https://[YOUR HOME ASSISTANT URL]/auth/token`
- Note: you must use a valid/trusted SSL Certificate and port 443 for account linking to work
* `Client ID`:
- https://pitangui.amazon.com/ if you are in US
- https://layla.amazon.com/ if you are in EU
- https://alexa.amazon.co.jp/ if you are in JP and AU (not verified yet)
- `Client ID`:
- `https://pitangui.amazon.com/` if you are in US
- `https://layla.amazon.com/` if you are in EU
- `https://alexa.amazon.co.jp/` if you are in JP and AU (not verified yet)
The trailing slash is important here.
* `Client Secret`: input anything you like, Home Assistant does not check this field
* `Client Authentication Scheme`: make sure you selected *Credentials in request body*. Home Assistant does not support *HTTP Basic*.
* `Scope`: input `smart_home`, Home Assistant is not using it yet, we may use it in the future when we allow more fine-grained access control.
- `Client Secret`: input anything you like, Home Assistant does not check this field
- `Client Authentication Scheme`: make sure you selected *Credentials in request body*. Home Assistant does not support *HTTP Basic*.
- `Scope`: input `smart_home`, Home Assistant is not using it yet, we may use it in the future when we allow more fine-grained access control.
- You can leave `Domain List` and `Default Access Token Expiration Time` as empty.
<p class='img'>
@ -204,12 +204,12 @@ Alexa can link your Amazon account to your Home Assistant account. Therefore Hom
- Click `Save` button in the top right corner.
- Next, you will use Alexa Mobile App or [Alexa web-based app](#alexa-web-based-app) to link your account.
* Open the Alexa app, navigate to `Skills` -> `Your Skills` -> `Dev Skills`
* Click the Smart Home skill you just created.
* Click `Enable`.
* A new window will open to direct you to your Home Assistant's login screen.
* After you success login, you will be redirected back to Alexa app.
* You can discovery your devices now.
- Open the Alexa app, navigate to `Skills` -> `Your Skills` -> `Dev Skills`
- Click the Smart Home skill you just created.
- Click `Enable`.
- A new window will open to direct you to your Home Assistant's login screen.
- After you success login, you will be redirected back to Alexa app.
- You can discovery your devices now.
- Now, you can ask your Echo or in Alexa App, _"Alexa, turn on bedroom"_ 🎉
## Alexa Smart Home Component Configuration
@ -238,6 +238,7 @@ alexa:
switch.stairs:
display_categories: LIGHT
```
{% configuration %}
alexa:
description: Alexa configuration
@ -321,6 +322,7 @@ alexa:
The `locale` should match the location and language used for your Amazon echo devices.
The supported locales are:
- `de-DE`
- `en-AU`
- `en-CA`
@ -349,6 +351,7 @@ The `endpoint`, `client_id` and `client_secret` are optional, and are only requi
By default, no entity will be excluded. To limit which entities are being exposed to Alexa, you can use the `filter` parameter. Keep in mind that only [supported components](#supported-integrations) can be added.
{% raw %}
```yaml
# Example filter to include specified domains and exclude specified entities
alexa:
@ -360,6 +363,7 @@ alexa:
exclude_entities:
- light.kitchen_light
```
{% endraw %}
Filters are applied as follows:
@ -368,14 +372,14 @@ Filters are applied as follows:
2. Includes, no excludes - only include specified entities
3. Excludes, no includes - only exclude specified entities
4. Both includes and excludes:
* Include domain specified
- Include domain specified
- if domain is included, and entity not excluded, pass
- if domain is not included, and entity not included, fail
* Exclude domain specified
- Exclude domain specified
- if domain is excluded, and entity not included, fail
- if domain is not excluded, and entity not excluded, pass
- if both include and exclude domains specified, the exclude domains are ignored
* Neither include or exclude domain specified
- Neither include or exclude domain specified
- if entity is included, pass (as #2 above)
- if entity include and exclude, the entity exclude is ignored
@ -401,6 +405,7 @@ See [Alexa Display Categories][alexa-display-categories] for a complete list
Home Assistant supports the following integrations through Alexa using a Smart Home Skill. For Home Assistant Cloud Users, documentation can be found [here](https://www.nabucasa.com/config/amazon_alexa/).
The following integrations are currently supported:
- [Alarm Control Panel](#alarm-control-panel)
- [Alert](#alert-automation-group-input-boolean)
- [Automation](#alert-automation-group-input-boolean)
@ -437,10 +442,10 @@ The following integrations are currently supported:
Arm and disarm Alarm Control Panel entities. Ask Alexa for the state of the Alarm Control Panel entity.
* _"Alexa, arm my home in away mode."_
* _"Alexa, arm my home."_
* _"Alexa, disarm my home."_
* _"Alexa, is my home armed?"_
- _"Alexa, arm my home in away mode."_
- _"Alexa, arm my home."_
- _"Alexa, disarm my home."_
- _"Alexa, is my home armed?"_
#### Arming
@ -472,28 +477,28 @@ The existing code is never communicated to Alexa from Home Assistant. During dis
Turn on and off Alerts, Automations, Groups, and Input Boolean entities as switches.
* _"Alexa, turn on the front door alert."_
* _"Alexa, turn off energy saving automations."_
* _"Alexa, Downstairs to on."_
- _"Alexa, turn on the front door alert."_
- _"Alexa, turn off energy saving automations."_
- _"Alexa, Downstairs to on."_
### Binary Sensor
Requires [Proactive Events](#proactive-events) enabled.
Binary Sensors with a [`device_class`](/integrations/binary_sensor/#device-class) attribute of `door` `garage_door` `opening` `window` `motion` `presense` are supported.
|`device_class`|Alexa Sensor Type|
| :---: | :---: |
|`door`|Contact|
|`garage_door`|Contact|
|`opening`|Contact|
|`window`|Contact|
|`motion`|Motion|
|`presense`|Motion|
| `device_class` | Alexa Sensor Type |
| :------------: | :---------------: |
| `door` | Contact |
| `garage_door` | Contact |
| `opening` | Contact |
| `window` | Contact |
| `motion` | Motion |
| `presense` | Motion |
Ask Alexa for the state of a contact sensor.
* _"Alexa, is the bedroom window open?"_
- _"Alexa, is the bedroom window open?"_
#### Routines
@ -508,6 +513,7 @@ Use the [Entity Customization Tool](/docs/configuration/customizing-devices/#cus
Requires [Proactive Events](#proactive-events) enabled.
Configure a `binary_sensor` with `display_category` of `DOORBELL` in the [`entity_config`](#entity_config) to gain access to the doorbell notification settings in the Alexa App.
```yaml
alexa:
smart_home:
@ -563,16 +569,17 @@ Each Echo device will need the communication and Announcements setting enabled,
### Climate
Single, double, and triple set-point thermostats are supported. The temperature value from the thermostat will also be exposed at a separate [temperature sensor](#sensor).
#### Set Thermostat Temperature
* _"Alexa, set thermostat to 20."_
* _"Alexa, set the AC to 75."_
* _"Alexa, make it warmer in here."_
* _"Alexa, make it cooler in here."_
- _"Alexa, set thermostat to 20."_
- _"Alexa, set the AC to 75."_
- _"Alexa, make it warmer in here."_
- _"Alexa, make it cooler in here."_
#### Thermostat Mode
* _"Alexa, set living room thermostat to automatic."_
- _"Alexa, set living room thermostat to automatic."_
- `DRY` is shown in Alexa app as `DEHUMIDIFY`
- `ECO` is handled as a `preset` in Home Assistant, and will not display in the Alexa app.
@ -580,23 +587,23 @@ Single, double, and triple set-point thermostats are supported. The temperature
To change the thermostat mode, the exact utterance must be used:
* _"Alexa, set [entity name] to [mode utterance]."_
- _"Alexa, set [entity name] to [mode utterance]."_
If the climate entity supports on/off, use _"turn on"_ and _"turn off"_ utterances with the entity name or the mode utterance.
* _"Alexa, turn on the [mode utterance]."_
* _"Alexa, turn off the [entity name]."_
- _"Alexa, turn on the [mode utterance]."_
- _"Alexa, turn off the [entity name]."_
Alexa supports the following utterances value for climate thermostat mode:
|HA Climate Mode | Alexa Mode Utterances |
|--- |--- |
|`AUTO` | _"auto"_, _"automatic"_|
|`COOL` | _"cool"_, _"cooling"_|
|`HEAT` | _"heat"_, _"heating"_|
|`ECO` | _"eco"_, _"economical"_|
|`DRY` | _"dry"_, _"dehumidify"_|
|`OFF` | _"off"_|
| HA Climate Mode | Alexa Mode Utterances |
| --------------- | ----------------------- |
| `AUTO` | _"auto"_, _"automatic"_ |
| `COOL` | _"cool"_, _"cooling"_ |
| `HEAT` | _"heat"_, _"heating"_ |
| `ECO` | _"eco"_, _"economical"_ |
| `DRY` | _"dry"_, _"dehumidify"_ |
| `OFF` | _"off"_ |
### Cover
@ -612,10 +619,10 @@ Use the [Entity Customization Tool](/docs/configuration/customizing-devices/#cus
Home Assistant configures covers with semantics that provide _"raise"_, _"lower"_, _"open"_, _"close"_ utterances for covers. In addition to semantics _"turn on"_ / _"turn off"_ utterances will also work.
* _"Alexa, open the garage door."_
* _"Alexa, close the curtain."_
* _"Alexa, lower the shades."_
* _"Alexa, raise the roof!"_
- _"Alexa, open the garage door."_
- _"Alexa, close the curtain."_
- _"Alexa, lower the shades."_
- _"Alexa, raise the roof!"_
Semantics are assigned based on the features supported by the cover. If the cover supports tilt functionality, the semantics _"open"_ and _"close"_ are assigned to the tilt functionality, and the semantics _"raise"_ and _"lower"_ are assigned to the position functionality.
@ -625,13 +632,13 @@ If the cover does not support tilt, all semantics _"raise"_, _"lower"_, _"open"_
Covers that support a set position can be controlled using percentages.
* _"Alexa, set the [entity name] position to thirty percent."_
* _"Alexa, increase [entity name] position by ten percent."_
* _"Alexa, decrease [entity name] position by twenty percent."_
- _"Alexa, set the [entity name] position to thirty percent."_
- _"Alexa, increase [entity name] position by ten percent."_
- _"Alexa, decrease [entity name] position by twenty percent."_
|Locale|Friendly Name Synonyms|
|---|---|
|`en-US`|_"position"_, _"opening"_|
| Locale | Friendly Name Synonyms |
| ------- | ------------------------- |
| `en-US` | _"position"_, _"opening"_ |
Currently, Alexa only supports friendly name synonyms for the `en-US` locale.
@ -639,13 +646,13 @@ Currently, Alexa only supports friendly name synonyms for the `en-US` locale.
Covers that support tilt position can be controlled using percentages.
* _"Alexa, set the [entity name] tilt to thirty percent."_
* _"Alexa, increase [entity name] tilt by ten percent."_
* _"Alexa, decrease [entity name] tilt by twenty percent."_
- _"Alexa, set the [entity name] tilt to thirty percent."_
- _"Alexa, increase [entity name] tilt by ten percent."_
- _"Alexa, decrease [entity name] tilt by twenty percent."_
|Locale|Friendly Name Synonyms|
|---|---|
|`en-US`|_"tilt"_, _"angle"_, _"direction"_|
| Locale | Friendly Name Synonyms |
| ------- | ---------------------------------- |
| `en-US` | _"tilt"_, _"angle"_, _"direction"_ |
Currently, Alexa only supports friendly name synonyms for the `en-US` locale.
@ -666,28 +673,28 @@ Control fan speed, direction, and oscillation.
The fan device must support the `speed` attribute. `speed` can be set using a percentage or a range value determined from the `speed_list` attribute.
* _"Alexa, set the fan speed to three."_
* _"Alexa, set the fan speed to fifty percent."_
* _"Alexa, set the fan power level to fifty percent."_
* _"Alexa, turn up the speed on the tower fan."_
* _"Alexa, set the air speed on the tower fan to maximum."_
- _"Alexa, set the fan speed to three."_
- _"Alexa, set the fan speed to fifty percent."_
- _"Alexa, set the fan power level to fifty percent."_
- _"Alexa, turn up the speed on the tower fan."_
- _"Alexa, set the air speed on the tower fan to maximum."_
The `speed_list` attribute is used to determine the range value. For example, using a `speed_list` consisting of `[off, low, medium, high]` the range values would be `0:off`, `1:low`, `2:medium`, `3:high`.
The following table lists the possible friendly name synonyms available for a fan with `speed_list: [off, low, medium, high]`.
|Fan Range|Friendly Name Synonyms|
|---|---|
|0|_"zero"_, _"off"_|
|1|_"one"_, _"thirty-three percent"_, _"low"_, _"minimum"_, _"min"_|
|2|_"two"_, _"sixty-six percent"_, _"medium"_|
|3|_"three"_, _"one hundred percent"_, _"high"_, _"maximum"_, _"max"_|
| Fan Range | Friendly Name Synonyms |
| --------- | ------------------------------------------------------------------ |
| 0 | _"zero"_, _"off"_ |
| 1 | _"one"_, _"thirty-three percent"_, _"low"_, _"minimum"_, _"min"_ |
| 2 | _"two"_, _"sixty-six percent"_, _"medium"_ |
| 3 | _"three"_, _"one hundred percent"_, _"high"_, _"maximum"_, _"max"_ |
The following synonyms can be used for _"fan speed"_
|Locale|Friendly Name Synonyms|
|---|---|
|`en-US`|_"fan speed"_, _"airflow speed"_, _"wind speed"_, _"air speed"_, _"air velocity"_, _"power level"_|
| Locale | Friendly Name Synonyms |
| ------- | -------------------------------------------------------------------------------------------------- |
| `en-US` | _"fan speed"_, _"airflow speed"_, _"wind speed"_, _"air speed"_, _"air velocity"_, _"power level"_ |
Currently, Alexa only supports friendly name synonyms for the `en-US` locale.
@ -695,20 +702,20 @@ Currently, Alexa only supports friendly name synonyms for the `en-US` locale.
The fan device must support the `direction` attribute.
* _"Alexa, set the fan direction to forward."_
* _"Alexa, set the fan direction to reverse."_
- _"Alexa, set the fan direction to forward."_
- _"Alexa, set the fan direction to reverse."_
#### Fan Oscillation
The fan device must support the `oscillating` attribute.
* _"Alexa, is oscillate on for the tower fan?"_
* _"Alexa, turn on swivel for the tower fan."_
* _"Alexa, turn on oscillation mode for the table fan."_
- _"Alexa, is oscillate on for the tower fan?"_
- _"Alexa, turn on swivel for the tower fan."_
- _"Alexa, turn on oscillation mode for the table fan."_
|Locale|Friendly Name Synonyms|
|---|---|
|`en-US`|_"oscillate"_, _"swivel"_, _"oscillation"_, _"spin"_, _"back and forth"_|
| Locale | Friendly Name Synonyms |
| ------- | ------------------------------------------------------------------------ |
| `en-US` | _"oscillate"_, _"swivel"_, _"oscillation"_, _"spin"_, _"back and forth"_ |
Currently, Alexa only supports friendly name synonyms for the `en-US` locale.
@ -737,29 +744,29 @@ Display category will default to `CAMERA` to enable presence detected notificati
Control an `input_number` entity with Alexa. Configures Alexa with the `min`, `max`, `step`, and `unit_of_measurement` attributes for the entity.
* _"Alexa, set [entity name] to forty five [unit of measurement]."_
* _"Alexa, increase the [entity name] by two."_
* _"Alexa, set the [entity name] to maximum."_
- _"Alexa, set [entity name] to forty five [unit of measurement]."_
- _"Alexa, increase the [entity name] by two."_
- _"Alexa, set the [entity name] to maximum."_
The following table lists the possible friendly name synonyms available for a Input Number with `min: -90, max: 90, step: 45, unit_of_measurement: degrees`.
|Fan Range|Friendly Name Synonyms|
|---|---|
|-90|_"negative ninety"_, _"minimum"_, _"min"_|
|-45|_"negative forty five"_|
|0|_"zero"_|
|45|_"forty five"_|
|90|_"ninety"_, _"maximum"_, _"max"_|
| Fan Range | Friendly Name Synonyms |
| --------- | ----------------------------------------- |
| -90 | _"negative ninety"_, _"minimum"_, _"min"_ |
| -45 | _"negative forty five"_ |
| 0 | _"zero"_ |
| 45 | _"forty five"_ |
| 90 | _"ninety"_, _"maximum"_, _"max"_ |
### Light
* _"Alexa, dim the bathroom light."_
* _"Alexa, set the bedroom light to fifty percent."_
- _"Alexa, dim the bathroom light."_
- _"Alexa, set the bedroom light to fifty percent."_
### Lock
* _"Alexa, lock my front door."_
* _"Alexa, unlock the dungeon."_
- _"Alexa, lock my front door."_
- _"Alexa, unlock the dungeon."_
#### Unlocking
@ -769,27 +776,27 @@ To unlock, Alexa will require a 4 digit voice personal identification number (PI
#### Change Channel
* _"Alexa, change the channel to 200 on the Living Room TV."_
* _"Alexa, change the channel to PBS on the TV."_
* _"Alexa, next channel on the Living Room TV."_
* _"Alexa, channel up on the TV."_
* _"Alexa, channel down on the TV."_
- _"Alexa, change the channel to 200 on the Living Room TV."_
- _"Alexa, change the channel to PBS on the TV."_
- _"Alexa, next channel on the Living Room TV."_
- _"Alexa, channel up on the TV."_
- _"Alexa, channel down on the TV."_
#### Speaker Volume
* _"Alexa, set the volume of the speakers to 50."_
* _"Alexa, turn the volume down on the stereo by 20."_
* _"Alexa, turn the volume down on Living Room TV."_
* _"Alexa, mute speakers."_
* _"Alexa, unmute speakers."_
* _"Alexa, lower the volume on the stereo."_
* _"Alexa, volume up 20 on the speakers."_
- _"Alexa, set the volume of the speakers to 50."_
- _"Alexa, turn the volume down on the stereo by 20."_
- _"Alexa, turn the volume down on Living Room TV."_
- _"Alexa, mute speakers."_
- _"Alexa, unmute speakers."_
- _"Alexa, lower the volume on the stereo."_
- _"Alexa, volume up 20 on the speakers."_
#### Equalizer Mode
Supports changing the Media Player `sound_mode` from the preset `sound_mode_list`.
* _"Alexa, set mode to movie on the TV."_
- _"Alexa, set mode to movie on the TV."_
Alexa only supports the following modes: `movie`, `music`, `night`, `sport`, `tv`.
@ -797,7 +804,7 @@ Alexa only supports the following modes: `movie`, `music`, `night`, `sport`, `tv
Supports changing the Media Player `source` from the preset `source_list`.
* _"Alexa, change the input to DVD on the Living Room TV."_
- _"Alexa, change the input to DVD on the Living Room TV."_
Home Assistant will attempt to translate the the `media_player` `source_list` into a valid `source` name for Alexa. Alexa only supports the following input names:
@ -809,23 +816,23 @@ Requires [Proactive Events](#proactive-events) enabled.
#### Seek
* _"Alexa, skip 30 seconds on device."_
* _"Alexa, go back 10 seconds on device."_
- _"Alexa, skip 30 seconds on device."_
- _"Alexa, go back 10 seconds on device."_
### Scene
Activate scenes with scene name, or _"turn on"_ utterance. Home Assistant does not support deactivate or _"turn off"_ for scenes at this time.
* _"Alexa, Party Time."_
* _"Alexa, turn on Party Time."_
- _"Alexa, Party Time."_
- _"Alexa, turn on Party Time."_
### Script
Run script with script name, or _"turn on"_ utterance. Deactivate a running script with _"turn off"_ utterance.
* _"Alexa, Party Time."_
* _"Alexa, turn on Party Time."_
* _"Alexa, turn off Party Time."_
- _"Alexa, Party Time."_
- _"Alexa, turn on Party Time."_
- _"Alexa, turn off Party Time."_
### Sensor
@ -833,24 +840,24 @@ Requires [Proactive Events](#proactive-events) enabled.
Only temperature sensors are configured at this time.
* _"Alexa, what's the temperature in the kitchen?"_
* _"Alexa, what's the upstairs temperature?"_
* _"Alexa, what's the temperature of my ex-girlfriend's heart?"_
- _"Alexa, what's the temperature in the kitchen?"_
- _"Alexa, what's the upstairs temperature?"_
- _"Alexa, what's the temperature of my ex-girlfriend's heart?"_
### Switch
Support _"turn on"_ and _"turn off"_ utterances.
* _"Alexa, turn on the vacuum."_
* _"Alexa, turn off the lights."_
- _"Alexa, turn on the vacuum."_
- _"Alexa, turn off the lights."_
### Timer
Start, Pause, and Restart Timer entities in Home Assistant.
* _"Alexa, pause the microwave."_
* _"Alexa, hold the sous vide."_
* _"Alexa, restart the microwave."_
- _"Alexa, pause the microwave."_
- _"Alexa, hold the sous vide."_
- _"Alexa, restart the microwave."_
<div class="note">
To avoid issues with Alexa built in timer functionality. The timer entity can not include the word "timer" in the friendly name.
@ -860,21 +867,22 @@ To avoid issues with Alexa built in timer functionality. The timer entity can no
Support _"turn on"_ and _"turn off"_ utterances. Pause and Resume
* _"Alexa, turn on the vacuum."_
* _"Alexa, pause the vacuum."_
* _"Alexa, restart the vacuum."_
- _"Alexa, turn on the vacuum."_
- _"Alexa, pause the vacuum."_
- _"Alexa, restart the vacuum."_
## Alexa Web-Based App
The following is a list of regions and the corresponding URL for the web-based Alexa app:
* United States: `https://alexa.amazon.com`
* United Kingdom: `https://alexa.amazon.co.uk`
* Germany: `https://alexa.amazon.de`
* Japan: `https://alexa.amazon.co.jp`
* Canada: `https://alexa.amazon.ca`
* Australia: `https://alexa.amazon.com.au`
* India: `https://alexa.amazon.in`
* Spain: `https://alexa.amazon.es`
- United States: `https://alexa.amazon.com`
- United Kingdom: `https://alexa.amazon.co.uk`
- Germany: `https://alexa.amazon.de`
- Japan: `https://alexa.amazon.co.jp`
- Canada: `https://alexa.amazon.ca`
- Australia: `https://alexa.amazon.com.au`
- India: `https://alexa.amazon.in`
- Spain: `https://alexa.amazon.es`
## Troubleshooting

61
source/_integrations/konnected.markdown
View File

@ -30,7 +30,7 @@ Konnected devices communicate with Home Assistant over your local LAN -- there i
</div>
### Configuration
## Configuration
A `konnected` section must be present in the `configuration.yaml` file that specifies the Konnected devices on the network and the sensors or actuators attached to them:
@ -69,7 +69,7 @@ devices:
type: list
keys:
id:
description: The MAC address of the NodeMCU WiFi module with colons/punctuation removed, for example `68c63a8bcd53`. You can usually find the mac address in your router's client list. Or, check the home-assistant.log for log messages from automatically discovered devices.
description: The MAC address of the NodeMCU Wi-Fi module with colons/punctuation removed, for example `68c63a8bcd53`. You can usually find the mac address in your router's client list. Or, check the home-assistant.log for log messages from automatically discovered devices.
required: true
type: string
binary_sensors:
@ -146,7 +146,7 @@ devices:
repeat:
description: Number of times to repeat a momentary pulse. Set to `-1` to make an infinite repeat. This is useful as an alarm or warning when used with a piezo buzzer.
required: false
host:
host:
type: string
required: false
description: Optionally specify the Konnected device's IP address or hostname to set up without discovery.
@ -167,12 +167,12 @@ devices:
{% endconfiguration%}
#### Configuration Notes
### Configuration Notes
- Either **pin** or **zone** is required for each actuator or sensor. Do not use both in the same definition.
- Pin `D8` or the `out` zone will only work when activation is set to high (the default).
### Extended Configuration
## Extended Configuration
```yaml
# Example configuration.yaml entry
@ -223,10 +223,9 @@ konnected:
- pin: 6
name: Kitchen
type: dht
```
### Unique IDs and the Entity Registry
## Unique IDs and the Entity Registry
Beginning in Home Assistant release 0.90, unique IDs are generated for each sensor or switch entity. This enables end users to modify the entity names and entity IDs through the Home Assistant UI on the _Entity Registry_ page (under _Configuration_).
@ -242,60 +241,60 @@ Unique IDs are internally generated as follows:
\* Switches are identified by a unique hash including the pin number, `momentary`, `pause`, and `repeat` values. If these values are modified, a new entity will be created and the old entity must be removed manually from the _Entity Registry_.
### Pin Mapping
## Pin Mapping
Konnected runs on an ESP8266 board with the NodeMCU firmware. It is commonly used with the NodeMCU dev kit WiFi module and optionally Konnected's Alarm Panel hardware. The following table shows the pin mapping between the Konnected hardware labeled zones, the NodeMCU labeled pins and the ESP8266 GPIO pins.
Konnected runs on an ESP8266 board with the NodeMCU firmware. It is commonly used with the NodeMCU dev kit Wi-Fi module and optionally Konnected's Alarm Panel hardware. The following table shows the pin mapping between the Konnected hardware labeled zones, the NodeMCU labeled pins and the ESP8266 GPIO pins.
| Konnected Alarm Panel Zone | NodeMCU pin | IO Index | ESP8266 GPIO |
|---|---|---|---|
| 1 | D1 | 1 | GPIO5 |
| 2 | D2 | 2 | GPIO4 |
| 3 | D5 | 5 | GPIO14 |
| 4 | D6 | 6 | GPIO12 |
| 5 | D7 | 7 | GPIO13 |
| 6 | RX | 9 | GPIO3 |
| ALARM or OUT | D8 | 8 | GPIO15 |
| Konnected Alarm Panel Zone | NodeMCU pin | IO Index | ESP8266 GPIO |
| -------------------------- | ----------- | -------- | ------------ |
| 1 | D1 | 1 | GPIO5 |
| 2 | D2 | 2 | GPIO4 |
| 3 | D5 | 5 | GPIO14 |
| 4 | D6 | 6 | GPIO12 |
| 5 | D7 | 7 | GPIO13 |
| 6 | RX | 9 | GPIO3 |
| ALARM or OUT | D8 | 8 | GPIO15 |
### Revision History
## Revision History
#### 0.91
### 0.91
- Improved Unique ID generation for Konnected switches
#### 0.90
### 0.90
- Added support for `dht` and `ds18b20` temperature sensors
- Added Unique IDs
#### 0.80
### 0.80
- Added ability to specify `host` and `port` to set up devices without relying on discovery.
- Added `discovery` and `blink` config options to enable/disable these features.
- Added `discovery` and `blink` configuration options to enable/disable these features.
#### 0.79
### 0.79
- Added `inverse` configuration option for binary sensors.
#### 0.77
### 0.77
- Added support for momentary and beep/blink switches. [[#15973](https://github.com/home-assistant/home-assistant/pull/15973)]
- Decouple entity initialization from discovery, enabling devices to recover faster after a Home Assistant reboot. [[#16146](https://github.com/home-assistant/home-assistant/pull/16146)]
- **Breaking change:** Device `id` in `configuration.yaml` must now be the full 12-character device MAC address. Previously, omitting the first 6 characters was allowed.
#### 0.72
### 0.72
- Adds `api_host` configuration option [[#14896](https://github.com/home-assistant/home-assistant/pull/14896)]
#### 0.70
### 0.70
- Initial release
### Binary Sensor
## Binary Sensor
The `konnected` binary sensor allows you to monitor wired door sensors, window sensors, motion sensors, smoke detectors, CO detectors, glass-break sensors, water leak sensors or any other simple wired open/close circuit attached to a NodeMCU ESP8266 WiFi module running the [open source Konnected software](https://github.com/konnected-io/konnected-security).
The `konnected` binary sensor allows you to monitor wired door sensors, window sensors, motion sensors, smoke detectors, CO detectors, glass-break sensors, water leak sensors or any other simple wired open/close circuit attached to a NodeMCU ESP8266 Wi-Fi module running the [open source Konnected software](https://github.com/konnected-io/konnected-security).
This integration supports all of the built-in device classes of the generic [Binary Sensor](/integrations/binary_sensor/) component.
### Switch
## Switch
The `konnected` switch platform allows you to actuate an alarm system siren, strobe light, buzzer or any other wired device using a [Konnected Alarm Panel board](https://konnected.io) or relay module and a NodeMCU ESP8266 WiFi module running the [open source Konnected software](https://github.com/konnected-io/konnected-security).
The `konnected` switch platform allows you to actuate an alarm system siren, strobe light, buzzer or any other wired device using a [Konnected Alarm Panel board](https://konnected.io) or relay module and a NodeMCU ESP8266 Wi-Fi module running the [open source Konnected software](https://github.com/konnected-io/konnected-security).

36
source/_integrations/life360.markdown
View File

@ -19,7 +19,7 @@ You must first [create a Life360 account](https://www.life360.com/websignup).
Then in the Home Assistant user interface (UI), click on Configuration in the left pane, then on Integrations and then on the yellow circle in the lower-right corner to "Set up a new integration." Scroll through the list and click on Life360. Enter your Life360 username and password and click SUBMIT. You can add as many Life360 accounts as you like.
If you would like to set any advanced options, see the following section. You may want to do this before entering your Life360 account information in the UI, or you can change it at any time. Any of the advanced options you want to set from the section below will need to be set manually in your configuration.yaml file. They are not able to be set from the UI. You can also enter your account information in the configuration file (in addition to, or instead of, the UI) if you prefer.
If you would like to set any advanced options, see the following section. You may want to do this before entering your Life360 account information in the UI, or you can change it at any time. Any of the advanced options you want to set from the section below will need to be set manually in your `configuration.yaml` file. They are not able to be set from the UI. You can also enter your account information in the configuration file (in addition to, or instead of, the UI) if you prefer.
After configuring, it is expected for the Life360 integration page to show "This integration has no devices". You should see a new Life360 device tracker entity showing up on the States page. If it does not:
@ -109,18 +109,18 @@ warning_threshold:
## Additional attributes
Attribute | Description
-|-
address | Address of the current location, or `none`.
at_loc_since | Date and time when first at current location (in UTC.)
battery_charging | Device is charging (`true`/`false`.)
driving | Device movement indicates driving (`true`/`false`.)
last_seen | Date and time when Life360 last updated device location (in UTC.)
moving | Device is moving (`true`/`false`.)
place | Name of Life360 Place where the device is located, or `none` if not located within one.
raw_speed | "Raw" speed value provided by Life360 server. (Units unknown.)
speed | Estimated speed of device (in MPH or KPH depending on Home Assistant's unit system configuration.)
wifi_on | Device WiFi is turned on (`true`/`false`.)
| Attribute | Description |
| ---------------- | -------------------------------------------------------------------------------------------------- |
| address | Address of the current location, or `none`. |
| at_loc_since | Date and time when first at current location (in UTC.) |
| battery_charging | Device is charging (`true`/`false`.) |
| driving | Device movement indicates driving (`true`/`false`.) |
| last_seen | Date and time when Life360 last updated device location (in UTC.) |
| moving | Device is moving (`true`/`false`.) |
| place | Name of Life360 Place where the device is located, or `none` if not located within one. |
| raw_speed | "Raw" speed value provided by Life360 server. (Units unknown.) |
| speed | Estimated speed of device (in MPH or KPH depending on Home Assistant's unit system configuration.) |
| wifi_on | Device Wi-Fi is turned on (`true`/`false`.) |
## Filtering
@ -142,7 +142,7 @@ Normally Home Assistant device trackers are "Home" when they enter `zone.home`.
## Home Assistant Zones & Life360 Places
See [Zone documentation](/integrations/zone/#home-zone) for details about how HA zones are defined. If you'd like to create HA zones from Life360 Places (e.g., to make HA's `zone.home` be identical to Life360's "Home Place"), make sure `logger` is set to `debug`. Then when HA starts the details of all the Places defined in the included Circles will be written to `home-assistant.log` in a format that can be copied into your configuration under `zone:`. E.g., you would see something like this:
See [Zone documentation](/integrations/zone/#home-zone) for details about how Home Assistant zones are defined. If you'd like to create Home Assistant zones from Life360 Places (e.g., to make Home Assistant's `zone.home` be identical to Life360's "Home Place"), make sure `logger` is set to `debug`. Then when Home Assistant starts the details of all the Places defined in the included Circles will be written to `home-assistant.log` in a format that can be copied into your configuration under `zone:`. E.g., you would see something like this:
```text
2019-05-31 12:16:58 DEBUG (SyncWorker_3) [homeassistant.components.life360.device_tracker] My Family Circle: will be included, id=xxxxx
@ -164,6 +164,7 @@ Therefore, an optional filtering mechanism has been implemented to prevent incon
### Typical configuration
{% raw %}
```yaml
life360:
# MPH, assuming imperial units.
@ -182,11 +183,13 @@ life360:
warning_threshold: 2
error_threshold: 3
```
{% endraw %}
### Circle and Member Filtering Example
{% raw %}
```yaml
life360:
# Only track Members that are in these Circles.
@ -196,22 +199,26 @@ life360:
members:
exclude: John Doe
```
{% endraw %}
### Entering accounts in configuration
{% raw %}
```yaml
life360:
accounts:
- username: LIFE360_USERNAME
password: LIFE360_PASSWORD
```
{% endraw %}
### Example overdue update automations
{% raw %}
```yaml
automation:
- alias: Life360 Overdue Update
@ -242,6 +249,7 @@ automation:
trigger.event.data.entity_id
}} restored after {{ trigger.event.data.wait }}.
```
{% endraw %}
## Disclaimer

2
source/_integrations/proxmoxve.markdown
View File

@ -120,7 +120,7 @@ Before creating the user, we need to create a permissions role for the user.
### Create Home Assistant User
Creating a dedicated user for home assistant limited to only the role just created is the most secure method. These instructions use the `pve` realm for the user. This allows a connection, but ensures that the user is not authenticated for SSH connections. If you use the `pve` realm, just be sure to add `realm: pve` to your config.
Creating a dedicated user for Home Assistant, limited to only the role just created is the most secure method. These instructions use the `pve` realm for the user. This allows a connection, but ensures that the user is not authenticated for SSH connections. If you use the `pve` realm, just be sure to add `realm: pve` to your config.
* Click `Datacenter`
* Open `Permissions` and click `Users`

170
source/_integrations/wink.markdown
View File

@ -52,7 +52,7 @@ Wink requests three pieces of information from the user when they sign up for a
2. `Website:` The external address of your Home Assistant instance. If not externally accessible you can use your email address.
3. `Redirect URI:` This should be `http://192.168.1.5:8123/auth/wink/callback` replacing the IP with the internal IP of your Home Assistant box.
No settings are required in the `configuration.yaml` other than `wink:`.
No settings are required in the `configuration.yaml` other than `wink:`.
After adding `wink:` to your `configuration.yaml` and restarting Home Assistant you will see a persistent notification on the frontend with a `CONFIGURE` button that will guide you through the setup via the frontend configurator.
@ -136,19 +136,19 @@ You can use the service wink/add_new_devices to pull any newly paired Wink devic
You can use the service wink/delete_wink_device to remove/unpair a device from Wink.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String that points at the `entity_id` of device to delete.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ---------------------------------------------------------- |
| `entity_id` | no | String that points at the `entity_id` of device to delete. |
## Service `pair_new_device`
You can use the service wink/pair_new_device to pair a new device to your Wink hub/relay
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `hub_name` | no | The name of the hub to pair a new device to.
| `pairing_mode` | no | One of the following [zigbee, zwave, zwave_exclusion, zwave_network_rediscovery, lutron, bluetooth, kidde]
| `kidde_radio_code` | conditional | A string of 8 1s and 0s one for each dip switch on the kidde device left --> right = 1 --> 8 (Required if pairing_mode = kidde)
| Service data attribute | Optional | Description |
| ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `hub_name` | no | The name of the hub to pair a new device to. |
| `pairing_mode` | no | One of the following [zigbee, zwave, zwave_exclusion, zwave_network_rediscovery, lutron, bluetooth, kidde] |
| `kidde_radio_code` | conditional | A string of 8 1s and 0s one for each dip switch on the kidde device left --> right = 1 --> 8 (Required if pairing_mode = kidde) |
<div class='note'>
Calling service wink/pull_newly_added_wink_devices after a device is paired will add that new device to Home Assistant. The device will also show up on the next restart of Home Assistant.
@ -158,10 +158,10 @@ Calling service wink/pull_newly_added_wink_devices after a device is paired will
You can use the service wink/rename_wink_device to change the name of a device.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String that points at the `entity_id` of device to rename.
| `name` | no | The name to change it to.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ---------------------------------------------------------- |
| `entity_id` | no | String that points at the `entity_id` of device to rename. |
| `name` | no | The name to change it to. |
<div class='note'>
Home Assistant entity_ids for Wink devices are based on the Wink device's name. Calling this service will not change the entity_id of the device until Home Assistant is restarted.
@ -181,10 +181,10 @@ The Wink hub, by default, can only be accessed via the cloud. This means it requ
You can use the service wink/set_siren_auto_shutoff to set how long the siren will sound before shutting off.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `auto_shutoff` | no | Int. One of [None, -1, 30, 60, 120] (None and -1 are forever. Use None for gocontrol, and -1 for Dome)
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `auto_shutoff` | no | Int. One of [None, -1, 30, 60, 120] (None and -1 are forever. Use None for gocontrol, and -1 for Dome) |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren. |
Example:
@ -205,10 +205,10 @@ The following services only work with the Dome siren/chime.
You can use the service wink/set_chime_volume to set the volume for the chime on your Dome siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `volume` | no | String. One of ["low", "medium", "high"]
| `entity_id` | yes | String or list of strings that point at `entity_id`s of the siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ------------------------------------------------------------------------ |
| `volume` | no | String. One of ["low", "medium", "high"] |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of the siren/chime. |
Example:
@ -225,10 +225,10 @@ script:
You can use the service wink/set_chime_volume to set the volume for the chime on your Dome siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `volume` | no | String. One of ["low", "medium", "high"]
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------------------------- |
| `volume` | no | String. One of ["low", "medium", "high"] |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. |
Example:
@ -245,10 +245,10 @@ script:
You can use the service wink/enable_chime to set the tone and enable the chime on your Dome siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `tone` | no | String. One of ["doorbell", "fur_elise", "doorbell_extended", "alert", "william_tell", "rondo_alla_turca", "police_siren", "evacuation", "beep_beep", "beep", "inactive"]
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tone` | no | String. One of ["doorbell", "fur_elise", "doorbell_extended", "alert", "william_tell", "rondo_alla_turca", "police_siren", "evacuation", "beep_beep", "beep", "inactive"] |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. |
Example:
@ -265,10 +265,10 @@ script:
You can use the service wink/set_siren_tone to set the tone on your Dome siren. This tone will be used the next time the siren is executed.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `tone` | no | String. One of ["doorbell", "fur_elise", "doorbell_extended", "alert", "william_tell", "rondo_alla_turca", "police_siren", "evacuation", "beep_beep", "beep"]
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tone` | no | String. One of ["doorbell", "fur_elise", "doorbell_extended", "alert", "william_tell", "rondo_alla_turca", "police_siren", "evacuation", "beep_beep", "beep"] |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. |
Example:
@ -285,10 +285,10 @@ script:
You can use the service wink/set_siren_strobe_enabled to enable or disable the strobe when the siren is executed.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `enabled` | no | Boolean. True or False.
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------------------------- |
| `enabled` | no | Boolean. True or False. |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of siren/chime. |
Example:
@ -305,10 +305,10 @@ script:
You can use the service wink/set_chime_strobe_enabled to enable or disable the strobe when the chime is executed.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `enabled` | no | Boolean. True or False.
| `entity_id` | yes | String or list of strings that point at `entity_id`s of chime/chime.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------------------------- |
| `enabled` | no | Boolean. True or False. |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of chime/chime. |
Example:
@ -325,11 +325,11 @@ script:
You can use the service wink/set_nimbus_dial_state to update an individual dial's value/position and its labels
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of chime/chime.
| `value` | no | A number, should be between the dials min and max value (See set_nimbus_dial_configuration below)
| `labels` | yes | A list of strings the first being the value set on the dial's face and the second being the value on the dial face when the Nimbus is pressed
| Service data attribute | Optional | Description |
| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of chime/chime. |
| `value` | no | A number, should be between the dials min and max value (See set_nimbus_dial_configuration below) |
| `labels` | yes | A list of strings the first being the value set on the dial's face and the second being the value on the dial face when the Nimbus is pressed |
Example:
@ -350,16 +350,16 @@ script:
You can use the service wink/set_nimbus_dial_configuration to update an individual dial's configuration.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of chime/chime.
| `rotation` | yes | One of "cw" or "ccw" the direction the dial hand should rotate.
| `ticks` | yes | A positive number, the number of times the hand should move.
| `scale` | yes | One of "linear" or "log" How the dial should move in response to higher values.
| `min_value` | yes | A number, the minimum value that the dial can have.
| `max_value` | yes | A number, the maximum value that the dial can have.
| `min_position` | yes | A number generally [0-360], the minimum position for the dial's hand.
| `max_value` | yes | A number generally [0-360], the maximum position for the dial's hand.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ------------------------------------------------------------------------------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of chime/chime. |
| `rotation` | yes | One of "cw" or "ccw" the direction the dial hand should rotate. |
| `ticks` | yes | A positive number, the number of times the hand should move. |
| `scale` | yes | One of "linear" or "log" How the dial should move in response to higher values. |
| `min_value` | yes | A number, the minimum value that the dial can have. |
| `max_value` | yes | A number, the maximum value that the dial can have. |
| `min_position` | yes | A number generally [0-360], the minimum position for the dial's hand. |
| `max_value` | yes | A number generally [0-360], the maximum position for the dial's hand. |
Example:
@ -400,7 +400,7 @@ The requirement is that you have setup [Wink](/integrations/wink/) from above.
- Motion sensors
- Ring Door bells (No hub required)
- Liquid presence sensors
- Z-wave lock key codes
- Z-Wave lock key codes
- Lutron connected bulb remote buttons
- Wink Relay buttons and presence detection
- Wink spotter loudness and vibration (No Wink hub required)
@ -474,7 +474,7 @@ The requirement is that you have setup [Wink](/integrations/wink/) from above.
### Supported light devices
- Z-wave switches with dimming
- Z-Wave switches with dimming
- Hue
- Lightify
- GE link
@ -495,7 +495,7 @@ The requirement is that you have setup [Wink](/integrations/wink/) from above.
- Kwikset
- Schlage
- August (No Wink hub required) (August Connect required)
- Generic Z-wave
- Generic Z-Wave
<div class='note'>
The following services have only been confirmed on Schlage locks.
@ -505,10 +505,10 @@ The following services have only been confirmed on Schlage locks.
You can use the service wink/set_lock_alarm_mode to set the alarm mode of your lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `mode` | no | String one of tamper, activity, or forced_entry
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------------------- |
| `mode` | no | String one of tamper, activity, or forced_entry |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. |
Example:
@ -525,10 +525,10 @@ script:
You can use the service wink/set_lock_alarm_sensitivity to set the alarm sensitivity of your lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `sensitivity` | no | String one of low, medium_low, medium, medium_high, high.
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------------------- |
| `sensitivity` | no | String one of low, medium_low, medium, medium_high, high. |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. |
Example:
@ -545,10 +545,10 @@ script:
You can use the service wink/set_lock_alarm_state to set the alarm state of your lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `enabled` | no | Boolean enabled or disabled, true or false
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------------------- |
| `enabled` | no | Boolean enabled or disabled, true or false | | |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. | | |
Example:
@ -565,10 +565,10 @@ script:
You can use the service wink/set_lock_beeper_state to set the beeper state of your lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `enabled` | no | Boolean enabled or disabled, true or false
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------------------- |
| `enabled` | no | Boolean enabled or disabled, true or false | |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. | |
Example:
@ -585,10 +585,10 @@ script:
You can use the service wink/set_lock_vacation_mode to set the vacation mode of your lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `enabled` | no | Boolean enabled or disabled, true or false
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------------------- |
| `enabled` | no | Boolean enabled or disabled, true or false |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of locks. |
Example:
@ -605,11 +605,11 @@ script:
You can use the service wink/add_new_lock_key_code to add a new user code to your Wink lock.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of locks.
| `name` | no | the name of the new key code
| `code` | no | The new code. Must match length of existing codes.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | -------------------------------------------------------------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of locks. |
| `name` | no | the name of the new key code |
| `code` | no | The new code. Must match length of existing codes. |
<div class='note'>
Calling service wink/pull_newly_added_wink_devices will add the new key code to Home Assistant. The device will also show up on the next restart of Home Assistant.
@ -648,7 +648,7 @@ The requirement is that you have set up [Wink](/integrations/wink/) from above.
## Supported switch devices
- Wink Pivot power genius (No Wink hub required)
- non-dimming Z-wave in-wall switches (dimming switches show up as lights)
- non-dimming Z-Wave in-wall switches (dimming switches show up as lights)
- Wink Relay load controlling switches
- Rachio sprinkler controller (No Wink hub required)
- iHome smart plug (No Wink hub required)

14
source/_integrations/yeelight.markdown
View File

@ -11,16 +11,16 @@ ha_codeowners:
- '@zewelor'
---
The `yeelight` integration allows you to control your Yeelight Wifi bulbs with Home Assistant. There are two possible methods for configuration of the Yeelight: Manual or Automatic.
The `yeelight` integration allows you to control your Yeelight Wi-Fi bulbs with Home Assistant. There are two possible methods for configuration of the Yeelight: Manual or Automatic.
There is currently support for the following device types within Home Assistant:
- **Light** - The yeelight platform for supporting lights.
- **Sensor** - The yeelight platform for supporting sensors. Currently only nightlight mode sensor, for ceiling lights.
- **Light** - The Yeelight platform for supporting lights.
- **Sensor** - The Yeelight platform for supporting sensors. Currently only nightlight mode sensor, for ceiling lights.
## Example configuration (Automatic)
After the lights are connected to the WiFi network and have been detected in Home Assistant, the discovered names will be shown in the `Light` section of the `Overview` view. Add the following lines to your `customize.yaml` file:
After the lights are connected to the Wi-Fi network and have been detected in Home Assistant, the discovered names will be shown in the `Light` section of the `Overview` view. Add the following lines to your `customize.yaml` file:
```yaml
# Example customize.yaml entry
@ -139,10 +139,10 @@ This integration is tested to work with the following models. If you have a diff
| `color2` | YLDP06YL | LED Bulb (Color) - 2nd generation |
| `strip1` | YLDD01YL | Lightstrip (Color) |
| `strip1` | YLDD02YL | Lightstrip (Color) |
| ? | YLDD04YL | Lightstrip (Color)
| `bslamp1` | MJCTD01YL | Xiaomi Mijia Bedside Lamp - WIFI Version! |
| ? | YLDD04YL | Lightstrip (Color) |
| `bslamp1` | MJCTD01YL | Xiaomi Mijia Bedside Lamp - Wi-Fi Version! |
| `bslamp1` | MJCTD02YL | Xiaomi Mijia Bedside Lamp II |
| `RGBW` | MJDP02YL | Mi Led smart Lamp - white and color WIFI Version |
| `RGBW` | MJDP02YL | Mi Led smart Lamp - white and color Wi-Fi Version|
| `lamp1` | MJTD01YL | Xiaomi Mijia Smart LED Desk Lamp (autodiscovery isn't possible because the device doesn't support mDNS due to the small amount of RAM) |
| `ceiling1` | YLXD01YL | Yeelight Ceiling Light |
| `ceiling2` | YLXD03YL | Yeelight Ceiling Light - Youth Version |

4
source/_lovelace/conditional.markdown
View File

@ -18,7 +18,7 @@ conditions:
keys:
entity:
required: true
description: HA entity ID.
description: Home Assistant entity ID.
type: string
state:
required: false
@ -38,7 +38,7 @@ card:
Note: Conditions with more than one entity are treated as an 'and' condition. This means that for the card to show, *all* entities must meet the state requirements set.
### Examples
## Examples
```yaml
type: conditional

4
source/_lovelace/entities.markdown
View File

@ -258,13 +258,13 @@ type:
type: string
url:
required: true
description: "Website URL (or internal URL e.g. `/hassio/dashboard` or `/panel_custom_name`)"
description: "Website URL (or internal URL e.g., `/hassio/dashboard` or `/panel_custom_name`)"
type: string
name:
required: false
description: Link label
type: string
default: url path
default: URL path
icon:
required: false
description: "Icon to display (e.g., `mdi:home`)"

2
source/_lovelace/entity-button.markdown
View File

@ -47,7 +47,7 @@ show_icon:
default: "true"
icon_height:
required: false
description: Set the height for the icon. This is in pixels which is handled by the config ui. (Advanced users can use other CSS values if they like)
description: Set the height for the icon. This is in pixels which is handled by the configuration UI. (Advanced users can use other CSS values if they like)
type: string
default: auto
tap_action:

2
source/_lovelace/history-graph.markdown
View File

@ -4,7 +4,7 @@ sidebar_label: History Graph
description: "History graph is a basic card, allowing you to display a graph for each of the entities in the list specified as config."
---
History graph is a basic card, allowing you to display a graph for each of the entities in the list specified as config.
History graph is a basic card, allowing you to display a graph for each of the entities in the list specified configuration.
<p class='img'>
<img src='/images/lovelace/lovelace_history_graph.png' alt='Screenshot of the history graph card for entities without a unit_of_measurement'>

8
source/_lovelace/markdown.markdown
View File

@ -7,7 +7,6 @@ description: "Markdown card is used to render markdown"
Markdown card is used to render [Markdown](https://commonmark.org/help/).
The renderer uses [Marked.js](https://marked.js.org), which supports [several specifications of Markdown](https://marked.js.org/#/README.md#specifications), including CommonMark, GitHub Flavored Markdown (GFM) and `markdown.pl`.
<p class='img'>
<img src='/images/lovelace/lovelace_markdown.png' alt='Screenshot of the markdown card'>
@ -32,7 +31,7 @@ card_size:
required: false
type: integer
default: none
description: The algorithm for placing cards aesthetically in lovelace may have problems with the markdown card if it contains templates. You can use this value to help it estimate the height of the card in units of 50 pixels (approximately 3 lines of text in default size). (e.g., `4`)
description: The algorithm for placing cards aesthetically in Lovelace may have problems with the markdown card if it contains templates. You can use this value to help it estimate the height of the card in units of 50 pixels (approximately 3 lines of text in default size). (e.g., `4`)
entity_id:
required: false
type: [string, list]
@ -58,8 +57,10 @@ content: >
A special template variable - `config` is set up for the `content` of the card. It contains the configuration of the card.
E.g.
For example:
{% raw %}
```yaml
type: entity-filter
entities:
@ -78,4 +79,5 @@ card:
And the door is {% if is_state('binary_sensor.door', 'on') %} open {% else %} closed {% endif %}.
```
{% endraw %}

2
source/_lovelace/picture-elements.markdown
View File

@ -765,7 +765,7 @@ conditions:
keys:
entity:
required: true
description: HA entity ID.
description: Home Assistant entity ID.
type: string
state:
required: false