+ This is not required on HassOS based Hass.io installs and should not be installed +
+ Supported platforms: Raspberry Pi 3. diff --git a/source/_addons/cec_scan.markdown b/source/_addons/cec_scan.markdown index 4c048eff157..a17d0ff09db 100644 --- a/source/_addons/cec_scan.markdown +++ b/source/_addons/cec_scan.markdown @@ -9,4 +9,4 @@ sharing: true footer: true --- -Help you to discover the HDMI CEC address. Start the add-on and look into log to see all connected device on HDMI. +Help you to discover the HDMI CEC address. Start the add-on and look into the log to see all connected device on HDMI. diff --git a/source/_addons/check_config.markdown b/source/_addons/check_config.markdown index 0b00f1b147e..f10f69848fe 100644 --- a/source/_addons/check_config.markdown +++ b/source/_addons/check_config.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -You can use this addon to check whether your configuration files are valid against the new version of Home Assistant before you actually update your Home Assistant installation. This will help you avoid errors due to breaking changes, resulting in an smooth update. +You can use this addon to check whether your configuration files are valid against the new version of Home Assistant before you actually update your Home Assistant installation. This addon will help you avoid errors due to breaking changes, resulting in a smooth update. ```json { diff --git a/source/_addons/configurator.markdown b/source/_addons/configurator.markdown index 97640ebe203..b5956384ba9 100644 --- a/source/_addons/configurator.markdown +++ b/source/_addons/configurator.markdown @@ -2,7 +2,7 @@ layout: page title: "HASS Configurator" description: "Browser-based configuration file editor for Home Assistant." -date: 2017-09-25 14:00 +date: 2018-07-16 14:00 sidebar: true comments: false sharing: true @@ -11,11 +11,9 @@ featured: true og_image: /images/hassio/screenshots/addon-hass-configurator.png --- -As long as a fully featured configuration GUI for Home Assistant is still under development, you can use this add-on to add a browser based file-editor to your Hass.IO installation. By default it will listen on port `3218` of the host Hass.IO is running on. +You can use this add-on to add a browser-based file editor to your Hass.io installation. By default it will listen on port `3218` of the host Hass.io is running on. -More information and a standalone version for regular Home Assistant installations can be found in the [GitHub repository][code]. - -[code]: https://github.com/danielperna84/hass-configurator +More information and a standalone version for regular Home Assistant installations can be found in the [GitHub repository](https://github.com/danielperna84/hass-configurator).
@@ -24,16 +22,17 @@ Screenshot of the HASS Configurator.
### {% linkable_title Feature list %}
-- Web-Based editor to modify your files with syntax highlighting.
+- Web-based editor to modify your files with syntax highlighting and YAML linting.
- Upload and download files.
-- Stage and commit changes in Git repositories, create and switch between branches, push to remotes.
-- Lists of available triggers, events, entities, conditions and services. Selected element gets inserted into the editor at the last cursor position.
-- Restart Home Assistant directly with the click of a button. Reloading groups, automations etc. can be done as well. An API-password is required.
-- SSL support.
+- Stage, stash and commit changes in Git repositories, create and switch between branches, push to remotes, view diffs.
+- Lists with available entities, triggers, events, conditions and services.
+- Restart Home Assistant directly with the click of a button. Reloading groups, automations, etc. can be done as well. An API password is required.
+- SSL/TLS support.
- Optional authentication and IP filtering for added security.
- Direct links to Home Assistant documentation and icons.
- Execute shell commands within the add-on container.
- Editor settings are saved in your browser.
+- And much more...
### {% linkable_title Add-on Configuration %}
@@ -41,29 +40,52 @@ Screenshot of the HASS Configurator.
{
"username": "admin",
"password": "secret",
+ "ssl": false,
"certfile": "fullchain.pem",
"keyfile": "privkey.pem",
- "ssl": false,
- "allowed_networks": ["192.168.0.0/16"],
- "banned_ips": ["8.8.8.8"],
+ "verify_hostname": false,
+ "allowed_networks": [
+ "192.168.0.0/16",
+ "172.30.0.0/16"
+ ],
+ "banned_ips": [
+ "8.8.8.8"
+ ],
"banlimit": 0,
- "ignore_pattern": ["__pycache__"],
+ "ignore_pattern": [
+ "__pycache__"
+ ],
"dirsfirst": false,
+ "enforce_basepath": false,
+ "notify_service": "persistent_notification.create",
+ "ignore_ssl": false
}
```
-- **username** (*Optional*): Set a username to access your configuration is protected.
+- **username** (*Required*): Set a username to access your configuration is protected.
- **password** (*Required*): Set a password for access.
-- **ssl** (*Optional*): Enable or Disable SSL for the editor.
-- **allowed_networks** (*Optional*): Limit access to the configurator by adding allowed IP addresses / networks to the list.
-- **banned_ips** (*Optional*): List of statically banned IP addresses.
-- **banlimit** (*Optional*): Ban access from IPs after `banlimit` failed login attempts. The default value `0` disables this feature. Restart the add-on to clear the list of banned IP addresses.
-- **ignore_pattern** (*Optional*): Files and folders to ignore in the UI.
-- **dirsfirst** (*Optional*): List directories before files in the filebrowser.
+- **ssl** (*Required*): Enable or Disable SSL/TLS for the editor.
+- **certfile** (*Required*): Set the path the your SSL certificate if the ssl-option is set to `true`.
+- **keyfile** (*Required*): Set the path the your SSL private key if the ssl-option is set to `true`.
+- **allowed_networks** (*Required*): Limit access to the configurator by adding allowed IP addresses/networks to the list.
+- **banned_ips** (*Required*): List of statically banned IP addresses.
+- **banlimit** (*Required*): Ban access from IPs after `banlimit` failed login attempts. The default value `0` disables this feature. Restart the add-on to clear the list of banned IP addresses.
+- **ignore_pattern** (*Required*): Files and folders to ignore in the UI.
+- **dirsfirst** (*Required*): List directories before files in the file browser.
+- **enforce_basepath** (*Required*): If set to `true`, access is limited to files within the `/config` directory.
+- **notify_service** (*Required*): Specify a custom notify-service to be used to push notifications.
+- **ignore_ssl** (*Required*): Ignore SSL errors when accessing the Home Assistant API.
+- **sesame** (*Optional*): Secret token to dynamically allow access from the IP the request originates from. Open your bookmark https://hassio.yourdomain.com:8123/somesecretnobodycanguess while `allowed_networks` is set to `[]` and your IP will get whitelisted. You can use the _Network status_ menu to revoke IP addresses for which access has been granted. Regular authentication is still required.
+- **sesame_totp_secret** (*Optional*): Like the `sesame` option, but instead as Base32 encoded secret string must be provided. This string then can be added to a TOTP App like Google Authenticator. This way you get a 6-digit `sesame` that changes every 30 seconds.
+- **loglevel** (*Optional*): You can change the logging level from the default value `info` if you want to. Valid values are: `debug`, `info`, `warning`, `error`, `critical`.
-### {% linkable_title Embedding into Home-Assistant %}
+
+Be careful when setting up port forwarding to the configurator while embedding into Home Assistant. If you don't restrict access by requiring authentication and/or blocking based on client IP addresses, your configuration will be exposed to the internet! +
-Using the Home Assistant component [panel_iframe](https://home-assistant.io/components/panel_iframe/) it is possible to embed the configurator directly into Home Assistant, allowing you to modify your configuration within the Home Assistant frontend. +### {% linkable_title Embedding into Home Assistant %} + +Using the Home Assistant component [panel_iframe](/components/panel_iframe/) it is possible to embed the configurator directly into Home Assistant, allowing you to modify your configuration from within the Home Assistant frontend. An example configuration would look like this: @@ -75,6 +97,3 @@ panel_iframe: url: http://hassio.local:3218 ``` --Be careful when setting up port forwarding to the configurator while embedding into Home Assistant. If you don't restrict access by requiring authentication and / or blocking based on client IP addresses, your configuration will be exposed to the internet! -
diff --git a/source/_addons/dhcp_server.markdown b/source/_addons/dhcp_server.markdown index 884a5432fac..1f0df69183c 100644 --- a/source/_addons/dhcp_server.markdown +++ b/source/_addons/dhcp_server.markdown @@ -47,7 +47,7 @@ Configuration variables: - **range_end** (*Required*): End address for dhcp leases. - **broadcast** (*Required*): Network broadcast address. - **gateway** (*Required*): A List of gateways. - - **interface** (*Required*): Inteface on that will be listen. Normally is `eth0` for ethernet wired connection and `wlan0` for wireless connection. + - **interface** (*Required*): Interface on that will be listen. Normally is `eth0` for ethernet wired connection and `wlan0` for wireless connection. - **hosts** (*Optional*): A list of fixed IPs for devices. - **name** (*Required*): Name/hostname of your device. - **mac** (*Required*): Mac address of your device. diff --git a/source/_addons/dnsmasq.markdown b/source/_addons/dnsmasq.markdown index 586a035f8f5..d894320ab02 100644 --- a/source/_addons/dnsmasq.markdown +++ b/source/_addons/dnsmasq.markdown @@ -11,10 +11,6 @@ footer: true Setup and manage a [Dnsmasq](http://thekelleys.org.uk/dnsmasq/doc.html) DNS server. This allows you to manipulate DNS requests. For example, you can have your Home Assistant domain resolve with an internal address inside your network. --`interface` options are for resinos based installation. On other system you can set it to `""`, for listen on every interface. -
- ```json { "defaults": ["8.8.8.8", "8.8.4.4"], @@ -23,14 +19,12 @@ Setup and manage a [Dnsmasq](http://thekelleys.org.uk/dnsmasq/doc.html) DNS serv ], "hosts": [ {"host": "home.mydomain.io", "ip": "192.168.1.10"} - ], - "interface": "eth1" + ] } ``` Configuration variables: -- **defaults** (*Required*): A list of dns server to forward default requests. +- **defaults** (*Required*): A list of DNS servers to forward default requests to. - **forwards** (*Optional*): A list of domains that will forward to a specific server. -- **hosts** (*Optional*): A list of hosts to resolve it static. -- **interface** (*Optional*): If a interface is set, it listen only on this interface. Need to set for resinos. Normally is `eth0` for ethernet wired connection and `wlan0` for wireless connection. +- **hosts** (*Optional*): A list of hosts to resolve statically. diff --git a/source/_addons/duckdns.markdown b/source/_addons/duckdns.markdown index f54e69f0da0..2f910f75b06 100644 --- a/source/_addons/duckdns.markdown +++ b/source/_addons/duckdns.markdown @@ -10,26 +10,27 @@ footer: true featured: true --- -[Duck DNS](https://duckdns.org/) is a free service which will point a DNS (sub domains of duckdns.org) to an IP of your choice. This add-on includes support for Let's Encrypt and will automatically create and renew your certificates. +[Duck DNS](https://www.duckdns.org/) is a free service which will point a DNS (sub domains of duckdns.org) to an IP of your choice. This add-on includes support for Let's Encrypt and will automatically create and renew your certificates. ```json { "lets_encrypt": { - "accept_terms": true + "accept_terms": true, + "certfile": "fullchain.pem", + "keyfile": "privkey.pem" }, "token": "sdfj-2131023-dslfjsd-12321", - "domains": ["my-domain.duckdns.org"] + "domains": ["my-domain.duckdns.org"], + "seconds": 300 } ``` Configuration variables: +- **lets_encrypt.accept_terms** (*Required*): If you accept the [Let's Encrypt Subscriber Agreement](https://letsencrypt.org/repository/), it will generate and update Let's Encrypt certificates for your DuckDNS domain. - **token** (*Required*): Your Duck DNS API key. - **domains** (*Required*): A list of domains to update DNS. -- **seconds** (*Optional*): Seconds between updates to Duck DNS. -- **lets_encrypt.accept_terms** (*Optional*): If you accept the [Let's Encrypt Subscriber Agreement][le], it will generate & update Let's Enrypt certificates for your DuckDNS domain. - -[le]: https://letsencrypt.org/repository/ +- **seconds** (*Required*): Seconds between updates to Duck DNS. ## {% linkable_title Home Assistant configuration %} @@ -42,8 +43,12 @@ http: ssl_key: /ssl/privkey.pem ``` -If you use a other port as `8123` or a SSL proxy, change the port number. +If you use a port other than `8123` or an SSL proxy, change the port number accordingly. ## {% linkable_title Router configuration %} -You'll need to forward the port you listed in your configuration (8123 in the example above) on your router to your Home Assistant system. You can find guides on how to do this on [Port Forward](https://portforward.com/) - noting that you'll only need to forward the TCP port. +You'll need to forward the port you listed in your configuration (8123 in the example above) on your router to your Home Assistant system. You can find guides on how to do this on [Port Forward](https://portforward.com/). Noting that you'll only need to forward the TCP port. + +Ensure that you allocate the Home Assistant system a fixed IP on your network before you configure port forwarding. You can do this either on the computer itself (see the [install guide](/hassio/installation/) or via a static lease on your router. + +Restart Home Assistant for the configured changes to take effect. When you access the Home Assistant frontend you will now need to use `https`, even when accessing local instances, for example at `https://192.168.0.1:8123`. diff --git a/source/_addons/git_pull.markdown b/source/_addons/git_pull.markdown index 126fab9c1a5..a316149cae4 100644 --- a/source/_addons/git_pull.markdown +++ b/source/_addons/git_pull.markdown @@ -1,6 +1,6 @@ --- layout: page -title: "GIT pull" +title: "Git pull" description: "Load and update configuration files for Home Assistant from a GIT repository." date: 2017-09-25 14:00 sidebar: true @@ -13,8 +13,11 @@ Load and update configuration files for Home Assistant from a GIT repository. ```json { - "repository": "https://example.com/my_configs", + "repository": "https://example.com/my_configs.git", "auto_restart": false, + "git_branch": "master", + "git_command": "pull", + "git_remote": "origin", "repeat": { "active": false, "interval": 300 @@ -32,10 +35,23 @@ Load and update configuration files for Home Assistant from a GIT repository. } ``` -- **repository** (*Required*): GIT url to your repository. -- **auto_restart** (*Optional*): Make a restart of Home-Assistant if the config have change and is valid. -- **repeat/active** (*Optional*): Pull periodic for GIT updates. +- **repository** (*Required*): Git URL to your repository (make sure to use double quotes). You have to add .git to your GitHub repository URL (see example config) +- **git_branch** (*Required*): Branch name of the git repo, leave this as 'master' if you are unsure. +- **git_remote** (*Required*): Name of the tracked repository, leave this as 'origin' if you are unsure. +- **git_command** (*Required*): Must be either 'pull' or 'reset', leave this as 'pull' if you are unsure. + + * **pull**: Incorporates changes from a remote repository into the current branch. Will preserve any local changes to tracked files. + * **reset**: Will execute ```git reset --hard``` and overwrite any local changes to tracked files and update from the remote repository. + ++ Using the reset option will overwrite changes to tracked files. Tracked files are those visible in the Github repository or those given by the output on this command: ```git ls-tree -r master --name-only``` +
+ +- **auto_restart** (*Optional*): Restart Home Assistant when the configuration has changed (and is valid). +- **repeat/active** (*Optional*): Pull periodic for git updates. - **repeat/interval** (*Optional*): Pull all x seconds and look for changes. +- **deployment_user** (*Optional*): Username to use when authenticating to a repo with a username and password. +- **deployment_password** (*Optional*): Password to use when authenticating to a repo. Ignored if deployment_user is not set. - **deployment_key** (*Optional*): A private SSH key that will be used for communication during git operations. This key is mandatory for ssh-accessed repositories, which are the ones with the following pattern: `You should only use this add-on if you do not have an existing configuration or if your existing configuration is already in a git repository. If the script does not find the necessary git files in your configuration folder, it will delete anything that might be there. Please ensure that there is a `.git` folder before using this. You can verify this by listing the items in the configuration folder including hidden files. The command is `ls -a /config`.
diff --git a/source/_addons/google_assistant.markdown b/source/_addons/google_assistant.markdown index 04458c65944..40923fdb19d 100644 --- a/source/_addons/google_assistant.markdown +++ b/source/_addons/google_assistant.markdown @@ -10,13 +10,21 @@ footer: true featured: true --- -[Google Assistant][GoogleAssistant] is an AI-powered voice assistant that runs on the Raspberry Pi and x86 platforms and interact over [api.ai] with Home-Assistant. You can also use [Google Actions][GoogleActions] to extend its functionality. ++ These instructions are outdated - the add-on has been updated and these are no longer accurate or complete +
+ ++ If you want to integrate your Google Home, or mobile phone running Google Assistant, with Home Assistant, then you want the [Google Assistant component](/components/google_assistant/). +
+ +[Google Assistant][GoogleAssistant] is an AI-powered voice assistant that runs on the Raspberry Pi and x86 platforms and interact via the [DialogFlow][comp] integration with Home-Assistant. You can also use [Google Actions][GoogleActions] to extend its functionality. To enable access to the Google Assistant API, do the following: 1. In the [Cloud Platform Console][project], go to the Projects page. Select an existing project or create a new project -2. Open the project. In the top of the page search for Google Assistant API or use [this link][API] and enable it. -3. Create an [OAuth Client ID][oauthclient], pick type "Other", click "Create" and download the JSON file by clicking the Download JSON button on the right side. +1. Open the project. In the top of the page search for Google Assistant API or use [this link][API] and enable it. +1. Create an [OAuth Client ID][oauthclient], pick type "Other", click "Create" and download the JSON file by clicking the Download JSON button on the right side. Now install and activate the [Samba] add-on so you can upload your credential file. Connect to the "share" Samba share and copy your credentials over. Name the file `google_assistant.json`. @@ -48,9 +56,9 @@ Find the microphone and speakers that you want to use and note down their device The next step is to authenticate your Google account with Google Assistant. Start the add-on and click on the "OPEN WEB UI" button to start authentication. -### Add-On configuration +### Add-on configuration -Configuration example that uses the USB microphone and use the built-in headset audio output on the Raspberry Pi. Note that card and device numbers can differ on your device. +Configuration example that uses the USB microphone and the built-in headset audio output on the Raspberry Pi. Note that card and device numbers can differ on your device. ```json { @@ -62,19 +70,17 @@ Configuration example that uses the USB microphone and use the built-in headset Configuration variables: -- **mic**: This is the hardware address of your microphone. Look at the add-on output +- **mic**: This is the hardware address of your microphone. Look at the add-on output - **speaker**: This is the hardware address of your speakers. Look at the add-on output ### {% linkable_title Home Assistant configuration %} -Use the Home Assistant [api.ai component][comp] to integrate the add-on into Home Assistant. - +Use the Home Assistant [DialogFlow component][comp] to integrate the add-on into Home Assistant. [GoogleAssistant]: https://assistant.google.com/ [GoogleActions]: https://actions.google.com/ -[api.ai]: https://api.ai/ [Samba]: /addons/samba/ -[comp]: /components/apiai/ +[comp]: /components/dialogflow/ [project]: https://console.cloud.google.com/project [API]: https://console.developers.google.com/apis/api/embeddedassistant.googleapis.com/overview [oauthclient]: https://console.developers.google.com/apis/credentials/oauthclient diff --git a/source/_addons/homematic.markdown b/source/_addons/homematic.markdown new file mode 100644 index 00000000000..6a92bbff817 --- /dev/null +++ b/source/_addons/homematic.markdown @@ -0,0 +1,70 @@ +--- +layout: page +title: "HomeMatic" +description: "HomeMatic hardware support to turn you Home-Assistant into a CCU." +date: 2017-04-30 13:28 +sidebar: true +comments: false +sharing: true +footer: true +--- + +Set up a [HomeMatic](https://github.com/eq-3/occu) hardware layer. At the moment we don't support hmIP, but that is in progress. For learning and handling devices use our internal HomeMatic panel and services (in progress) or use [Homematic-Manager](https://github.com/hobbyquaker/homematic-manager) > 2.0. + +The logic layer will be Home-Assistant. There is no ReGa or other logic layer installed. You can't import an existing configuration, you'll need re-learn it into Home-Assistant. + +Follow devices will be supported and tested: +- [HM-MOD-RPI-PCB](https://www.elv.ch/homematic-funkmodul-fuer-raspberry-pi-bausatz.html) + +```json +{ + "rf_enable": true, + "rf": [ + { + "type": "CCU2", + "device": "/dev/ttyAMA0" + } + ], + "wired_enable": false, + "wired": [ + { + "serial": "xy", + "key": "abc", + "ip": "192.168.0.0" + } + ] +} +``` + +Configuration variables: + +- **rf_enable** (*Require*): Boolean. Enable or disable BidCoS-RF. +- **wired_enable** (*Require*): Boolean. Enable or disable BidCoS-Wired. + +For RF devices +- **type** (*Require*): Device type for RFD service. Look into the manual of your device. +- **device** (*Require*): Device on the host. + +For RF devices +- **serial** (*Require*): Serial number of the device. +- **key** (*Require*): Encrypted key. +- **ip** (*Require*): IP address of LAN gateway. + +## {% linkable_title Home Assistant configuration %} + +Use the following configuration in Home Assistant to use it: + +```yaml +homematic: + interfaces: + rf: + host: core-homematic + port: 2001 +``` + +## {% linkable_title Raspberry Pi3 %} + +With HM-MOD-PRI-PCB you need to add follow into your `config.txt` on boot partition: +``` +dtoverlay=pi3-miniuart-bt +``` diff --git a/source/_addons/lets_encrypt.markdown b/source/_addons/lets_encrypt.markdown index 8917e007bf4..0ac8d019945 100644 --- a/source/_addons/lets_encrypt.markdown +++ b/source/_addons/lets_encrypt.markdown @@ -2,7 +2,7 @@ layout: page title: "Let's Encrypt" description: "Automatically manage your SSL certificate using Let's Encrypt." -date: 2017-04-30 13:28 +date: 2018-04-18 10:55 sidebar: true comments: false sharing: true @@ -14,15 +14,10 @@ featured: false You should not use this if you are also using the [DuckDNS add-on]. The DuckDNS add-on has integrated Let's Encrypt support. -Setup and manage a [Let's Encrypt](https://letsencrypt.org/) certificate. This will create a certificate on the first run and will auto-renew if the certificate is within 30 days of expiration. - --This add-on uses ports 80/443 to verify the certificate request. You will need to stop all other add-ons that also use these ports. If you don't need a port (like with https you don't need port 80) you can remove this from network config. -
+Setup and manage a [Let's Encrypt](https://letsencrypt.org/) certificate. This addon will create a certificate on the first run and will auto-renew if the certificate is within 30 days of expiration. This add-on uses port 80 to verify the certificate request. You will need to stop all other add-ons that also use this port. ```json { - "challenge": "https", "email": "example@example.com", "domains": ["example.com", "mqtt.example.com", "hass.example.com"] } @@ -30,7 +25,6 @@ This add-on uses ports 80/443 to verify the certificate request. You will need t Configuration variables: -- **challenge** (*Optional*): Default it use 443 ('https') you can change it to 'http' for use port 80. - **email** (*Required*): Your email address for registration on Let's Encrypt. - **domains** (*Required*): A list of domains to create/renew the certificate. @@ -45,6 +39,26 @@ http: ssl_key: /ssl/privkey.pem ``` -If you use a other port as `8123` or a SSL proxy, change the port number. +If you use another port such as `8123` or an SSL proxy, change the port number. + +## {% linkable_title Enabling auto-renewals %} + +Out of the box, the add-on will not automatically renew your certificate. In fact, it only starts, tries to get/renew your certificte, and then stops. It's up to you to manually start it again whenever your certificate comes close to expiry. + +However, you can automate this process using Home Assistant. + +Use this in your `automations.yaml` to attempt certificate renewal each day at midnight: + +```yaml +- id: letsencrypt-renewal + alias: "Let's Encrypt Renewal" + trigger: + - platform: time + at: '00:00:00' + action: + - service: hassio.addon_restart + data: + addon: core_letsencrypt +``` [DuckDNS add-on]: /addons/duckdns/ diff --git a/source/_addons/mariadb.markdown b/source/_addons/mariadb.markdown index b7882dd2c6f..013bdc8ebb4 100644 --- a/source/_addons/mariadb.markdown +++ b/source/_addons/mariadb.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -Set up a [mariadb](https://mariadb.org/) SQL server. It supports multiple databases, users and permission settings. If you want to only connect from inside home assistant use `core-mariadb` as the host address. +Set up a [mariadb](https://mariadb.org/) SQL server. It supports multiple databases, users and permission settings. If you want to only connect from inside Home Assistant use `core-mariadb` as the host address. ```json { diff --git a/source/_addons/mosquitto.markdown b/source/_addons/mosquitto.markdown index f944dc7989c..2150b1a3080 100644 --- a/source/_addons/mosquitto.markdown +++ b/source/_addons/mosquitto.markdown @@ -18,33 +18,81 @@ Set up [Mosquitto](https://mosquitto.org/) as MQTT broker. "ssl": false, "anonymous": true, "logins": [ - {"username": "testuser", "password": "mypw"} + {"username": "testuser", "password": "mypw"}, + {"username": "testuser2", "password": "mypw2"} ], "customize": { "active": false, "folder": "mosquitto" - } + }, + "certfile": "fullchain.pem", + "keyfile": "privkey.pem" } ``` -+
Make sure you use logins and disable anonymous access if you want to secure the system.
Configuration variables: -- **plain** (*Optional*): Listen to broker on port 1883 without SSL/TLS. Defaults to `true`. -- **ssl** (*Optional*): Listen to broker on port 8883 with SSL/TLS. This requires certificates. Defaults to `false`. -- **anonymous** (*Optional*): Allow anonymous connection. If *logins* is set, anonymous user can only read data. Defaults to `true`. -- **logins** (*Optional*): A list of user that will be created with *username* and *password*. +- **plain** (*Optional*): Listen on port 1883 without SSL/TLS. Defaults to `true`. +- **ssl** (*Optional*): Listen on port 8883 with SSL/TLS. This requires certificates. Defaults to `false`. +- **anonymous** (*Optional*): Allow anonymous connections. If *logins* is set, the anonymous user can only read data. Defaults to `true`. +- **logins** (*Optional*): A list of users that will be created with *username* and *password*. - **customize** (*Optional*): If you enable it, it reads additional configuration files (`*.conf`) from `/share/mosquitto`. ### {% linkable_title Home Assistant configuration %} -To use the Mosquitto as [broker](/docs/mqtt/broker/#run-your-own) add the following entry to the `configuration.yaml` file. +To use the Mosquitto as [broker](/docs/mqtt/broker/#run-your-own), add the following entry to the `configuration.yaml` file. ```yaml # Example configuration.yaml entry mqtt: broker: core-mosquitto ``` + +If username and password are set up in add-on, your `configuration.yaml` file should contain that data. + +```yaml +mqtt: + broker: core-mosquitto + username: YOUR_USERNAME + password: YOUR_PASSWORD +``` + +### {% linkable_title Listening simultaneously on SSL/TLS (8883) and insecure (1883) ports %} + +1. Configure SSL/TLS as normal. +2. Set `customize` flag to `true` in your configuration. +3. Create a file in `/share/mosquitto` named `insecure.conf` with the following contents: + +```text +listener 1883 +protocol mqtt +``` + +4. Restart MQTT + ++It's recommended that you only open your firewall to the SSL/TLS port (8883) and only use the insecure port (1883) for local devices. Also, disable `anonymous:` and set `logins:`. +
+ +### {% linkable_title Access Control Lists (ACLs) %} + +It is possible to restrict access to topics based upon the user logged in to Mosquitto. In this scenario it is recommended to create individual users for each of your clients and create an appropriate ACL. + +See the following links for more information: + +* [Mosquitto topic restrictions](http://www.steves-internet-guide.com/topic-restriction-mosquitto-configuration/) +* [Mosquitto.conf man page](https://mosquitto.org/man/mosquitto-conf-5.html) + +Add the following configuration to enable ACLs: + +1. Set `customize` flag to `true` in your configuration. +2. Create a file in `/share/mosquitto` named `acl.conf` with the following contents: + +```text +acl_file /share/mosquitto/accesscontrollist +``` +3. Create a file in `/share/mosquitto` named `accesscontrollist` and add contents according to your requirements. diff --git a/source/_addons/nginx_proxy.markdown b/source/_addons/nginx_proxy.markdown index 318b9768d9c..2b43ab72740 100644 --- a/source/_addons/nginx_proxy.markdown +++ b/source/_addons/nginx_proxy.markdown @@ -9,21 +9,32 @@ sharing: true footer: true --- -Setup a SSL proxy with NGINX and redirect port 80 to 443. Make sure you have generated a certificate before you start this add-on. - -In the `http` section of the `configuration.yaml` file remove `ssl_certificate` and `ssl_key` and don't enter the port in the `base_url` to avoid a HTTP 502 error. +Sets up an SSL proxy with NGINX and redirect port 80 to 443. Make sure you have generated a certificate before you start this add-on. +In the `http` section of the `configuration.yaml` file remove `ssl_certificate` and `ssl_key` and don't enter the port in the `base_url` to avoid an HTTP 502 error. ```json { - "domain": "home.example.com" + "domain": "home.example.com", + "certfile": "fullchain.pem", + "keyfile": "privkey.pem", + "hsts": "max-age=31536000; includeSubDomains", + "customize": { + "active": false, + "default": "nginx_proxy_default*.conf", + "servers": "nginx_proxy/*.conf" + } } ``` Configuration variables: - **domain** (*Required*): Domain they will proxy run with it. +- **certfile** (*Required*): Certificate file to use in the /ssl dir. +- **keyfile** (*Required*): Private key file to use in the /ssl dir. +- **hsts** (*Optional*): Value for the [`Strict-Transport-Security`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) HTTP header to send. If empty or `null`, the header is not sent. +- **customize** (*Optional*): If true, additional NGINX configuration files for the default server and additional servers are read from files in the /share dir specified by the `default` and `servers` variables.-It is possible to deactive port 80 if you need this for things like `emulate_hue`. Remove the host port from Network option of this add-on. +It is possible to deactivate port 80 if you need this for things like `emulate_hue`. Remove the host port from Network option of this add-on.
diff --git a/source/_addons/rpc_shutdown.markdown b/source/_addons/rpc_shutdown.markdown index 10aba2dcf5f..a4d2d6689a9 100644 --- a/source/_addons/rpc_shutdown.markdown +++ b/source/_addons/rpc_shutdown.markdown @@ -9,7 +9,7 @@ sharing: true footer: true --- -Allow to shutdown a Windows computer with a service call from Home Assistant. +Allows you to shut down a Windows computer with a service call from Home Assistant. ```json { @@ -23,10 +23,10 @@ Allow to shutdown a Windows computer with a service call from Home Assistant. } ``` -- **computers** (*Required*): A list of computer object to shutdown from Home-Assistant. -- **computers/alias** (*Required*): Set a alias for this record and that is the name for the input. -- **computers/address** (*Required*): IP address or netbios name of the computer for shutdown. -- **computers/credentials** (*Required*): Credentials for logging into computer. Use a `%` as delimiter of username and password. +- **computers** (*Required*): A list of computer objects to shutdown from Home-Assistant. +- **computers/alias** (*Required*): Set an alias for this record which becomes the name for the input. +- **computers/address** (*Required*): IP address or NetBIOS name of the computer for the shutdown. +- **computers/credentials** (*Required*): Credentials for logging into computer. Use a `%` as the delimiter of username and password. ## {% linkable_title Home Assistant %} diff --git a/source/_addons/samba.markdown b/source/_addons/samba.markdown index f6aff2fd92d..6b378a5dd87 100644 --- a/source/_addons/samba.markdown +++ b/source/_addons/samba.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Samba" -description: "Manage your Home Assistant and custom addons over Samba." +description: "Manage your Home Assistant and custom add-ons over Samba." date: 2017-04-30 13:28 sidebar: true comments: false @@ -10,7 +10,7 @@ footer: true featured: true --- -This allows you to set up a [Samba](https://samba.org/) server to access hass.io folders using Windows network shares. +This addon allows you to set up a [Samba](https://samba.org/) server to access hass.io folders using Windows network shares. ```json { @@ -22,7 +22,7 @@ This allows you to set up a [Samba](https://samba.org/) server to access hass.io "addons": true, "share": true, "backup": true, - "ssl": false, + "ssl": false }, "username": "", "password": "", @@ -32,10 +32,14 @@ This allows you to set up a [Samba](https://samba.org/) server to access hass.io Configuration variables: -- **name** (*Optional*): default `hassio`. Set netbios name of hassio device. -- **workgroup** (*Optional*): default `WORKGROUP`. Set network workgroup. -- **guest** (*Optional*): Allow login without a username or password. Defaults to `true`. -- **map** (*Optional*): Control which folder will be expose. `config` is for Home Assistant configuration folder. `addons` for local custom repositiory. `share` is a folder that can access from add-ons and Home Assistant too. `backup` for access to snapshot files. `ssl` for certificate storage, be careful with this option! Defaults all to `true`, except for `ssl`. -- **username** (*Optional*): The username for logging in if guest login is not used. +- **name** (*Optional*): Set netbios name of Hass.io device. Default is `hassio`. +- **workgroup** (*Optional*): Set network workgroup name. Default is `WORKGROUP`. +- **guest** (*Optional*): Allow login without a username or password. Default is `true`. +- **map** (*Optional*): Control which folders will be exposed. `config` shares the Home Assistant configuration folder. `addons` shares the local custom repository. `share` shares a folder that can be accessed by add-ons and Home Assistant. `backup` shares access to snapshot files. `ssl` shares certificate storage. Be careful with the `ssl` option! Defaults are all set to `true`, except for `ssl`. +- **username** (*Optional*): Username for logging in if guest login is not used. - **password** (*Optional*): Password for `username`. An empty password is not supported. -- **interface** (*Optional*): Interface on that will start the share. Normally is `eth0` for ethernet wired connection and `wlan0` for wireless connection. +- **interface** (*Optional*): Interface that will start the share. Normally this is `eth0` for ethernet wired connection and `wlan0` for wireless connection. If you are running on an Intel NUC this could also be `enp3s0` for ethernet or `wlp5s0` for wireless connection. + ++Be careful when setting up port forwarding to the remote access. If you don't restrict access by requiring authentication and guest access is enabled, your configuration could be exposed to the internet! +
diff --git a/source/_addons/snips.markdown b/source/_addons/snips.markdown index 954d04d613e..851afd8e7d9 100644 --- a/source/_addons/snips.markdown +++ b/source/_addons/snips.markdown @@ -2,51 +2,39 @@ layout: page title: "Snips.ai" description: "Enhance your Hass.io installation with a local voice assistant." -date: 2017-04-30 13:28 +date: 2018-05-02 13:28 sidebar: true comments: false sharing: true footer: true --- -[Snips.ai] is an AI-powered voice assistant that runs on the Raspberry Pi 3 and x86 platforms. It runs on-device and is Private by Design. +[Snips.ai](https://snips.ai/) is an AI-powered voice assistant that runs on the Raspberry Pi 3 and x86 platforms. It runs on-device and is Private by Design. -To get started, follow [their tutorial] to create an assistant and download the training data. +The Snips add-on depends on the Mosquitto add on to bridge to Home Assistant, so make sure that is installed. -Now install and activate the [Samba] add-on so you can upload your training data. Connect to the "share" Samba share and copy your training data over. Name the file `assistant.zip`. +HomeAssistant comes with certain Intents builtin to handle common tasks. A complete list of Intents can be found in this wiki [Hass Snips Bundle](https://github.com/tschmidty69/hass-snips-bundle-intents/wiki). -Now it's time to start Snips for the first time. When the Snips add-on starts, it will output your audio devices: +The Snips addon by default comes with an assistant that allows you to turn on lights or switches, open covers, or add and list items to a shopping list if that component is enabled. -```text -**** List of PLAYBACK Hardware Devices **** -card 0: ALSA [bcm2835 ALSA], device 0: bcm2835 ALSA [bcm2835 ALSA] - Subdevices: 8/8 - Subdevice #0: subdevice #0 - Subdevice #1: subdevice #1 - Subdevice #2: subdevice #2 - Subdevice #3: subdevice #3 - Subdevice #4: subdevice #4 - Subdevice #5: subdevice #5 - Subdevice #6: subdevice #6 - Subdevice #7: subdevice #7 -card 0: ALSA [bcm2835 ALSA], device 1: bcm2835 ALSA [bcm2835 IEC958/HDMI] - Subdevices: 1/1 - Subdevice #0: subdevice #0 +If using a USB microphone and speakers plugged into the Raspberry Pi output, Snips will work without any change to the configuration. Trying saying things like: + +``` +Turn on kitchen light +Open garage door +What is on my shopping list ``` -You need to use this information to point the add-on at the right speakers and microphone. The information describes different cards and devices. On a Raspberry Pi 3, card 0 - device 0 is the built-in headset port, card 0 - device 1 is the HDMI port. In the example above, the USB microphone showed up as card 1 - device 0. +To get started creating your own configuration, follow [their tutorial](https://snips.gitbook.io/documentation/console) to create an assistant and download the training data. You can also add the HomeAssistant Skill to your assistant to enable the built-in intents, and add or create your own intents to do more complex tasks. -Find the microphone and speakers that you want to use and note down their device and card number. We will need that to configure the add-on options `mic` (microphone to use) and `speaker` (speaker to use). The format for these options is `This add-on will not enable you to install packages or do anything as root. This is not allowed with Hass.io.
-To use this add-on, you must have a private/public key to log in. To generate them, follow the [instructions for Windows][win] and [these for other platforms][other]. It is possible to set a password for login since version 2.0 but for high security use private/public keys. You can not run both variant at same time. +To use this add-on, you must have a private/public key to log in. To generate them, follow the [instructions for Windows][win] and [these for other platforms][other]. It is possible to set a password for login since version 2.0 but for high security use private/public keys. You can not run both variants at the same time. -In order to start this add-on for the first time, you either need to include an ssh key (enclosed in quotation marks, on a single line without line breaks) or set a password in the options section. +To start this add-on for the first time, you either need to include a key (enclosed in quotation marks, on a single line without line breaks) or set a password in the options section. ```json { @@ -33,14 +33,14 @@ In order to start this add-on for the first time, you either need to include an } ``` -The username for login over ssh is `root`. The complete login command is `ssh root@hassio.local`. +The username for login over SSH is `root`. The complete login command is `ssh root@hassio.local`. After logging in, you will find yourself in this add-ons container. The Home Assistant configuration directory is mounted on the path `/config`. Configuration variables: -- **authorized_keys** (*Optional*): Your public keys for authorized keyfile. Every element will be a line inside that file. -- **password** (*Optional*): Set a password for login. We do not recommend this variant. +- **authorized_keys** (*Optional*): Your public keys for the authorized key file. Every element will be a line inside that file. +- **password** (*Optional*): Set a password for login. We do **NOT** recommend this variant.
@@ -50,4 +50,6 @@ Configuration variables:
[win]: https://www.digitalocean.com/community/tutorials/how-to-create-ssh-keys-with-putty-to-connect-to-a-vps
[other]: https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/
-
+
+To enable this platform in Home Assistant, add the following lines to your `configuration.yaml`:
```yaml
# Example configuration.yaml entry
@@ -26,4 +28,3 @@ Configuration variables:
- **host** (*Optional*): The host where the concord232 server process is running. Defaults to localhost.
- **port** (*Optional*): The port where the Alarm panel is listening. Defaults to 5007.
-
diff --git a/source/_components/alarm_control_panel.egardia.markdown b/source/_components/alarm_control_panel.egardia.markdown
index b8309efd549..bef700af164 100644
--- a/source/_components/alarm_control_panel.egardia.markdown
+++ b/source/_components/alarm_control_panel.egardia.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Egardia / Woonveilig Alarm Control Panel"
-description: "Instructions how to integrate Egardia / Woonveilig into Home Assistant."
+description: "Instructions on how to integrate Egardia / Woonveilig into Home Assistant."
date: 2016-07-02 22:00
sidebar: true
comments: false
@@ -12,79 +12,5 @@ ha_release: 0.51
ha_category: Alarm
---
-The `egardia` platform enables the ability to control an [Egardia](http://egardia.com/)/Woonveilig control panel. These alarm panels are known under different brand names across the world, including Woonveilig in the Netherlands. This was tested on a Gate01 version of the Egardia/Woonveilig platform.
-
-You will need to know the IP of your alarm panel on your local network. Test if you can login to the panel by browsing to the IP address and log in using your Egardia/Woonveilig account.
-
-To enable this, add the following lines to your `configuration.yaml`:
-
-```yaml
-# Example configuration.yaml entry
-alarm_control_panel:
- - platform: egardia
- host: YOUR_HOST
- username: YOUR_USERNAME
- password: YOUR_PASSWORD
-```
-
-Configuration variables:
-
-- **host** (*Required*): The local IP address of the Egardia/Woonveilig alarm panel.
-- **username** (*Required*): Username for the Egardia/Woonveilig account.
-- **password** (*Required*): Password for Egardia/Woonveilig account.
-- **port** (*Optional*): The port of the alarm panel. Defaults to 80.
-- **name** (*Optional*): Name to use for the alarm panel. Defaults to `Egardia`.
-- **report_server_enabled** (*Optional*): Enable reporting by server. Defaults to `False`.
-- **report_server_port** (*Optional*): Port of the Egardia server. Defaults to 85.
-- **report_server_codes** list (*Optional*): List of codes for the different states.
-
-Note that this basic configuration will only enable you to read the armed/armed away/disarmed status of your alarm and will **not** update the status if the alarm is triggered. This is because of how Egardia built their system. The alarm triggers normally go through their servers.
-You can change this, however, using the following procedure. This is a more advanced configuration.
-
-1. Log in into your alarm system's control panel. You will need to access http://[IP of your control panel]. You know this already since you need it in the basic configuration from above. Log in to the control panel with your Egardia/Woonveilig username and password.
-2. Once logged in, go to *System Settings*, *Report* and change the Server Address for your primary server to the IP or hostname of your Home Assistant machine. Also, update the port number 85 or to anything you like. The provided software that you will set up in the next steps runs on port 85 by default. **Make sure to change the settings of the primary server otherwise the messages will not come through. Note that this will limit (or fully stop) the number of alarm messages you will get through Egardia's / Woonveilig services.** Maybe, that is just what you want. Make sure to save your settings by selecting 'OK'.
-3. On your Home Assistant machine run `$ sudo python3 egardiaserver.py`. Refer to the [python-egardia repository](https://github.com/jeroenterheerdt/python-egardia) for detailed documentation on parameters. This will receive status codes from your alarm control panel and display them. You will need the codes to include in your configuration.yaml. Make sure to change the status of your alarm to all states (disarm, arm, home) by all means possible (all users, remotes, web login, app) as well as trigger the alarm in all ways possible to get 100% coverage. **Before triggering the alarm it might be good to disable the siren temporarily (can be done in Panel Settings).**
-4. Once you have the codes, update your `configuration.yaml`:
-```yaml
-# Example configuration.yaml entry
-alarm_control_panel:
- - platform: egardia
- host: YOUR_HOST
- username: YOUR_USERNAME
- password: YOUR_PASSWORD
- report_server_enabled: True
- report_server_port: PORT_OF_EGARDIASERVER (85 as per the instructions above)
- report_server_codes:
- arm: XXXXXXXXXXXXXXXX, XXXXXXXXXXXXXXXX
- disarm: XXXXXXXXXXXXXXXX, XXXXXXXXXXXXXXXX
- home: XXXXXXXXXXXXXXXX
- triggered: XXXXXXXXXXXXXXXX, XXXXXXXXXXXXXXXX, XXXXXXXXXXXXXXXX
- ignore: XXXXXXXXXXXXXXXX
-```
-
-Note that for triggered, arm and disarm multiple codes can be entered since each sensor triggers with a different code and each user of the system has its own arm and disarm codes. Also note that your system will do regular system checks which will be reported as well. Since Home Assistant provides no way of handling them properly, you can enter those codes as ignore (again, multiple codes can be used here). The egardia component will ignore these codes and continue returning the old status if it receives any of the codes that are listed as ignore. This is useful for example when you have armed your alarm at night: normally a system check will occur at least once during the night and if that code is not specified anywhere Home Assistant will set the status of the alarm to its default, which is unarmed. This is in fact wrong. Listing the code as ignore changes this behavior and Home Assistant will continue to show the status the alarm is in (disarm, arm, home, triggered) even when system checks occur.
-
-5. Start the `egardiaserver.py` script on boot of your Home Assistant machine, for example by using `systemctl` by `systemd`. To use this method, create a shell script named `egardiaserver.sh` that contains something like the following:
-
-```bash
-$ source /srv/homeassistant/bin/activate
-$ python3 /srv/homeassistant/lib/python3.5/site-packages/pythonegardia/egardiaserver.py -host [YOURHOST] -password '[YOURPASSWORD]' -ssl True > /tmp/egardiaserver.log 2>&1
-```
-
-Mark it as executable (`$ chmod +x`) and run `sudo nano /lib/systemd/system/egardiaserver.service`. Enter the following into the `egardiaserver.service` file:
-
-```bash
-[Unit]
-Description=Egardia Server Service
-
-[Service]
-ExecStart=/bin/bash /srv/homeassistant/homeassistant_venv/lib/python3.5/site-packages/pythonegardia/egardiaserver.sh
-StandardOutput=journal+console
-
-[Install]
-WantedBy=multi-user.target
-Alias=egardiaserver.service
-```
-
-Save and then run `sudo systemctl enable egardiaserver.service` and `sudo systemctl start egardiaserver.service`.
-6. Test your setup and enjoy. The component will update if the alarm status changes, including triggers. You can use this to build your own automations and send notifications as you wish.
+The `egardia` platform allows you to integrate your [Egardia](http://www.egardia.com)/[Woonveilig](http://www.woonveilig.nl) alarm control panel in Home Assistant.
+You will need to set up your [Egardia hub](/components/egardia/).
diff --git a/source/_components/alarm_control_panel.envisalink.markdown b/source/_components/alarm_control_panel.envisalink.markdown
index b5b6b3d593a..fe58c6fb4d7 100644
--- a/source/_components/alarm_control_panel.envisalink.markdown
+++ b/source/_components/alarm_control_panel.envisalink.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Envisalink Alarm"
-description: "Instructions how to setup the Envisalink Alarm control panel within Home Assistant."
+description: "Instructions on how to setup the Envisalink Alarm control panel within Home Assistant."
date: 2016-07-01 08:00
sidebar: true
comments: false
diff --git a/source/_components/alarm_control_panel.homematicip_cloud.markdown b/source/_components/alarm_control_panel.homematicip_cloud.markdown
new file mode 100644
index 00000000000..c4e06783b8e
--- /dev/null
+++ b/source/_components/alarm_control_panel.homematicip_cloud.markdown
@@ -0,0 +1,21 @@
+---
+layout: page
+title: "HomematicIP Cloud Alarm Control Panel"
+description: "Instructions on how to integrate HomematicIP alarm control panel into Home Assistant."
+date: 2018-05-18 22:40
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: homematicip_cloud.png
+ha_category: Sensor
+ha_release: 0.73
+ha_iot_class: "Cloud Push"
+---
+
+The `homematicip_cloud` alarm_control_panel platform allows you to control your [HomematicIP](https://www.homematic-ip.com) `Security Zones` through Home Assistant.
+
+This component will automatically add `Security Zones` configured in your HomematicIP cloud.
+
+Please refer to the
+[component](/components/homematicip_cloud/) configuration on how to setup HomematicIP Cloud.
diff --git a/source/_components/alarm_control_panel.ialarm.markdown b/source/_components/alarm_control_panel.ialarm.markdown
new file mode 100644
index 00000000000..d72261c908f
--- /dev/null
+++ b/source/_components/alarm_control_panel.ialarm.markdown
@@ -0,0 +1,48 @@
+---
+layout: page
+title: "Antifurto365 iAlarm Control Panel"
+description: "Instructions on how to integrate iAlarms alarms into Home Assistant."
+date: 2017-11-30 20:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: antifurto365-ialarm.png
+ha_category: Alarm
+ha_release: "0.60"
+---
+
+The `ialarm` platform provides connectivity with the [Antifurto365](https://www.antifurtocasa365.it/) iAlarm alarm systems.
+
+This platform supports the following services: `alarm_arm_away`, `alarm_arm_home` and `alarm_disarm`.
+
+To enable this, add the following lines to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+alarm_control_panel:
+ - platform: ialarm
+ host: ALARM_SYSTEM_IP
+ username: YOUR_USERNAME
+ password: YOUR_PASSWORD
+```
+
+{% configuration %}
+ host:
+ description: The IP address of the iAlarm device on your home network.
+ required: true
+ type: string
+ username:
+ description: Username used to sign into the iAlarm web client (should be admin by default).
+ required: true
+ type: string
+ password:
+ description: Password used to sign into the iAlarm web client. If it has a leading zero you need to put the password within quotes.
+ required: true
+ type: string
+ name:
+ description: Name of device in Home Assistant.
+ required: false
+ type: string
+{% endconfiguration %}
+
diff --git a/source/_components/alarm_control_panel.ifttt.markdown b/source/_components/alarm_control_panel.ifttt.markdown
new file mode 100644
index 00000000000..e2f1a13955a
--- /dev/null
+++ b/source/_components/alarm_control_panel.ifttt.markdown
@@ -0,0 +1,93 @@
+---
+layout: page
+title: "IFTTT Alarm Control Panel"
+description: "Instructions on how to integrate IFTTT-controlled security systems into Home Assistant."
+date: 2018-03-10 21:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: ifttt.png
+ha_category: Alarm
+ha_release: 0.66
+---
+
+The `ifttt` platform allows you to integrate security systems that have no open API but can be controlled through [IFTTT](https://ifttt.com/discover).
+
+This platform depends on the [IFTTT](/components/ifttt/) Home Assistant component. See the component's documentation to set it up.
+
+` and Alexa will activate that scene for you.
@@ -325,9 +330,53 @@ Please refer to the [Amazon documentation][flash-briefing-api-docs] for more inf
- All other settings are up to you
- Hit "Next"
- Test
- - Having passed all validations to reach this screen, you can now click on "< Back to All Skills" as your flash briefing is now available as in "Development" service.
+ - Having passed all validations to reach this screen, you can now click on "< Back to All Skills" as your flash briefing is now available as in "Development" service.
- To invoke your flash briefing, open the Alexa app on your phone or go to the [Alexa Settings Site][alexa-settings-site], open the "Skills" configuration section, select "Your Skills", scroll to the bottom, tap on the Flash Briefing Skill you just created, enable it, then manage Flash Briefing and adjust ordering as necessary. Finally ask your Echo for your "news","flash briefing", or "briefing".
+
+## {% linkable_title Smart Home %}
+
+While the Skills API described above allows for arbitrary intents, all
+utterances must begin with "Alexa, tell $invocation_name ..."
+
+The [Emulated Hue component][emulated-hue-component] provides a simpler
+interface such as, "Alexa, turn on the kitchen light". However it has some
+limitations since everything looks like a light bulb.
+
+Amazon provides a Smart Home API for richer home automation control. It takes
+considerable effort to configure. The easy solution is to use
+[Home Assistant Cloud](/components/cloud/).
+
+If you don't want to use Home Assistant Cloud and are willing to do the
+integration work yourself, Home Assistant can expose an HTTP API which makes
+the integration work easier. Example configuration:
+
+```yaml
+alexa:
+ smart_home:
+ filter:
+ include_entities:
+ - light.kitchen
+ - light.kitchen_left
+ include_domains:
+ - switch
+ exclude_entities:
+ - switch.outside
+ entity_config:
+ light.kitchen:
+ name: Custom Name for Alexa
+ description: The light in the kitchen
+ switch.stairs:
+ display_categories: LIGHT
+```
+
+This exposes an HTTP POST endpoint at `http://your_hass_ip/api/alexa/smart_home`
+which accepts and returns messages conforming to the
+[Smart Home v3 payload](https://developer.amazon.com/docs/smarthome/smart-home-skill-api-message-reference.html).
+You must then create an Amazon developer account with an Alexa skill and Lambda
+function to integrate this endpoint. See
+[Haaska](https://github.com/mike-grant/haaska) for an example.
+
[amazon-dev-console]: https://developer.amazon.com
[flash-briefing-api]: https://developer.amazon.com/alexa-skills-kit/flash-briefing
[flash-briefing-api-docs]: https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/flash-briefing-skill-api-feed-reference
diff --git a/source/_components/amcrest.markdown b/source/_components/amcrest.markdown
index c910e10647e..9c0aad4929e 100644
--- a/source/_components/amcrest.markdown
+++ b/source/_components/amcrest.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Amcrest IP Camera"
-description: "Instructions how to integrate Amcrest IP cameras within Home Assistant."
+description: "Instructions on how to integrate Amcrest IP cameras within Home Assistant."
date: 2017-06-24 10:00
sidebar: true
comments: false
@@ -13,23 +13,28 @@ ha_iot_class: "Local Polling"
ha_release: 0.49
---
-The `amcrest` platform allows you to integrate your [Amcrest](https://amcrest.com/) IP camera in Home Assistant.
+The `amcrest` camera platform allows you to integrate your [Amcrest](https://amcrest.com/) IP camera in Home Assistant.
+
+## {% linkable_title Configuration %}
To enable your camera in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
amcrest:
- - host: IP_ADDRESS
- username: USERNAME
- password: PASSWORD
+ - host: IP_ADDRESS_CAMERA_1
+ username: YOUR_USERNAME
+ password: YOUR_PASSWORD
sensors:
- motion_detector
- sdcard
+ switches:
+ - motion_detection
+ - motion_recording
- - host: IP_ADDRESS
- username: USERNAME
- password: PASSWORD
+ - host: IP_ADDRESS_CAMERA_2
+ username: YOUR_USERNAME
+ password: YOUR_PASSWORD
resolution: low
stream_source: snapshot
sensors:
@@ -45,18 +50,21 @@ Configuration variables:
- **port** (*Optional*): The port that the camera is running on. The default is 80.
- **resolution** (*Optional*): This parameter allows you to specify the camera resolution. For a high resolution (1080/720p), specify the option `high`. For VGA resolution (640x480p), specify the option `low`. If omitted, it defaults to *high*.
- **stream_source** (*Optional*): The data source for the live stream. `mjpeg` will use the camera's native MJPEG stream, whereas `snapshot` will use the camera's snapshot API to create a stream from still images. You can also set the `rtsp` option to generate the streaming via RTSP protocol. If omitted, it defaults to *snapshot*.
-- **ffmpeg_arguments**: (*Optional*): Extra options to pass to ffmpeg, e.g. image quality or video filter options.
+- **ffmpeg_arguments**: (*Optional*): Extra options to pass to ffmpeg, e.g., image quality or video filter options.
- **authentication**: (*Optional*): Defines which authentication method to use only when **stream_source** is **mjpeg**. Currently, *aiohttp* only support *basic*. It defaults to *basic*.
- **scan_interval** (*Optional*): Defines the update interval of the sensor in seconds. The default is 10 seconds.
- **sensors** array (*Optional*): Conditions to display in the frontend. By default, *none* of the conditions are enabled. The following conditions can be monitored.
- **motion_detector**: Return True/False when a motion is detected
- **sdcard**: Return the SD card usage by reporting the total and used space
- **ptz_preset**: Return the number of PTZ preset positions configured for the given camera
+- **switches** array (*Optional*): Switches to display in the frontend. By default, *none* of the switches are shown. The following switches can be monitored.
+ - **motion_detection**: Enable/disable motion detection setting
+ - **motion_recording**: Enable/disable recording on motion detection setting
**Note:** Amcrest cameras with newer firmware no longer have the ability to stream `high` definition video with MJPEG encoding. You may need to use `low` resolution stream or the `snapshot` stream source instead. If the quality seems too poor, lower the `Frame Rate (FPS)` and max out the `Bit Rate` settings in your camera's configuration manager. If you defined the *stream_source* to **mjpeg**, make sure your camera supports *Basic* HTTP authentication. Newer Amcrest firmware may not work, then **rtsp** is recommended instead.
**Note:** If you set the `stream_source` option to `rtsp`, make sure to follow the steps mentioned at
-[FFMPEG](https://home-assistant.io/components/ffmpeg/) documentation to install the `ffmpeg`.
+[FFMPEG](/components/ffmpeg/) documentation to install the `ffmpeg`.
Finish its configuration by visiting the [Amcrest sensor page](/components/sensor.amcrest/) or [Amcrest camera page](/components/camera.amcrest/).
diff --git a/source/_components/android_ip_webcam.markdown b/source/_components/android_ip_webcam.markdown
index 5a62ccefdeb..c616b33a35e 100644
--- a/source/_components/android_ip_webcam.markdown
+++ b/source/_components/android_ip_webcam.markdown
@@ -48,6 +48,9 @@ Sensors:
- light
- motion
- pressure
+- proximity
+- sound
+- video_connections
Settings (Switches):
@@ -76,6 +79,9 @@ android_ip_webcam:
- light
- motion
- pressure
+ - proximity
+ - sound
+ - video_connections
switches:
- exposure_lock
- ffc
diff --git a/source/_components/api.markdown b/source/_components/api.markdown
new file mode 100644
index 00000000000..ba1097738e9
--- /dev/null
+++ b/source/_components/api.markdown
@@ -0,0 +1,25 @@
+---
+layout: page
+title: "API"
+description: "Instructions on how to setup the RESTful API within Home Assistant."
+date: 2018-01-21 08:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: home-assistant.png
+ha_category: "Other"
+---
+
+The `api` component exposes a RESTful API and allows one to interact with a Home Assistant instance that is running headless. This component depends on the [`http` component](/components/http/).
+
+
-Select `apple_tv` as domain, `apple_tv_authenticate` as service and enter `{"entity_id": "XXX"}` into "Service Data", but replace XXX with the entity id of your device (e.g. `media_player.apple_tv`). Press the button and hopefully you are presented with an input dialog asking for a pin code:
+Select `apple_tv` as domain, `apple_tv_authenticate` as service and enter `{"entity_id": "XXX"}` into "Service Data", but replace XXX with the entity id of your device (e.g., `media_player.apple_tv`). Press the button and hopefully you are presented with an input dialog asking for a pin code:
@@ -129,6 +112,24 @@ apple_tv:
Restart Home Assistant, and you should now be able to use `play_url` as before.
+### {% linkable_title My Apple TV turns on when I restart Home Assistant %}
+
+The Apple TV will automatically turn on if a request is sent to it, e.g., if a button is pressed, something is streamed to it via AirPlay or if current state (currently playing) is accessed. This is how Apple has designed it, and it will cause problems if you are using HDMI CEC. Every time Home Assistant is started, a new request is sent to the device to figure out what is currently playing. When using CEC, this will wake up your TV and other devices you have configured.
+
+So, if your TV is randomly turning on, this is probably the reason. As stated, this is by design, and there is no real fix for it. There's also no known way to turn off the Apple TV via the protocol used for communication. You have the following options:
+
+- Do not use this platform
+- Disable HDMI CEC on your Apple TV
+- Use "fake standby"
+
+The first two points are quite obvious. Fake standby is a concept implemented in this platform that disables all requests to the device and makes it appear as being "off" in the web interface. This will make sure that the device is not woken up, but it will of course not show any information or allow you to control it. It is however easy to turn it on (or off) in the web interface or to use an automation with `turn_on`. To make it more useful, you can write automations that turn it on or off depending on some other device, like the input source on your receiver.
+
+To put a device into fake standby when starting Home Assistant, add `start_off: true` to your configuration.
+
+
-This allows one to reload the automation without restarting Home Assistant itself. If you don't want to see the automation rule in your frontend use `hide_entity: True` to hide it. You can also use `initial_state: 'off'` so that the automation is not automatically turned on after a Home assistant reboot.
+This allows one to reload the automation without restarting Home Assistant itself. If you don't want to see the automation rule in your frontend use `hide_entity: True` to hide it. You can also use `initial_state: 'off'` so that the automation is not automatically turned on after a Home Assistant reboot.
```yaml
automation:
diff --git a/source/_components/axis.markdown b/source/_components/axis.markdown
index a23a97c2dfc..6f9a2cc4826 100644
--- a/source/_components/axis.markdown
+++ b/source/_components/axis.markdown
@@ -68,10 +68,6 @@ axis:
location: köket
```
-/api/geofency`. Use the default POST format, and make sure to include the API password if you have configured a password in Home Assistant (add `?api_password=` to the end of the URL). Make sure to enable the 'Update Geo-Position' functionality for mobile beacons.
-Geofency will automatically generate the device tracker name used for geofences, and you will find it in `known_devices.yaml` after the first request. For beacons, the device name will be `beacon_`, e.g., `device_tracker.beacon_car`.
+Geofency will automatically generate the device tracker name used for geofences, and you will find it in `known_devices.yaml` after the first request. For beacons, the device name will be `beacon_`, e.g., `device_tracker.beacon_car`.
-When you enter a geofence or stationary beacon, your location name in Home Assistant will be set to the name of the geofence or beacon location in Geofency. When you exit a geofence or stationary beacon, your location name in Home Assistant will be set to 'not home'. For mobile beacons, the location name will be 'not_home' whenever the beacon is entered or exited outside of a [zone](https://home-assistant.io/components/zone/), otherwise, it will be set to the name of the zone.
+When you enter a geofence or stationary beacon, your location name in Home Assistant will be set to the name of the geofence or beacon location in Geofency. When you exit a geofence or stationary beacon, your location name in Home Assistant will be set to 'not home'. For mobile beacons, the location name will be 'not_home' whenever the beacon is entered or exited outside of a [zone](/components/zone/), otherwise, it will be set to the name of the zone.
-To make Geofency work better with the [proximity](https://home-assistant.io/components/proximity/) component, you should enable the 'Send Current Location' feature in the Webhook configuration screen. This ensures that the _current_ GPS coordinates are included in exit events instead of the coordinates of the (center of) the zone that was exited.
\ No newline at end of file
+To make Geofency work better with the [proximity](/components/proximity/) component, you should enable the 'Send Current Location' feature in the Webhook configuration screen. This ensures that the _current_ GPS coordinates are included in exit events instead of the coordinates of the (center of) the zone that was exited.
\ No newline at end of file
diff --git a/source/_components/device_tracker.google_maps.markdown b/source/_components/device_tracker.google_maps.markdown
new file mode 100644
index 00000000000..206c2cc9bec
--- /dev/null
+++ b/source/_components/device_tracker.google_maps.markdown
@@ -0,0 +1,48 @@
+---
+layout: page
+title: "Google Maps Location Sharing"
+description: "Instructions how to use Google Maps Location Sharing to track devices in Home Assistant."
+date: 2017-02-12 10:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: google_maps.png
+ha_release: 0.67
+ha_category: Presence Detection
+ha_iot_class: "Cloud Polling"
+---
+
+The `google_maps` platform allows you to detect presence using the unofficial API of [Google Maps Location Sharing](https://myaccount.google.com/locationsharing).
+
+## {% linkable_title Configuration %}
+
+You first need to create an additional Google account and share your location with that account. This platform will use that account to fetch the location of your device(s). You have to setup sharing through the Google Maps app on your mobile phone. You can find more information [here](https://support.google.com/accounts?p=location_sharing).
+
+This platform will create a file named `.google_maps_location_sharing.cookies` where it caches your login session.
+
+_` and could be set in app configuration. More details about this config can found in [device tracker](/components/device_tracker/).
An example showing the inclusion of the `mac` field for multiple component tracking. The `mac` field will need to be added to the `owntracks` device and will enable tracking by all components that track via the `mac` address.
@@ -55,13 +63,14 @@ An example showing the inclusion of the `mac` field for multiple component track
USERNAME_DEVICE_ID:
name: Friendly Name
mac: EA:AA:55:E7:C6:94
- picture: https://home-assistant.io/images/favicon-192x192.png
+ picture: https://www.home-assistant.io/images/favicon-192x192.png
gravatar: test@example.com
track: yes
hide_if_away: no
```
### {% linkable_title Using Owntracks regions %}
+
Owntracks can track regions, and send region entry and exit information to Home Assistant (HA). You set up a region in the Owntracks app which you should name the same as your HA Zone, and then make sure to turn on the `share` option for the region in the owntracks app. Please see the [owntracks documentation](http://owntracks.org/booklet/guide/waypoints/).
Home Assistant will use the enter and leave messages to set your zone location. Your location will be set to the center of zone when you enter. Location updates from OwnTracks will be ignored while you are inside a zone.
@@ -69,6 +78,7 @@ Home Assistant will use the enter and leave messages to set your zone location.
When you exit a zone, Home Assistant will start using location updates to track you again. To make sure that Home Assistant correctly exits a zone (which it calculates based on your GPS coordinates), you may want to set your Zone radius in HA to be slightly smaller that the Owntracks region radius.
### {% linkable_title Using Owntracks regions - forcing Owntracks to update using %}iBeacons
+
When run in the usual *significant changes mode* (which is kind to your phone battery), Owntracks sometimes doesn't update your location as quickly as you'd like when you arrive at a zone. This can be annoying if you want to trigger an automation when you get home. You can improve the situation using iBeacons.
iBeacons are simple Bluetooth devices that send out an "I'm here" message. They are supported by IOS and some Android devices. Owntracks explain more [here](http://owntracks.org/booklet/guide/beacons/).
@@ -80,18 +90,21 @@ When you exit an iBeacon region HA will switch back to using GPS to determine yo
Sometimes Owntracks will lose connection with an iBeacon for a few seconds. If you name your beacon starting with `-` Owntracks will wait longer before deciding it has exited the beacon zone. HA will ignore the `-` when it matches the Owntracks region with Zones. So if you call your Owntracks region `-home` then HA will recognize it as `home`, but you will have a more stable iBeacon connection.
### {% linkable_title Using Owntracks iBeacons to track devices %}
+
iBeacons don't need to be stationary. You could put one on your key ring, or in your car.
When your phone sees a mobile iBeacon that it knows about, it will tell HA the location of that iBeacon. If your phone moves while you are connected to the iBeacon, HA will update the location of the iBeacon. But when your phone loses the connection, HA will stop updating the iBeacon location.
-To use mobile iBeacons with HA, you just set up a region that doesn't match your Zone names. If HA sees an entry event for a iBeacon region that doesn't match a Zone name (say `keys`) - it will start tracking it, calling the device `device_tracker.beacon_keys`).
+To use mobile iBeacons with HA, you just set up a region that doesn't match your Zone names. If HA sees an entry event for an iBeacon region that doesn't match a Zone name (say `keys`) - it will start tracking it, calling the device `device_tracker.beacon_keys`).
This allows you to write zone automations for devices that can't track themselves (for example *alert me if I leave the house and my keys are still at home*). Another example would be *open the gates if my car arrives home*.
### {% linkable_title Using mobile and fixed iBeacons together %}
+
You can use iBeacons of both types together, so if you have a Zone `drive` with an iBeacon region called `-drive` and you arrive home with a mobile iBeacon called `-car`, then `device_tracker.beacon_car` will be set to a state of `drive`.
### {% linkable_title Importing Owntracks waypoints as zones %}
+
By default, any Owntracks user connected to Home Assistant can export their waypoint definitions (from the *Export - Export to Endpoint* menu item) which will then be translated to zone definitions in Home Assistant. The zones will be named `- - `. This functionality can be controlled in 2 ways:
1. The configuration variable `waypoints` can be set to `False` which will disable importing waypoints for all users.
diff --git a/source/_components/device_tracker.owntracks_http.markdown b/source/_components/device_tracker.owntracks_http.markdown
index 7e91746e55a..64df68dd04e 100644
--- a/source/_components/device_tracker.owntracks_http.markdown
+++ b/source/_components/device_tracker.owntracks_http.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "OwnTracks (via HTTP)"
-description: "Instructions how to use Owntracks via HTTP to track devices in Home Assistant."
+description: "Instructions on how to use Owntracks via HTTP to track devices in Home Assistant."
date: 2017-09-28 07:00
sidebar: true
comments: false
@@ -32,5 +32,21 @@ Open OwnTracks and go to Connection preferences:
- Mode: Select **Private HTTP**
- Host: [Home Assistant URL]:[port]/api/owntracks/[your name]/[device name]
- Identification: Turn **Authentication** on, username `homeassistant` and password is your API password that you use to login to Home Assistant.
-
+
Host example: If I host my Home Assistant at `https://example.duckdns.org`, my name is Paulus and my phone is a Pixel I would set the host to be `https://example.duckdns.org/api/owntracks/paulus/pixel`. This will result in an entity with an ID of `device_tracker.paulus_pixel`. You can pick any name for the user and the device.
+
+Since the battery data is available as an attribute of the device tracker entity, it can be tracked with a [`template` sensor](/components/sensor.template/).
+
+{% raw %}
+```yaml
+# Example configuration.yaml entry
+sensor:
+ - platform: template
+ sensors:
+ pixel_battery:
+ friendly_name: Pixel of Paulus
+ unit_of_measurement: "%"
+ value_template: '{{ states.device_tracker.paulus_pixel.attributes.battery|int }}'
+ device_class: battery
+```
+{% endraw %}
diff --git a/source/_components/device_tracker.ping.markdown b/source/_components/device_tracker.ping.markdown
index 79798811983..1f343680127 100644
--- a/source/_components/device_tracker.ping.markdown
+++ b/source/_components/device_tracker.ping.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Ping (ICMP)"
-description: "Instructions how to integrate Ping (ICMP)-based presence detection into Home Assistant."
+description: "Instructions on how to integrate Ping (ICMP)-based presence detection into Home Assistant."
date: 2017-01-06 08:00
sidebar: true
comments: false
diff --git a/source/_components/device_tracker.sky_hub.markdown b/source/_components/device_tracker.sky_hub.markdown
index e5a12718946..792aece8a85 100644
--- a/source/_components/device_tracker.sky_hub.markdown
+++ b/source/_components/device_tracker.sky_hub.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Sky Hub"
-description: "Instructions how to integrate Sky Hub routers into Home Assistant."
+description: "Instructions on how to integrate Sky Hub routers into Home Assistant."
date: 2017-01-28 09:00
sidebar: true
comments: false
diff --git a/source/_components/device_tracker.snmp.markdown b/source/_components/device_tracker.snmp.markdown
index 22767d9907a..faea7253981 100644
--- a/source/_components/device_tracker.snmp.markdown
+++ b/source/_components/device_tracker.snmp.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "SNMP"
-description: "Instructions how to integrate SNMP into Home Assistant."
+description: "Instructions on how to integrate SNMP into Home Assistant."
date: 2015-10-08 12:00
sidebar: true
comments: false
@@ -33,6 +33,8 @@ The following OID examples pull the current MAC Address table from a router. Thi
| TP-Link | Archer VR600 | `1.3.6.1.2.1.3.1.1.2` |
| EdgeRouter | Lite v1.9.0 | `1.3.6.1.2.1.4.22.1.2` |
| Ruckus | ZoneDirector 9.13.3 | `1.3.6.1.4.1.25053.1.2.2.1.1.3.1.1.1.6` |
+| DD-WRT | unknown RouterOS version/model | `1.3.6.1.2.1.4.22.1.2` |
+| Apple Airport Express (2nd gen.) | 7.6.9 | `1.3.6.1.2.1.3.1.1.2` or `1.3.6.1.2.1.4.22.1.2`|
To use the SNMP version 1 platform in your installation, add the following to your `configuration.yaml` file:
diff --git a/source/_components/device_tracker.swisscom.markdown b/source/_components/device_tracker.swisscom.markdown
index bee21be205f..49c4f72ba96 100644
--- a/source/_components/device_tracker.swisscom.markdown
+++ b/source/_components/device_tracker.swisscom.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Swisscom Internet-Box"
-description: "Instructions how to integrate Swisscom Internet-Box into Home Assistant."
+description: "Instructions on how to integrate Swisscom Internet-Box into Home Assistant."
date: 2016-10-29 23:30
sidebar: true
comments: false
diff --git a/source/_components/device_tracker.tado.markdown b/source/_components/device_tracker.tado.markdown
index 446c79131d6..70f130c7e01 100644
--- a/source/_components/device_tracker.tado.markdown
+++ b/source/_components/device_tracker.tado.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Tado"
-description: "Instructions how to integrate Tado into Home Assistant."
+description: "Instructions on how to integrate Tado into Home Assistant."
date: 2017-01-17 12:00
sidebar: true
comments: false
@@ -12,7 +12,7 @@ ha_category: Presence Detection
ha_release: 0.37
---
-The `tado` device tracker is using the [Tado Smart Thermostat](https://www.tado.com/) and it's support for person presence detection based on smartphone location by geofencing.
+The `tado` device tracker is using the [Tado Smart Thermostat](https://www.tado.com/) and its support for person presence detection based on smartphone location by geofencing.
This tracker uses the Tado API to determine if a mobile device is at home. It tracks all devices in your home that Tado knows about.
diff --git a/source/_components/device_tracker.tesla.markdown b/source/_components/device_tracker.tesla.markdown
index 68307d1057f..affbe9a1a85 100644
--- a/source/_components/device_tracker.tesla.markdown
+++ b/source/_components/device_tracker.tesla.markdown
@@ -1,6 +1,6 @@
---
layout: page
-title: "Tesla"
+title: "Tesla Device Tracker"
description: "Instructions on for how to integrate Tesla into Home Assistant."
date: 2017-08-02 12:20
sidebar: true
diff --git a/source/_components/device_tracker.thomson.markdown b/source/_components/device_tracker.thomson.markdown
index f9d39eb6d7f..810d586d27b 100644
--- a/source/_components/device_tracker.thomson.markdown
+++ b/source/_components/device_tracker.thomson.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Thomson"
-description: "Instructions how to integrate Thomson routers into Home Assistant."
+description: "Instructions on how to integrate Thomson routers into Home Assistant."
date: 2015-08-30 19:00
sidebar: true
comments: false
diff --git a/source/_components/device_tracker.tile.markdown b/source/_components/device_tracker.tile.markdown
index 7dc534339f4..8abb07a6764 100644
--- a/source/_components/device_tracker.tile.markdown
+++ b/source/_components/device_tracker.tile.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Tile"
-description: "Instructions how to use Tile to track devices in Home Assistant."
+description: "Instructions on how to use Tile to track devices in Home Assistant."
date: 2017-11-08 20:40:00
sidebar: true
comments: false
@@ -25,9 +25,6 @@ device_tracker:
- platform: tile
username: email@address.com
password: MY_PASSWORD_123
- monitored_variables:
- - TILE
- - PHONE
```
{% configuration %}
@@ -43,4 +40,8 @@ device_tracker:
description: the Tile types to monitor; valid values are `TILE` and `PHONE` (default is for all types to be included)
required: false
type: list
+ show_inactive:
+ description: whether to show expired/disabled Tiles
+ required: false
+ type: boolean
{% endconfiguration %}
diff --git a/source/_components/device_tracker.tomato.markdown b/source/_components/device_tracker.tomato.markdown
index e7a105ea2fe..279cd63b687 100644
--- a/source/_components/device_tracker.tomato.markdown
+++ b/source/_components/device_tracker.tomato.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Tomato"
-description: "Instructions how to integrate Tomato routers into Home Assistant."
+description: "Instructions on how to integrate Tomato routers into Home Assistant."
date: 2015-03-23 19:59
sidebar: true
comments: false
@@ -29,14 +29,47 @@ device_tracker:
http_id: YOUR_HTTP_ID
```
-Configuration variables:
-
-- **host** (*Required*): The IP address of your router, e.g. 192.168.1.1.
-- **username** (*Required*: The username of an user with administrative privileges, usually *admin*.
-- **password** (*Required*): The password for your given admin account.
-- **http_id** (*Required*): The value can be obtained by logging in to the Tomato admin interface and search for `http_id` in the page source code.
+{% configuration %}
+host:
+ description: "The IP address or hostname of your router, e.g., `192.168.1.1` or `rt-ac68u`."
+ required: false
+ type: string
+port:
+ description: "The port number of your router, e.g., `443`."
+ required: false
+ type: int
+ default: 80/443 (automatically detected)
+ssl:
+ description: "Whether to connect via `https`."
+ required: false
+ type: bool
+ default: false
+verify_ssl:
+ description: "If SSL verification for https resources needs to be turned off (for self-signed certs, etc.) this can take on boolean values `False` or `True` or you can pass a location on the device where a certificate can be used for verification e.g., `/mnt/NAS/router_cert.pem`."
+ required: false
+ type: [string, bool]
+ default: true
+username:
+ description: "The username of an user with administrative privileges, usually *admin*."
+ required: true
+ type: string
+password:
+ description: "The password for your given admin account."
+ required: true
+ type: string
+http_id:
+ description: "The value can be obtained by logging in to the Tomato admin interface and search for `http_id` in the page source code."
+ required: true
+ type: string
+{% endconfiguration %}
See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked.
A description of the API s available in this [Tomato API](http://paulusschoutsen.nl/blog/2013/10/tomato-api-documentation/) blog post.
-
+
+SSL Certificate:
+
+Gathering the SSL Certificate of your router can be accomplished with this (or a similar) command:
+```bash
+openssl s_client -showcerts -connect 172.10.10.1:443 /dev/null | openssl x509 -outform PEM > router_cert.pem
+```
\ No newline at end of file
diff --git a/source/_components/device_tracker.tplink.markdown b/source/_components/device_tracker.tplink.markdown
index 89897bb1e02..89b47681796 100644
--- a/source/_components/device_tracker.tplink.markdown
+++ b/source/_components/device_tracker.tplink.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "TP-Link"
-description: "Instructions how to integrate TP-Link routers into Home Assistant."
+description: "Instructions on how to integrate TP-Link routers into Home Assistant."
date: 2015-06-22 10:30
sidebar: true
comments: false
@@ -13,7 +13,14 @@ ha_release: pre 0.7
---
-The `tplink` platform allows you to detect presence by looking at connected devices to a [TP-Link](https://www.tp-link.com) device. This includes the ArcherC9 line.
+The `tplink` platform allows you to detect presence by looking at connected devices to a [TP-Link](https://www.tp-link.com) device.
+
+Currently supported devices includes the following:
+
+- Archer C7 firmware version 150427
+- Archer C9 firmware version 150811
+- EAP-225 AP with latest firmware version
+- Archer D9 firmware version 0.9.1 0.1 v0041.0 Build 160224 Rel.59129n
- password:
- language:
+ username: YOUR_DYSON_USERNAME
+ password: YOUR_DYSON_PASSWORD
+ language: YOUR_DYSON_ACCOUNT_LANGUGAGE
devices:
- - device_id: # eg: Pure Cool Link device
- device_ip:
- - device_id: # eg: Eye 360 robot vacuum
- device_ip:
- ...
+ - device_id: DEVICE_ID_1 # eg. Serial number: XXX-XX-XXXXXXXX
+ device_ip: DEVICE_ID_1
+ - device_id: DEVICE_ID_2
+ device_ip: DEVICE_ID_2
```
Configuration variables:
-- **username** (*Required*): Dyson account username (email address)
-- **password** (*Required*): Dyson account password
+- **username** (*Required*): Dyson account username (email address).
+- **password** (*Required*): Dyson account password.
- **language** (*Required*): Dyson account language country code. Known working codes: `FR`, `NL`, `GB`, `AU`. But others codes should work.
-- **devices** (*Optional*): List of devices
- - **device_id** (*Required*): Device ID. Available in the mobiles applications (*Settings* page)
- - **device_ip** (*Required*): Device IP address
+- **devices** (*Optional*): List of devices.
+ - **device_id** (*Required*): Device ID. The Serial Number of the device. Found in the mobiles applications device settings page.
+ - **device_ip** (*Required*): Device IP address.
`devices` list is optional but you'll have to provide them if discovery is not working (warnings in the logs and the devices are not available in Home Assistant web interface).
*If your are using a robot vacuum (Dyson 360 Eye), discovery is not yet supported so you have to provide `devices` list.*
diff --git a/source/_components/ecobee.markdown b/source/_components/ecobee.markdown
index a3e6da2ceef..217922806b2 100644
--- a/source/_components/ecobee.markdown
+++ b/source/_components/ecobee.markdown
@@ -14,25 +14,24 @@ ha_release: 0.9
ha_iot_class: "Cloud Push"
---
-
The `ecobee` component lets you control a thermostats and view sensor data from [ecobee](https://ecobee.com) thermostats.
You will need to obtain an API key from ecobee's [developer site](https://www.ecobee.com/developers/) to use this component. To get the key, first you need to register your thermostat which should be done as part of the ecobee installation. Once you have done that perform the following steps.
-1. Click on the **Become a developer** link on the [developer site](https://www.ecobee.com/developers/).
+1. Click on the **Become a developer** link on the [developer site](https://www.ecobee.com/developers/).
2. Login with your ecobee credentials.
3. Accept the SDK agreement.
4. Fill in the fields.
-5. Click **save**.
+5. Click **save**.
Now login to the regular consumer portal, and in the hamburger menu there will be a new option **Developer**. Now we can create the Application to hook up to Home Assistant.
-1. Select the Developer option.
-2. Select **Create New**.
-3. Give your app a name (it appears to need to be unique across all users, as I tried 'home-assistant' and it said it was already in use. Try -home-assistant) and a summary (neither of these are important as they are not used anywhere).
-4. For Authorization method select **ecobee PIN**.
-5. You don't need an Application Icon or Detailed Description.
-6. Click **Create**.
+1. Select the Developer option.
+2. Select **Create New**.
+3. Give your app a name (it appears to need to be unique across all users, as I tried 'home-assistant' and it said it was already in use. Try -home-assistant) and a summary (neither of these are important as they are not used anywhere).
+4. For Authorization method select **ecobee PIN**.
+5. You don't need an Application Icon or Detailed Description.
+6. Click **Create**.
Now under the Name and Summary Section you will have an API key. Copy this key and use it in you configuration section below. Click the **X** to close the Developer section.
@@ -40,8 +39,8 @@ The first time you run Home Assistant with this component it will give you a PIN
The PIN can be found from the Home Assistant portal on the Ecobee card or from the **configurator.ecobee** entity in states in the portal.
-- If you do not have an ecobee card, you may be using groups with `default_view` that don't show the card. To get around this you can temporarily comment out the `default_view` section or add the `configurator.ecobee` component to your `default_view` and restart Home Assistant.
-
+- If you do not have an ecobee card, you may be using groups with `default_view` that don't show the card. To get around this you can temporarily comment out the `default_view` section or add the `configurator.ecobee` component to your `default_view` and restart Home Assistant.
+
Once you enter the PIN on the ecobee site, wait approximately 5 minutes and then click on the **I have authorized the app** link at the bottom of the ecobee pop-up window. If everything worked correctly, you should now be able to restart Home Assistant again to see the full ecobee card with all of the sensors populated or see the list of sensors in the developer tools. Now you can re-enable your `default_view` (if you had to disable it) and add the ecobee sensors to a group and/or view.
To set it up, add the following information to your `configuration.yaml` file:
@@ -61,3 +60,5 @@ Configuration variables:
+
+If for whatever reason you delete and re-create your ecobee app at ecobee.com such that your developer API key changes, you will need to delete your `/conf/ecobee.conf file`. You will also need to update the `api_key:` in the `configuration.yaml` or `secrets.yaml` file.
diff --git a/source/_components/egardia.markdown b/source/_components/egardia.markdown
new file mode 100644
index 00000000000..50efce55a66
--- /dev/null
+++ b/source/_components/egardia.markdown
@@ -0,0 +1,121 @@
+---
+layout: page
+title: "Egardia"
+description: "Instructions on how to setup Egardia / Woonveilig within Home Assistant."
+date: 2018-03-13 09:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+ha_category: Hub
+ha_release: 0.65
+logo: egardia.png
+---
+
+The `egardia` platform enables the ability to control an [Egardia](http://egardia.com/)/[Woonveilig](http://woonveilig.nl) control panel. These alarm panels are known under different brand names across the world, including Woonveilig in the Netherlands. This was tested on the WL-1716, GATE-01, GATE-02 and GATE-03 versions of the Egardia/Woonveilig platform. Not only will you integrate your alarm control panel, supported sensors (door contacts at this moment) will be added automatically (hidden by default).
+
+You will need to know the IP of your alarm panel on your local network. Test if you can login to the panel by browsing to the IP address and log in using your Egardia/Woonveilig account.
+
+## {% linkable_title Basic configuration %}
+
+To enable the integration with your alarm panel, add the following lines to your `configuration.yaml` file:
+ ```yaml
+ # Example configuration.yaml entry
+ egardia:
+ host: YOUR_HOST
+ username: YOUR_USERNAME
+ password: YOUR_PASSWORD
+```
+
+{% configuration %}
+host:
+ description: The local IP address of the Egardia/Woonveilig alarm panel.
+ required: true
+ type: string
+username:
+ description: Username for the Egardia/Woonveilig account.
+ required: true
+ type: string
+password:
+ description: Password for Egardia/Woonveilig account.
+ required: true
+ type: string
+version:
+ description: The version of the Egardia system. `GATE-01`, `GATE-02` and `GATE-03` are currently supported.
+ required: false
+ type: string
+ default: 'GATE-01'
+port:
+ description: The port of the alarm panel.
+ required: false
+ type: int
+ default: 80
+report_server_enabled:
+ description: Enable reporting by server.
+ required: false
+ type: string
+ default: false
+report_server_port:
+ description: Port of the Egardia server.
+ required: false
+ type: int
+ default: 52010
+report_server_codes:
+ description: Map of list of codes for the different states.
+ required: false
+ type: map
+ keys:
+ arm:
+ description: List of codes for the 'arm' state.
+ required: false
+ type: list
+ disarm:
+ description: List of codes for the 'disarm' state.
+ required: false
+ type: list
+ armhome:
+ description: List of codes for the 'armhome' state.
+ required: false
+ type: list
+ triggered:
+ description: List of codes for the 'triggered' state.
+ required: false
+ type: list
+ ignore:
+ description: List of codes that will be ignored.
+ required: false
+ type: list
+{% endconfiguration %}
+
+Note that this basic configuration will only enable you to read the armed/armed away/disarmed status of your alarm and will **not** update the status if the alarm is triggered. This is because of how Egardia built their system. The alarm triggers normally go through their servers.
+You can change this, however, using the following procedure. This is a more advanced (and more useful) configuration.
+
+:8300/description.xml` - This URL should return a descriptor file in the form of an XML file.
- `http://:8300/api/pi/lights` - This will return a list of devices, lights, scenes, groups, etc.. that `emulated_hue` is exposing to Alexa.
-For Google Home, verify that the URLs above are using port 80, rather than port 8300 (i.e. `http://:80/description.xml`).
+For Google Home, verify that the URLs above are using port 80, rather than port 8300 (i.e. `http://:80/description.xml`).
-An additional step is required to run Home Assistant as non-root user and use port 80 when using the AiO script. Execute the following command to allow `emulated_hue` to use port 80 as non-root user.
+An additional step is required to run Home Assistant as a non-root user and use port 80 when using the AiO script. Execute the following command to allow `emulated_hue` to use port 80 as a non-root user.
```bash
sudo setcap 'cap_net_bind_service=+ep' /srv/homeassistant/homeassistant_venv/bin/python3
```
-Please note that your path may be different depending on your installation method. For example, if you followed the [Virtualenv instructions](https://home-assistant.io/docs/installation/virtualenv/), your path will be `/srv/homeassistant/bin/python3`.
+Please note that your path may be different depending on your installation method. For example, if you followed the [Virtualenv instructions](/docs/installation/virtualenv/), your path will be `/srv/homeassistant/bin/python3`.
### {% linkable_title License %}
diff --git a/source/_components/enocean.markdown b/source/_components/enocean.markdown
index 3a10858445e..4e38d204446 100644
--- a/source/_components/enocean.markdown
+++ b/source/_components/enocean.markdown
@@ -13,7 +13,7 @@ ha_release: 0.21
ha_iot_class: "Local Push"
---
-The [EnOcean](https://en.wikipedia.org/wiki/EnOcean) standard is supported by many different vendors. There are switches and sensors of many different kinds, and typically they employ energy harvesting to get power such that no batteries are unnecessary.
+The [EnOcean](https://en.wikipedia.org/wiki/EnOcean) standard is supported by many different vendors. There are switches and sensors of many different kinds, and typically they employ energy harvesting to get power such that no batteries are necessary.
The `enocean` component adds support for some of these devices. You will need a controller like the [USB300](https://www.enocean.com/en/enocean_modules/usb-300-oem/) in order for it to work.
diff --git a/source/_components/envisalink.markdown b/source/_components/envisalink.markdown
index 02d0746982c..57deb9f53fb 100644
--- a/source/_components/envisalink.markdown
+++ b/source/_components/envisalink.markdown
@@ -13,7 +13,7 @@ ha_release: 0.23
ha_iot_class: "Local Push"
---
-The `envisalink` component will allow Home Assistant users who own either a DSC or Honeywell alarm panel to leverage their alarm system and it's sensors to provide Home Assistant with rich information about their homes. Connectivity between Home Assistant and the alarm panel is accomplished through a device produced by Eyez On, known as the Envisalink. The Envisalink evl3 and evl4 boards provide a TCP/IP interface to the alarm panel, where it emulates an alarm keypad. This board also exposes a raw TCP/IP based API, upon which this component is built. Currently, the Envisalink version 4 is the latest model. This component supports both the evl3 and the evl4.
+The `envisalink` component will allow Home Assistant users who own either a DSC or Honeywell alarm panel to leverage their alarm system and its sensors to provide Home Assistant with rich information about their homes. Connectivity between Home Assistant and the alarm panel is accomplished through a device produced by Eyez On, known as the Envisalink. The Envisalink evl3 and evl4 boards provide a TCP/IP interface to the alarm panel, where it emulates an alarm keypad. This board also exposes a raw TCP/IP based API, upon which this component is built. Currently, the Envisalink version 4 is the latest model. This component supports both the evl3 and the evl4.
Please visit the [eyezon website](http://www.eyezon.com/) for further information about the evl3 and evl4 boards.
diff --git a/source/_components/eufy.markdown b/source/_components/eufy.markdown
new file mode 100644
index 00000000000..60ec2a470dd
--- /dev/null
+++ b/source/_components/eufy.markdown
@@ -0,0 +1,54 @@
+---
+layout: page
+title: "Eufy"
+description: "Instructions on how to integrate Eufy devices into Home Assistant."
+date: 2018-04-09 19:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: eufy.png
+ha_category: Hub
+ha_release: 0.68
+---
+
+The `eufy` component is the main component to integrate various [eufy](https://www.eufylife.com/) devices with Home Assistant.
+
+Supported devices will be discovered after the `eufy` component is configured:
+
+```yaml
+# Example configuration.yaml entry
+eufy:
+ username: testuser@domain
+ password: p4ssw0rd
+```
+
+where username and password are the ones configured in the EufyHome app. Alternately, Eufy devices that are not discoverable can be statically configured.
+
+```yaml
+eufy:
+ devices:
+ - address: 192.168.1.10
+ access_token: 1234567890abcdef
+ type: T1012
+ name: Smart Light
+ - address: 192.168.1.11
+ access_token: abcdef1234567890
+ type: T1201
+ name: Smart Switch
+```
+
+access_token can be obtained by running:
+
+```
+curl -H "Content-Type: application/json" -d '{"client_id":"eufyhome-app", "client_Secret":"GQCpr9dSp3uQpsOMgJ4xQ", "email":"USERNAME", "password":"PASSWORD"}' https://home-api.eufylife.com/v1/user/email/login | jq
+```
+
+replacing USERNAME and PASSWORD with the Eufy username and password. This will give an access_token. Then run:
+
+```
+curl -H token:TOKEN -H category:Home https://home-api.eufylife.com/v1/device/list/devices-and-groups | jq
+```
+
+replacing TOKEN with the access_token from the previous command. This will provide the local_code for each device.
+
diff --git a/source/_components/fan.comfoconnect.markdown b/source/_components/fan.comfoconnect.markdown
index d24d4eb1845..f1ac6f944f3 100644
--- a/source/_components/fan.comfoconnect.markdown
+++ b/source/_components/fan.comfoconnect.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Zehnder ComfoAir Q Ventilation fans"
-description: "Instructions how to integrate Zehnder ComfoAir Q350/450/600 fans into Home Assistant."
+description: "Instructions on how to integrate Zehnder ComfoAir Q350/450/600 fans into Home Assistant."
date: 2017-06-28 18:00
sidebar: true
comments: false
diff --git a/source/_components/fan.dyson.markdown b/source/_components/fan.dyson.markdown
index e827c7ab2cb..d1ae60c6381 100644
--- a/source/_components/fan.dyson.markdown
+++ b/source/_components/fan.dyson.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Dyson Purifier Fan"
-description: "Instructions how to setup the Dyson Purifier fans within Home Assistant."
+description: "Instructions on how to setup the Dyson Purifier fans within Home Assistant."
date: 2017-05-27 10:00
sidebar: true
comments: false
diff --git a/source/_components/fan.insteon_hub.markdown b/source/_components/fan.insteon_hub.markdown
deleted file mode 100644
index 364b94fa40c..00000000000
--- a/source/_components/fan.insteon_hub.markdown
+++ /dev/null
@@ -1,17 +0,0 @@
----
-layout: page
-title: "Insteon Hub Fan"
-description: "Instructions how to setup the Insteon Hub Fans within Home Assistant."
-date: 2017-08-26 08:00
-sidebar: true
-comments: false
-sharing: true
-footer: true
-logo: insteon.png
-ha_category: Fan
-ha_release: 0.30
----
-
-The `insteon_hub` fan component lets you control your fans connected to an [Insteon Hub](http://www.insteon.com/insteon-hub/) with Home Assistant.
-
-To get your Insteon Hub fan working with Home Assistant, follow the instructions for the general [Insteon Hub component](/components/insteon_hub/).
diff --git a/source/_components/fan.insteon_local.markdown b/source/_components/fan.insteon_local.markdown
index 8476fc43d06..69a2249ff9a 100644
--- a/source/_components/fan.insteon_local.markdown
+++ b/source/_components/fan.insteon_local.markdown
@@ -1,7 +1,7 @@
---
layout: page
-title: "Insteon (Local) Fan"
-description: "Instructions how to setup the Insteon Hub Fans locally within Home Assistant."
+title: "Insteon (local) Fan"
+description: "Instructions on how to setup the Insteon Hub Fans locally within Home Assistant."
date: 2017-04-06 11:00
sidebar: true
comments: false
@@ -9,26 +9,10 @@ sharing: true
footer: true
logo: insteon.png
ha_category: Fan
-ha_version: 0.48
+ha_release: 0.48
+redirect_from: /components/fan.insteon_hub/
---
-The `insteon_local` fan component lets you control your fan connected to an [Insteon Hub](http://www.insteon.com/insteon-hub/) with Home Assistant.
-
-To integrate add a fan, configure your hub Insteon(local) with Home Assistant, add the following section to your `configuration.yaml` file:
-
-```yaml
-# Example configuration.yaml platform entry
-insteon_local:
- host: YOUR HUB IP
- username: YOUR HUB USERNAME
- password: YOUR HUB PASSWORD
- timeout: 10
- port: 25105
-```
-
-To add fans to your set-up, add the platform to your light configuration:
-```yaml
-fan:
- - platform: insteon_local
-```
+The `insteon_local` fan component lets you control your fans connected to an [Insteon Hub](http://www.insteon.com/insteon-hub/) with Home Assistant.
+To get your Insteon fans working with Home Assistant, follow the instructions for the general [Insteon local component](/components/insteon_local/). The fans will be automatically discovered and added to Home Assistant. The device names will be the Insteon address of the fans.
diff --git a/source/_components/fan.insteon_plm.markdown b/source/_components/fan.insteon_plm.markdown
new file mode 100644
index 00000000000..0c4478778e3
--- /dev/null
+++ b/source/_components/fan.insteon_plm.markdown
@@ -0,0 +1,16 @@
+---
+layout: page
+title: "Insteon PLM Fan"
+description: "Instructions on how to setup the Insteon PLM Fans locally within Home Assistant."
+date: 2017-02-19 17:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: insteon.png
+ha_category: Fan
+ha_iot_class: "Local Push"
+ha_release: 0.65
+---
+
+The `insteon_plm` fan platform lets you control your [FanLinc](https://www.smarthome.com/fanlinc-insteon-2475f-ceiling-fan-and-light-controller-fixture-module-dual-band.html) through an INSTEON PowerLinc Modem (PLM) device connected directly to your system on a USB or serial port. To add support, set up the primary [insteon_plm](/components/insteon_plm/) component.
diff --git a/source/_components/fan.isy994.markdown b/source/_components/fan.isy994.markdown
index 6b9e55f2895..4c47e76fc40 100644
--- a/source/_components/fan.isy994.markdown
+++ b/source/_components/fan.isy994.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "ISY994 Fan"
-description: "Instructions how to integrate ISY994 fans into Home Assistant."
+description: "Instructions on how to integrate ISY994 fans into Home Assistant."
date: 2016-09-03 23:00
sidebar: true
comments: false
diff --git a/source/_components/fan.markdown b/source/_components/fan.markdown
index c196d9f7705..aac9c8c7636 100644
--- a/source/_components/fan.markdown
+++ b/source/_components/fan.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Fan"
-description: "Instructions how to setup Fan devices within Home Assistant."
+description: "Instructions on how to setup Fan devices within Home Assistant."
date: 2016-08-26 19:00
sidebar: true
comments: false
diff --git a/source/_components/fan.mqtt.markdown b/source/_components/fan.mqtt.markdown
index 82c5193ba30..45fa55d41bc 100644
--- a/source/_components/fan.mqtt.markdown
+++ b/source/_components/fan.mqtt.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "MQTT Fan"
-description: "Instructions how to integrate MQTT fans into Home Assistant."
+description: "Instructions on how to integrate MQTT fans into Home Assistant."
date: 2016-08-27 09:00
sidebar: true
comments: false
@@ -15,6 +15,8 @@ ha_iot_class: depends
The `mqtt` fan platform lets you control your MQTT enabled fans.
+## {% linkable_title Configuration %}
+
In an ideal scenario, the MQTT device will have a `state_topic` to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT fan will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the fan will be `false` / `off`.
When a `state_topic` is not available, the fan will work in optimistic mode. In this mode, the fan will immediately change state after every command. Otherwise, the fan will wait for state confirmation from the device (message from `state_topic`).
@@ -24,36 +26,123 @@ Optimistic mode can be forced even if a `state_topic` is available. Try to enabl
To enable MQTT fans in your installation, add the following to your `configuration.yaml` file:
```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
fan:
- platform: mqtt
command_topic: "bedroom_fan/on/set"
```
-Configuration variables:
-
-- **command_topic** (*Required*): The MQTT topic to publish commands to change the fan state.
-- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates.
-- **name** (*Optional*): The name of the fan. Default is 'MQTT Fan'.
-- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates.
-- **payload_on** (*Optional*): The payload that represents the running state. Default is "ON".
-- **payload_off** (*Optional*): The payload that represents the stop state. Default is "OFF".
-- **state_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the state.
-- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages.
-- **optimistic** (*Optional*): Flag that defines if lock works in optimistic mode. Default is `true` if no state topic defined, else `false`.
-- **retain** (*Optional*): If the published message should have the retain flag on or not.
-- **oscillation_state_topic** (*Optional*): The MQTT topic subscribed to receive oscillation state updates.
-- **oscillation_command_topic** (*Optional*): The MQTT topic to publish commands to change the oscillation state.
-- **payload_oscillation_on** (*Optional*): The payload that represents the oscillation on state. Default is "oscillate_on".
-- **payload_oscillation_off** (*Optional*): The payload that presents the oscillation off state. Default is "oscillate_off".
-- **oscillation_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the oscillation.
-- **speed_state_topic** (*Optional*): The MQTT topic subscribed to receive speed state updates.
-- **speed_command_topic** (*Optional*): The MQTT topic to publish commands to change speed state.
-- **payload_low_speed** (*Optional*): The payload that represents the fan's low speed.
-- **payload_medium_speed** (*Optional*): The payload that represents the fan's medium speed.
-- **payload_high_speed** (*Optional*): The payload that represents the fan's high speed.
-- **speed_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload.
-- **speeds** array (*Optional*): Valid entries for the list are `off`, `low`, `medium`, and `high`.
+{% configuration %}
+name:
+ description: The name of the fan.
+ required: false
+ type: string
+ default: MQTT Fan
+command_topic:
+ description: The MQTT topic to publish commands to change the fan state.
+ required: true
+ type: string
+state_topic:
+ description: The MQTT topic subscribed to receive state updates.
+ required: false
+ type: string
+payload_on:
+ description: The payload that represents the running state.
+ required: false
+ type: string
+ default: ON
+payload_off:
+ description: The payload that represents the stop state.
+ required: false
+ type: string
+ default: OFF
+state_value_template:
+ description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the state."
+ required: false
+ type: string
+qos:
+ description: The maximum QoS level of the state topic.
+ required: false
+ type: integer
+ default: 0
+optimistic:
+ description: Flag that defines if lock works in optimistic mode
+ required: false
+ type: boolean
+ default: "`true` if no state topic defined, else `false`."
+retain:
+ description: If the published message should have the retain flag on or not.
+ required: false
+ type: boolean
+ default: true
+oscillation_state_topic:
+ description: The MQTT topic subscribed to receive oscillation state updates.
+ required: false
+ type: string
+oscillation_command_topic:
+ description: The MQTT topic to publish commands to change the oscillation state.
+ required: false
+ type: string
+payload_oscillation_on:
+ description: The payload that represents the oscillation on state.
+ required: false
+ type: string
+ default: oscillate_on
+payload_oscillation_off:
+ description: The payload that represents the oscillation off state.
+ required: false
+ type: string
+ default: oscillate_off
+oscillation_value_template:
+ description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the oscillation."
+ required: false
+ type: string
+speed_state_topic:
+ description: The MQTT topic subscribed to receive speed state updates.
+ required: false
+ type: string
+speed_command_topic:
+ description: The MQTT topic to publish commands to change speed state.
+ required: false
+ type: string
+payload_low_speed:
+ description: The payload that represents the fan's low speed.
+ required: false
+ type: string
+ default: low
+payload_medium_speed:
+ description: The payload that represents the fan's medium speed.
+ required: false
+ type: string
+ default: medium
+payload_high_speed:
+ description: The payload that represents the fan's high speed.
+ required: false
+ type: string
+ default: high
+speed_value_template:
+ description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the speed payload."
+ required: false
+ type: string
+speeds:
+ description: "List of speeds this fan is capable of running at. Valid entries are `off`, `low`, `medium`, and `high`."
+ required: false
+ type: string list
+availability_topic:
+ description: The MQTT topic subscribed to receive availability (online/offline) updates.
+ required: false
+ type: string
+payload_available:
+ description: The payload that represents the available state.
+ required: false
+ type: string
+ default: online
+payload_not_available:
+ description: The payload that represents the unavailable state.
+ required: false
+ type: string
+ default: offline
+{% endconfiguration %}
`':
+ description: Entity to configure
+ required: false
+ type: map
+ keys:
+ name:
+ description: Name of the entity to show in Google Assistant
+ required: false
+ type: string
+ expose:
+ description: Force an entity to be exposed/excluded.
+ required: false
+ type: boolean
+ aliases:
+ description: Aliases that can also be used to refer to this entity
+ required: false
+ type: list
+ room:
+ description: Allows for associating this device to a Room in Google Assistant.
+ required: false
+ type: string
+{% endconfiguration %}
+
+### {% linkable_title Available domains %}
+Currently, the following domains are available to be used with Google Assistant, listed with their default types:
+
+- group (on/off)
+- input boolean (on/off)
+- scene (on)
+- script (on)
+- switch (on/off)
+- fan (on/off)
+- light (on/off/brightness/rgb color/color temp)
+- cover (on/off/set position (via set brightness))
+- media_player (on/off/set volume (via set brightness))
+- climate (temperature setting)
+
+It's very important that you use very long strings for `client_id` and `access_token`. Those are essentially the credentials to your Home Assistant instance. You can generate them with the following command:
+
+```bash
+$ cat /dev/urandom | fold -w 120 | head -n 1 | base64 -w 0 | tr -dc '0-9A-Za-z' | cut -c -80
+```
+
+If you're not using Linux, you can use sites such as [this one](https://www.browserling.com/tools/random-string) to generate a random string (containing mixed case letters and numbers) of up to 80 characters.
### {% linkable_title Setup %}
-1. Install the [gactions CLI](https://developers.google.com/actions/tools/gactions-cli) (you'll use this later) - you can download this anywhere, just remember where you put it for later (and don't forget to run `chmod +x gactions`)
-2. Create a new file named `project.json` (in the same directory you downloaded `gactions` to) and replace the `[YOUR HOME ASSISTANT URL]` below with the URL you use to access Home Assistant.
- Note: This must be an HTTPS URL to work.
+1. Create a new project in the [developer console](https://console.actions.google.com/).
+ a. Add/Import project, give it a name
+ b. Click on `Home Control` card, select the `Smart home` recommendation
+ c. Create an Action, under the build section. Add in your home assistant url: `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant`, replace the `[YOUR HOME ASSISTANT URL:PORT]` with the domain / ip address and the port under which your Home Assistant is reachable. If you have set `api_password:` add this password to the URL - eg `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant?api_password=[YOUR API PASSWORD]`)
+ d. Click `Done`. Then click on `Overview`, which will lead you back to the app details screen.
+2. `Account linking` is required for your app to interact with Home Assistant. Set this up under the `Quick Setup` section
+ a. Leave it at the default `No, I only want to allow account creation on my website` and select Next
+ b. For the `Linking type` select `OAuth` and `Implicit`
+ c. Client ID: The `client_id` from your Home Assistant configuration above
+ d. Authorization URL (replace with your actual URL): `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant/auth`. If you have set `api_password:` add this password to the URL `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant/auth?api_password=[YOUR API PASSWORD]`)
+ e. Configure your client. Add scopes for `email` and `name`.
+ f. Testing instructions: Enter anything. It doesn't matter since you won't submit this app.
+3. Back on the overview page. Click `Simulator` under `TEST` - you don't have to actually test .
+4. If you haven't already added the component configuration to `configuration.yaml` and restarted Home Assistant, you'll be unable to continue until you have.
+5. Open the Google Assistant app and go into `Settings > Home Control`
+6. Click the `+` sign, and near the bottom, you should have `[test] your app name`. Selecting that should lead you the screen where you can set rooms for your devices or nicknames for your devices.
+7. If you want to allow other household users to control the devices:
+ a. Go to the settings for the project you created in point 1 in the developer console.
+ b. Under the gear icon, click `Permissions`
+ c. Click `Add`, type the new user's e-mail address and choose `Project -> Editor` role
+ d. Have the new user go to [developer console](https://console.actions.google.com/) and repeat steps starting from point 4
+8. If you want to use the `google_assistant.request_sync` service, to update devices without unlinking and relinking, in Home Assistant, then enable Homegraph API for your project:
+ a. Go to the [cloud console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview)
+ b. Select your project and click Enable Homegraph API
+ c. Go to Credentials, which you can find on the left navigation bar under the key icon, and select API Key from Create Credentials
+ d. Note down the generated API Key and use this in the configuration
-```json
-{
- "actions": [{
- "name": "actions.devices",
- "deviceControl": {
- },
- "fulfillment": {
- "conversationName": "automation"
- }
- }],
- "conversations": {
- "automation" :
- {
- "name": "automation",
- "url": "https://[YOUR HOME ASSISTANT URL]/api/google_assistant"
- }
- }
-}
-```
+### {% linkable_title Troubleshooting the request_sync service %}
-3. Create a new project in the [developer console](https://console.actions.google.com/).
- 1. Add/Import project
- 2. Go to Build under the Actions SDK box
- 3. Copy the command that looks like:
- `gactions update --action_package PACKAGE_NAME --project doctest-2d0b8`
-4. Replace `PACKAGE_NAME` with `project.json` and run that command from the same directory you saved `project.json` in (you'll need to put `./` before `gactions` so that it reads `./gactions`). It should output a URL like `https://console.actions.google.com/project/doctest-2d0b8/overview` - go there.
-5. You'll need to fill out most of the information on that page, but none of it really matters since you won't be addressing the App directly, only through the Smart Home functionality built into Google Assistant.
-6. The final item on that page `Account linking` is required for your app to interact with Home Assistant.
- 1. Grant type: `Implicit`
- 2. Client ID: The `client_id` from your Home Assistant configuration above
- 3. Authorization URL (replace with your actual URL): `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth`
- 4. Configure your client. Add scopes for `email` and `name`
- 5. Testing instructions: doesn't matter since you won't submit this app
-7. Back on the main app draft page. Click `Test Draft`. That will take you to the simulator (which won't work) so just close that window.
-8. Open the Google Assistant app and go into `Settings > Home Control`
-9. Click the `+` sign, and near the bottom, you should have `[test] your app name`. Selecting that should lead to you the screen where you can set rooms for your devices or nicknames for your devices.
-10. If you want to allow other houshold users to control the devices:
- 1. Go to the developer console using address from point 4.
- 2. Under the gear icon, click `Permissions`
- 3. Click `Add`, type the new user's e-mail address and choose `Project -> Editor` role
- 4. Have the new user go to [developer console](https://console.actions.google.com/) and repeat steps starting from point 7.
-11. If you want to use the `google_assistant.request_sync` service in Home Assistant, then enable Homegraph API for your project:
- 1. Go to https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview
- 2. Select your project and click Enable Homegraph API
- 3. Go to Credentials and select API Key from Create Credentials
- 4. Note down the generated API Key and use this in the configuration
+The request_sync service requires that the initial sync from Google includes the agent_user_id. If not, the service will log an error that reads something like "Request contains an invalid argument". If this happens, then [unlink the account](https://support.google.com/googlehome/answer/7506443?hl=en-GB) from Home Control and relink.
-*Note:* The request_sync service requires that the initial sync from Google includes the agent_user_id. If not, the service will log an error that reads something like "Request contains an invalid argument". If this happens, then [unlink the account](https://support.google.com/googlehome/answer/7506443?hl=en-GB) from Home Control and relink.
+The request_sync service may fail with a 404 if the project_id of the Homegraph API differs from the project_id of the Actions SDK found in the preferences of your project on [developer console](https://console.actions.google.com). Resolve this by:
+
+ 1. Removing your project from the [developer console](https://console.actions.google.com).
+ 2. Add a new project to the [cloud console](https://console.cloud.google.com). Here you get a new `project_id`.
+ 3. Enable Homegraph API to the new project.
+ 4. Generate a new API key.
+ 5. Again, create a new project in the [developer console](https://console.actions.google.com/). Described above. But at the step 'Build under the Actions SDK box' choose your newly created project. By this, they share the same `project_id`.
+
+### {% linkable_title Troubleshooting with NGINX %}
+
+When using NGINX, ensure that your `proxy_pass` line *does not* have a trailing `/`, as this will result in errors. Your line should look like:
+
+ proxy_pass http://localhost:8123;
diff --git a/source/_components/group.markdown b/source/_components/group.markdown
index 74f07dc49bb..924c55e24ac 100644
--- a/source/_components/group.markdown
+++ b/source/_components/group.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Group"
-description: "Instructions how to setup groups within Home Assistant."
+description: "Instructions on how to setup groups within Home Assistant."
date: 2015-03-23 19:59
sidebar: true
comments: false
@@ -22,7 +22,7 @@ By default, every group appears in the HOME tab. If you create a group `default_
group:
default_view:
view: yes
- icon: mdi:home
+ icon: mdi:home
entities:
- group.kitchen
- group.awesome_people
@@ -56,7 +56,7 @@ group:
Configuration variables:
-- **view** (*Optional*): If yes then the entry will be shown as a view (tab) at the top.
+- **view** (*Optional*): If yes then the entry will be shown as a view (tab) at the top. Groups that are set to `view: yes` cannot be used as entities in other views.
- **name** (*Optional*): Name of the group.
- **icon** (*Optional*): If the group is a view, this icon will show at the top in the frontend instead of the name. If the group is a view and both name and icon have been specified, the icon will appear at the top of the frontend and the name will be displayed as the mouse-over text. If it's not a view, then the icon shows when this group is used in another group.
- **control** (*Optional*): Set value to `hidden`. If hidden then the group switch will be hidden.
@@ -69,7 +69,7 @@ Example of groups shown as views in the frontend.
If all entities in a group are switches or lights then Home Assistant adds a switch at the top of the card that turns them all on/off at once. If you want to hide this switch, set `control` to `hidden`.
-You can create views (tabs) that contain other groups.
+You can create views (tabs) that contain other groups (but not other groups which are marked as `view: yes`).
Notice in the example below that in order to refer to the group "Living Room", you use `group.living_room` (lowercase and spaces replaced with underscores).
```yaml
@@ -86,7 +86,7 @@ Notice in the example below that in order to refer to the group "Living Room", y
entities:
- group.living_room
- group.bedroom
-```
+```
## {% linkable_title Default groups %}
@@ -118,7 +118,7 @@ group:
- group.all_scripts
```
-## {% linkable_title Group behaviour %}
+## {% linkable_title Group behavior %}
When any member of a group is `on` then the group will also be `on`. Similarly with a device tracker, when any member of the group is `home` then the group is `home`.
diff --git a/source/_components/hdmi_cec.markdown b/source/_components/hdmi_cec.markdown
index 43c95c45ada..198d89b01bc 100644
--- a/source/_components/hdmi_cec.markdown
+++ b/source/_components/hdmi_cec.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "HDMI CEC"
-description: "Instructions how to interact with HDMI CEC via Home Assistant."
+description: "Instructions on how to interact with HDMI CEC via Home Assistant."
date: 2016-06-24 19:59
sidebar: true
comments: false
@@ -31,32 +31,24 @@ If you are using [Hass.io](/hassio/) then just move forward to the configuration
#### {% linkable_title Symlinking into virtual environment %}
-Create a symlink to the `cec` installation. Keep in mind different installation methods will result in different locations of cec.
+Create a symlink to the `cec` installation including the _cec.so file. Keep in mind different installation methods will result in different locations of cec.
```bash
-$ ln -s /path/to/your/installation/of/cec /path/to/your/venv/lib/python3.4/site-packages
+$ ln -s /path/to/your/installation/of/cec /path/to/your/venv/lib/python*/site-packages
+$ ln -s /path/to/your/installation/of/_cec.so /path/to/your/venv/lib/python*/site-packages
+
```
+
##### {% linkable_title Symlinking examples: %}
For the default virtual environment of a [HASSbian Image for Raspberry Pi](/getting-started/installation-raspberry-pi-image/) the command would be as follows.
```bash
-$ ln -s /usr/local/lib/python3.4/dist-packages/cec /srv/homeassistant/lib/python3.4/site-packages
+$ ln -s /usr/local/lib/python*/dist-packages/cec /srv/homeassistant/lib/python*/site-packages
+$ ln -s /usr/local/lib/python*/dist-packages/_cec.so /srv/homeassistant/lib/python*/site-packages
+
```
-For the default virtual environment of a [Raspberry Pi All-In-One installation](/getting-started/installation-raspberry-pi-all-in-one/) the command would be as follows.
-
-```bash
-$ ln -s /usr/local/lib/python3.4/site-packages/cec /srv/homeassistant/homeassistant_venv/lib/python3.4/site-packages
-```
-
-For the default virtual environment of a [Manual installation](/getting-started/installation-raspberry-pi/) the command would be as follows.
-
-```bash
-$ ln -s /usr/local/lib/python3.4/site-packages/cec /srv/hass/hass_venv/lib/python3.4/site-packages
-```
-
-
`':
+ description: Additional options for specific entities.
+ required: false
+ type: map
+ keys:
+ name:
+ description: Name of entity to show in HomeKit. HomeKit will cache the name on the first run so a device must be removed and then re-added for any change to take effect.
+ required: false
+ type: string
+ code:
+ description: Code to `arm / disarm` an alarm or `lock / unlock` a lock. Only applicable for `alarm_control_panel` or `lock` entities.
+ required: false
+ type: string
+ default: '``'
+ feature_list:
+ description: Only for `media_player` entities. List of feature dictionaries to add for a given entity. Comparable to the platform schema.
+ required: false
+ type: list
+ keys:
+ feature:
+ description: Name of the feature to add to the entity representation. Valid features are `on_off`, `play_pause`, `play_stop` and `toogle_mute`. The media_player entity must support the feature to be valid.
+ required: true
+ type: string
+ type:
+ description: Only for `switch` entities. Type of accessory to be created within HomeKit. Valid types are `switch` and `outlet`. HomeKit will cache the type on the first run so a device must be removed and then re-added for any change to take effect.
+ required: false
+ type: string
+ default: '`switch`'
+{% endconfiguration %}
+
+
+2018-01-27 11:51:32 INFO (Thread-12) [pyhomematic.devicetypes.generic] HMGeneric.event: address=MEQ1234567:6, interface_id=homeassistant-CCU2, key=INSTALL_TEST, value=True
+```
+
+It may happen that "your_nice_name" is not resolved correctly; the according message (#2 in the above example) will be missing. This might be due to secure communication between your HM interface and the HM device. You can change the communication from "secure" to "standard" within your HM-interface to solve that issue (in "Einstellungen" - "Geräte" find your device and change "Übertragungsmodus" from secure to standard) - not recommended for devices that should have secure communication.
+
+#### {% linkable_title `homematic.keypress` events for HomeMatic IP devices %}
+
+To get the `homematic.keypress` event for some HomeMatic IP devices like WRC2 / WRC6 (wall switch) or SPDR (passage sensor) you have to temporary create an empty program for each channel in the CCU:
+
+1. In the menu of your CCU's admin panel go to `Programs and connections` > `Programs & CCU connection`
+2. Go to `New` in the footer menu
+3. Click the plus icon below `Condition: If...` and press the button `Device selection`
+4. Select one of the device's channels you need (1-2 / 1-6 for WRC2 / WRC6 and 2-3 for SPDR)
+5. Save the program with the `OK` button
+6. When your channel is working now, you can edit it to select the other channels one by one
+7. At the end, you can delete this program from the CCU
### {% linkable_title Services %}
-* *homematic.virtualkey*: Simulate a keypress (or other valid action) on CCU/Homegear with device or virtual keys.
-* *homematic.reconnect*: Reconnect to CCU/Homegear without restarting Home Assistant (useful when CCU has been restarted)
-* *homematic.set_var_value*: Set the value of a system variable.
-* *homematic.set_dev_value*: Control a device manually (even devices without support). Equivalent to setValue-method from XML-RPC.
+- *homematic.virtualkey*: Simulate a keypress (or other valid action) on CCU/Homegear with device or virtual keys.
+- *homematic.reconnect*: Reconnect to CCU/Homegear without restarting Home Assistant (useful when CCU has been restarted)
+- *homematic.set_variable_value*: Set the value of a system variable.
+- *homematic.set_device_value*: Control a device manually (even devices without support). Equivalent to setValue-method from XML-RPC.
#### {% linkable_title Examples %}
-Simulate a button being pressed
+
+Simulate a button being pressed:
+
```yaml
...
action:
@@ -169,7 +202,8 @@ action:
param: PRESS_LONG
```
-Open KeyMatic
+Open KeyMatic:
+
```yaml
...
action:
@@ -180,13 +214,14 @@ action:
param: OPEN
```
-Set boolean variable to true
+Set boolean variable to true:
+
```yaml
...
action:
- service: homematic.set_var_value
+ service: homematic.set_variable_value
data:
- entity_id: homematic.rf
+ entity_id: homematic.ccu2
name: Variablename
value: true
```
@@ -196,11 +231,12 @@ action:
If you are familiar with the internals of HomeMatic devices, you can manually set values on the devices. This can serve as a workaround if support for a device is currently not available, or only limited functionality has been implemented.
Using this service provides you direct access to the setValue-method of the primary connection. If you have multiple hosts, you may select the one hosting a specific device by providing the proxy-parameter with a value equivalent to the name you have chosen. In the example configuration from above `rf`, `wired` and `ip` would be valid values.
-Manually turn on a switch actor
+Manually turn on a switch actor:
+
```yaml
...
action:
- service: homematic.set_dev_value
+ service: homematic.set_device_value
data:
address: LEQ1234567
channel: 1
@@ -208,14 +244,89 @@ action:
value: true
```
-Manually set temperature on thermostat
+Manually set temperature on thermostat:
+
```yaml
...
action:
- service: homematic.set_dev_value
+ service: homematic.set_device_value
data:
address: LEQ1234567
channel: 4
param: SET_TEMPERATURE
value: 23.0
```
+
+Manually set lock on KeyMatic devices:
+
+```yaml
+...
+action:
+ service: lock.lock
+ entity_id: lock.leq1234567
+```
+
+Manually set unlock on KeyMatic devices:
+
+```yaml
+...
+action:
+ service: lock.unlock
+ entity_id: lock.leq1234567
+```
+
+#### {% linkable_title Detecting lost connections %}
+
+When the connection to your HomeMatic CCU or Homegear is lost, Home Assistant will stop getting updates from devices. This may happen after rebooting the CCU for example. Due to the nature of the communication protocol this cannot be handled automatically, so you must call *homematic.reconnect* in this case. That's why it is usually a good idea to check if your HomeMatic components are still updated properly, in order to detect connection losses. This can be done in several ways through an automation:
+
+- If you have a sensor which you know will be updated frequently (e.g. an outdoor temperature sensor or light sensor) you could set up an automation like this:
+
+ ```yaml
+ automation:
+ - alias: Homematic Reconnect
+ trigger:
+ platform: state
+ entity_id: sensor.outdoor_light_level
+ for:
+ hours: 3
+ action:
+ # Reconnect, if sensor has not been updated for over 3 hours
+ service: homematic.reconnect
+ ```
+
+- If you have a CCU you can also create a system variable on the CCU, which stores it's last reboot time. Since Home Assistant can still refresh system variables from the CCU (even after a reboot), this is a pretty reliable way to detect situations where you need to call *homematic.reconnect*. This is how this can be done:
+
+ 1. Create a string variable **V_Last_Reboot** on the CCU
+
+ 2. Creata a new programm on the CCU **without any conditions**, which executes the following *HM-Script* with a delay of 30 seconds:
+
+ ```javascript
+ var obj = dom.GetObject("V_Last_Reboot");
+ string now = system.Date("%d.%m.%Y %H:%M:%S");
+ obj.State(now);
+ ```
+
+ The HomeMatic CCU will execute all active programs which meet their conditions (none in this case) on every reboot.
+
+ 3. Set up a template sensor in Home Assistant, which contains the value of the system variable:
+
+ ```yaml
+ - platform: template
+ sensors:
+ v_last_reboot:
+ value_template: "{% raw %}{{ state_attr('homematic.ccu2', 'V_Last_Reboot') or '01.01.1970 00:00:00' }}{% endraw %}"
+ icon_template: "mdi:clock"
+ entity_id: homematic.ccu2
+ ```
+
+ 4. Set up an automation which calls *homematic.reconnect* whenever the sensor variable changes:
+
+ ```yaml
+ automation:
+ - alias: Homematic CCU Reboot
+ trigger:
+ platform: state
+ entity_id: sensor.v_last_reboot
+ action:
+ service: homematic.reconnect
+ ```
diff --git a/source/_components/homematicip_cloud.markdown b/source/_components/homematicip_cloud.markdown
new file mode 100644
index 00000000000..70f90d77af9
--- /dev/null
+++ b/source/_components/homematicip_cloud.markdown
@@ -0,0 +1,44 @@
+---
+layout: page
+title: "HomematicIP Cloud"
+description: "Instructions for integrating HomematicIP into Home Assistant."
+date: 2018-04-02 13:40
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: homematicip_cloud.png
+ha_category: Hub
+ha_iot_class: "Cloud Push"
+ha_release: 0.66
+featured: false
+---
+
+The [HomematicIP](http://www.homematic-ip.com) component platform is used as an interface to the cloud server.
+For for communication [homematicip-rest-api](https://github.com/coreGreenberet/homematicip-rest-api) is used.
+
+To set up the component:
+
+- generate the authentication token:
+```yaml
+generate_auth_token.py
+```
+
+- add the information to your `configuration.yaml` file:
+```yaml
+homematicip_cloud:
+ - accesspoint: IDENTIFIER
+ authtoken: AUTHTOKEN
+ - name: Location2
+ accesspoint: IDENTIFIER2
+ authtoken: AUTHTOKEN2
+```
+
+Configuration variables (global):
+
+- **name** (*Optional*): Name to identify your access point, this will be
+ used to prefix your device names.
+- **accesspoint** (*Required*): This is the access point id (SGTIN)
+- **authtoken** (*Required*): Authentification token generated with
+`generate_auth_token.py`.
+
diff --git a/source/_components/http.markdown b/source/_components/http.markdown
index e6e396109c0..0616476bf07 100644
--- a/source/_components/http.markdown
+++ b/source/_components/http.markdown
@@ -17,6 +17,10 @@ The `http` component serves all files and data required for the Home Assistant f
It is HIGHLY recommended that you set the `api_password`, especially if you are planning to expose your installation to the internet.
+/api//groups
+```
+
+The `` is the string that is used to register Home Assistant on the bridge, you can find it in the `phue.conf` file in your configuration path. `` is the IP address or hostname of your Hue bridge.
+
+You can find out the ids of your lights by executing the following command:
+
+```bash
+$ curl http:///api//lights
+```
+
+Home Assistant will automatically detect your new `LightGroup` and add it to the interface.
+
+ or \ eleements.
+Shown as inputs or outputs of products in the IHC application.
+You can also use inputs and outputs from function blocks.
+These are the \ and \ elements from the project file.
+
+The IHC resource id should be specified as an integer value. (In the project file the id will be specified as a hex number)
+
+If you want an easier way to get the IHC resource ids, you can download the [Alternative Service View application](https://www.dingus.dk/updated-ihc-alternative-service-view/).
+The application will show the product tree. You can expand it, select inputs and outputs and when selected you can see the resource id.
+
+See the manual of each device type for configuration options.
diff --git a/source/_components/image_processing.dlib_face_detect.markdown b/source/_components/image_processing.dlib_face_detect.markdown
index 6673146847d..f4275902565 100644
--- a/source/_components/image_processing.dlib_face_detect.markdown
+++ b/source/_components/image_processing.dlib_face_detect.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Dlib Face Detect"
-description: "Instructions how to integrate Dlib Face Detect into Home Assistant."
+description: "Instructions on how to integrate Dlib Face Detect into Home Assistant."
date: 2017-05-05 00:00
sidebar: true
comments: false
diff --git a/source/_components/image_processing.dlib_face_identify.markdown b/source/_components/image_processing.dlib_face_identify.markdown
index 1e47bf13e40..34690d6b8fd 100644
--- a/source/_components/image_processing.dlib_face_identify.markdown
+++ b/source/_components/image_processing.dlib_face_identify.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Dlib Face Identify"
-description: "Instructions how to integrate Dlib Face Identify into Home Assistant."
+description: "Instructions on how to integrate Dlib Face Identify into Home Assistant."
date: 2017-01-25 00:00
sidebar: true
comments: false
@@ -13,7 +13,7 @@ featured: false
ha_release: 0.44
---
-The `dlib_face_identify` image processing platform allows you to use the [Dlib](http://www.dlib.net/) through Home Assistant. This platform allow you to identify persons on camera and fire a event with identify persons.
+The `dlib_face_identify` image processing platform allows you to use the [Dlib](http://www.dlib.net/) through Home Assistant. This platform allow you to identify persons on camera and fire an event with identify persons.
For using the result inside an automation rule, take a look at the [component](/components/image_processing/) page.
@@ -36,3 +36,7 @@ Configuration variables:
- **entity_id** (*Required*): A camera entity id to get picture from.
- **name** (*Optional*): This parameter allows you to override the name of your `image_processing` entity.
- **faces** array (*Required*): List of faces sources.
+
+
`month`
`day` | The year, month and day of the date.
(only available if `has_date: true`) +| `hour`
`minute`
`second` | The hour, minute and second of the time.
(only available if `has_time: true`) +| `timestamp` | A timestamp representing the time held in the input.
If `has_date: true`, this is the UNIX timestamp of the date / time held by the input. Otherwise if only `has_time: true`, this is the number of seconds since midnight representing the time held by the input. + +### {% linkable_title Restore State %} + +This component will automatically restore the state it had prior to Home Assistant stopping as long as you have the `recorder` component enabled and your entity does **not** have a set value for `initial`. To disable this feature, set a valid value for `initial`. Additional information can be found in the [Restore state](/components/recorder/#restore-state) section of the [`recorder`](/components/recorder/) component documentation. + +### {% linkable_title Services %} + +This component provides a service to modify the state of the `input_datetime`. + +| Service | Data | Description | +| ----- | ----- | ----- | +| `set_datetime` | `time` | This can be used to dynamically set the time. +| `set_datetime` | `date` | This can be used to dynamically set the date. + +## {% linkable_title Automation Examples %} + +The following example shows the usage of the `input_datetime` as a trigger in an automation (note that you will need a [time sensor](/components/sensor.time_date/) elsewhere in your configuration): + +{% raw %} +```yaml +# Example configuration.yaml entry +# Turns on bedroom light at the time specified. +automation: + trigger: + platform: template + value_template: "{{ states('sensor.time') == (states.input_datetime.bedroom_alarm_clock_time.attributes.timestamp | int | timestamp_custom('%H:%M', False)) }}" + action: + service: light.turn_on + entity_id: light.bedroom +``` +{% endraw %} + +To dynamically set the `input_datetime` you can call `input_datetime.set_datetime`. The following example can be used in an automation rule: + +```yaml +# Example configuration.yaml entry +# Sets input_datetime to '05:30' when an input_boolean is turned on. +automation: + trigger: + platform: state + entity_id: input_boolean.example + to: 'on' + action: + service: input_datetime.set_datetime + entity_id: input_datetime.bedroom_alarm_clock_time + data: + time: '05:30:00' +``` diff --git a/source/_components/input_number.markdown b/source/_components/input_number.markdown index 9c041e1b7f3..9f7f65ed956 100644 --- a/source/_components/input_number.markdown +++ b/source/_components/input_number.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Number" -description: "Instructions how to integrate the Input Number component into Home Assistant." +description: "Instructions on how to integrate the Input Number component into Home Assistant." date: 2017-09-19 03:30 sidebar: true comments: false @@ -14,7 +14,7 @@ redirect_from: /components/input_slider/ ---
`entity_id(s)` | Set the options for specific `input_select` entities. +| `select_previous` | | Select the previous option. +| `select_next` | | Select the next option. + +### {% linkable_title Scenes %} + +To specify a target option in a [Scene](/components/scene/) you have to specify the target as `option` attribute: + +```yaml +# Example configuration.yaml entry +scene: + - name: Example1 + entities: + input_select.who_cooks: + option: Paulus +``` + +## {% linkable_title Automation Examples %} The following example shows the usage of the `input_select.select_option` service in an automation: @@ -87,23 +124,10 @@ automation: options: ["Item A", "Item B", "Item C"] ``` -### {% linkable_title Scenes %} - -To specify a target option in a [Scene](/components/scene/) you have to specify the target as `option` attribute: - -```yaml -# Example configuration.yaml entry -scene: - - name: Example1 - entities: - input_select.who_cooks: - option: Paulus -``` - Example of `input_select` being used in a bidirectional manner, both being set by and controlled by an MQTT action in an automation. -```yaml {% raw %} +```yaml # Example configuration.yaml entry using 'input_select' in an action in an automation # Define input_select @@ -129,7 +153,7 @@ input_select: service: input_select.select_option data_template: entity_id: input_select.thermostat_mode - option: '{{ trigger.payload }}' + option: "{{ trigger.payload }}" # This automation script runs when the thermostat mode selector is changed. # It publishes its value to the same MQTT topic it is also subscribed to. @@ -142,6 +166,6 @@ input_select: data_template: topic: "thermostatMode" retain: true - payload: '{{ states.input_select.thermostat_mode.state }}' -{% endraw %} + payload: "{{ states('input_select.thermostat_mode') }}" ``` +{% endraw %} diff --git a/source/_components/input_text.markdown b/source/_components/input_text.markdown index 26ad4846a74..187f08a0e46 100644 --- a/source/_components/input_text.markdown +++ b/source/_components/input_text.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Text" -description: "Instructions how to integrate the Input Text component into Home Assistant." +description: "Instructions on how to integrate the Input Text component into Home Assistant." date: 2016-03-15 06:00 sidebar: true comments: false @@ -12,7 +12,7 @@ ha_category: Automation ha_release: 0.53 --- -The `input_text` component allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. Changes to the value stored in the text box generate state events. These state events can be utilized as `automation` triggers as well. +The `input_text` component allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. Changes to the value stored in the text box generate state events. These state events can be utilized as `automation` triggers as well. It can also be configured in password mode (obscured text). ```yaml # Example configuration.yaml entries @@ -27,13 +27,48 @@ input_text: text3: name: Text 3 pattern: '[a-fA-F0-9]*' + text4: + name: Text 4 + mode: password ``` -Configuration variables: +{% configuration %} + input_text: + description: Alias for the input. Multiple entries are allowed. + required: true + type: map + keys: + name: + description: Friendly name of the text input. + required: false + type: String + min: + description: Minimum length for the text value. + required: false + type: int + default: 0 + max: + description: Maximum length for the text value. + required: false + type: int + default: 100 + initial: + description: Initial value when Home Assistant starts. + required: false + type: String + default: empty + pattern: + description: Regex pattern for client side validation. + required: false + type: String + default: empty + mode: + description: Can specify `text` or `password`. Elements of type "password" provide a way for the user to securely enter a value. + required: false + type: String + default: text +{% endconfiguration %} -- **[alias]** (*Required*): Alias for the text input. -- **min** (*Optional*): Minimum length for the text value. Default is `0`. -- **max** (*Optional*): Maximum length for the text value. Default is `100`. -- **name** (*Optional*): Friendly name of the text input. -- **initial** (*Optional*): Initial value when Home Assistant starts. Default is empty string. -- **pattern** (*Optional*): Regex pattern for client side validation. Default is empty string, which is treated same as `.*`. +### {% linkable_title Restore State %} + +This component will automatically restore the state it had prior to Home Assistant stopping as long as you have the `recorder` component enabled and your entity does **not** have a set value for `initial`. To disable this feature, set a valid value for `initial`. Additional information can be found in the [Restore state](/components/recorder/#restore-state) section of the [`recorder`](/components/recorder/) component documentation. diff --git a/source/_components/insteon_hub.markdown b/source/_components/insteon_hub.markdown deleted file mode 100644 index 03bf4b8a6ec..00000000000 --- a/source/_components/insteon_hub.markdown +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: page -title: "Insteon Hub" -description: "Instructions how to setup the Insteon Hub within Home Assistant." -date: 2016-01-27 08:00 -sidebar: true -comments: false -sharing: true -footer: true -logo: insteon.png -ha_category: Hub -ha_iot_class: "Cloud Polling" ---- - -
The logbook component provides a different perspective on the history of your house by showing all the changes that happened to your house in reverse chronological order. [See the demo for a live example](/demo/). It depends on the `recorder` component for storing the data. This means that if the [`recorder`](/components/recorder/) component is set up to use e.g. MySQL or PostgreSQL as data store, the `logbook` component does not use the default SQLite database to store data.
+ The logbook component provides a different perspective on the history of your house by showing all the changes that happened to your house in reverse chronological order. [See the demo for a live example](/demo/). It depends on the `recorder` component for storing the data. This means that if the [`recorder`](/components/recorder/) component is set up to use e.g., MySQL or PostgreSQL as data store, the `logbook` component does not use the default SQLite database to store data.
To enable the logbook in your installation, add the following to your `configuration.yaml` file:
@@ -26,8 +26,8 @@ Configuration variables:
- **entities** (*Optional*): The list of entity ids to be excluded from creating logbook entries.
- **domains** (*Optional*): The list of domains to be excluded from creating logbook entries.
- **include** (*Optional*): Configure which components should create logbook entries.
- - **entities** (*Optional*): The list of entity ids to be included from creating logbook entries.
- - **domains** (*Optional*): The list of domains to be included from creating logbook entries.
+ - **entities** (*Optional*): The list of entity ids to be included in creating logbook entries.
+ - **domains** (*Optional*): The list of domains to be included in creating logbook entries.
If you want to exclude messages of some entities or domains from the logbook just add the `exclude` parameter like:
@@ -73,7 +73,7 @@ logbook:
### {% linkable_title Exclude Events %}
-Entities customized as hidden are excluded from the logbook by default, but sometimes you want to show the entity in the UI and not in the logbook. For instance you use the `sensor.date`to show the current date in the UI, but you do not want an logbook entry for that sensor every day.
+Entities customized as hidden are excluded from the logbook by default, but sometimes you want to show the entity in the UI and not in the logbook. For instance you use the `sensor.date`to show the current date in the UI, but you do not want a logbook entry for that sensor every day.
To exclude these entities just add them to the `exclude` > `entities` list in the configuration of the logbook.
To exclude all events from a whole domain add it to the `exclude` > `domain` list. For instance you use the `sun` domain only to trigger automations on the `azimuth attribute, then you possible are not interested in the logbook entries for sun rise and sun set.
diff --git a/source/_components/logentries.markdown b/source/_components/logentries.markdown
index e14b908b871..b365e57f63d 100644
--- a/source/_components/logentries.markdown
+++ b/source/_components/logentries.markdown
@@ -11,7 +11,9 @@ footer: true
ha_category: "History"
---
-The `logentries` component makes it possible to log all state changes to [your Logentries account](http://logentries.com/) using Logentries Webhook endpoint and a token based log
+The `logentries` component makes it possible to log all state changes to [Logentries](http://logentries.com/) using Logentries Webhook endpoint.
+
+Open the **Add a Log** page and choose **Manual**. Enter a name for your log in **Log Name**, add a group in **Select Log Set**, set **Token TCP - logs are identified by a token.** and press **Create Log Token**. The generated token is required for the Home Assistant configuration.
To use the `logentries` component in your installation, add the following to your `configuration.yaml` file:
@@ -21,6 +23,10 @@ logentries:
token: TOKEN
```
-Configuration variables:
+{% configuration %}
+token:
+ description: The token for the log to use.
+ required: true
+ type: string
+{% endconfiguration %}
-- **token** (*Required*): Your Logentries log token.
diff --git a/source/_components/logger.markdown b/source/_components/logger.markdown
index 70168cf440b..d3cef23a013 100644
--- a/source/_components/logger.markdown
+++ b/source/_components/logger.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Logger"
-description: "Instructions how to enable the logger component for Home Assistant."
+description: "Instructions on how to enable the logger component for Home Assistant."
date: 2015-11-12 17:00
sidebar: true
comments: false
@@ -11,15 +11,16 @@ logo: home-assistant.png
ha_category: "Utility"
---
-The logger component lets you define the level of logging activities in Home Assistant.
+The `logger` component lets you define the level of logging activities in Home Assistant.
-To enable the logger in your installation, add the following to your `configuration.yaml` file:
+To enable the `logger` component in your installation, add the following to your `configuration.yaml` file:
-To have a full log and log everything only this entry is needed (without any qualifier):
```yaml
+# Example configuration.yaml entry
logger:
```
-To log all messages and ignore events lower than critical for specified components.
+
+To log all messages and ignore events lower than critical for specified components:
```yaml
# Example configuration.yaml entry
@@ -30,7 +31,7 @@ logger:
homeassistant.components.camera: critical
```
-To ignore all messages lower than critical and log event for specified components.
+To ignore all messages lower than critical and log event for specified components:
```yaml
# Example configuration.yaml entry
@@ -43,7 +44,25 @@ logger:
homeassistant.components.camera: critical
```
-Possible log severities are:
+{% configuration %}
+ default:
+ description: Default log level.
+ required: false
+ type: '[log_level](#log-levels)'
+ default: debug
+ logs:
+ description: List of components and their log level.
+ required: false
+ type: map
+ keys:
+ '<component_namespace>':
+ description: Logger namespace of the component.
+ type: '[log_level](#log-levels)'
+{% endconfiguration %}
+
+### {% linkable_title Log Levels %}
+
+Possible log severity levels are:
- critical
- fatal
@@ -53,11 +72,26 @@ Possible log severities are:
- info
- debug
- notset
-
+
+## {% linkable_title Services %}
+
+### {% linkable_title Service `set_default_level` %}
+
+You can alter the default log level (for components without a specified log
+level) using the service `logger.set_default_level`.
+
+An example call might look like this:
+
+```yaml
+service: logger.set_default_level
+data:
+ level: info
+```
+
### {% linkable_title Service `set_level` %}
You can alter log level for one or several components using the service
-``logger.set_level``. It accepts the same format as ``logs`` in the configuration.
+`logger.set_level`. It accepts the same format as `logs` in the configuration.
An example call might look like this:
@@ -68,7 +102,9 @@ data:
homeassistant.components.media_player.yamaha: debug
```
-The log information are stored in the [configuration directory](/docs/configuration/) as `home-assistant.log` and you can read it with the command-line tool `cat` or follow it dynamically with `tail -f`.
+The log information are stored in the [configuration directory](/docs/configuration/)
+as `home-assistant.log` and you can read it with the command-line tool `cat` or
+follow it dynamically with `tail -f`.
If you are a Hassbian user you can use the example below:
@@ -76,7 +112,8 @@ If you are a Hassbian user you can use the example below:
$ tail -f /home/homeassistant/.homeassistant/home-assistant.log
```
-If you are a Hass.io user you can use the example below, whenlogged in through the ssh addon:
+If you are a Hass.io user, you can use the example below, when logged in through
+the [SSH add-on](/addons/ssh/):
```bash
$ tail -f /config/home-assistant.log
diff --git a/source/_components/lutron.markdown b/source/_components/lutron.markdown
index c946160db1e..6799e1feb55 100644
--- a/source/_components/lutron.markdown
+++ b/source/_components/lutron.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Lutron"
-description: "Instructions how to use Lutron devices with Home Assistant."
+description: "Instructions on how to use Lutron devices with Home Assistant."
date: 2017-01-28 13:00
sidebar: true
comments: false
@@ -18,6 +18,8 @@ ha_iot_class: "Local Polling"
Presently, there's only support for communicating with the [RadioRA 2](http://www.lutron.com/en-US/Products/Pages/WholeHomeSystems/RadioRA2/Overview.aspx) Main Repeater and only handle light switches and dimmers.
+## {% linkable_title Configuration %}
+
When configured, the `lutron` component will automatically discover the rooms and their associated switches/dimmers as configured by the RadioRA 2 software from Lutron. Each room will be treated as a separate group.
To use Lutron RadioRA 2 devices in your installation, add the following to your `configuration.yaml` file using the IP address of your RadioRA 2 main repeater:
diff --git a/source/_components/lutron_caseta.markdown b/source/_components/lutron_caseta.markdown
index 912bd82dc41..9783766c89d 100644
--- a/source/_components/lutron_caseta.markdown
+++ b/source/_components/lutron_caseta.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Lutron Caseta"
-description: "Instructions how to use Lutron Caseta devices with Home Assistant."
+description: "Instructions on how to use Lutron Caseta devices with Home Assistant."
date: 2017-01-28 13:00
sidebar: true
comments: false
@@ -25,7 +25,7 @@ The currently supported Caseta devices are:
- Scenes as Home Assistant [scenes](/components/scene.lutron_caseta/)
- Lutron shades as Home Assistant [covers](/components/cover.lutron_caseta/)
-When configured, the `lutron_caseta` component will automatically discover the currently supported devices as setup in the Lutron Smart Bridge. The name assigned in the Lutron mobile app will be used to form the `entity_id` used in Home Assistant. e.g. a dimmer called 'Bedroom Lamp' becomes `light.bedroom_lamp` in Home Assistant.
+When configured, the `lutron_caseta` component will automatically discover the currently supported devices as setup in the Lutron Smart Bridge. The name assigned in the Lutron mobile app will be used to form the `entity_id` used in Home Assistant. e.g., a dimmer called 'Bedroom Lamp' becomes `light.bedroom_lamp` in Home Assistant.
To use Lutron Caseta devices in your installation, you must first log in to your Lutron account and generate a certificate that allows Home Assistant to connect to your bridge. This can be accomplished by downloading and executing [this script](/assets/get_lutron_cert.zip), which will generate three files: caseta.key, caseta.crt, caseta-bridge.crt when you run it. See the instructions at the top of the script for more information.
diff --git a/source/_components/mailbox.asterisk_mbox.markdown b/source/_components/mailbox.asterisk_mbox.markdown
index 25a0859aa92..07e50d287c1 100644
--- a/source/_components/mailbox.asterisk_mbox.markdown
+++ b/source/_components/mailbox.asterisk_mbox.markdown
@@ -1,15 +1,15 @@
---
layout: page
title: "Asterisk Voicemail Mailbox"
-description: "Instructions how to integrate an Asterisk Voicemail within Home Assistant."
+description: "Instructions on how to integrate an Asterisk Voicemail within Home Assistant."
date: 2017-06-30 18:30
sidebar: true
comments: false
sharing: true
footer: true
+logo: asterisk.png
ha_category: Mailbox
-ha_version: 0.51
+ha_release: 0.51
---
-The Asterisk Voicemail Mailbox provides visual and audio access to voicemail on the Asterisk PBX server. This mailbox is enabled automatically through the [Asterisk Voicemail component](/components/asterisk_mbox) configuration.
-
+The Asterisk Voicemail Mailbox provides visual and audio access to voicemail on the Asterisk PBX server. This mailbox is enabled automatically through the [Asterisk Voicemail component](/components/asterisk_mbox/) configuration.
diff --git a/source/_components/mailbox.markdown b/source/_components/mailbox.markdown
index 88ff203523f..c6d270fdad9 100644
--- a/source/_components/mailbox.markdown
+++ b/source/_components/mailbox.markdown
@@ -1,18 +1,17 @@
---
layout: page
title: "Mailbox"
-description: "Instructions how to setup your mailboxes with Home Assistant."
+description: "Instructions on how to setup your mailboxes with Home Assistant."
date: 2017-06-30 18:30
sidebar: true
comments: false
sharing: true
-ha_version: 0.51
footer: true
+ha_release: 0.51
---
-Mailboxes provide an list of messages with short information about each. Mailbox messages appear on a separate panel in the frontend.
+Mailboxes provide a list of messages with short information about each. Mailbox messages appear on a separate panel in the frontend.
Home Assistant currently supports only the [Asterisk Voicemail](/component/mailbox.asterisk_mbox) mailbox.
Each mailbox also provides an entity to indicate the number of messages available on the main page.
-
diff --git a/source/_components/mailgun.markdown b/source/_components/mailgun.markdown
index 835464dfd06..2f13d2c0625 100644
--- a/source/_components/mailgun.markdown
+++ b/source/_components/mailgun.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Mailgun"
-description: "Instructions how to add Mailgun mail notifications to Home Assistant."
+description: "Instructions on how to add Mailgun mail notifications to Home Assistant."
date: 2017-02-06 16:52
sidebar: true
comments: false
@@ -12,7 +12,7 @@ ha_category: Notifications
ha_release: 0.38
---
-The component supports push messages and generates events based on inbound data. To use, add a Route set to Store and Notify with a URL of the following form: `https:///api/mailgun?api_password=`
+The component supports push messages and generates events based on inbound data. To use, add a Route set to Store and Notify with a URL of the following form: `https:///api/mailgun?api_password=`
To send messages, use the [Mailgun notify platform][notify].
@@ -25,11 +25,10 @@ To send messages, use the [Mailgun notify platform][notify].
mailgun:
domain: mg.example.com
api_key: token-XXXXXXXXX
- sandbox: False
```
Configuration variables:
-- **domain** (*Optional*): This is the domain name to be used when sending out mail. Defaults to the first custom domain you have set up.
-- **sandbox** (*Optional*): Whether to use the sandboxed domain for outgoing mail. The `domain` item takes precedence over this. Defaults to `False`.
+- **domain** (*Required*): This is the domain name to be used when sending out mail. Defaults to the first custom domain you have set up.
- **api_key** (*Required*): This is the API token that has been generated in your Mailgun account.
+- **sandbox** (*Optional*): Whether to use the sandboxed domain for outgoing mail. The `domain` item takes precedence over this. Defaults to `False`.
diff --git a/source/_components/matrix.markdown b/source/_components/matrix.markdown
new file mode 100644
index 00000000000..75bd6da0e6a
--- /dev/null
+++ b/source/_components/matrix.markdown
@@ -0,0 +1,136 @@
+---
+layout: page
+title: "Matrix"
+description: "Matrix chatbot support"
+date: 2018-03-25 18:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: matrix.png
+ha_category: Hub
+ha_release: 0.69
+---
+
+This component allows you to send messages to matrix rooms, as well as to react to messages in matrix rooms. Reacting to commands is accomplished by firing an event when one of the configured commands is triggered.
+
+```yaml
+# Example configuration.yaml entry
+matrix:
+ homeserver: https://matrix.org
+ username: "@my_matrix_user:matrix.org"
+ password: supersecurepassword
+ rooms:
+ - "#hasstest:matrix.org"
+ commands:
+ - word: my_command
+ name: my_command
+```
+
+Configuration variables:
+
+{% configuration %}
+username:
+ description: "The matrix username that Home Assistant should use to log in. *Note*: You must specify a full matrix ID here, including the homeserver domain, e.g. '@my_matrix_bot:matrix.org'. Please note also that the '@' character has a special meaning in YAML, so this must always be given in quotes."
+ required: true
+ type: string
+password:
+ description: The password for your Matrix account.
+ required: true
+ type: string
+homeserver:
+ description: "The full URL for your homeserver. If you use the default matrix.org homeserver, this is 'https://matrix.org'."
+ required: true
+ type: string
+verify_ssl:
+ description: Verify the homeservers certificate.
+ required: false
+ type: string
+ default: true
+rooms:
+ description: "The list of rooms that the bot should join and listen for commands (see below) in. While you can limit the list of rooms that a certain command applies to on a per-command basis (see below), you must still list all rooms here that commands should be received in. Rooms can be given either by their internal ID (e.g., '!cURbafjkfsMDVwdRDQ:matrix.org') or any of their aliases (e.g., '#matrix:matrix.org')."
+ required: false
+ type: [string]
+ default: empty
+commands:
+ description: "A list of commands that the bot should listen for. If a command is triggered (via its *word* or *expression*, see below), an event is fired that you can handle using automations. Every command consists of these possible configuration options:"
+ required: false
+ type: map
+ default: empty
+ keys:
+ word:
+ description: "Specifies a word that the bot should listen for. If you specify 'my_command' here, the bot will react to any message starting with '!my_command'."
+ required: false
+ type: string
+ expression:
+ description: "Specifies a regular expression (in python regexp syntax) that the bot should listen to. The bot will react to any message that matches the regular expression."
+ required: false
+ type: string
+ name:
+ description: "The name of the command. This will be an attribute of the event that is fired when this command triggers."
+ required: true
+ type: string
+ rooms:
+ description: "A list of rooms that the bot should listen for this command in. If this is not given, the *rooms* list from the main config is used. Please note that every room in this list must also be in the main *room* config."
+ required: false
+ type: [string]
+ default: empty
+{% endconfiguration %}
+
+### {% linkable_title Event Data %}
+
+If a command is triggered, a `matrix_command` event is fired. The event contains the name of the command in the `name` field.
+
+If the command is a word command, the `data` field contains a list of the command's arguments, i.e., everything that stood behind the word, split at spaces. If the command is an expression command, the `data` field contains the [group dictionary](https://docs.python.org/3.6/library/re.html?highlight=re#re.match.groupdict) of the regular expression that matched the message.
+
+### {% linkable_title Comprehensive Configuration Example %}
+
+This example also uses the [matrix `notify` platform](/components/notify.matrix/).
+
+```yaml
+# The Matrix component
+matrix:
+ homeserver: https://matrix.org
+ username: "@my_matrix_user:matrix.org"
+ password: supersecurepassword
+ rooms:
+ - "#hasstest:matrix.org"
+ - "#someothertest:matrix.org"
+ commands:
+ - word: testword
+ rooms:
+ - "#someothertest:matrix.org"
+ - expression: "My name is (?P.*)"
+ name: introduction
+
+notify:
+ - name: matrix_notify
+ platform: matrix
+ default_room: "#hasstest:matrix.org"
+
+automation:
+ - alias: 'React to !testword'
+ trigger:
+ platform: event
+ event_type: matrix_command
+ event_data:
+ command: testword
+ action:
+ service: notify.matrix_notify
+ data:
+ message: 'It looks like you wrote !testword'
+ - alias: 'React to an introduction'
+ trigger:
+ platform: event
+ event_type: matrix_command
+ event_data:
+ command: introduction
+ action:
+ service: notify.matrix_notify
+ data_template:
+ message: "Hello {{trigger.event.data.name}}"
+```
+
+This configuration will:
+- Listen for "!testword" in the room "#someothertest:matrix.org" (and *only*) there. If such a message is encountered, it will answer with "It looks like you wrote !testword" into the "#hasstest:matrix.org" channel.
+- Listen in both rooms for any message matching "My name is " and answer with "Hello " into "#hasstest:matrix.org".
diff --git a/source/_components/maxcube.markdown b/source/_components/maxcube.markdown
index c26cbe114bc..7439d2d19fe 100644
--- a/source/_components/maxcube.markdown
+++ b/source/_components/maxcube.markdown
@@ -25,13 +25,42 @@ Supported Devices:
- MAX! Window Sensor (tested)
- MAX! Wall Thermostat (tested)
+### {% linkable_title One Gateway %}
+
A `maxcube` section must be present in the `configuration.yaml` file and contain the following options as required:
```yaml
# Example configuration.yaml entry
maxcube:
- host: 192.168.0.20
+ gateways:
+ - host: 192.168.0.20
```
-Configuration variables:
-- **host** (*Required*): The IP address of the eQ-3 MAX! Cube to use.
-- **port** (*Optional*): The UDP port number. Defaults to `62910`.
+
+### {% linkable_title Multiple Gateways %}
+
+```yaml
+# Example configuration.yaml entry
+maxcube:
+ gateways:
+ - host: 192.168.0.20
+ port: 62910
+ - host: 192.168.0.21
+ port: 62910
+```
+
+{% configuration %}
+ host:
+ description: The IP address of the eQ-3 MAX! Cube to use.
+ required: true
+ type: string
+ port:
+ description: The UDP port number.
+ required: false
+ type: int
+ default: 62910
+ scan_interval:
+ description: The update interval in seconds
+ required: false
+ type: int
+ default: 300
+{% endconfiguration %}
diff --git a/source/_components/media_extractor.markdown b/source/_components/media_extractor.markdown
index 114d70f3fe7..8386b0390a3 100644
--- a/source/_components/media_extractor.markdown
+++ b/source/_components/media_extractor.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Media Extractor"
-description: "Instructions how to integrate the Media Extractor into Home Assistant."
+description: "Instructions on how to integrate the Media Extractor into Home Assistant."
date: 2017-07-12 07:00
sidebar: true
comments: false
diff --git a/source/_components/media_player.anthemav.markdown b/source/_components/media_player.anthemav.markdown
index 945fdc0c648..8e59296db99 100644
--- a/source/_components/media_player.anthemav.markdown
+++ b/source/_components/media_player.anthemav.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Anthem A/V Receivers"
-description: "Instructions how to integrate Anthem A/V Receivers into Home Assistant."
+description: "Instructions on how to integrate Anthem A/V Receivers into Home Assistant."
date: 2016-12-31 23:11
sidebar: true
comments: false
diff --git a/source/_components/media_player.apple_tv.markdown b/source/_components/media_player.apple_tv.markdown
index 383afdae981..7b163077602 100644
--- a/source/_components/media_player.apple_tv.markdown
+++ b/source/_components/media_player.apple_tv.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Apple TV Media Player"
-description: "Instructions how to integrate Apple TV devices into Home Assistant."
+description: "Instructions on how to integrate Apple TV devices into Home Assistant."
date: 2017-02-08 07:11
sidebar: true
comments: false
diff --git a/source/_components/media_player.aquostv.markdown b/source/_components/media_player.aquostv.markdown
index c9d7d2124d3..0e3dbcba7e0 100644
--- a/source/_components/media_player.aquostv.markdown
+++ b/source/_components/media_player.aquostv.markdown
@@ -53,5 +53,6 @@ Currently known supported models:
- LC-60LE925UN
- LC-60LE857U
- LC-60EQ10U
+- LC-60SQ15U
If your model is not on the list then give it a test, if everything works correctly then add it to the list on [GitHub](https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_components/media_player.aquostv.markdown).
diff --git a/source/_components/media_player.blackbird.markdown b/source/_components/media_player.blackbird.markdown
new file mode 100644
index 00000000000..fbd5fb20edc
--- /dev/null
+++ b/source/_components/media_player.blackbird.markdown
@@ -0,0 +1,65 @@
+---
+layout: page
+title: "Blackbird 8x8 HDMI Matrix Switch"
+description: "Instructions on how to integrate Monoprice Blackbird 4k 8x8 HDBaseT Matrix Switch into Home Assistant."
+date: 2018-03-29 16:35
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: monoprice.svg
+ha_category: Media Player
+ha_release: 0.68
+ha_iot_class: "Local Polling"
+---
+
+The `blackbird` platform allows you to control [Monoprice Blackbird Matrix Switch](https://www.monoprice.com/product?p_id=21819) using a serial connection.
+
+To add a Blackbird device to your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+media_player:
+ - platform: blackbird
+ port: /dev/ttyUSB0
+ zones:
+ 1:
+ name: Living Room
+ sources:
+ 3:
+ name: BluRay
+```
+
+{% configuration %}
+port:
+ description: The serial port to which Blackbird matrix switch is connected. [`port`](#port) and [`host`](#host) cannot be specified concurrently.
+ required: exclusive
+ type: string
+host:
+ description: The IP address of the Blackbird matrix switch. [`port`](#port) and [`host`](#host) cannot be specified concurrently.
+ required: exclusive
+ type: string
+zones:
+ description: This is the list of zones available. Valid zones are 1, 2, 3, 4, 5, 6, 7, 8. Each zone must have a name assigned to it.
+ required: true
+ type: int
+ keys:
+ name:
+ description: The name of the zone.
+sources:
+ description: The list of sources available. Valid source numbers are 1, 2, 3, 4, 5, 6, 7, 8. Each source number corresponds to the input number on the Blackbird matrix switch. Similar to zones, each source must have a name assigned to it.
+ required: true
+ type: int
+ keys:
+ name:
+ description: The name of the source.
+{% endconfiguration %}
+
+### {% linkable_title Service `media_player.blackbird_set_all_zones` %}
+
+Set all zones to the same input source. This service allows you to immediately synchronize all the TVs in your home. Regardless of `entity_id` provided, all zones will be updated.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String that points at an `entity_id` of a zone.
+| `source` | no | String of source name to activate.
diff --git a/source/_components/media_player.bluesound.markdown b/source/_components/media_player.bluesound.markdown
index f711cbe8971..69372c8c332 100644
--- a/source/_components/media_player.bluesound.markdown
+++ b/source/_components/media_player.bluesound.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Bluesound"
-description: "Instructions how to integrate Bluesound devices into Home Assistant."
+description: "Instructions on how to integrate Bluesound devices into Home Assistant."
date: 2017-04-21 19:00
sidebar: true
comments: false
@@ -46,3 +46,37 @@ media_player:
port: 11000
- host: 192.168.1.131
```
+
+### {% linkable_title Service `bluesound_join` %}
+
+Group players together under a single master speaker. That will make a new group or join to exists group.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `master` | no | A single `entity_id` that will become/hold the master speaker.
+| `entity_id` | no | String or list of a single `entity_id` that will group to master speaker.
+
+### {% linkable_title Service `bluesound_unjoin` %}
+
+Remove one or more speakers from a group of speakers. If no `entity_id` is provided, all speakers are unjoined.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String or list of `entity_id`s that will be separated from their master speaker.
+
+### {% linkable_title Service `bluesound_set_sleep_timer` %}
+
+Sets a timer that will turn off the speaker. For each time you call this it will increase the time by one step. The steps are (in minutes): 15, 30, 45, 60, 90, 0.
+If you increase an ongoing timer of for example 13 minutes, it will increase it to 15. If the timer is set to 90, it will remove the time (hence the 0).
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | no | String or list of `entity_id`s that will have their timers set.
+
+### {% linkable_title Service `bluesound_clear_sleep_timer` %}
+
+Clear the sleep timer on a speaker, if one is set.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | no | String or list of `entity_id`s that will have their timers cleared.
diff --git a/source/_components/media_player.cast.markdown b/source/_components/media_player.cast.markdown
deleted file mode 100644
index 52d0e1d39c0..00000000000
--- a/source/_components/media_player.cast.markdown
+++ /dev/null
@@ -1,31 +0,0 @@
----
-layout: page
-title: "Google Cast"
-description: "Instructions how to integrate Google Cast into Home Assistant."
-date: 2015-03-23 19:59
-sidebar: true
-comments: false
-sharing: true
-footer: true
-logo: google_cast.png
-ha_category: Media Player
-featured: true
-ha_release: pre 0.7
-ha_iot_class: "Local Polling"
----
-
-
-Google Cast devices like Android TVs and Chromecasts will be automatically discovered if you enable [the discovery component]({{site_root}}/components/discovery/). There is a issue where Chromecasts can only be discovered if your device is connected to the same subnet as your Chromecast.
-
-Chromecast platform can also be forced to load by adding the following lines to your `configuration.yaml`:
-
-```yaml
-# Example configuration.yaml entry
-media_player:
- - platform: cast
-```
-
-Configuration variables:
-
-- **host** (*Optional*): Use only if you don't want to scan for devices.
-- **ignore_cec** (*Optional*) A list of chromecasts that should ignore CEC data for determining the active input. [See the upstream documentation for more information.](https://github.com/balloob/pychromecast#ignoring-cec-data)
diff --git a/source/_components/media_player.channels.markdown b/source/_components/media_player.channels.markdown
new file mode 100644
index 00000000000..12138976e26
--- /dev/null
+++ b/source/_components/media_player.channels.markdown
@@ -0,0 +1,61 @@
+---
+layout: page
+title: "Channels"
+description: "Instructions on how to integrate Channels into Home Assistant."
+date: 2018-03-06 11:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: channels.png
+ha_category: Media Player
+ha_release: 0.65.0
+ha_iot_class: "Local Polling"
+---
+
+
+The Channels platform allows you to control [Channels](https://getchannels.com/) from Home Assistant. Play, pause, seek, or skip commercials on an instance of Channels that is running on your network.
+
+Your favorite channels will appear as sources in the Source List in Home Assistant.
+
+To add Channels to your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+media_player:
+ - platform: channels
+ name: Family Room Channels
+ host: 192.168.1.50
+```
+
+Configuration variables:
+
+- **host** (*Required*): The IP of the device running Channels, e.g., 192.168.1.50
+- **port** (*Optional*): The port where Channels is accessible, defaults to 57000.
+- **name** (*Optional*): The name of the Channels instance in Home Assistant, eg. Family Room Channels. Defaults to Channels.
+
+### {% linkable_title Service `channels_seek_forward` %}
+
+Seek forward by the number of seconds currently set in settings on the instance of Channels.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | no | String that points at `entity_id` of Channels app.
+
+
+### {% linkable_title Service `channels_seek_backward` %}
+
+Seek backward by the number of seconds currently set in settings on the instance of Channels.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | no | String that points at `entity_id` of Channels app.
+
+### {% linkable_title Service `channels_seek_by` %}
+
+Seek forward or backward by a provided number of seconds.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | no | String that points at `entity_id` of Channels app.
+| `seconds` | no | Number of seconds to seek in the timeline by. Negative seconds seeks backwards.
diff --git a/source/_components/media_player.clementine.markdown b/source/_components/media_player.clementine.markdown
index c730daf5d96..781ac147a56 100644
--- a/source/_components/media_player.clementine.markdown
+++ b/source/_components/media_player.clementine.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Clementine Music Player"
-description: "Instructions how to integrate Clementine Music Player within Home Assistant."
+description: "Instructions on how to integrate Clementine Music Player within Home Assistant."
date: 2017-02-11 17:15
sidebar: true
comments: false
diff --git a/source/_components/media_player.cmus.markdown b/source/_components/media_player.cmus.markdown
index e798889686c..1415de1e547 100644
--- a/source/_components/media_player.cmus.markdown
+++ b/source/_components/media_player.cmus.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "cmus"
-description: "Instructions how to integrate cmus Music Player into Home
+description: "Instructions on how to integrate cmus Music Player into Home
Assistant."
date: 2016-06-17 18:45
sidebar: true
@@ -23,19 +23,19 @@ media_player:
- platform: cmus
```
-if cmus is running on a remote server:
+If cmus is running on a remote server:
```yaml
# Example configuration.yaml entry
media_player:
- platform: cmus
- host: IP_ADDRESS
- password: PASSWORD
+ host: IP_ADDRESS_OF_CMUS_PLAYER
+ password: YOUR_PASSWORD
```
Configuration variables:
-- **host** (*Optional*): Hostname or IP address of the machine running cmus. Note if a remote cmus is configured that instance must be configured to listen to remote connections, which also requires a password to be set.
+- **host** (*Optional*): Hostname or IP address of the machine running cmus. Note if a remote cmus is configured that instance must be configured to listen to remote connections, which also requires a password to be set.
- **password** (*Required if host is set*): Password for your cmus player.
- **port** (*Optional*): Port of the cmus socket, defaults to 3000.
- **name** (*Optional*): The name you'd like to give the cmus player in Home Assistant
diff --git a/source/_components/media_player.denon.markdown b/source/_components/media_player.denon.markdown
index b8c0e380133..ebfe0177bae 100644
--- a/source/_components/media_player.denon.markdown
+++ b/source/_components/media_player.denon.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Denon Network Receivers"
-description: "Instructions how to integrate Denon Network Receivers into Home Assistant."
+description: "Instructions on how to integrate Denon Network Receivers into Home Assistant."
date: 2015-09-08 09:00
sidebar: true
comments: false
diff --git a/source/_components/media_player.denonavr.markdown b/source/_components/media_player.denonavr.markdown
index a64c85c44b3..6c4d2d81957 100644
--- a/source/_components/media_player.denonavr.markdown
+++ b/source/_components/media_player.denonavr.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Denon AVR Network Receivers"
-description: "Instructions how to integrate Denon AVR Network Receivers into Home Assistant."
+description: "Instructions on how to integrate Denon AVR Network Receivers into Home Assistant."
date: 2015-09-08 09:00
sidebar: true
comments: false
@@ -13,11 +13,11 @@ ha_iot_class: "Local Polling"
ha_release: 0.7.2
---
-
The `denonavr` platform allows you to control a [Denon Network Receivers](http://www.denon.co.uk/chg/product/compactsystems/networkmusicsystems/ceolpiccolo) from Home Assistant. It might be that your device is supported by the [Denon] platform.
Supported devices:
+- Denon AVR-X1300W
- Denon AVR-X2000
- Denon AVR-X2100W
- Denon AVR-X4100W
@@ -29,6 +29,7 @@ Supported devices:
- Marantz M-RC610
- Marantz SR5008
- Marantz SR6007 - SR6010
+- Marantz NR1506
- Marantz NR1604
- Other Denon AVR receivers (untested)
- Marantz receivers (experimental)
@@ -54,18 +55,19 @@ media_player:
Configuration variables:
-- **host** (*Optional*): IP address of the device. Example: 192.168.1.32. If not set, auto discovery is used.
-- **name** (*Optional*): Name of the device. If not set, friendlyName of receiver is used.
-- **show_all_sources** (*Optional*): If True all sources are displayed in sources list even if they are marked as deleted in the receiver. If False deleted sources are not displayed (default). Some receivers have a bug that marks all sources as deleted in the interface. In this case this option could help.
+- **host** (*Optional*): IP address of the device. Example: 192.168.1.32. If not set, auto-discovery is used.
+- **name** (*Optional*): Name of the device. If not set, friendlyName of the receiver is used.
+- **show_all_sources** (*Optional*): If True all sources are displayed in sources list even if they are marked as deleted in the receiver. If False deleted sources are not displayed (default). Some receivers have a bug that marks all sources as deleted in the interface. In this case, this option could help.
- **timeout** (*Optional*): Timeout for HTTP requests to the receiver. Defaults to 2 seconds if not provided.
- **zones** (*Optional*): List of additional zones to be activated. They are displayed as additional media players with the same functionality Main Zone of the device supports
- **zone**: Zone which should be activated. Valid options are Zone2 and Zone3
- - **name** (*Optional*): Name of the zone. If not set the name of the main device + zone as suffix is taken.
+ - **name** (*Optional*): Name of the zone. If not set the name of the main device + zone as a suffix is taken.
A few notes:
-- Additional option the control Denon AVR receivers with a builtin web server is using the HTTP interface with denonavr platform.
-- denonavr platform supports some additional functionalities like album covers, custom input source names and auto discovery.
-- Marantz receivers seem to a have quite simliar interface. Thus if you own one, give it a try.
+- An additional option for the control of Denon AVR receivers with a built-in web server is using the HTTP interface with `denonavr` platform.
+- The `denonavr` platform supports some additional functionalities like album covers, custom input source names and auto discovery.
+- Marantz receivers seem to a have quite a similar interface. Thus if you own one, give it a try.
+- Sound mode: The command to set a specific sound mode is different from the value of the current sound mode reported by the receiver (sound_mode_raw). There is a key-value structure (sound_mode_dict) that matches the raw sound mode to one of the possible commands to set a sound mode (for instance {'MUSIC':['PLII MUSIC']}. If you get a "Not able to match sound mode" warning, please open an issue on the [denonavr library](https://github.com/scarface-4711/denonavr), stating which raw sound mode could not be matched so it can be added to the matching dictionary. You can find the current raw sound mode under "Development Tools/States" in the front panel.
[Denon]: /components/media_player.denon/
diff --git a/source/_components/media_player.directv.markdown b/source/_components/media_player.directv.markdown
index 2cd2c7f44dd..f7f6559619e 100644
--- a/source/_components/media_player.directv.markdown
+++ b/source/_components/media_player.directv.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "DirecTV"
-description: "Instructions how to integrate DirecTV receivers into Home Assistant."
+description: "Instructions on how to integrate DirecTV receivers into Home Assistant."
date: 2016-07-19 01:0+0000
sidebar: true
comments: false
diff --git a/source/_components/media_player.dunehd.markdown b/source/_components/media_player.dunehd.markdown
index 76c084bcf48..bbf646f0fb9 100644
--- a/source/_components/media_player.dunehd.markdown
+++ b/source/_components/media_player.dunehd.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "DuneHD media players"
-description: "Instructions how to integrate DuneHD media players into Home Assistant."
+description: "Instructions on how to integrate DuneHD media players into Home Assistant."
date: 2016-11-26 09:00
sidebar: true
comments: false
diff --git a/source/_components/media_player.emby.markdown b/source/_components/media_player.emby.markdown
index ca77cbde1a3..2f12bc1d808 100644
--- a/source/_components/media_player.emby.markdown
+++ b/source/_components/media_player.emby.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Emby"
-description: "Instructions how to integrate Emby into Home Assistant."
+description: "Instructions on how to integrate Emby into Home Assistant."
date: 2016-10-13 22:00
sidebar: true
comments: false
diff --git a/source/_components/media_player.epson.markdown b/source/_components/media_player.epson.markdown
new file mode 100644
index 00000000000..e24397901d7
--- /dev/null
+++ b/source/_components/media_player.epson.markdown
@@ -0,0 +1,63 @@
+---
+layout: page
+title: "Epson"
+description: "Instructions on how to integrate Epson projector into Home Assistant."
+date: 2018-06-13 15:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: epson.png
+ha_category: Media Player
+ha_release: 0.72
+ha_iot_class: "Local Polling"
+---
+
+The `epson` platform allows you to control a Epson projector from Home Assistant.
+
+To add Epson to your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+media_player:
+ - platform: epson
+ host: 192.168.0.123
+```
+
+{% configuration %}
+host:
+ description: The host name or address of the Epson projector
+ required: true
+ type: string
+port:
+ description: The HTTP port number.
+ required: false
+ type: int
+ default: 80
+name:
+ description: The name of the device used in the frontend.
+ required: false
+ type: string
+ default: 'EPSON Projector'
+ssl:
+ description: Enable SSL. **Feature not tested.**
+ required: false
+ type: bool
+ default: false
+{% endconfiguration %}
+
+Supported features of Epson projector:
+- turn on/off
+- set input
+- set/get color mode
+- increase/decrease volume
+- mute/unmute audio
+- send next/previous track
+
+Supported devices:
+- Epson projectors supporting ESC/VP21 protocol.
+
+Tested devices:
+- Epson EH-TW5350
+
+To make this module work you need to connect your projector to your LAN. The best is to use iProjection app by Epson to test if it is working.
diff --git a/source/_components/media_player.firetv.markdown b/source/_components/media_player.firetv.markdown
index 855333def81..0abf2b3dadc 100644
--- a/source/_components/media_player.firetv.markdown
+++ b/source/_components/media_player.firetv.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "FireTV"
-description: "Instructions how to integrate Fire-TV into Home Assistant."
+description: "Instructions on how to integrate Fire-TV into Home Assistant."
date: 2015-10-23 18:00
sidebar: true
comments: false
@@ -16,7 +16,7 @@ ha_iot_class: "Local Polling"
The `firetv` platform allows you to control a [Amazon Fire TV/stick](http://www.amazon.com/Amazon-DV83YW-Fire-TV/dp/B00U3FPN4U).
-The python-firetv Python 2.x module with its helper script that exposes a HTTP server to fetch state and perform actions is used.
+The python-firetv Python 2.x module with its helper script that exposes an HTTP server to fetch state and perform actions is used.
Steps to configure your Amazon Fire TV stick with Home Assistant:
diff --git a/source/_components/media_player.frontier_silicon.markdown b/source/_components/media_player.frontier_silicon.markdown
index 0c6a5843fa9..c7887e9c8b7 100644
--- a/source/_components/media_player.frontier_silicon.markdown
+++ b/source/_components/media_player.frontier_silicon.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Frontier Silicon Internet Radios"
-description: "Instructions how to integrate Frontier Silicon Internet Radios into Home Assistant."
+description: "Instructions on how to integrate Frontier Silicon Internet Radios into Home Assistant."
date: 2017-02-04 00:01
sidebar: true
comments: false
diff --git a/source/_components/media_player.gpmdp.markdown b/source/_components/media_player.gpmdp.markdown
index 7207e0e0924..c65ed0dff0f 100644
--- a/source/_components/media_player.gpmdp.markdown
+++ b/source/_components/media_player.gpmdp.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Google Play Music Desktop Player"
-description: "Instructions how to integrate GPMDP into Home Assistant."
+description: "Instructions on how to integrate GPMDP into Home Assistant."
date: 2016-05-09 08:00
sidebar: true
comments: false
diff --git a/source/_components/media_player.gstreamer.markdown b/source/_components/media_player.gstreamer.markdown
index c77e8c40496..288ef12120c 100644
--- a/source/_components/media_player.gstreamer.markdown
+++ b/source/_components/media_player.gstreamer.markdown
@@ -58,7 +58,7 @@ If you're running Home Assistant in a virtual environment, you'll need to symlin
ln -s /path/to/your/installation/of/gi /path/to/your/venv/lib/python3.4/site-packages
```
-On a Raspberry PI, you may need to add the Home Assistant user to the `audio` group:
+On a Raspberry Pi, you may need to add the Home Assistant user to the `audio` group:
```bash
sudo usermod -a -G audio
@@ -68,7 +68,7 @@ sudo usermod -a -G audio
### {% linkable_title Using with TTS %}
-To play TTS on your local computer (for example, if you have speakers attached to your Raspberry PI:
+To play TTS on your local computer (for example, if you have speakers attached to your Raspberry Pi:
```yaml
media_player:
diff --git a/source/_components/media_player.horizon.markdown b/source/_components/media_player.horizon.markdown
new file mode 100644
index 00000000000..d867d348c9e
--- /dev/null
+++ b/source/_components/media_player.horizon.markdown
@@ -0,0 +1,45 @@
+---
+layout: page
+title: "Horizon HD Recorder"
+description: "Instructions how to integrate the Unitymedia Horizon HD Recorder into Home Assistant."
+date: 2018-05-02 20:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: unitymedia.png
+ha_category: Media Player
+ha_iot_class: "Local Polling"
+ha_release: 0.72
+---
+
+The `horizon` component allows you to control a [Unitymedia](https://www.unitymedia.de) Horizon HD Recorder from Home Assistant.
+
+To add a Horizon HD Recorder to your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+media_player:
+ - platform: horizon
+ host: 192.168.0.127
+```
+
+{% configuration %}
+ host:
+ description: The hostname or address of the device.
+ required: true
+ type: string
+ port:
+ description: The port of the device to connect to.
+ required: false
+ type: int
+ name:
+ description: The name of the device used in the frontend.
+ required: false
+ type: string
+{% endconfiguration %}
+
+
+#### {% linkable_title Preparation of the Horizon HD Recorder %}
+
+The Home Networking ("Heimnetzwerk") service needs to be enabled at the settings menu of the Horizon receiver. Once you have set up the Media Library ("Medienbibliothek"), we can determine whether the device is turned on or off. Without this, the component will fail to start.
diff --git a/source/_components/media_player.itunes.markdown b/source/_components/media_player.itunes.markdown
index fd357eb8ec7..6885a333855 100644
--- a/source/_components/media_player.itunes.markdown
+++ b/source/_components/media_player.itunes.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "iTunes"
-description: "Instructions how to integrate iTunes into Home Assistant."
+description: "Instructions on how to integrate iTunes into Home Assistant."
date: 2015-06-22 11:00
sidebar: true
comments: false
diff --git a/source/_components/media_player.kodi.markdown b/source/_components/media_player.kodi.markdown
index 556812292c6..83689d4c1ae 100644
--- a/source/_components/media_player.kodi.markdown
+++ b/source/_components/media_player.kodi.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Kodi"
-description: "Instructions how to integrate Kodi into Home Assistant."
+description: "Instructions on how to integrate Kodi into Home Assistant."
date: 2015-06-22 11:00
sidebar: true
comments: false
@@ -17,7 +17,9 @@ ha_iot_class: "Local Push"
The `kodi` platform allows you to control a [Kodi](http://kodi.tv/) multimedia system from Home Assistant.
-To add Kodi to your installation, add the following to your `configuration.yaml` file:
+The preferred way to set up the Kodi platform is by enabling the [discovery component](https://www.home-assistant.io/components/discovery/) which requires enabled [web interface](https://kodi.wiki/view/Web_interface) on your Kodi installation.
+
+In case the discovery does not work, or you need specific configuration variables, you can add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
diff --git a/source/_components/media_player.lg_netcast.markdown b/source/_components/media_player.lg_netcast.markdown
index 138eaec8bde..7a60e235781 100644
--- a/source/_components/media_player.lg_netcast.markdown
+++ b/source/_components/media_player.lg_netcast.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "LG Netcast TV"
-description: "Instructions how to integrate a LG TV (Netcast 3.0 & 4.0) within Home Assistant."
+description: "Instructions on how to integrate a LG TV (Netcast 3.0 & 4.0) within Home Assistant."
date: 2016-05-12 23:22
sidebar: true
comments: false
diff --git a/source/_components/media_player.markdown b/source/_components/media_player.markdown
index 18350ce1326..46ead6f4af8 100644
--- a/source/_components/media_player.markdown
+++ b/source/_components/media_player.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Media Player"
-description: "Instructions how to setup your media players with Home Assistant."
+description: "Instructions on how to setup your media players with Home Assistant."
date: 2015-01-24 14:39
sidebar: true
comments: false
@@ -9,39 +9,39 @@ sharing: true
footer: true
---
-Interacts with media players on your network. Please check the sidebar for a full list of supported devices.
+Interacts with media players on your network. Please check the right sidebar for a full list of supported devices.
## {% linkable_title Services %}
### {% linkable_title Media control services %}
-Available services: `turn_on`, `turn_off`, `toggle`, `volume_up`, `volume_down`, `media_play_pause`, `media_play`, `media_pause`, `media_stop`, `media_next_track`, `media_previous_track`, `clear_playlist`
+Available services: `turn_on`, `turn_off`, `toggle`, `volume_up`, `volume_down`, `volume_set`, `media_play_pause`, `media_play`, `media_pause`, `media_stop`, `media_next_track`, `media_previous_track`, `clear_playlist`, `shuffle_set`
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ------------------------------------------------ |
| `entity_id` | yes | Target a specific media player. Defaults to all. |
-#### {% linkable_title Service `media_player/volume_mute` %}
+#### {% linkable_title Service `media_player.volume_mute` %}
| Service data attribute | Optional | Description |
|------------------------|----------|--------------------------------------------------|
| `entity_id` | yes | Target a specific media player. Defaults to all. |
| `is_volume_muted` | no | True/false for mute/unmute |
-#### {% linkable_title Service `media_player/volume_set` %}
+#### {% linkable_title Service `media_player.volume_set` %}
| Service data attribute | Optional | Description |
|------------------------|----------|--------------------------------------------------|
| `entity_id` | yes | Target a specific media player. Defaults to all. |
-| `volume_level` | no | Float for volume level |
+| `volume_level` | no | Float for volume level. Range 0..1 |
-#### {% linkable_title Service `media_player/media_seek` %}
+#### {% linkable_title Service `media_player.media_seek` %}
| Service data attribute | Optional | Description |
|------------------------|----------|--------------------------------------------------------|
| `entity_id` | yes | Target a specific media player. Defaults to all. |
| `seek_position` | no | Position to seek to. The format is platform dependent. |
-#### {% linkable_title Service `media_player/play_media` %}
+#### {% linkable_title Service `media_player.play_media` %}
| Service data attribute | Optional | Description |
| -----------------------| -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -49,20 +49,29 @@ Available services: `turn_on`, `turn_off`, `toggle`, `volume_up`, `volume_down`,
| `media_content_id` | no | A media identifier. The format of this is component dependent. For example, you can provide URLs to Sonos and Cast but only a playlist ID to iTunes. |
| `media_content_type` | no | A media type. Must be one of `music`, `tvshow`, `video`, `episode`, `channel` or `playlist`. For example, to play music you would set `media_content_type` to `music`. |
-#### {% linkable_title Service `media_player/select_source` %}
+#### {% linkable_title Service `media_player.select_source` %}
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ---------------------------------------------------- |
| `entity_id` | yes | Target a specific media player. Defaults to all. |
| `source` | no | Name of the source to switch to. Platform dependent. |
+#### {% linkable_title Service `media_player/select_sound_mode` %}
+
+Currently only supported on [Denon AVR](/components/media_player.denonavr/) and [Songpal](/components/media_player.songpal/).
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ---------------------------------------------------- |
+| `entity_id` | no | Target a specific media player. For example `media_player.marantz`|
+| `sound_mode` | no | Name of the sound mode to switch to. Platform dependent.|
+
#### {% linkable_title Service `media_player/shuffle_set` %}
-Currently only supported on [Spotify](/components/media_player.spotify/), [MPD](/components/media_player.mpd/), [Kodi](/components/media_player.kodi/), and [Universal](/components/media_player.universal/).
+Currently only supported on [Spotify](/components/media_player.spotify/), [MPD](/components/media_player.mpd/), [Kodi](/components/media_player.kodi/), [Squeezebox](/components/media_player.squeezebox/) and [Universal](/components/media_player.universal/).
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ---------------------------------------------------- |
| `entity_id` | no | Target a specific media player. For example `media_player.spotify`|
-| `shuffle` | no | `true`/`false` for enabling/disabling shuffle |
+| `shuffle` | no | `true`/`false` for enabling/disabling shuffle |
diff --git a/source/_components/media_player.mediaroom.markdown b/source/_components/media_player.mediaroom.markdown
new file mode 100644
index 00000000000..39a417a5f31
--- /dev/null
+++ b/source/_components/media_player.mediaroom.markdown
@@ -0,0 +1,85 @@
+---
+layout: page
+title: "Mediaroom"
+description: "Instructions on how to integrate Mediaroom Set-Top Boxes into Home Assistant."
+date: 2018-01-22 22:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: mediaroom.png
+ha_category: Media Player
+ha_iot_class: "Local Polling"
+ha_release: "0.63"
+---
+
+The `mediaroom` component allows you to control a [Mediaroom](https://en.wikipedia.org/wiki/Ericsson_Mediaroom) Set-Top Box (STB) from Home Assistant.
+
+To add a Mediaroom STB to your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+media_player:
+ - platform: mediaroom
+```
+
+{% configuration %}
+ host:
+ description: The hostname or IP address of the device.
+ required: false
+ type: string
+ default: Tries to discovery your device.
+ name:
+ description: The name of the device used in the frontend.
+ required: false
+ type: string
+ default: Mediaroom STB
+ optimistic:
+ description: In case the component cannot determine the status of the box, consider the box always ON.
+ required: false
+ type: boolean
+ default: false
+{% endconfiguration %}
+
+Notice that all parameters are optional, and discovery should configure everything for you.
+
+#### {% linkable_title Using the Mediaroom component %}
+
+The component has been developed for Portuguese TV operators currently using the Mediaroom platform, but should also work in other deployments in which the STB can be controlled remotely through a socket on port 8082.
+
+In most cases (single STB) you just need to setup the *platform* and discovery will do the rest.
+
+If the STB is on the same network segment as Home Assistant, it can determine whether the device is turned on or off. Without this, the component will fail to determine the Set-top box status, and you are required to add the *optimistic* configuration variable.
+
+## {% linkable_title Examples %}
+
+### {% linkable_title Example `press_button` script %}
+
+The `play_media` function can be used in scripts to change channels and emulate button pressing from a remote control.
+
+{% raw %}
+```yaml
+# Example play_media script
+#
+press_button:
+ sequence:
+ service: media_player.play_media
+ data_template:
+ entity_id: media_player.mediaroom_stb
+ media_content_id: "{{ value }}"
+ media_content_type: "channel"
+```
+{% endraw %}
+
+### {% linkable_title Example configuration with 2 STB %}
+
+```yaml
+# Example configuration.yaml entry for 2 STB
+media_player:
+ - platform: mediaroom
+ host: 192.168.1.64
+ name: Living Room STB
+ - platform: mediaroom
+ host: 192.168.1.65
+ name: Bedroom STB
+```
diff --git a/source/_components/media_player.monoprice.markdown b/source/_components/media_player.monoprice.markdown
index 7487e75b1e8..75e41d9b631 100644
--- a/source/_components/media_player.monoprice.markdown
+++ b/source/_components/media_player.monoprice.markdown
@@ -47,3 +47,25 @@ Configuration variables:
- **port** (*Required*): The serial port to which Monoprice amplifier is connected
- **zones** (*Required*): This is the list of zones available. Valid zones are 11,12,13,14,15,16. In case multiple Monoprice devices are stacked together the list of valid zones is extended by 21,22,23,24,25,26 for the second device and 31,32,33,34,35,36 for the third device. Each zone must have a name assigned to it.
- **sources** (*Required*): The list of sources available. Valid source numbers are 1,2,3,4,5,6. Each source number corresponds to the input number on the Monoprice amplifier. Similar to zones, each source must have a name assigned to it.
+
+### {% linkable_title Service `snapshot` %}
+
+Take a snapshot of one or more zones' states. This service, and the following one are useful if you want to play a doorbell or notification sound and resume playback afterward. If no `entity_id` is provided, all zones are snapshotted.
+
+The following attributes are stored in a snapshot:
+- Power status (On/Off)
+- Mute status (On/Off)
+- Volume level
+- Source
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String or list of strings that point at `entity_id`s of zones.
+
+### {% linkable_title Service `restore` %}
+
+Restore a previously taken snapshot of one or more speakers. If no `entity_id` is provided, all zones are restored.
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String or list of strings that point at `entity_id`s of zones.
diff --git a/source/_components/media_player.mpchc.markdown b/source/_components/media_player.mpchc.markdown
index 4e4c187d0f4..98f6846f3a1 100644
--- a/source/_components/media_player.mpchc.markdown
+++ b/source/_components/media_player.mpchc.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "MPC-HC"
-description: "Instructions how to integrate MPC-HC into Home Assistant."
+description: "Instructions on how to integrate MPC-HC into Home Assistant."
date: 2016-07-27 21:21
sidebar: true
comments: false
diff --git a/source/_components/media_player.mpd.markdown b/source/_components/media_player.mpd.markdown
index b561797aacb..51888be2b20 100644
--- a/source/_components/media_player.mpd.markdown
+++ b/source/_components/media_player.mpd.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Music Player Daemon (MPD)"
-description: "Instructions how to integrate Music Player Daemon into Home Assistant."
+description: "Instructions on how to integrate Music Player Daemon into Home Assistant."
date: 2016-09-30 23:06
sidebar: true
comments: false
diff --git a/source/_components/media_player.nad.markdown b/source/_components/media_player.nad.markdown
index b35a5ea99b1..41684f72129 100644
--- a/source/_components/media_player.nad.markdown
+++ b/source/_components/media_player.nad.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "NAD"
-description: "Instructions how to integrate NAD receivers into Home Assistant."
+description: "Instructions on how to integrate NAD receivers into Home Assistant."
date: 2016-01-05 20:00
sidebar: true
comments: false
diff --git a/source/_components/media_player.nadtcp.markdown b/source/_components/media_player.nadtcp.markdown
index 98a160f76b9..e673e4472d8 100644
--- a/source/_components/media_player.nadtcp.markdown
+++ b/source/_components/media_player.nadtcp.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "NAD tcp"
-description: "Instructions how to integrate the NAD D 7050 or C338 digital amplifiers into Home Assistant."
+description: "Instructions on how to integrate the NAD D 7050 or C338 digital amplifiers into Home Assistant."
date: 2017-06-07 20:00
sidebar: true
comments: false
diff --git a/source/_components/media_player.onkyo.markdown b/source/_components/media_player.onkyo.markdown
index e78075c01a5..630182ba6df 100644
--- a/source/_components/media_player.onkyo.markdown
+++ b/source/_components/media_player.onkyo.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Onkyo"
-description: "Instructions how to integrate Onkyo and some Pioneer receivers into Home Assistant."
+description: "Instructions on how to integrate Onkyo and some Pioneer receivers into Home Assistant."
date: 2016-03-30 08:00
sidebar: true
comments: false
@@ -16,6 +16,8 @@ ha_iot_class: "Local Polling"
The `onkyo` platform allows you to control a [Onkyo](http://www.onkyo.com/) and some recent [Pioneer](http://www.pioneerelectronics.com) receivers from Home Assistant. Please be aware that you need to enable "Network Standby" for this component to work in your Hardware.
+## {% linkable_title Configuration %}
+
To add an Onkyo or Pioneer receiver to your installation, add the following to your `configuration.yaml` file:
```yaml
@@ -28,11 +30,26 @@ media_player:
pc: 'HTPC'
```
-Configuration variables:
+ If your receiver has second or third zone’s available, they are displayed as additional media players with the same functionality as the main zone.
-- **host** (*Optional*): IP address of the device. Example:`192.168.1.2`. If not specified, the platform will load any discovered receivers.
-- **name** (*Required if host is specified*): Name of the device.
-- **sources** (*Optional*): A list of mappings from source to source name. Valid sources can be found below. A default list will be used if no source mapping is specified.
+{% configuration %}
+host:
+ description: IP address of the device. Example:`192.168.1.2`. If not specified, the platform will load any discovered receivers.
+ required: false
+ type: string
+name:
+ description: Name of the device. (*Required if host is specified*)
+ required: false
+ type: string
+max_volume:
+ description: Maximum volume. Defaults to 80.
+ required: false
+ type: number
+sources:
+ description: A list of mappings from source to source name. Valid sources can be found below. A default list will be used if no source mapping is specified.
+ required: false
+ type: list
+{% endconfiguration %}
List of source names:
diff --git a/source/_components/media_player.openhome.markdown b/source/_components/media_player.openhome.markdown
index e1749688272..ae10d32d3c6 100644
--- a/source/_components/media_player.openhome.markdown
+++ b/source/_components/media_player.openhome.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Linn / Openhome"
-description: "Instructions how to integrate Linn Ds and Openhome renderers into Home Assistant."
+description: "Instructions on how to integrate Linn Ds and Openhome renderers into Home Assistant."
date: 2017-02-21 22:40
sidebar: true
comments: false
diff --git a/source/_components/media_player.panasonic_viera.markdown b/source/_components/media_player.panasonic_viera.markdown
index 38cf5f1f8bd..28778486017 100644
--- a/source/_components/media_player.panasonic_viera.markdown
+++ b/source/_components/media_player.panasonic_viera.markdown
@@ -18,17 +18,18 @@ The `panasonic_viera` platform allows you to control a Panasonic Viera TV.
Currently known supported models:
-- TX-P42STW50
- TC-P65VT30
-- TX-55CX700E
+- TX-32AS520E
- TX-49DX650B
- TX-50DX700B
-- TX-L42ET50
-- TX-P50GT60E
+- TX-55CX700E
- TX-65EXW784
-- TX-32AS520E
+- TX-L42ET50
+- TX-P42STW50
+- TX-P50GT30Y
+- TX-P50GT60E
-If your model is not on the list then give it a test, if everything works correctly then add it to the list on [GitHub](https://github.com/home-assistant/home-assistant.io).
+If your model is not on the list then give it a test, if everything works correctly then add it to the list on [GitHub](https://github.com/home-assistant/home-assistant.github.io/blob/next/source/_components/media_player.panasonic_viera.markdown).
Some Panasonic Viera TVs allow Home Assistant to turn them on, if you specify the MAC address with `mac:`.
@@ -43,7 +44,33 @@ media_player:
Configuration variables:
-- **host** (*Required*): The IP of the Panasonic Viera TV, e.g. `192.168.0.10`.
+- **host** (*Required*): The IP of the Panasonic Viera TV, e.g., `192.168.0.10`.
- **port** (*Optional*): The port number of your Panasonic Viera TV. Defaults to `55000`.
-- **mac** (*Optional*): The MAC address of your Panasonic Viera TV, e.g. `AA:BB:CC:DD:99:1A`.
+- **mac** (*Optional*): The MAC address of your Panasonic Viera TV, e.g., `AA:BB:CC:DD:99:1A`.
- **name** (*Optional*): The name you would like to give to the Panasonic Viera TV.
+
+### {% linkable_title Example `play_media` script %}
+
+The `play_media` function can be used to open web pages and other media types (images, movies) in the TV web browser.
+
+```yaml
+# Example play_media script that can be triggered when someone is detected at the door
+#
+script:
+ front_door_camera:
+ alias: "Show who's at the door"
+ sequence:
+ - service: media_player.turn_on
+ data:
+ entity_id: media_player.living_room_tv
+ - service: media_player.play_media
+ data:
+ entity_id: media_player.living_room_tv
+ media_content_type: "url"
+ media_content_id: "http://google.com"
+ - delay:
+ seconds: 5
+ - service: media_player.media_stop
+ data:
+ entity_id: media_player.living_room_tv
+```
diff --git a/source/_components/media_player.pandora.markdown b/source/_components/media_player.pandora.markdown
index 5f0098cff83..76c04061252 100644
--- a/source/_components/media_player.pandora.markdown
+++ b/source/_components/media_player.pandora.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Pandora"
-description: "Instructions how to integrate Pandora radio into Home Assistant."
+description: "Instructions on how to integrate Pandora radio into Home Assistant."
date: 2016-06-10 19:59
sidebar: true
comments: false
@@ -14,17 +14,17 @@ ha_release: 0.22
ha_iot_class: "Local Polling"
---
-If you have a Pandora account, you can control it from Home Assistant with this media player.
+If you have a Pandora account, you can control it from Home Assistant with this media player.
### {% linkable_title Installation of Pianobar %}
This media player uses the [Pianobar command-line Pandora client](https://github.com/PromyLOPh/pianobar), which you have to install separately. This can be done on a Raspberry Pi 2/3 with Raspbian Jessie as follows . _(Note: Other platforms may have different installation processes)_
-The version of pianobar that comes with Jessie has a bug, so you have to build a more recent version. The latest version depends on a recent version of libraries associated with ffmpeg, so you should make sure you go through the backport process documented in [The FFmpeg component](https://home-assistant.io/components/ffmpeg/) before doing this. Install the following basic dependencies:
+The version of pianobar that comes with Jessie has a bug, so you have to build a more recent version. The latest version depends on a recent version of libraries associated with ffmpeg, so you should make sure you go through the backport process documented in [The FFmpeg component](/components/ffmpeg/) before doing this. Install the following basic dependencies:
```bash
-$ sudo apt-get install git libao-dev libgcrypt11-dev libfaad-dev libmad0-dev libjson0-dev make pkg-config libcurl4-openssl-dev
+$ sudo apt-get install git libao-dev libgcrypt11-dev libfaad-dev libmad0-dev libjson0-dev make pkg-config libcurl4-openssl-dev
```
And now install the backported ffmpeg-related libraries (note that if you're using an older version of ffmpeg for other things on this machine, you may encounter issues after doings this):
@@ -61,7 +61,7 @@ media_player:
- platform: pandora
```
-That's it! Now you will find a media player. If you click it you will find all your stations listed as different sources. If you switch to one, the station will begin playing.
+That's it! Now you will find a media player. If you click it you will find all your stations listed as different sources. If you switch to one, the station will begin playing.
:/api/spotify`
@@ -38,7 +38,7 @@ To create the required Spotify Application:
The URL is whatever you use to access Home Assistant from outside your network (including port if applicable).
-- Click **Save** after adding the URI. You may also need to set the `base_url` attribute of the [HTTP Component](https://home-assistant.io/components/http/).
+- Click **Save** after adding the URI. You may also need to set the `base_url` attribute of the [HTTP Component](/components/http/).
## {% linkable_title Configuration %}
@@ -71,8 +71,7 @@ After the prerequisites and configuration are complete, restart Home Assistant.
The sources are based on if you have streamed to these devices before in Spotify. If you don't have any sources, then simply stream from your phone to another device in your house, Bluetooth, echo, etc. Once you do the sources will show up in the developer console as a device to cast/stream to. Also know that the devices won't show up in the dev-console as sources unless they are powered on as well.
## {% linkable_title URI Links For Playlists/Etc %}
-You can send playlists to spotify via the "media_content_type": "playlist" and "media_content_id": "spotify:user:spotify:playlist:37i9dQZF1DWSkkUxEhrBdF" which are a part of the media_player.play_media service, you can test this from the services control panel in the Home Assistant frontend.
+You can send playlists to spotify via the "media_content_type": "playlist" and "media_content_id": "spotify:user:spotify:playlist:37i9dQZF1DWSkkUxEhrBdF" which are a part of the [media_player.play_media](/components/media_player/#service-media_playerplay_media) service, you can test this from the services control panel in the Home Assistant frontend.
-In this example this is a URI link to the Reggae Infusions playlist, the link below from Spotify explains how to get this URI value to use for playlists in the Spotify component.
+In this example this is a URI link to the Reggae Infusions playlist, [this support document from Spotify](https://support.spotify.com/us/using_spotify/share_music/why-do-you-have-two-different-link-formats/) explains how to get this URI value to use for playlists in the Spotify component.
-https://support.spotify.com/us/using_spotify/share_music/why-do-you-have-two-different-link-formats/
diff --git a/source/_components/media_player.squeezebox.markdown b/source/_components/media_player.squeezebox.markdown
index d091d13b6d9..b226960e31b 100644
--- a/source/_components/media_player.squeezebox.markdown
+++ b/source/_components/media_player.squeezebox.markdown
@@ -33,3 +33,25 @@ Configuration variables:
- **password** (*Optional*): The password, if password protection is enabled.
` and use the sources listed in `source_list:` remembering to split them per line into your `sources:` configuration.
+
+### {% linkable_title Change channel through play_media service %}
+
+The `play_media` service can be used in a script to switch to the specified tv channel.
+It selects the best matching cannel according to the `media_content_id` parameter:
+ 1. Channel number *(i.e. '1' or '6')*
+ 2. Exact channel name *(i.e. 'France 2' or 'CNN')*
+ 3. Substring in channel name *(i.e. 'BFM' in 'BFM TV')*
+
+```yaml
+# Example action entry in script to switch to channel number 1
+service: media_player.play_media
+data:
+ entity_id: media_player.lg_webos_smart_tv
+ media_content_id: 1
+ media_content_type: "channel"
+
+# Example action entry in script to switch to channel including 'TF1' in its name
+service: media_player.play_media
+data:
+ entity_id: media_player.lg_webos_smart_tv
+ media_content_id: "TF1"
+ media_content_type: "channel"
+```
+
+### {% linkable_title Next/Previous buttons %}
+
+The behaviour of the next and previsous buttons is different depending on the active source:
+
+ - if the source is 'LiveTV' (television): next/previous buttons act as channel up/down
+ - otherwise: next/previous buttons act as next/previous track
diff --git a/source/_components/media_player.xiaomi_tv.markdown b/source/_components/media_player.xiaomi_tv.markdown
new file mode 100644
index 00000000000..ffc2f1efc7d
--- /dev/null
+++ b/source/_components/media_player.xiaomi_tv.markdown
@@ -0,0 +1,51 @@
+---
+layout: page
+title: "Xiaomi TV"
+description: "Instructions on how to integrate a Xiaomi TV into Home Assistant."
+date: 2018-02-12 19:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: xiaomi.png
+ha_category: Media Player
+ha_release: 0.64
+ha_iot_class: "Assumed State"
+---
+
+The `xiaomi_tv` platform allows you to control a [Xiaomi TV](http://www.mi.com/en/mitv3s/65flat/).
+
+You need to make sure the TV is connected to the internet, and that your Home Assistant instance is on the same network.
+
+To add a TV to your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+media_player:
+ - platform: xiaomi_tv
+```
+
+
-
+
+
+You will need the last part of the URL which is the `access_token` for your room.
+
+`. The name will default to `notify` if not supplied.
+The **name** parameter is optional but needed if you want to use multiple platforms. The platform will be exposed as service `notify.`. The name will default to `notify` if not supplied.
### {% linkable_title Service %}
@@ -36,7 +36,7 @@ Once loaded, the `notify` platform will expose a service that can be called to s
The notification component supports specifying [templates](/topics/templating/) with `data_template`. This will allow you to use the current state of Home Assistant in your notifications.
-In an [action](https://home-assistant.io/getting-started/automation-action/) of your [automation setup](/getting-started/automation/) it could look like this with a customized subject.
+In an [action](/getting-started/automation-action/) of your [automation setup](/getting-started/automation/) it could look like this with a customized subject.
```yaml
action:
@@ -59,8 +59,8 @@ For services which have support for sending images.
```json
{ "message": "Test plugin",
- "data": {
- "photo": {
+ "data": {
+ "photo": {
"url": "http://www.gbsun.de/gbpics/berge/berge106.jpg"
}
}
diff --git a/source/_components/notify.mastodon.markdown b/source/_components/notify.mastodon.markdown
new file mode 100644
index 00000000000..65bdc1e38a4
--- /dev/null
+++ b/source/_components/notify.mastodon.markdown
@@ -0,0 +1,51 @@
+---
+layout: page
+title: "Mastodon"
+description: "Instructions on how to add Instapush notifications to Home Assistant."
+date: 2018-03-25 18:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: mastodon.png
+ha_category: Notifications
+ha_release: 0.67
+---
+
+The `mastodon` platform uses [MAstodon](https://joinmastodon.org/) to delivery notifications from Home Assistant.
+
+Go to **Preferences** in the Mastodon web interface, then to **Development** and create a new application.
+
+To add Mastodon to your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+notify:
+ - name: NOTIFIER_NAME
+ platform: mastodon
+ access_token: !secret mastodon_access_token
+ client_id: !secret mastodon_client_id
+ client_secret: !secret mastodon_client_secret
+```
+
+{% configuration %}
+access_token:
+ description: Your Mastodon access token.
+ required: true
+ type: string
+client_id:
+ description: Your Mastodon client ID
+ required: true
+ type: string
+client_secret:
+ description: Your Mastodon client secret.
+ required: true
+ type: string
+base_url:
+ description: URL of the Mastodon instance to use.
+ required: false
+ type: string
+ default: https://mastodon.social
+{% endconfiguration %}
+
+To use notifications, please see the [getting started with automation page](/getting-started/automation/).
diff --git a/source/_components/notify.matrix.markdown b/source/_components/notify.matrix.markdown
index fe5d7fc3a40..29890d46c8b 100644
--- a/source/_components/notify.matrix.markdown
+++ b/source/_components/notify.matrix.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Matrix"
-description: "Instructions how to add Matrix notifications to Home Assistant."
+description: "Instructions on how to add Matrix notifications to Home Assistant."
date: 2016-10-11 23:51
sidebar: true
comments: false
@@ -15,27 +15,23 @@ ha_release: 0.32
The `matrix` platform allows you to deliver notifications from Home Assistant to a [Matrix](http://matrix.org) room. Rooms can be both direct as well as group chats.
-To enable Matrix notifications in your installation, add the following to your `configuration.yaml` file:
+## {% linkable_title Configuration %}
+
+To enable Matrix notifications in your installation, you first need to configure
+the [Matrix component](/components/matrix/). Then, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
notify:
- name: NOTIFIER_NAME
platform: matrix
- homeserver: HOMESERVER
- username: USERNAME
- password: PASSWORD
default_room: ROOM_ID_OR_ALIAS
```
Configuration variables:
- **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`.
-- **homeserver** (*Required*): The base URL of the homeserver, where the notifier account is registered (e.g. `https://matrix.org`).
-- **username** (*Required*): The username of the notifying Matrix account.
-- **password** (*Required*): The password for the given Matrix account.
- **default_room** (*Required*): The room all messages will be sent to, when no other target is given.
-- **verify_ssl** (*Optional*): Verify the homeservers certificate. Defaults to `true`.
The target room has to be precreated, the room id can be obtained from the rooms settings dialog. Rooms by default have a canonical id of the form `"!:homeserver.tld"`, but can also be allocated aliases like `"#roomname:homeserver.tld"`. Make sure to use quotes around the room id or alias to escape special characters (`!`, and `#`) in YAML. The notifying account may need to be invited to the room, depending on the individual rooms policies.
diff --git a/source/_components/notify.message_bird.markdown b/source/_components/notify.message_bird.markdown
index d8baf5fa0d7..2234a86310e 100644
--- a/source/_components/notify.message_bird.markdown
+++ b/source/_components/notify.message_bird.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "MessageBird"
-description: "Instructions how to add user notifications to Home Assistant."
+description: "Instructions on how to add user notifications to Home Assistant."
date: 2016-03-15 17:00
sidebar: true
comments: false
@@ -28,7 +28,7 @@ Configuration variables:
- **api_key** (*Required*): Enter the API key for MessageBird. Go to https://www.messagebird.com/ to retrieve your API key.
- **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`.
-- **sender** (*Optional*): Setting the optional parameter `sender`. This will be the sender of the SMS. It may be either a telephone number (e.g. `+4915112345678`) or a text with a maximum length of 11 characters. Defaults to `HA`.
+- **sender** (*Optional*): Setting the optional parameter `sender`. This will be the sender of the SMS. It may be either a telephone number (e.g., `+4915112345678`) or a text with a maximum length of 11 characters. Defaults to `HA`.
### {% linkable_title Usage %}
diff --git a/source/_components/notify.mqtt.markdown b/source/_components/notify.mqtt.markdown
index 7aefb8743f0..a1a33ef7e43 100644
--- a/source/_components/notify.mqtt.markdown
+++ b/source/_components/notify.mqtt.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "MQTT Notifications"
-description: "Instructions how to add MQTT notifications to Home Assistant."
+description: "Instructions on how to add MQTT notifications to Home Assistant."
date: 2016-02-01 08:00
sidebar: true
comments: false
@@ -14,7 +14,7 @@ ha_iot_class: depends
The MQTT notification support is different than the other [notification](/components/notify/) platforms. It is a service. This means that you don't have to create a configuration entry but you need to provide more details when calling the service.
-**Call Service** section from the **Developer Tools** allows you to send MQTT messages. Choose *mqtt/publish* from the list of **Available services:** and enter something like the sample below into the **Service Data** field and hit **CALL SERVICE**.
+**Call Service** section from the 
**Developer Tools** allows you to send MQTT messages. Choose *mqtt.publish* from the list of **Available services:** and enter something like the sample below into the **Service Data** field and hit **CALL SERVICE**.
```json
{"payload": "Test message from HA", "topic": "home/notification", "qos": 0, "retain": 0}
@@ -24,7 +24,18 @@ The MQTT notification support is different than the other [notification](/compon
-Using the [REST API](/developers/rest_api/#post-apiservicesltdomainltservice) to send a message to a given topic.
+The same will work for automations.
+
+
This add-on is not compatible if Hass.io was installed via the generic Linux installer.
++This add-on is not compatible if Hass.io was installed via the generic Linux installer. +
diff --git a/source/_addons/tellstick.markdown b/source/_addons/tellstick.markdown new file mode 100644 index 00000000000..49764d93dae --- /dev/null +++ b/source/_addons/tellstick.markdown @@ -0,0 +1,102 @@ +--- +layout: page +title: "TellStick" +description: "Telldus TellStick service enabler and tools." +date: 2017-12-04 21:31 +sidebar: true +comments: false +sharing: true +footer: true +featured: false +--- + +Setting up the [Tellstick](http://telldus.com) service and tools contained in the [telldus-core](http://developer.telldus.com/) package and adding configuration to enable Tellstick and Tellstick Duo to work on your Hass.io. + +To use this add-on, you first install it from the list of Built-in add-ons in Hass.io. +After installation you are presented with a default and example configuration, to alter this you must follow both the JSON format and also be aligned with the [valid parameters for Tellstick configuration file (tellstick.conf)](https://developer.telldus.com/wiki/TellStick_conf). + +After any changes have been made to the configuration, you need to restart the add-on for the changes to take effect. + +Configuration variables: + +- **id** (*Required*): A number and must be unique for each device. +- **name** (*Required*): A name for easy identification of the device. +- **protocol** (*Required*): This is the protocol the device uses. More on the different protocols later down. +- **model** (*Optional*): The model parameter is only used by some protocols where there exists different types of devices using the same protocol. This can be dimmers versus non-dimmers, codeswitch versus self-learning, etc. +- **house** (*Optional*): Depending on protocol the values here can vary a lot to identify or group per house or type. +- **unit** (*Optional*): Unit identifier, in most cases a value between 1 to 16 and often used in combination with the house. +- **fade** (*Optional*): Fade is either `true` or `false` and tells a dimmer if it should fade smooth or instant between values (only for IKEA protocol as it seems). +- **code** (*Optional*): A number series based on ones and zeroes often used for dip-switch based devices. + +You will need to add internal communication details to `configuration.yaml` to enable the integration from Hass.io and the add-on. + + +```yaml +# Example configuration.yaml entry + +tellstick: + host: core-tellstick + port: [50800, 50801] + +``` + +To add [lights](/components/light.tellstick/), [sensors](/components/sensor.tellstick/) and [switches](/components/switch.tellstick/) you follow the guidelines for each type individually that is [described for Home Assistant](/components/tellstick/) + +The add-on will also enable you to interact with the `tdtool` via a Home Assistant services call, see example below for self-learning device. + +## {% linkable_title Examples %} + +Example for adding more devices in the add-on configuration (note the comma separator between devices): + +```json +{ + "devices": [ + { + "id": 1, + "name": "Outdoor light", + "protocol": "everflourish", + "model": "selflearning-switch", + "house": "A", + "unit": "1" + }, + { + "id": 2, + "name": "Hallway dimmer", + "protocol": "risingsun", + "model": "selflearning-dimmer", + "house": "A", + "unit": "2" + } + ] +} +``` + +## Service calls + +If you wish to teach a selflearning device in your TellStick configuration: + +Go to Home Assistant [service call](http://hassio.local:8123/dev-service) in Developer tools and select. +- Service: `hassio.addon_stdin` +- Enter service Data: + `{"addon":"core_tellstick","input":{"function":"learn","device":"1"}}` + +Replace `1` with the corresponding ID of the device in your TellStick configuration. + +You can also use this to list devices or sensors and read the output in the add-on log: +`{"addon":"core_tellstick","input":{"function":"list-sensors"}}` + + +#### Supported service commands + +- `"function":"list"`: List currently configured devices with name and device id and all discovered sensors. + +- `"function":"list-sensors"` +- `"function":"list-devices"`: Alternative devices/sensors listing: Shows devices and/or sensors using key=value format (with tabs as separators, one device/sensor per line, no header lines.) + +- `"function":"on","device":"x"`: Turns on device. ’x’ could either be an integer of the device-id, or the name of the device. + +- `"function":"off","device":"x"`: Turns off device. ’x’ could either be an integer of the device-id, or the name of the device. + +- `"function":"bell","device":"x"`: Sends bell command to devices supporting this. ’x’ could either be an integer of the device-id, or the name of the device. + +- `"function":"learn","device":"x"`: Sends a special learn command to devices supporting this. This is normally devices of ’selflearning’ type. ’x’ could either be an integer of the device-id, or the name of the device. diff --git a/source/_components/abode.markdown b/source/_components/abode.markdown index 3314bcc9038..87b689230bc 100644 --- a/source/_components/abode.markdown +++ b/source/_components/abode.markdown @@ -13,7 +13,7 @@ ha_release: 0.52 ha_iot_class: "Cloud Push" --- -The `abode` component will allow users to integrate their Abode Home Security systems into Home Assistant and use its alarm system and sensors to automate their homes. +The `abode` component will allow users to integrate their Abode Home Security systems into Home Assistant and use its alarm system and sensors to automate their homes. Please visit the [Abode website](https://goabode.com/) for further information about Abode Security. @@ -24,7 +24,7 @@ There is currently support for the following device types within Home Assistant: - [Camera](/components/camera.abode/): Reports on `Camera` devices and will download and show the latest captured still image. - [Cover](/components/cover.abode/): Reports on `Secure Barriers` and can be used to open and close the cover. - [Lock](/components/cover.abode/): Reports on `Door Locks` and can be used to lock and unlock the door. -- [Light](/components/light.abode/): Reports on `Dimmer` lights and can be used to dim, change color, or turn the light on and off. +- [Light](/components/light.abode/): Reports on `Dimmer` lights and can be used to dim or turn the light on and off. - [Switch](/components/switch.abode/): Reports on `Power Switch` devices and can be used to turn the power switch on and off. Also reports on `Automations` set up in the Abode system and allows you to activate or deactivate them. - [Sensor](/components/sensor.abode/): Reports on `Temperature`, `Humidity`, and `Light` sensors. diff --git a/source/_components/ads.markdown b/source/_components/ads.markdown new file mode 100644 index 00000000000..9e8463add0b --- /dev/null +++ b/source/_components/ads.markdown @@ -0,0 +1,58 @@ +--- +layout: page +title: "ADS" +description: Connect Home Assistant to TwinCAT devices via the ADS interface +date: 2017-12-05 12:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: beckhoff.png +ha_category: Hub +ha_release: "0.60" +ha_iot_class: "Local Push" +--- + +The ADS (automation device specification) describes a device-independent and fieldbus independent interface for communication between [Beckhoff](https://www.beckhoff.com/) automation devices running [TwinCAT](http://www.beckhoff.hu/english.asp?twincat/default.htm) and other devices implementing this interface. + +To enable ADS, add the following lines to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +ads: + device: '127.0.0.1.1.1' + port: 48898 +``` + +{% configuration %} + device: + required: true + description: The AMS NetId that identifies the device. + type: string + port: + required: true + description: The port that runs the AMS server on the device, typically this would be 801 or 851. + type: int + ip_address: + required: false + description: The IP address of the ADS device, if not set the first 4 bytes of the device id will be used. + type: string +{% endconfiguration %} + +## {% linkable_title Service %} + +The ADS component will register the service `write_by_name` allowing you to write a value to a variable on your ADS device. + +```json +{ + "adsvar": ".myvariable", + "adstype": "int", + "value": 123 +} +``` + +Service parameters: + +- **adsvar**: Name of the variable on the ADS device. To access global variables on *TwinCAT2* use a prepending dot `.myvariable`, for TwinCAT3 use `GBL.myvariable`. +- **adstype**: Specify the type of the variable. Use one of the following: `int`, `byte`, `uint`, `bool` +- **value**: The value that will be written in the variable. diff --git a/source/_components/alarm_control_panel.abode.markdown b/source/_components/alarm_control_panel.abode.markdown index 99889db76d4..588eb46f407 100644 --- a/source/_components/alarm_control_panel.abode.markdown +++ b/source/_components/alarm_control_panel.abode.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Abode Alarm Control Panel" -description: "Instructions how to setup the Abode Alarm control panel within Home Assistant." +description: "Instructions on how to setup the Abode Alarm control panel within Home Assistant." date: 2017-08-26 0:28 sidebar: true comments: false @@ -13,7 +13,6 @@ ha_release: 0.52 ha_iot_class: "Cloud Push" --- - The `abode` security control panel platform allows you to control your [Abode](https://goabode.com/) alarms. The requirement is that you have setup your [Abode hub](/components/abode/). diff --git a/source/_components/alarm_control_panel.alarmdecoder.markdown b/source/_components/alarm_control_panel.alarmdecoder.markdown index fec4f0cb3fd..98810aaa2a1 100644 --- a/source/_components/alarm_control_panel.alarmdecoder.markdown +++ b/source/_components/alarm_control_panel.alarmdecoder.markdown @@ -1,7 +1,7 @@ --- layout: page title: "AlarmDecoder Alarm Control Panel" -description: "Instructions how to setup the AlarmDecoder Alarm control panel within Home Assistant." +description: "Instructions on how to setup the AlarmDecoder Alarm control panel within Home Assistant." date: 2017-04-02 13:28 sidebar: true comments: false @@ -13,8 +13,64 @@ ha_release: 0.43 ha_iot_class: "Local Push" --- - The `alarmdecoder` alarm control panel platform allows you to control your [AlarmDecoder](https://www.alarmdecoder.com) alarms. The requirement is that you have setup your [AlarmDecoder hub](/components/alarmdecoder/). +### {% linkable_title Services %} + +The Alarm Decoder component gives you access to several services for you to control your alarm with. + +- `alarm_arm_away`: Arms the alarm in away mode; all faults will trigger the alarm. +- `alarm_arm_home`: Arms the alarm in stay mode; faults to the doors or windows will trigger the alarm. +- `alarm_arm_night`: Arms the alarm in instant mode; all faults will trigger the alarm. Additionally, the entry delay is turned off on the doors. +- `alarm_disarm`: Disarms the alarm from any state. Also clears a `check_zone` flag after an alarm was triggered. +- `alarmdecoder_alarm_toggle_chime`: Toggles the alarm's chime state. + ++`alarm_arm_custom_bypass` and `alarm_trigger`, while available in the services list in Home Assistant, are not currently implemented in the Alarm Decoder platform. +
+ +### {% linkable_title Attributes %} + +There are several attributes available on the alarm panel to give you more information about your alarm. + +- `ac_power`: Set to `true` if your system has AC power supplying it. +- `backlight_on`: Set to `true` if your keypad's backlight is on. +- `battery_low`: Set to `true` if your system's back-up battery is low. +- `check_zone`: Set to `true` if your system was recently triggered. When `check_zone` is `true`, it must be cleared by entering your code + 1 before attempting to rearm your alarm. +- `chime`: Set to `true` if your system's chime is activated. When activated, your system will beep anytime a door or window is faulted while the alarm is disarmed. +- `entry_delay_off`: Set to `true` if your system is in "Instant" mode, meaning the alarm will sound on any faults. +- `programming_mode`: Set to `true` if your system is in programming mode. +- `ready`: Set to `true` if your system is ready to be armed. Any faults, including motions sensors, will make this value `false`. +- `zone_bypassed`: Set to `true` if your system is currently bypassing a zone. + +### {% linkable_title Examples %} + +Using a combination of the available services and attributes, you can create switch templates. + +#### {% linkable_title Chime Status and Control %} + +{% raw %} +```yaml +- platform: template + switches: + alarm_chime: + friendly_name: Chime + value_template: "{{ is_state_attr('alarm_control_panel.alarm_panel', 'chime', true) }}" + turn_on: + service: alarm_control_panel.alarmdecoder_alarm_toggle_chime + data: + code: !secret alarm_code + turn_off: + service: alarm_control_panel.alarmdecoder_alarm_toggle_chime + data: + code: !secret alarm_code + icon_template: >- + {% if is_state_attr('alarm_control_panel.alarm_panel', 'chime', true) %} + mdi:bell-ring + {% else %} + mdi:bell-off + {% endif %} +``` +{% endraw %} diff --git a/source/_components/alarm_control_panel.alarmdotcom.markdown b/source/_components/alarm_control_panel.alarmdotcom.markdown index ebffcc5c0df..82e1a7774e7 100644 --- a/source/_components/alarm_control_panel.alarmdotcom.markdown +++ b/source/_components/alarm_control_panel.alarmdotcom.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Alarm.com Alarm Control Panel" -description: "Instructions how to integrate Alarm.com into Home Assistant." +description: "Instructions on how to integrate Alarm.com into Home Assistant." date: 2016-01-14 22:00 sidebar: true comments: false @@ -30,4 +30,3 @@ Configuration variables: - **password** (*Required*): Password for Alarm.com account. - **name** (*Optional*): The name of the alarm. Default is 'Alarm.com'. - **code** (*Optional*): Specifies a code to enable or disable the alarm in the frontend. - diff --git a/source/_components/alarm_control_panel.arlo.markdown b/source/_components/alarm_control_panel.arlo.markdown index c58bb46d992..e47a6322d62 100644 --- a/source/_components/alarm_control_panel.arlo.markdown +++ b/source/_components/alarm_control_panel.arlo.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Arlo Control Panel" -description: "Instructions how to setup the Netgear Arlo Base Stations as a control panel within Home Assistant." +description: "Instructions on how to setup the Netgear Arlo Base Stations as a control panel within Home Assistant." date: 2017-10-05 17:45 sidebar: true comments: false @@ -13,8 +13,7 @@ ha_release: 0.56 ha_iot_class: "Cloud Polling" --- - -The `arlo` control panel platform allows you to control your [Arlo](https://arlo.netgear.com/) base stations. +The `arlo` alarm control panel allows you to control your [Arlo](https://arlo.netgear.com/) base stations. You can use it to switch modes and trigger alarms from Home Assistant. To get your [Arlo](https://arlo.netgear.com/) base stations working within Home Assistant, please follow the instructions for the general [Arlo component](/components/arlo). @@ -26,6 +25,52 @@ alarm_control_panel: - platform: arlo ``` -Configuration variables: +{% configuration %} +home_mode_name: + description: "Arlo base station does not have a built-in home mode. You can map one of your custom modes to Home Assistant's home mode by setting the name of the custom mode in this configuration variable. The name of the custom mode should match exactly as you set it up in the Arlo app." + required: false + type: string +away_mode_name: + description: "Arlo base station does not have a built-in away mode. You can map one of your custom modes to Home Assistant's away mode by setting the name of the custom mode in this configuration variable. The name of the custom mode should match eactly as you set it up in the Arlo app." + required: false + type: string + default: "`Armed` mode in Arlo" +{% endconfiguration %} -- **home_mode_name**: (*Optional*): Arlo base station does not have a built-in home mode. You can map one of your custom modes to home assistant's home mode by setting the name of the custom mode in this configuration variable. The name of the custom mode should match exactly as you set it up in the Arlo app. +## {% linkable_title Examples %} + +These examples are based on an Arlo base station named `my_arlo_base_station`. Replace this with the name of your base station's `entity_id`. + +Arming the Arlo Base Station when leaving. + +```yaml +- id: arm_arlo_when_leaving + alias: Arm Arlo cameras when leaving + trigger: + platform: state + entity_id: group.family + from: home + to: not_home + action: + service: alarm_control_panel.alarm_arm_away + entity_id: alarm_control_panel.my_arlo_base_station +``` + +Setting Arlo to a custom mode (mapped to `home_mode_name` in `configuration.yaml`) when arriving. + +```yaml +- id: disarm_arlo_when_arriving + alias: Set Arlo cameras to Home mode when arriving + trigger: + platform: state + entity_id: group.family + from: not_home + to: home + action: + service: alarm_control_panel.alarm_arm_home + entity_id: alarm_control_panel.my_arlo_base_station +``` + +You can also completely disarm the Arlo base station by calling the `alarm_control_panel.alarm_disarm` service, and trigger the alarm by calling the `alarm_control_panel.alarm_trigger` service. + +More examples and configuration options can be found on the [Manual Alarm Control page](/components/alarm_control_panel.manual/#examples). diff --git a/source/_components/alarm_control_panel.canary.markdown b/source/_components/alarm_control_panel.canary.markdown new file mode 100644 index 00000000000..59125f8746a --- /dev/null +++ b/source/_components/alarm_control_panel.canary.markdown @@ -0,0 +1,18 @@ +--- +layout: page +title: "Canary Alarm Control Panel" +description: "Instructions on how to integrate your Canary devices into Home Assistant." +date: 2017-12-07 22:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: canary.png +ha_category: Alarm +ha_release: "0.60" +ha_iot_class: "Cloud Polling" +--- + +The `canary` alarm control panel platform allows you to integrate your [Canary](https://canary.is) alarm system in Home Assistant. + +To add `canary` alarm control panel to your installation, follow instructions in [Canary component](/components/canary/). diff --git a/source/_components/alarm_control_panel.concord232.markdown b/source/_components/alarm_control_panel.concord232.markdown index 9581683f3ec..36f897e21e5 100644 --- a/source/_components/alarm_control_panel.concord232.markdown +++ b/source/_components/alarm_control_panel.concord232.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Concord232 Alarm Control Panel" -description: "Instructions how to integrate Interlogix/GE Concord4 with RS-232 Automation Control Module into Home Assistant." +description: "Instructions on how to integrate Interlogix/GE Concord4 with RS-232 Automation Control Module into Home Assistant." date: 2016-10-11 10:00 sidebar: true comments: false @@ -14,7 +14,9 @@ ha_release: 0.31 The `concord232` platform provides integration with GE, Interlogix (and other brands) alarm panels that support the RS-232 Automation Control Panel interface module (or have it built in). Supported panels include Concord 4. -To enable this, add the following lines to your `configuration.yaml`: +To use this platform, you will need to have the external concord232 client and server installed. The server must be running on the device which is connected to the automation module's serial port. The client must be installed on the machine running Home Assistant. These may often be the same machine, but do not have to be. For additional details in setting up and testing the client and server, see+It is important to note that this platform fully relies on IFTTT to receive updates when the security system's state changes. Therefore, this platform shows an assumed state. +
+ +To enable this, setup the required IFTTT applets as listed below and add the following lines to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +ifttt: + key: YOUR_WEBHOOK_KEY + +alarm_control_panel: + - platform: ifttt + name: YOUR_ALARM_NAME + code: YOUR_ALARM_CODE + event_arm_away: YOUR_ARM_AWAY_EVENT + event_arm_home: YOUR_ARM_HOME_EVENT + event_arm_night: YOUR_ARM_NIGHT_EVENT + event_disarm: YOUR_DISARM_EVENT +``` + ++It is strongly discouraged to use this platform when you don't use encryption; otherwise, your API password will be send unprotected through the IFTTT Webhooks. It is advised to [setup encryption using Let's Encrypt](https://home-assistant.io/blog/2017/09/27/effortless-encryption-with-lets-encrypt-and-duckdns/). +
+ +{% linkable_title Required IFTTT applets %} + +This platform supports the services `alarm_disarm`, `alarm_arm_away`, `alarm_arm_home` and `alarm_arm_night`. For each of these services, an IFTTT webhook will be triggered. + +For this system to operate correctly, the following IFTTT applets have to be setup. Obviously, if your alarm device does not support some states, no applets have to be provided for those. +* **IF** Webhook event `YOUR_DISARM_EVENT` is called, **THEN** disarm the alarm system. +* **IF** Webhook event `YOUR_ARM_HOME_EVENT` is called, **THEN** set the alarm system to armed home. +* **IF** Webhook event `YOUR_ARM_NIGHT_EVENT` is called, **THEN** set the alarm system to armed away. +* **IF** Webhook event `YOUR_DISARM_EVENT` is called, **THEN** set the alarm system to armed night. +* **IF** the alarm system was disarmed, **THEN** perform a Webhook `POST` web request to url `https://HASS_URL/api/services/alarm_control_panel/ifttt_push_alarm_state?api_password=API_PASSWORD` with content type `application/json` and body `{"entity_id": "alarm_control_panel.DEVICE_NAME", "state": "disarmed"}`. +* **IF** the alarm system state changed to armed home, **THEN** perform a Webhook `POST` web request to url `https://HASS_URL/api/services/alarm_control_panel/ifttt_push_alarm_state?api_password=API_PASSWORD` with content type `application/json` and body `{"entity_id": "alarm_control_panel.DEVICE_NAME", "state": "armed_home"}`. +* **IF** the alarm system state changed to armed away, **THEN** perform a Webhook `POST` web request to url `https://HASS_URL/api/services/alarm_control_panel/ifttt_push_alarm_state?api_password=API_PASSWORD` with content type `application/json` and body `{"entity_id": "alarm_control_panel.DEVICE_NAME", "state": "armed_away"}`. +* **IF** the alarm system state changed to armed night, **THEN** perform a Webhook `POST` web request to url `https://HASS_URL/api/services/alarm_control_panel/ifttt_push_alarm_state?api_password=API_PASSWORD` with content type `application/json` and body `{"entity_id": "alarm_control_panel.DEVICE_NAME", "state": "armed_night"}`. + + +{% configuration %} + name: + description: The name of your Home Assistant alarm control panel. + required: false + type: string + code: + description: The code for the alarm control panel. + required: false + type: string + event_arm_away: + description: IFTTT webhook event to call when the state is set to armed away. + required: false + type: string + default: alarm_arm_away + event_arm_home: + description: IFTTT webhook event to call when the state is set to armed home. + required: false + type: string + default: alarm_arm_home + event_arm_night: + description: IFTTT webhook event to call when the state is set to armed night. + required: false + type: string + default: alarm_arm_night + event_disarm: + description: IFTTT webhook event to call when the state is set to disarmed. + required: false + type: string + default: alarm_disarm + optimistic: + description: Specify if the state will be updated by an ifttt_push_alarm_state call (false) or can be set immediately (true). + required: false + type: boolean + default: false +{% endconfiguration %} diff --git a/source/_components/alarm_control_panel.manual.markdown b/source/_components/alarm_control_panel.manual.markdown index 0bdb28cd801..feeda4b7684 100644 --- a/source/_components/alarm_control_panel.manual.markdown +++ b/source/_components/alarm_control_panel.manual.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Manual Alarm Control Panel" -description: "Instructions how to integrate manual alarms into Home Assistant." +description: "Instructions on how to integrate manual alarms into Home Assistant." date: 2015-10-13 19:10 sidebar: true comments: false @@ -25,13 +25,62 @@ Configuration variables: - **name** (*Optional*): The name of the alarm. Default is "HA Alarm". - **code** (*Optional*): If defined, specifies a code to enable or disable the alarm in the frontend. -- **pending_time** (*Optional*): The time in seconds of the pending time before arming the alarm. Default is 60 seconds. +- **code_template** (*Optional*): If defined, returns a code to enable or disable the alarm in the frontend; an empty string disables checking the code. Inside the template, the variables **from_state** and **to_state** identify the current and desired state. Only one of **code** and **code_template** can be specified. +- **delay_time** (*Optional*): The time in seconds of the pending time before triggering the alarm. Default is 0 seconds. +- **pending_time** (*Optional*): The time in seconds of the pending time before effecting a state change. Default is 60 seconds. - **trigger_time** (*Optional*): The time in seconds of the trigger time in which the alarm is firing. Default is 120 seconds. - **disarm_after_trigger** (*Optional*): If true, the alarm will automatically disarm after it has been triggered instead of returning to the previous state. -- **armed_home/armed_away/armed_night/triggered** (*Optional*): State specific settings - - **pending_time**: State specific pending time override. +- **armed_custom_bypass/armed_home/armed_away/armed_night/disarmed/triggered** (*Optional*): State specific settings + - **delay_time** (*Optional*): State specific setting for **delay_time** (all states except **triggered**) + - **pending_time** (*Optional*): State specific setting for **pending_time** (all states except **disarmed**) + - **trigger_time** (*Optional*): State specific setting for **trigger_time** (all states except **triggered**) -In the config example below, armed_home state will have no pending time and triggered state will have pending time of 20 second whereas armed_away state will have a default pending time of 30 seconds. +## {% linkable_title State machine %} + +The state machine of the manual alarm component is complex but powerful. The +transitions are timed according to three values, **delay_time**, **pending_time** +and **trigger_time**. The values in turn can come from the default configuration +variable or from a state-specific override. + +When the alarm is armed, its state first goes to **pending** for a number +of seconds equal to the destination state's **pending_time**, and then +transitions to one of the "armed" states. Note that **code_template** +never receives "pending" in the **to_state** variable; instead, +**to_state** contains the state which the user has requested. However, +**from_state** *can* contain "pending". + +When the alarm is triggered, its state goes to **pending** for a number of +seconds equal to the previous state's **delay_time** plus the triggered +state's **pending_time**. Then the alarm transitions to the "triggered" +states. The code is never checked when triggering the alarm, so the +**to_state** variable of **code_template** cannot ever contain "triggered" +either; again, **from_state** *can* contain "triggered". + +The alarm remains in the "triggered" state for a number of seconds equal to the +previous state's **trigger_time**. Then, depending on **disarm_after_trigger**, +it goes back to either the previous state or **disarmed**. If the previous +state's **trigger_time** is zero, the transition to "triggered" is entirely +blocked and the alarm remains in the armed state. + +Each of the settings is useful in different scenarios. **pending_time** gives +you some time to leave the building (for "armed" states) or to disarm the alarm +(for the "triggered" state). + +**delay_time** can also be used to allow some time to disarm the alarm, but with +more flexibility. For example, you could specify a delay time for the +"armed away" state, in order to avoid triggering the alarm while the +garage door opens, but not for the "armed home" state. + +**trigger_time** is useful to disable the alarm when disarmed, but it can also +be used for example to sound the siren for a shorter time during the night. + +In the config example below: + +- the disarmed state never triggers the alarm; + +- the armed_home state will leave no time to leave the building or disarm the alarm; + +- while other states state will give 30 seconds to leave the building before triggering the alarm, and 20 seconds to disarm the alarm when coming back. ```yaml # Example configuration.yaml entry @@ -40,11 +89,13 @@ alarm_control_panel: name: Home Alarm code: 1234 pending_time: 30 + delay_time: 20 + trigger_time: 4 + disarmed: + trigger_time: 0 armed_home: pending_time: 0 - triggered: - pending_time: 20 - trigger_time: 4 + delay_time: 0 ``` ## {% linkable_title Examples %} diff --git a/source/_components/alarm_control_panel.manual_mqtt.markdown b/source/_components/alarm_control_panel.manual_mqtt.markdown index bf5ba5bdcc7..5ceaa64e3a0 100644 --- a/source/_components/alarm_control_panel.manual_mqtt.markdown +++ b/source/_components/alarm_control_panel.manual_mqtt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Manual Alarm Control Panel with MQTT Support" -description: "Instructions how to integrate manual alarms into Home Assistant with MQTT support." +description: "Instructions on how to integrate manual alarms into Home Assistant with MQTT support." date: 2017-07-02 9:10 sidebar: true comments: false @@ -9,7 +9,7 @@ sharing: true footer: true logo: home-assistant.png ha_category: Alarm -ha_release: 0.50 +ha_release: "0.50" --- This platform extends the [manual alarm](/components/alarm_control_panel.manual/) by adding support for MQTT control of the alarm by a remote device. It can be used to create external keypads which simply change the state of the manual alarm in Home Assistant. @@ -32,6 +32,8 @@ When the state of the manual alarm changes, Home Assistant will publish one of t - 'pending' - 'triggered' +To use your panel in your installation, add the following to your `configuration.yaml` file: + ```yaml # Example configuration.yaml entry alarm_control_panel: @@ -42,15 +44,21 @@ alarm_control_panel: Configuration variables: -All configuration variables from the base manual alarm platform are available: +The following configuration variables from the base manual alarm platform are available: - **name** (*Optional*): The name of the alarm. Default is "HA Alarm". - **code** (*Optional*): If defined, specifies a code to enable or disable the alarm in the frontend. This code is not required for MQTT interactions. -- **pending_time** (*Optional*): The time in seconds of the pending time before arming the alarm. Default is 60 seconds. +- **code_template** (*Optional*): If defined, returns a code to enable or disable the alarm in the frontend; an empty string disables checking the code. Inside the template, the variables **from_state** and **to_state** identify the current and desired state. Only one of **code** and **code_template** can be specified. +- **delay_time** (*Optional*): The time in seconds of the pending time before triggering the alarm. Default is 0 seconds. +- **pending_time** (*Optional*): The time in seconds of the pending time before effecting a state change. Default is 60 seconds. - **trigger_time** (*Optional*): The time in seconds of the trigger time in which the alarm is firing. Default is 120 seconds. - **disarm_after_trigger** (*Optional*): If true, the alarm will automatically disarm after it has been triggered instead of returning to the previous state. -- **armed_home|armed_away|armed_night|triggered** (*Optional*): State specific settings - - **pending_time**: State specific pending time override. +- **armed_home/armed_away/armed_night/disarmed/triggered** (*Optional*): State specific settings + - **delay_time** (*Optional*): State specific setting for **delay_time** (all states except **triggered**) + - **pending_time** (*Optional*): State specific setting for **pending_time** (all states except **disarmed**) + - **trigger_time** (*Optional*): State specific setting for **trigger_time** (all states except **triggered**) + +See the documentation for the [manual alarm platform](/components/alarm_control_panel.manual/) for a description. Additionally, the following MQTT configuration variables are also available: @@ -62,7 +70,11 @@ Additionally, the following MQTT configuration variables are also available: - **payload_arm_away** (*Optional*): The payload to set armed-away mode on this Alarm Panel. Default is "ARM_AWAY". - **payload_arm_night** (*Optional*): The payload to set armed-night mode on this Alarm Panel. Default is "ARM_NIGHT". -In the config example below, armed_home state will have no pending time and triggered state will have a pending time of 20 seconds whereas armed_away state will have a default pending time of 30 seconds. +In the configuration example below: + +- The disarmed state never triggers the alarm. +- The armed_home state will leave no time to leave the building or disarm the alarm. +- While other states state will give 30 seconds to leave the building before triggering the alarm, and 20 seconds to disarm the alarm when coming back. ```yaml # Example configuration.yaml entry @@ -71,11 +83,13 @@ alarm_control_panel: state_topic: home/alarm command_topic: home/alarm/set pending_time: 30 + delay_time: 20 + trigger_time: 4 + disarmed: + trigger_time: 0 armed_home: pending_time: 0 - triggered: - pending_time: 20 - trigger_time: 4 + delay_time: 0 ``` ## {% linkable_title Examples %} diff --git a/source/_components/alarm_control_panel.markdown b/source/_components/alarm_control_panel.markdown index ba5f469915b..bdc1adf3987 100644 --- a/source/_components/alarm_control_panel.markdown +++ b/source/_components/alarm_control_panel.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Alarm Control Panels" -description: "Instructions how to integrate Alarm Control Panels into Home Assistant." +description: "Instructions on how to integrate Alarm Control Panels into Home Assistant." date: 2015-10-13 19:10 sidebar: true comments: false diff --git a/source/_components/alarm_control_panel.mqtt.markdown b/source/_components/alarm_control_panel.mqtt.markdown index 7e6feaa7a2e..cb93a1b5958 100644 --- a/source/_components/alarm_control_panel.mqtt.markdown +++ b/source/_components/alarm_control_panel.mqtt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MQTT Alarm Control Panel" -description: "Instructions how to integrate MQTT capable Alarm Panels into Home Assistant." +description: "Instructions on how to integrate MQTT capable Alarm Panels into Home Assistant." date: 2015-09-14 19:10 sidebar: true comments: false @@ -35,14 +35,56 @@ alarm_control_panel: command_topic: "home/alarm/set" ``` -Configuration variables: - -- **state_topic** (*Required*): The MQTT topic subscribed to receive state updates. -- **command_topic** (*Required*): The MQTT topic to publish commands to change the alarm state. -- **name** (*Optional*): The name of the alarm. Default is 'MQTT Alarm'. -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0. This QoS will also be used to publishing messages. -- **payload_disarm** (*Optional*): The payload to disarm your Alarm Panel. Default is "DISARM". -- **payload_arm_home** (*Optional*): The payload to set armed-home mode on your Alarm Panel. Default is "ARM_HOME". -- **payload_arm_away** (*Optional*): The payload to set armed-away mode on your Alarm Panel. Default is "ARM_AWAY". -- **code** (*Optional*): If defined, specifies a code to enable or disable the alarm in the frontend. - +{% configuration %} +name: + description: The name of the alarm. + required: false + type: string + default: MQTT Alarm +state_topic: + description: The MQTT topic subscribed to receive state updates. + required: true + type: string +command_topic: + description: The MQTT topic to publish commands to change the alarm state. + required: true + type: string +qos: + description: The maximum QoS level of the state topic. + required: false + type: integer + default: 0 +payload_disarm: + description: The payload to disarm your Alarm Panel. + required: false + type: string + default: DISARM +payload_arm_home: + description: The payload to set armed-home mode on your Alarm Panel. + required: false + type: string + default: ARM_HOME +payload_arm_away: + description: The payload to set armed-away mode on your Alarm Panel. + required: false + type: string + default: ARM_AWAY +code: + description: If defined, specifies a code to enable or disable the alarm in the frontend. + required: false + type: string +availability_topic: + description: The MQTT topic subscribed to receive availability (online/offline) updates. + required: false + type: string +payload_available: + description: The payload that represents the available state. + required: false + type: string + default: online +payload_not_available: + description: The payload that represents the unavailable state. + required: false + type: string + default: offline +{% endconfiguration %} diff --git a/source/_components/alarm_control_panel.nx584.markdown b/source/_components/alarm_control_panel.nx584.markdown index 0a14c880db4..a98ad9050a6 100644 --- a/source/_components/alarm_control_panel.nx584.markdown +++ b/source/_components/alarm_control_panel.nx584.markdown @@ -1,7 +1,7 @@ --- layout: page title: "NX584 Alarm Control Panel" -description: "Instructions how to integrate NX584 into Home Assistant." +description: "Instructions on how to integrate NX584 into Home Assistant." date: 2016-02-07 10:00 sidebar: true comments: false diff --git a/source/_components/alarm_control_panel.satel_integra.markdown b/source/_components/alarm_control_panel.satel_integra.markdown index 77752ae7d0b..a5f8915d08c 100644 --- a/source/_components/alarm_control_panel.satel_integra.markdown +++ b/source/_components/alarm_control_panel.satel_integra.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Satel Integra Alarm Control Panel" -description: "Instructions how to setup the Satel Integra control panel within Home Assistant." +description: "Instructions on how to setup the Satel Integra control panel within Home Assistant." date: 2017-09-07 13:28 sidebar: true comments: false diff --git a/source/_components/alarm_control_panel.simplisafe.markdown b/source/_components/alarm_control_panel.simplisafe.markdown index af38f6ad372..ac5c14183a2 100644 --- a/source/_components/alarm_control_panel.simplisafe.markdown +++ b/source/_components/alarm_control_panel.simplisafe.markdown @@ -1,7 +1,7 @@ --- layout: page title: "SimpliSafe Alarm Control Panel" -description: "Instructions how to integrate SimpliSafe into Home Assistant." +description: "Instructions on how to integrate SimpliSafe into Home Assistant." date: 2016-07-02 22:00 sidebar: true comments: false diff --git a/source/_components/alarm_control_panel.spc.markdown b/source/_components/alarm_control_panel.spc.markdown index 78e7066f00e..5cc4025f001 100644 --- a/source/_components/alarm_control_panel.spc.markdown +++ b/source/_components/alarm_control_panel.spc.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Vanderbilt SPC Alarm" -description: "Instructions how to setup the Vanderbilt SPC Alarm control panel within Home Assistant." +description: "Instructions on how to setup the Vanderbilt SPC Alarm control panel within Home Assistant." date: 2017-05-18 22:01 sidebar: true comments: false diff --git a/source/_components/alarm_control_panel.totalconnect.markdown b/source/_components/alarm_control_panel.totalconnect.markdown index 668b7492054..203d53a5c04 100644 --- a/source/_components/alarm_control_panel.totalconnect.markdown +++ b/source/_components/alarm_control_panel.totalconnect.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Honeywell TotalConnect Alarm Control Panel" -description: "Instructions how to integrate TotalConnect alarms into Home Assistant." +description: "Instructions on how to integrate TotalConnect alarms into Home Assistant." date: 2017-04-02 22:00 sidebar: true comments: false @@ -34,3 +34,27 @@ Configuration variables: - **username** (*Required*): Username used to sign into the TotalConnect app/web client. - **password** (*Required*): Password used to sign into the TotalConnect app/web client. +Automation example: + +```yaml +automation: + - alias: "Alarm: Disarmed Daytime" + trigger: + platform: state + entity_id: alarm_control_panel.total_connect + to: 'disarmed' + condition: + condition: sun + before: sunset + action: + service: scene.turn_on + entity_id: scene.OnDisarmedDaytime + - alias: "Alarm: Armed Away" + trigger: + platform: state + entity_id: alarm_control_panel.total_connect + to: 'armed_away' + action: + service: scene.turn_on + entity_id: scene.OnArmedAway +``` diff --git a/source/_components/alarm_control_panel.verisure.markdown b/source/_components/alarm_control_panel.verisure.markdown index 0c06294c3ec..669de867612 100644 --- a/source/_components/alarm_control_panel.verisure.markdown +++ b/source/_components/alarm_control_panel.verisure.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Verisure Alarm" -description: "Instructions how to setup the Verisure Alarm control panel within Home Assistant." +description: "Instructions on how to setup the Verisure Alarm control panel within Home Assistant." date: 2016-02-15 22:00 sidebar: true comments: false diff --git a/source/_components/alarm_control_panel.wink.markdown b/source/_components/alarm_control_panel.wink.markdown index 032bbd3cb36..e6fee5cdb50 100644 --- a/source/_components/alarm_control_panel.wink.markdown +++ b/source/_components/alarm_control_panel.wink.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Wink Alarm" -description: "Instructions how to setup the Wink alarms within Home Assistant." +description: "Instructions on how to setup the Wink alarms within Home Assistant." date: 2017-01-14 12:00 sidebar: true comments: false diff --git a/source/_components/alarmdecoder.markdown b/source/_components/alarmdecoder.markdown index 82beb4b5e62..ae81c2cf1f5 100644 --- a/source/_components/alarmdecoder.markdown +++ b/source/_components/alarmdecoder.markdown @@ -20,7 +20,7 @@ Please visit the [AlarmDecoder website](https://www.alarmdecoder.com/) for furth There is currently support for the following device types within Home Assistant: - [Binary Sensor](/components/binary_sensor.alarmdecoder/): Reports on zone status -- [Sensor](/components/sensor.alarmdecoder/): Emulates an keypad display +- [Sensor](/components/sensor.alarmdecoder/): Emulates a keypad display - [Alarm Control Panel](/components/alarm_control_panel.alarmdecoder/): Reports on alarm status, and can be used to arm/disarm the system This is a fully event-based component. Any event sent by the AlarmDecoder device will be immediately reflected within Home Assistant. @@ -39,6 +39,7 @@ alarmdecoder: 01: name: 'Smoke Detector' type: 'smoke' + rfid: '0123456' 02: name: 'Front Door' type: 'opening' @@ -53,3 +54,6 @@ Configuration variables: - **baudrate** (*Optional*): The baud rate of the AlarmDecoder device, if using serial type. Default: `115200` - **panel_display** (*Optional*): Create a sensor called sensor.alarm_display to match the Alarm Keypad display. Default: `off` - **zones** (*Optional*): AlarmDecoder has no way to tell us which zones are actually in use, so each zone must be configured in Home Assistant. For each zone, at least a name must be given. For more information on the available zone types, take a look at the [Binary Sensor](/components/binary_sensor.alarmdecoder/) docs. *Note: If no zones are specified, Home Assistant will not load any binary_sensor components.* +- **rfid** (*Optional*): The RF serial-number associated with RF zones. Providing this field allows Home Assistant to associate raw sensor data to a given zone, allowing direct monitoring of the state, battery, and supervision status. +- **relayaddr** (*Optional*): Address of the relay expander board to associate with the zone. (ex: 12, 13, 14, or 15). Typically used in cases where a panel will not send bypassed zones such as motion during an armed home state, the Vista 20P is an example of this. Alarmdecoder can emulate a zone expander board and the panel can be programmed to push zone events to this virtual expander. This allows the bypassed zone binary sensors to be utilized. One example is using bypassed motion sensors at night for motion-based automated lights while the system is armed with the motion sensor bypassed. +- **relaychan** (*Optional*): Channel of the relay expander board to associate with the zone. (ex: 1, 2, 3, or 4) diff --git a/source/_components/alert.markdown b/source/_components/alert.markdown index acdf983305f..e1af527f5f2 100644 --- a/source/_components/alert.markdown +++ b/source/_components/alert.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Alert" -description: "Instructions how to setup automatic alerts within Home Assistant." +description: "Instructions on how to setup automatic alerts within Home Assistant." date: 2017-01-15 20:00 sidebar: true comments: false @@ -16,7 +16,9 @@ The `alert` component is designed to notify you when problematic issues arise. F Alerts will add an entity to the front end only when they are firing. This entity allows you to silence an alert until it is resolved. +When using the `alert` component, it is important that the time zone used for Home Assistant and the underlying operating system match. Failing to do so may result in multiple alerts being sent at the same time (such as when Home Assistant is set to the `America/Detroit` time zone but the operating system uses `UTC`). +
### {% linkable_title Basic Example %} diff --git a/source/_components/alexa.markdown b/source/_components/alexa.markdown index bccf44f2e77..23c8bc9c86d 100644 --- a/source/_components/alexa.markdown +++ b/source/_components/alexa.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Alexa / Amazon Echo" -description: "Instructions how to connect Alexa/Amazon Echo to Home Assistant." +description: "Instructions on how to connect Alexa/Amazon Echo to Home Assistant." date: 2015-12-13 13:02 sidebar: true comments: false @@ -10,13 +10,18 @@ footer: true logo: amazon-echo.png ha_category: Voice featured: true -ha_release: 0.10 +ha_release: '0.10' --- ++ Use [Home Assistant Cloud](/components/cloud/) to integrate with Alexa without any effort. +
+ There are a few ways that you can use Amazon Echo and Home Assistant together. - [Build custom commands to use](#i-want-to-build-custom-commands-to-use-with-echo) - [Create a new Flash Briefing source](#flash-briefing-skills) +- [Use the Smart Home API to control lights, etc](#smart-home) - Alternative: use the [Emulated Hue component][emulated-hue-component] to trick Alexa to thinking Home Assistant is a Philips Hue hub. Amazon has released [Echosim], a website that simulates the Alexa service in your browser. That way it is easy to test your skills without having access to a physical Amazon Echo. @@ -41,7 +46,7 @@ Additionally, note that at the time of this writing, your Alexa skill endpoint * OR 2. Change your Home Assistant serving port to 443 this is done in the [`http`](/components/http/) section with the `server_port` entry in your `configuration.yaml` file -[blog-lets-encrypt]: https://home-assistant.io/blog/2015/12/13/setup-encryption-using-lets-encrypt/ +[blog-lets-encrypt]: /blog/2015/12/13/setup-encryption-using-lets-encrypt/ To get started with Alexa skills: @@ -162,7 +167,7 @@ intent_script: text: OK ``` -Here we are using [templates] to take the name we gave to Alexa e.g. `downstairs on` and replace the space with an underscore so it becomes `downstairs_on` as Home Assistant expects. +Here we are using [templates] to take the name we gave to Alexa e.g., `downstairs on` and replace the space with an underscore so it becomes `downstairs_on` as Home Assistant expects. Now say `Alexa ask Home Assistant to activate+It is HIGHLY recommended that you set the `api_password`, especially if you are planning to expose your installation to the internet. +
+ +```yaml +# Example configuration.yaml entry +api: +``` + +For details to use the API, please refer to the [REST API](/developers/rest_api/) or the [Python REST API documentation](/developers/python_api/) in the "Developer" section. diff --git a/source/_components/apple_tv.markdown b/source/_components/apple_tv.markdown index 5709958530d..93d192a00c2 100644 --- a/source/_components/apple_tv.markdown +++ b/source/_components/apple_tv.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Apple TV" -description: "Instructions how to integrate Apple TV devices into Home Assistant." +description: "Instructions on how to integrate Apple TV devices into Home Assistant." date: 2017-06-26 20:47 sidebar: true comments: false @@ -13,7 +13,7 @@ ha_iot_class: "Local Push" ha_release: 0.49 --- -The `apple_tv` platform allows you to control an Apple TV (3rd and 4th generation). See the [remote platform](/components/remote.apple_tv/) if you want to send remote control buttons, e.g. arrow keys. +The `apple_tv` platform allows you to control an Apple TV (3rd and 4th generation). See the [remote platform](/components/remote.apple_tv/) if you want to send remote control buttons, e.g., arrow keys.
Currently, you must have Home Sharing enabled for this to work. Support for pairing Home Assistant with your device will be supported in a later release.
@@ -56,7 +56,9 @@ In order to connect to the device, you need a *login id*. The easiest way to obt
### {% linkable_title Scanning for devices %}
-To scan for devices, press the icon in the upper left corner and select the leftmost icon according to the image:
+Make sure Home Sharing is enabled on the Apple TV.
+
+To scan for devices and determine the `login_id`, press the icon in the upper left corner and select the leftmost icon according to the image:
@@ -78,26 +80,7 @@ Found Apple TVs:
Note: You must use 'pair' with devices that have home sharing disabled
```
-Just copy and paste the login id from the device you want to add. For more details about `atvremote`, see: [this page](http://pyatv.readthedocs.io/en/master/atvremote.html).
-
-### {% linkable_title My Apple TV turns on when I restart Home Assistant %}
-
-The Apple TV will automatically turn on if a request is sent to it, e.g., if a button is pressed, something is streamed to it via AirPlay or if current state (currently playing) is accessed. This is how Apple has designed it, and it will cause problems if you are using HDMI CEC. Every time Home Assistant is started, a new request is sent to the device to figure out what is currently playing. When using CEC, this will wake up your TV and other devices you have configured.
-
-So, if your TV is randomly turning on, this is probably the reason. As stated, this is by design, and there is no real fix for it. There's also no known way to turn off the Apple TV via the protocol used for communication. You have the following options:
-
-- Do not use this platform
-- Disable HDMI CEC on your Apple TV
-- Use "fake standby"
-
-The first two points are quite obvious. Fake standby is a concept implemented in this platform that disables all requests to the device and makes it appear as being "off" in the web interface. This will make sure that the device is not woken up, but it will of course not show any information or allow you to control it. It is however easy to turn it on (or off) in the web interface or to use an automation with `turn_on`. To make it more useful, you can write automations that turn it on or off depending on some other device, like the input source on your receiver.
-
-To put a device into fake standby when starting Home Assistant, add `start_off: true` to your configuration.
-
-
-Turning the device on/off in the user interface will *not* turn the physical device on/off according to the description above. -
- +Just copy and paste the `login_id` from the device you want to add. For more details about `atvremote`, see: [this page](http://pyatv.readthedocs.io/en/master/atvremote.html). ### {% linkable_title Setting up device authentication %} @@ -109,7 +92,7 @@ then device authentication is required. Press the icon in the upper left corner
-Select `apple_tv` as domain, `apple_tv_authenticate` as service and enter `{"entity_id": "XXX"}` into "Service Data", but replace XXX with the entity id of your device (e.g. `media_player.apple_tv`). Press the button and hopefully you are presented with an input dialog asking for a pin code:
+Select `apple_tv` as domain, `apple_tv_authenticate` as service and enter `{"entity_id": "XXX"}` into "Service Data", but replace XXX with the entity id of your device (e.g., `media_player.apple_tv`). Press the button and hopefully you are presented with an input dialog asking for a pin code:
@@ -129,6 +112,24 @@ apple_tv:
Restart Home Assistant, and you should now be able to use `play_url` as before.
+### {% linkable_title My Apple TV turns on when I restart Home Assistant %}
+
+The Apple TV will automatically turn on if a request is sent to it, e.g., if a button is pressed, something is streamed to it via AirPlay or if current state (currently playing) is accessed. This is how Apple has designed it, and it will cause problems if you are using HDMI CEC. Every time Home Assistant is started, a new request is sent to the device to figure out what is currently playing. When using CEC, this will wake up your TV and other devices you have configured.
+
+So, if your TV is randomly turning on, this is probably the reason. As stated, this is by design, and there is no real fix for it. There's also no known way to turn off the Apple TV via the protocol used for communication. You have the following options:
+
+- Do not use this platform
+- Disable HDMI CEC on your Apple TV
+- Use "fake standby"
+
+The first two points are quite obvious. Fake standby is a concept implemented in this platform that disables all requests to the device and makes it appear as being "off" in the web interface. This will make sure that the device is not woken up, but it will of course not show any information or allow you to control it. It is however easy to turn it on (or off) in the web interface or to use an automation with `turn_on`. To make it more useful, you can write automations that turn it on or off depending on some other device, like the input source on your receiver.
+
+To put a device into fake standby when starting Home Assistant, add `start_off: true` to your configuration.
+
++Turning the device on/off in the user interface will *not* turn the physical device on/off according to the description above. +
+ ## {% linkable_title Services %} ### {% linkable_title Service `apple_tv_authenticate` %} @@ -142,4 +143,3 @@ To play media on an Apple TV with device authentication enabled (e.g., ATV4 with ### {% linkable_title Service `apple_tv_scan` %} Scans the local network for Apple TVs. All found devices are presented as a persistent notification. - diff --git a/source/_components/arduino.markdown b/source/_components/arduino.markdown index 5105f19c4cc..ca16dd32b75 100644 --- a/source/_components/arduino.markdown +++ b/source/_components/arduino.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Arduino" -description: "Instructions how to setup an Arduino boards within Home Assistant." +description: "Instructions on how to setup an Arduino boards within Home Assistant." date: 2015-06-27 10:28 sidebar: true comments: false @@ -43,7 +43,7 @@ The exact number can be determined with the command shown below. $ ls /dev/ttyACM* ``` -If that's not working, check your `dmesg` or `journalctl -f` output. Keep in mind that Arduino clones are often using a different name for the port (e.g. `/dev/ttyUSB*`). +If that's not working, check your `dmesg` or `journalctl -f` output. Keep in mind that Arduino clones are often using a different name for the port (e.g., `/dev/ttyUSB*`).A word of caution: The Arduino boards are not storing states. This means that with every initialization the pins are set to off/low. diff --git a/source/_components/arlo.markdown b/source/_components/arlo.markdown index 479a7713293..a95acd4999e 100644 --- a/source/_components/arlo.markdown +++ b/source/_components/arlo.markdown @@ -15,29 +15,41 @@ ha_iot_class: "Cloud Polling" The `arlo` implementation allows you to integrate your [Arlo](https://arlo.netgear.com/) devices in Home Assistant. +## {% linkable_title Configuration %} + To enable device linked in your [Arlo](https://arlo.netgear.com/) account, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry arlo: - username: you@example.com - password: secret + username: YOUR_USERNAME + password: YOUR_PASSWORD ``` -Configuration variables: - -- **username** (*Required*): The username for accessing your Arlo account. -- **password** (*Required*): The password for accessing your Arlo account. +{% configuration %} +username: + description: The username for accessing your Arlo account. + required: true + type: string +password: + description: The password for accessing your Arlo account. + required: true + type: string +scan_interval: + description: How frequently to query for new data. Defaults to 60 seconds. + required: false + type: int +{% endconfiguration %} It is recommended to create a dedicated user on Arlo website to be used within Home Assistant and then share your Arlo cameras. -Finish its configuration by visiting the [Arlo sensor page](/components/sensor.arlo/) or [Arlo camera page](/components/camera.arlo/) or [Arlo control panel page](/components/alarm_control_panel.arlo/). +Finish its configuration by visiting the [Arlo sensor page](/components/sensor.arlo/) or [Arlo camera page](/components/camera.arlo/) or [Arlo control panel page](/components/alarm_control_panel.arlo/). Arlo also has a service call `arlo.update` that can be manually called to force an update prior to the regular scheduled interval. -The Arlo component also provides a service to enable/disable the motion detection sensor. The example below enables the motion detection every time the Home Assistant service starts. +The Arlo component also provides a camera service to enable/disable the motion detection sensor. The example below enables the motion detection every time the Home Assistant service starts. ```yaml #automation.yaml -- alias: Enable Arlo upton HA start' +- alias: Enable Arlo upon HA start' initial_state: 'on' trigger: platform: homeassistant diff --git a/source/_components/asterisk_mbox.markdown b/source/_components/asterisk_mbox.markdown index d0d7ba72fe2..f040acd99bb 100644 --- a/source/_components/asterisk_mbox.markdown +++ b/source/_components/asterisk_mbox.markdown @@ -1,42 +1,51 @@ --- layout: page title: "Asterisk Voicemail" -description: "Instructions how to integrate your existing Asterisk voicemail within Home Assistant." +description: "Instructions on how to integrate your existing Asterisk voicemail within Home Assistant." date: 2017-06-30 18:30 sidebar: true comments: false sharing: true footer: true +logo: asterisk.png ha_category: Other -ha_version: 0.51 ha_iot_class: "Local Push" +ha_release: 0.51 --- -The Asterisk Voicemail integration for Home Assistant allows you to view, listen to, and delete voicemails from an Asterisk voicemail mailbox. The component includes a panel on the frontend that provides caller-id and speech-to-text transcription (using Google's API) of messages in addition to playback and message deletion. There is also an included sensor that indicates of the number of available messages. There is no requirement that the Asterisk PBX and Home Assistant are running on the same machine. +The `asterisk_mbox` Asterisk Voicemail integration for Home Assistant allows you to view, listen to, and delete voicemails from an Asterisk voicemail mailbox. The component includes a panel on the frontend that provides caller-id and speech-to-text transcription (using Google's API) of messages in addition to playback and message deletion. There is also an included sensor that indicates of the number of available messages. There is no requirement that the Asterisk PBX and Home Assistant are running on the same machine. To enable the component, a configuration is required in both Home Assistant as well as on the Asterisk server. -First follow the [Asterisk PBX configuration guide](/docs/asterisk_mbox) to setup the necessary server on the Asterisk PBX server (this is needed even if Asterisk and Home Assistant are running on the same server) +First follow the [Asterisk PBX configuration guide](/docs/asterisk_mbox/) to setup the necessary server on the Asterisk PBX server (this is needed even if Asterisk and Home Assistant are running on the same server) Once that is complete, add the following entry `configuration.yaml` file: ```yaml # Example configuration.yaml entry asterisk_mbox: - password: ASTERISK_PBX_PASSWORD - host: ASTERISK_PBX_SERVER_IP_ADDRESS - port: ASTERISK_PBX_SERVER_PORT + password: ASTERISK_PBX_PASSWORD + host: ASTERISK_PBX_SERVER_IP_ADDRESS + port: ASTERISK_PBX_SERVER_PORT ``` This will add a new 'Mailbox' side-panel, as well as a sensor to indicate # of messages available. -Configuration variables: - -- **password** (*Required*): The password that was set during Asterisk PBX configuration -- **host** (*Required*): The ip-address of the server that is running the Asterisk PBX -- **port** (*Required*): The port on the Asterisk PBX server that was configured during Asterisk PBX configuration +{% configuration %} +password: + description: The password that was set during Asterisk PBX configuration + required: true + type: string +host: + description: The ip-address of the server that is running the Asterisk PBX + required: true + type: string +port: + description: The port on the Asterisk PBX server that was configured during Asterisk PBX configuration + required: true + type: string +{% endconfiguration %}
Communication between the Asterisk PBX server and the Home Assistant server is password-protected, but the data transmission is not encrypted. It is recommended to only use this component when communication is contained within a local area network.
- diff --git a/source/_components/august.markdown b/source/_components/august.markdown new file mode 100644 index 00000000000..818002e14c7 --- /dev/null +++ b/source/_components/august.markdown @@ -0,0 +1,56 @@ +--- +layout: page +title: "August" +description: "Instructions on how to integrate your August devices into Home Assistant." +date: 2018-02-17 22:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: august.png +ha_category: Hub +ha_release: "0.64" +ha_iot_class: "Cloud Polling" +--- + +The `august` component allows you to integrate your [August](http://august.com) devices in Home Assistant. Currently this component supports August Lock and Doorbell. + ++August Lock 2nd Gen will need either August Connect or Doorbell to connect to Home Assistant. +
+ +## {% linkable_title Configuration %} + +You will need your August login information (username (either phone# or email), and password) to use this module. + +To set it up, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +august: + login_method: phone + username: "+16041234567" + password: YOUR_PASSWORD +``` + +{% configuration %} +login_method: + description: Method to login to your August account, either "email" or "phone". A verification code will be sent to your email or phone during setup. + required: true + type: string +username: + description: The username for accessing your August account. This depends on your login_method, if login_method is email, this will be your email of the account. Otherwise, this will be your phone number. + required: true + type: string +password: + description: The password for accessing your August account. + required: true + type: string +timeout: + description: Timeout to wait for connections. + required: false + type: int + default: 10 +{% endconfiguration %} + +Once Home Assistant is started, a configurator will pop up asking you to enter verification code that is sent to your phone number or email. diff --git a/source/_components/auth.markdown b/source/_components/auth.markdown new file mode 100644 index 00000000000..96d0ab055a2 --- /dev/null +++ b/source/_components/auth.markdown @@ -0,0 +1,15 @@ +--- +layout: page +title: "Auth" +description: "This component is responsible for providing the authentication endpoints." +date: 2018-03-19 21:04 +sidebar: true +comments: false +sharing: true +footer: true +logo: home-assistant.png +ha_category: Other +ha_release: 0.73 +--- + +This component creates the endpoints for the authentication system that is built into Home Assistant. There are no configuration options for this component directly as it relies on the auth system in the core. diff --git a/source/_components/automation.markdown b/source/_components/automation.markdown index 181d28ba123..658c0ebc63c 100644 --- a/source/_components/automation.markdown +++ b/source/_components/automation.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Automation" -description: "Instructions how to setup automation within Home Assistant." +description: "Instructions on how to setup automation within Home Assistant." date: 2015-01-20 22:36 sidebar: true comments: false @@ -19,7 +19,7 @@ Starting with 0.28 your automation rules can be controlled with the frontend.
-This allows one to reload the automation without restarting Home Assistant itself. If you don't want to see the automation rule in your frontend use `hide_entity: True` to hide it. You can also use `initial_state: 'off'` so that the automation is not automatically turned on after a Home assistant reboot.
+This allows one to reload the automation without restarting Home Assistant itself. If you don't want to see the automation rule in your frontend use `hide_entity: True` to hide it. You can also use `initial_state: 'off'` so that the automation is not automatically turned on after a Home Assistant reboot.
```yaml
automation:
diff --git a/source/_components/axis.markdown b/source/_components/axis.markdown
index a23a97c2dfc..6f9a2cc4826 100644
--- a/source/_components/axis.markdown
+++ b/source/_components/axis.markdown
@@ -68,10 +68,6 @@ axis:
location: köket
```
--If you are using Python 3.6, you might need to replace the 34m with 36m in the _gi.*.so filename in the gi folder. -
-Any specific levels for triggers needs to be configured on the device.
diff --git a/source/_components/bbb_gpio.markdown b/source/_components/bbb_gpio.markdown index ab6a13d94e8..785aec4f2df 100644 --- a/source/_components/bbb_gpio.markdown +++ b/source/_components/bbb_gpio.markdown @@ -1,7 +1,7 @@ --- layout: page title: "BeagleBone Black GPIO" -description: "Instructions how to integrate the GPIO capability of a BeagleBone Black into Home Assistant." +description: "Instructions on how to integrate the GPIO capability of a BeagleBone Black into Home Assistant." date: 2017-01-14 10:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.abode.markdown b/source/_components/binary_sensor.abode.markdown index 14e8e14533a..def5cabb192 100644 --- a/source/_components/binary_sensor.abode.markdown +++ b/source/_components/binary_sensor.abode.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Abode Binary Sensor" -description: "Instructions how to integrate Abode binary sensors into Home Assistant." +description: "Instructions on how to integrate Abode binary sensors into Home Assistant." date: 2017-08-26 0:28 sidebar: true comments: false diff --git a/source/_components/binary_sensor.ads.markdown b/source/_components/binary_sensor.ads.markdown new file mode 100644 index 00000000000..753858d9737 --- /dev/null +++ b/source/_components/binary_sensor.ads.markdown @@ -0,0 +1,41 @@ +--- +layout: page +title: "ADS Binary Sensor" +description: "Instructions on how to set up ADS binary sensors within Home Assistant." +date: 2017-10-25 10:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: beckhoff.png +ha_category: Binary Sensor +ha_release: "0.60" +ha_iot_class: "Local Push" +--- + +The `ads` binary sensor platform can be used to monitor a boolean value on your ADS device. + +To use your ADS device, you first have to set up your [ADS hub](/components/ads/) and then add the following to your `configuration.yaml` +file: + +```yaml +# Example configuration.yaml entry +binary_sensor: + - platform: ads + adsvar: .boolean1 +``` + +{% configuration %} + adsvar: + required: true + description: The name of the variable which you want to access on the ADS device. + type: string + name: + required: false + description: An identifier for the light in the frontend. + type: string + device_class: + required: false + description: The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend. + type: string +{% endconfiguration %} diff --git a/source/_components/binary_sensor.alarmdecoder.markdown b/source/_components/binary_sensor.alarmdecoder.markdown index 1bfbd1be9f1..92cfa7fa4e1 100644 --- a/source/_components/binary_sensor.alarmdecoder.markdown +++ b/source/_components/binary_sensor.alarmdecoder.markdown @@ -1,7 +1,7 @@ --- layout: page title: "AlarmDecoder Binary Sensor" -description: "Instructions how to integrate AlarmDecoder binary sensors into Home Assistant." +description: "Instructions on how to integrate AlarmDecoder binary sensors into Home Assistant." date: 2017-04-02 13:28 sidebar: true comments: false diff --git a/source/_components/binary_sensor.android_ip_webcam.markdown b/source/_components/binary_sensor.android_ip_webcam.markdown index 80775c3b2e6..0c5c2abbe87 100644 --- a/source/_components/binary_sensor.android_ip_webcam.markdown +++ b/source/_components/binary_sensor.android_ip_webcam.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Android IP Webcam Binary Sensor" -description: "Instructions how to integrate binary motion sensors for Android IP webcam within Home Assistant." +description: "Instructions on how to integrate binary motion sensors for Android IP webcam within Home Assistant." date: 2017-03-10 00:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.arest.markdown b/source/_components/binary_sensor.arest.markdown index a03c972e7b8..d18a2d321a7 100644 --- a/source/_components/binary_sensor.arest.markdown +++ b/source/_components/binary_sensor.arest.markdown @@ -1,7 +1,7 @@ --- layout: page title: "aREST Binary Sensor" -description: "Instructions how to integrate aREST binary sensors within Home Assistant." +description: "Instructions on how to integrate aREST binary sensors within Home Assistant." date: 2015-11-20 18:15 sidebar: true comments: false @@ -14,7 +14,7 @@ ha_release: 0.9 --- -The `arest` binary sensor platform allows you to get all data from your devices (like Arduinos with a ethernet/wifi connection, the ESP8266, and the Raspberry Pi) running the [aREST](http://arest.io/) RESTful framework. +The `arest` binary sensor platform allows you to get all data from your devices (like Arduinos with an ethernet/wifi connection, the ESP8266, and the Raspberry Pi) running the [aREST](http://arest.io/) RESTful framework. To use your aREST binary sensor in your installation, add the following to your `configuration.yaml` file: @@ -28,7 +28,7 @@ binary_sensor: Configuration variables: -- **resource** (*Required*): IP address and schema of the device that is exposing an aREST API, e.g. http://192.168.1.10. +- **resource** (*Required*): IP address and schema of the device that is exposing an aREST API, e.g., http://192.168.1.10. - **pin** (*Required*): Number of the pin to monitor. - **name** (*Optional*): Let you overwrite the name of the device. By default *name* from the device is used. diff --git a/source/_components/binary_sensor.august.markdown b/source/_components/binary_sensor.august.markdown new file mode 100644 index 00000000000..be793af19b8 --- /dev/null +++ b/source/_components/binary_sensor.august.markdown @@ -0,0 +1,22 @@ +--- +layout: page +title: "August Binary Sensor" +description: "Instructions on how to integrate your August devices into Home Assistant." +date: 2018-02-17 22:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: august.png +ha_category: Binary Sensor +ha_release: "0.64" +ha_iot_class: "Cloud Polling" +--- + +To get your [August](http://august.com) doorbell binary sensors working within Home Assistant, please follow the instructions for the general [August component](/components/august/). + +If you have August Doorbell, once you have enabled the [August component](/components/august/), you should see following sensors: + +* Doorbell ding sensor +* Doorbell motion sensor +* Doorbell online sensor diff --git a/source/_components/binary_sensor.axis.markdown b/source/_components/binary_sensor.axis.markdown index 77ece6d1474..499739b0589 100644 --- a/source/_components/binary_sensor.axis.markdown +++ b/source/_components/binary_sensor.axis.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Axis Binary Sensor" -description: "Instructions how to integrate Axis binary sensors into Home Assistant." +description: "Instructions on how to integrate Axis binary sensors into Home Assistant." date: 2017-04-01 19:00 sidebar: true comments: false @@ -19,10 +19,9 @@ See the [Axis main component](/components/axis/) for configuration instructions. The following sensor types are supported: - - * Motion detection - * Passive IR motion detection - * Sound detection - * Day/night mode - * Tampering detection - * Input port +- Motion detection +- Passive IR motion detection +- Sound detection +- Day/night mode +- Tampering detection +- Input port diff --git a/source/_components/binary_sensor.bayesian.markdown b/source/_components/binary_sensor.bayesian.markdown index 0d2858e9829..ad52a8e85fd 100644 --- a/source/_components/binary_sensor.bayesian.markdown +++ b/source/_components/binary_sensor.bayesian.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Bayesian Binary Sensor" -description: "Instructions how to integrate threshold Bayesian sensors into Home Assistant." +description: "Instructions on how to integrate threshold Bayesian sensors into Home Assistant." date: 2017-08-27 20:05 sidebar: true comments: false diff --git a/source/_components/binary_sensor.bbb_gpio.markdown b/source/_components/binary_sensor.bbb_gpio.markdown index fbe724abf1f..be2a9bd9fb3 100644 --- a/source/_components/binary_sensor.bbb_gpio.markdown +++ b/source/_components/binary_sensor.bbb_gpio.markdown @@ -1,7 +1,7 @@ --- layout: page title: "BeagleBone Black GPIO Binary Sensor" -description: "Instructions how to integrate the GPIO sensor capability of a BeagleBone Black into Home Assistant." +description: "Instructions on how to integrate the GPIO sensor capability of a BeagleBone Black into Home Assistant." date: 2017-01-14 10:00 sidebar: true comments: false @@ -33,7 +33,7 @@ Configuration variables: - **pins** array (*Required*): Array of used pins. - **pin_name** (*Required*): Pin numbers and corresponding names. - **name** (*Required*): Friendly name to use for the frontend. - - **bouncetime** (*Optional*): Debounce time for reading input pin defined in miliseconds [ms]. Defaults to `50 ms`. + - **bouncetime** (*Optional*): Debounce time for reading input pin defined in milliseconds [ms]. Defaults to `50 ms`. - **invert_logic** (*Optional*): If `true`, inverts the input logic to ACTIVE LOW. Default is `false` (ACTIVE HIGH). - **pull_mode** (*Optional*): Type of internal pull resistor connected to input. Options are `UP` - pull-up resistor and `DOWN` - pull-down resistor. Defaults to `UP`. diff --git a/source/_components/binary_sensor.bmw_connected_drive.markdown b/source/_components/binary_sensor.bmw_connected_drive.markdown new file mode 100755 index 00000000000..74330ec5635 --- /dev/null +++ b/source/_components/binary_sensor.bmw_connected_drive.markdown @@ -0,0 +1,20 @@ +--- +layout: page +title: "BMW Connected Drive Binary Sensor" +description: "Instructions on how to setup your BMW Connected Drive account with Home Assistant." +date: 2018-02-22 23:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: bmw.png +ha_category: Binary Sensor +ha_release: 0.66 +--- + + +The `bmw_connected_drive` platform allows you to import data on your BMW into Home Assistant. + +The binary sensors will be automatically configured if `bmw_connected_drive` component is configured. + +For more configuration information see the [`bmw_connected_drive` component](/components/bmw_connected_drive/) documentation. diff --git a/source/_components/binary_sensor.command_line.markdown b/source/_components/binary_sensor.command_line.markdown index f966144470b..93769da9729 100644 --- a/source/_components/binary_sensor.command_line.markdown +++ b/source/_components/binary_sensor.command_line.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Command line Binary Sensor" -description: "Instructions how to integrate Command binary sensors within Home Assistant." +description: "Instructions on how to integrate Command binary sensors within Home Assistant." date: 2016-01-13 12:15 sidebar: true comments: false @@ -33,7 +33,8 @@ Configuration variables: - **payload_on** (*Optional*): The payload that represents enabled state. Default is "ON". - **payload_off** (*Optional*): The payload that represents disabled state. Default is "OFF". - **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload. -- **scan_interval** (*Optional*): Defines number of seconds for polling interval (defaults to 60 seconds). +- **scan_interval** (*Optional*): Defines number of seconds for polling interval (defaults to 60 seconds). +- **command_timeout** (*Optional*): Defines number of seconds for command timeout (defaults to 15 seconds). ## {% linkable_title Examples %} @@ -81,3 +82,27 @@ binary_sensor: ``` Consider to use the [`ping` sensor ](/components/binary_sensor.ping/) as an alternative to the samples above. + +### {% linkable_title Check if a system service is running %} + +The services running is listed in `/etc/systemd/system` and can be checked with the `systemctl` command: + +``` +$ systemctl is-active home-assistant@rock64.service +active +$ sudo service home-assistant@rock64.service stop +$ systemctl is-active home-assistant@rock64.service +inactive +``` + +A binary command line sensor can check this: + +```yaml +binary_sensor: + - platform: command_line + command: '/bin/systemctl is-active home-assistant@rock64.service' + payload_on: 'active' + payload_off: 'inactive' +``` + +Note: Use single quotes! diff --git a/source/_components/binary_sensor.concord232.markdown b/source/_components/binary_sensor.concord232.markdown index 4378b5fb149..39320bb6723 100644 --- a/source/_components/binary_sensor.concord232.markdown +++ b/source/_components/binary_sensor.concord232.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Concord232 Binary Sensor" -description: "Instructions how to integrate Interlogix/GE Concord4 binary sensors into Home Assistant." +description: "Instructions on how to integrate Interlogix/GE Concord4 binary sensors into Home Assistant." date: 2016-10-11 10:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.deconz.markdown b/source/_components/binary_sensor.deconz.markdown new file mode 100644 index 00000000000..f0499482838 --- /dev/null +++ b/source/_components/binary_sensor.deconz.markdown @@ -0,0 +1,35 @@ +--- +layout: page +title: "deCONZ Binary Sensor" +description: "Instructions on how to integrate Zigbee binary sensors from deCONZ into Home Assistant." +date: 2017-11-12 16:30 +sidebar: true +comments: false +sharing: true +footer: true +logo: deconz.jpeg +ha_category: Binary Sensor +ha_release: "0.61" +ha_iot_class: "Local Push" +--- + +See the [deCONZ main component](/components/deconz/) for configuration instructions. + +The following sensor types are supported: + + * Fire/Smoke detection + * Open/Close detection + * Presence detection + * Water leakage detection + +Entity ids will be binary_sensor.device_name, where device_name is defined in deCONZ. + +#### {% linkable_title Verified to be supported binary sensors %} + +- Open/Close Detection + - Xiaomi Smart Home Security Door & Window Contact Sensor +- Presence Detection + - IKEA Trådfri Motion Sensor + - Philips Hue Motion Sensor + - Xiaomi Motion Sensor + - Xiaomi Smart Home Aqara Human Body Sensor diff --git a/source/_components/binary_sensor.doorbird.markdown b/source/_components/binary_sensor.doorbird.markdown deleted file mode 100644 index b16dc68c5e9..00000000000 --- a/source/_components/binary_sensor.doorbird.markdown +++ /dev/null @@ -1,28 +0,0 @@ ---- -layout: page -title: "DoorBird Binary Sensor" -description: "Instructions how to integrate DoorBird video doorbell state into Home Assistant." -date: 2017-08-06 11:30 -sidebar: true -comments: false -sharing: true -footer: true -logo: doorbird.png -ha_category: Binary Sensor -ha_release: "0.54" -ha_iot_class: "Local Polling" ---- - -The `doorbird` binary sensor platform allows Home Assistant to monitor when your [DoorBird](http://www.doorbird.com/) doorbell rings. - -- You must have the [DoorBird component](/components/doorbird/) configured to use this binary sensor. -
- -To enable the binary sensor, add the following to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -binary_sensor: - - platform: doorbird -``` diff --git a/source/_components/binary_sensor.ecobee.markdown b/source/_components/binary_sensor.ecobee.markdown index 189c943bf97..25f58c42cbc 100644 --- a/source/_components/binary_sensor.ecobee.markdown +++ b/source/_components/binary_sensor.ecobee.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Ecobee Binary Sensor" -description: "Instructions how to setup the Ecobee sensors within Home Assistant." +description: "Instructions on how to setup the Ecobee sensors within Home Assistant." date: 2015-11-30 18:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.egardia.markdown b/source/_components/binary_sensor.egardia.markdown new file mode 100644 index 00000000000..d418559f8e9 --- /dev/null +++ b/source/_components/binary_sensor.egardia.markdown @@ -0,0 +1,19 @@ +--- +layout: page +title: "Egardia Binary Sensor" +description: "Instructions on how to integrate Egardia / Woonveilig binary sensors into Home Assistant." +date: 2018-03-02 09:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: egardia.png +ha_release: 0.65 +ha_category: Binary Sensor +ha_iot_class: "Polling" +--- + +The `egardia` platform allows you to get data from your [Egardia](http://www.egardia.com)/[Woonveilig](http://www.woonveilig.nl) binary sensors from within Home Assistant. +Currently only door contacts are supported. IR sensors are not supported and will probably never be since their status cannot be read outside of the alarm control panel. Smoke sensors and others might be added but currently are not supported. + +You will need to set up your [Egardia hub](/components/egardia/). diff --git a/source/_components/binary_sensor.eight_sleep.markdown b/source/_components/binary_sensor.eight_sleep.markdown index fa949ae66e9..cf9f2c52bfd 100644 --- a/source/_components/binary_sensor.eight_sleep.markdown +++ b/source/_components/binary_sensor.eight_sleep.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Eight Sleep Binary Sensor" -description: "Instructions how to integrate binary motion sensors for Eight Sleep within Home Assistant." +description: "Instructions on how to integrate binary motion sensors for Eight Sleep within Home Assistant." date: 2017-04-24 00:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.enocean.markdown b/source/_components/binary_sensor.enocean.markdown index 32f3fc3340e..fe4ea3dd681 100644 --- a/source/_components/binary_sensor.enocean.markdown +++ b/source/_components/binary_sensor.enocean.markdown @@ -13,7 +13,13 @@ ha_release: 0.21 ha_iot_class: "Local Push" --- -This can typically be one of those batteryless wall switches. Currently only one type has been tested: Eltako FT55 which uses the EnOcean PTM 215 module. All switches using this module are expected to work. Other devices will most likely not work without changing the Home Assistant code. +This can typically be one of those batteryless wall switches. +Tested with: + +- Eltako FT55 which uses the EnOcean PTM 215 module +- [TRIO2SYS Wall switches](http://www.trio2sys.fr/index.php/fr/produits-enocean-sans-fil-sans-pile-interoperable/emetteur-sans-fils-sans-pile-interoperable-enocean) which uses the EnOcean PTM210 DB module + +All switches using theses modules are expected to work. Other devices will most likely not work without changing the Home Assistant code. To use your EnOcean device, you first have to set up your [EnOcean hub](/components/enocean/) and then add the following to your `configuration.yaml` file: diff --git a/source/_components/binary_sensor.envisalink.markdown b/source/_components/binary_sensor.envisalink.markdown index 6e56da0b94b..52735a8dbfd 100644 --- a/source/_components/binary_sensor.envisalink.markdown +++ b/source/_components/binary_sensor.envisalink.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Envisalink Binary Sensor" -description: "Instructions how to integrate Envisalink binary sensors into Home Assistant." +description: "Instructions on how to integrate Envisalink binary sensors into Home Assistant." date: 2016-07-01 08:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.ffmpeg_motion.markdown b/source/_components/binary_sensor.ffmpeg_motion.markdown index 453c76d7e01..6635bae9e69 100644 --- a/source/_components/binary_sensor.ffmpeg_motion.markdown +++ b/source/_components/binary_sensor.ffmpeg_motion.markdown @@ -42,7 +42,7 @@ Configuration variables: - **reset** (*Optional*): The time to reset the state after no new motion is detected. Defaults to 20 seconds. - **repeat** (*Optional*): How many events need to be detected in *repeat_time* in order to trigger a motion. Defaults to 0 repeats (deactivated). - **repeat_time** (*Optional*): The span of time *repeat* events need to occur in before triggering a motion. Defaults to 0 seconds (deactivated). -- **extra_arguments** (*Optional*): Extra options to pass to `ffmpeg`, e.g. video denoise filtering. +- **extra_arguments** (*Optional*): Extra options to pass to `ffmpeg`, e.g., video denoise filtering. To experiment with values (changes/100 is the scene value in `ffmpeg`): diff --git a/source/_components/binary_sensor.ffmpeg_noise.markdown b/source/_components/binary_sensor.ffmpeg_noise.markdown index 16b18761430..d68ec7d1630 100644 --- a/source/_components/binary_sensor.ffmpeg_noise.markdown +++ b/source/_components/binary_sensor.ffmpeg_noise.markdown @@ -39,7 +39,7 @@ Configuration variables: - **duration** (*Optional*): Default 1 second. How long the noise needs to be over the peak to trigger the state. - **reset** (*Optional*): Default 20 seconds. The time to reset the state after no new noise is over the peak. - **extra_arguments** (*Optional*): Extra options to pass to `ffmpeg`, like audio frequency filtering. -- **output** (*Optional*): Allows you to send the audio output of this sensor to an Icecast server or other FFmpeg-supported output, e.g. to stream with Sonos after a state is triggered. +- **output** (*Optional*): Allows you to send the audio output of this sensor to an Icecast server or other FFmpeg-supported output, e.g., to stream with Sonos after a state is triggered. To experiment with values: diff --git a/source/_components/binary_sensor.flic.markdown b/source/_components/binary_sensor.flic.markdown index 558c30b3a09..3767ed7476a 100644 --- a/source/_components/binary_sensor.flic.markdown +++ b/source/_components/binary_sensor.flic.markdown @@ -1,7 +1,7 @@ --- layout: page title: Flic Smart Button -description: "Instructions how to integrate flic buttons within Home Assistant." +description: "Instructions on how to integrate flic buttons within Home Assistant." date: 2016-12-02 22:03 sidebar: true comments: false diff --git a/source/_components/binary_sensor.gc100.markdown b/source/_components/binary_sensor.gc100.markdown index 3be8c013046..80d828723bd 100644 --- a/source/_components/binary_sensor.gc100.markdown +++ b/source/_components/binary_sensor.gc100.markdown @@ -1,7 +1,7 @@ --- layout: page title: gc100 Binary Sensor -description: "Instructions on how to set up an gc100 binary sensor within Home Assistant." +description: "Instructions on how to set up a gc100 binary sensor within Home Assistant." date: 2017-10-27 17:26 sidebar: true comments: false diff --git a/source/_components/binary_sensor.hikvision.markdown b/source/_components/binary_sensor.hikvision.markdown index ae37f2e9797..97c63757163 100644 --- a/source/_components/binary_sensor.hikvision.markdown +++ b/source/_components/binary_sensor.hikvision.markdown @@ -15,18 +15,22 @@ ha_iot_class: "Local Push" The Hikvision Binary Sensor is a platform that parses the event stream of a [Hikvision IP Camera or NVR](http://www.hikvision.com/) and presents the camera/nvr events to Home Assistant as binary sensors with either an "off" or "on" state. -The platform will automatically add all sensors to Home Assistant that are configured within the camera/nvr interface to "Notify the surveillance center" as a trigger. If you would like to hide a sensor type you can do so by either unchecking "Notify the surveillance center" in the camera configuration or by using the "ignored" customize option detailed below. +The platform will automatically add all sensors to Home Assistant that are configured within the camera/nvr interface to "Notify the surveillance center" as a trigger. If you would like to hide a sensor type you can do so by either unchecking "Notify the surveillance center" in the camera configuration or by using the "ignored" customize option detailed below. + ++In order for the sensors to work the hikvision user must have the 'Remote: Notify Surveillance Center/Trigger Alarm Output' permission which can be enabled from the user management section of the web interface. Also the 'WEB Authentication' needs to be set to 'digest/basic' in the security/authentication section. +
For example, if you configure a camera with the name "Front Porch" that has motion detection and line crossing events enabled to notify the surveillance center the following binary sensors will be added to Home Assistant: -``` +```text binary_sensor.front_porch_motion binary_sensor.front_port_line_crossing ``` -When used with a NVR device the sensors will be appended with the channel number they represent. For example, if you configure an NVR with the name "Home" that supports 2 cameras with motion detection and line crossing events enabled to notify the surveillance center the following binary sensors will be added to Home Assistant: +When used with a NVR device the sensors will be appended with the channel number they represent. For example, if you configure an NVR with the name "Home" that supports 2 cameras with motion detection and line crossing events enabled to notify the surveillance center the following binary sensors will be added to Home Assistant: -``` +```text binary_sensor.home_motion_1 binary_sensor.home_motion_2 binary_sensor.home_line_crossing_1 @@ -34,35 +38,38 @@ binary_sensor.home_line_crossing_2 ``` This platform should work with all Hikvision cameras and nvrs, and has been confirmed to work with the following models: + - DS-2CD3132-I - DS-2CD2232-I5 - DS-2CD2032-I - DS-2CD2042WD-I - DS-2CD2142FWD-I +- DS-2CD2155FWD-IS -To enable this sensor, the following lines are required in your `configuration.yaml`: +To enable this sensor, the following lines are required in your `configuration.yaml` file: ```yaml binary_sensor: - platform: hikvision - host: IP_ADDRESS - username: user - password: pass + - platform: hikvision + host: IP_ADDRESS + username: user + password: pass ``` Configuration options for a Hikvision Sensor: -- **name** (*Optional*): The name you'd like to give the camera in Home Assistant, defaults to name defined in the camera. - **host** (*Required*): The IP address of the camera you would like to connect to. -- **port** (*Optional*): The port to connect to the camera on, defaults to 80. -- **ssl** (*Optional*): True if you want to connect with https. Be sure to set the port also. - **username** (*Required*): The username to authenticate with. - **password** (*Required*): The password to authenticate with. +- **name** (*Optional*): The name you'd like to give the camera in Home Assistant, defaults to name defined in the camera. +- **port** (*Optional*): The port to connect to the camera on, defaults to 80. +- **ssl** (*Optional*): True if you want to connect with https. Be sure to set the port also. - **customize** (*Optional*): This attribute contains sensor-specific override values. Only sensor name needs defined: - **ignored** (*Optional*): Ignore this sensor completely. It won't be shown in the Web Interface and no events are generated for it. - **delay** (*Optional*): Specify the delay to wait after a sensor event ends before notifying Home Assistant. This is useful to catch multiple quick trips in one window without the state toggling on and off. The default delay is 5 seconds. Supported sensor/event types are: + - Motion - Line Crossing - Field Detection @@ -80,37 +87,36 @@ Supported sensor/event types are: - Face Detection - Scene Change Detection - Example of a configuration in your `configuration.yaml` that utilizes the customize options for a camera: ```yaml binary_sensor: - platform: hikvision - host: 192.168.X.X - port: 80 - ssl: False - username: user - password: pass - customize: - motion: - delay: 30 - line_crossing: - ignored: True + - platform: hikvision + host: 192.168.X.X + port: 80 + ssl: False + username: user + password: pass + customize: + motion: + delay: 30 + line_crossing: + ignored: True ``` Example of a configuration in your `configuration.yaml` that utilizes the customize options for a nvr: ```yaml binary_sensor: - platform: hikvision - host: 192.168.X.X - port: 80 - ssl: False - username: user - password: pass - customize: - motion_1: - delay: 30 - field_detection_2: - ignored: True + - platform: hikvision + host: 192.168.X.X + port: 80 + ssl: False + username: user + password: pass + customize: + motion_1: + delay: 30 + field_detection_2: + ignored: True ``` diff --git a/source/_components/binary_sensor.hive.markdown b/source/_components/binary_sensor.hive.markdown index 62022aa898c..49486d62d76 100644 --- a/source/_components/binary_sensor.hive.markdown +++ b/source/_components/binary_sensor.hive.markdown @@ -1,6 +1,6 @@ --- layout: page -title: "Hive Sensor" +title: "Hive Binary Sensor" description: "Instructions on how to integrate Hive Sensors with Home Assistant." date: 2017-09-24 21:00 sidebar: true @@ -14,11 +14,12 @@ ha_iot_class: "Cloud Polling" --- -The 'hive' binary sensor component integrates your Hive sensors into Home Assistant. +The `hive` binary sensor component integrates your Hive sensors into Home Assistant. -The Hive sensor component supports the following Hive products: -- **Hive Window or Door Sensor** -- **Hive Motion Sensor** +The platform supports the following Hive products: + +- Hive Window or Door Sensor +- Hive Motion Sensordiff --git a/source/_components/binary_sensor.homematic.markdown b/source/_components/binary_sensor.homematic.markdown index 37140c84337..5155aedeea1 100644 --- a/source/_components/binary_sensor.homematic.markdown +++ b/source/_components/binary_sensor.homematic.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Homematic Binary Sensor" -description: "Instructions how to integrate binary Homematic sensors within Home Assistant." +description: "Instructions on how to integrate binary Homematic sensors within Home Assistant." date: 2016-06-28 08:30 sidebar: true comments: false diff --git a/source/_components/binary_sensor.homematicip_cloud.markdown b/source/_components/binary_sensor.homematicip_cloud.markdown new file mode 100644 index 00000000000..7e9336cf1f9 --- /dev/null +++ b/source/_components/binary_sensor.homematicip_cloud.markdown @@ -0,0 +1,21 @@ +--- +layout: page +title: "HomematicIP Cloud Binary Sensor" +description: "Instructions on how to integrate HomematicIP binary sensors within Home Assistant." +date: 2018-04-02 13:40 +sidebar: true +comments: false +sharing: true +footer: true +logo: homematicip_cloud.png +ha_category: Binary Sensor +ha_release: 0.70 +ha_iot_class: "Cloud Push" +--- + +The `homematicip_cloud` binary_switch platform allows you to control +[HomematicIP](http://www.homematic-ip.com) binary sensors through Home Assistant. + +Devices will be configured automatically. Please refer to the +[component](/components/homematicip_cloud/) configuration on how to setup +HomematicIP Cloud. diff --git a/source/_components/binary_sensor.http.markdown b/source/_components/binary_sensor.http.markdown index aaddf8a7256..c2442aa881f 100644 --- a/source/_components/binary_sensor.http.markdown +++ b/source/_components/binary_sensor.http.markdown @@ -1,7 +1,7 @@ --- layout: page title: "HTTP Binary Sensor" -description: "Instructions how to integrate HTTP binary sensors within Home Assistant." +description: "Instructions on how to integrate HTTP binary sensors within Home Assistant." date: 2016-02-05 12:15 sidebar: true comments: false diff --git a/source/_components/binary_sensor.hydrawise.markdown b/source/_components/binary_sensor.hydrawise.markdown new file mode 100644 index 00000000000..cd066354673 --- /dev/null +++ b/source/_components/binary_sensor.hydrawise.markdown @@ -0,0 +1,41 @@ +--- +layout: page +title: "Hunter Hydrawise Binary Sensor" +description: "Instructions on how to integrate your Hunter Hydrawise Wi-Fi irrigation control system within Home Assistant." +date: 2018-04-11 08:02 +sidebar: true +comments: false +sharing: true +footer: true +logo: hydrawise_logo.png +ha_category: Binary Sensor +ha_release: 0.71 +ha_iot_class: Cloud Polling +--- + +Before setting up the [Hunter Hydrawise](https://hydrawise.com) binary sensors please follow the instructions for setting up the [Hydrawise hub](/components/hydrawise) component. + +Once you have enabled the `hydrawise` component, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +binary_sensor: + - platform: hydrawise +``` + +{% configuration %} +monitored_conditions: + description: The binary sensors that should be displayed on the frontend. + required: false + type: list + default: All binary sensors are enabled. + keys: + is_watering: + description: The binary sensor is `on` when the zone is actively watering. + rain_sensor: + description: Is `on` when the rain_sensor (if installed on the controller) is active (wet). + status: + description: This will indicate `on` when there is a connection to the Hydrawise cloud. It is not an indication of whether the irrigation controller hardware is online. +{% endconfiguration %} + +Finish the configuration by visiting the [Hydrawise sensor](/components/sensor.hydrawise/) and [Hydrawise switch](/components/switch.hydrawise/) documentation. diff --git a/source/_components/binary_sensor.ihc.markdown b/source/_components/binary_sensor.ihc.markdown new file mode 100644 index 00000000000..da5aac7615e --- /dev/null +++ b/source/_components/binary_sensor.ihc.markdown @@ -0,0 +1,69 @@ +--- +layout: page +title: "IHC Binary Sensor" +description: "Instructions on how to integrate IHC Binary Sensors within Home Assistant." +date: 2017-11-27 13:35 +sidebar: true +comments: false +sharing: true +footer: true +logo: ihc.png +ha_category: Binary Sensor +ha_release: 0.62 +ha_iot_class: "Local Push" +--- + +Before you can use the IHC Binary Sensor platform, you must setup the [IHC Component](/components/ihc/) + +When auto setup is enabled the following products will be found in the IHC project and setup as binary sensors: + +* Dataline magnet contacts +* Dataline Pir sensors +* Dataline Pir sensors with twilight detection +* Dataline Pir alarm sensor +* Dataline smoke detector +* Dataline gas detector +* Dataline light sensor + +To manually configure IHC Binary Sensors insert this section in your configuration: + +```yaml +binary_sensor: + - platform: ihc + binary_sensors: + - id: 12345 + name: mysensor + type: opening + inverting: True + - id: 12346 + ... +``` + +{% configuration %} +binary_sensors: + description: List of binary sensors to setup manually. + required: false + type: map + keys: + id: + description: The IHC resource id. + required: true + type: int + inverting: + description: If True the sensor will be inverted. + required: false + type: bool + default: false + name: + description: The name of the component + required: false + type: string + type: + description: The binary sensor type. See [Home Assistant binary sensor](/components/binary_sensor/) for available types. + required: false + type: string +{% endconfiguration %} + +The resource id should be an id of a boolean IHC resource. +For more information about IHC resource ids see [Manual Setup](/components/ihc/#manual-setup) + diff --git a/source/_components/binary_sensor.insteon_plm.markdown b/source/_components/binary_sensor.insteon_plm.markdown index bd685df7c29..0ee0aaf0375 100644 --- a/source/_components/binary_sensor.insteon_plm.markdown +++ b/source/_components/binary_sensor.insteon_plm.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Insteon PLM Binary Sensor" -description: "Instructions how to setup the Insteon PLM switches locally within Home Assistant." +description: "Instructions on how to setup the Insteon PLM binary sensors locally within Home Assistant." date: 2017-02-19 17:00 sidebar: true comments: false @@ -10,13 +10,12 @@ footer: true logo: insteon.png ha_category: Binary Sensor ha_iot_class: "Local Push" -ha_version: 0.39 +ha_release: 0.39 --- -The `insteon_plm` binary sensor platform lets you control your sensors through +The `insteon_plm` binary sensor platform lets you control your sensors through an INSTEON PowerLinc Modem (PLM) device connected directly to your system on a USB or serial port. To add support, set up the primary [insteon_plm] component. [insteon_plm]: /components/insteon_plm/ - diff --git a/source/_components/binary_sensor.iss.markdown b/source/_components/binary_sensor.iss.markdown index c2061706882..0d4e4276b30 100644 --- a/source/_components/binary_sensor.iss.markdown +++ b/source/_components/binary_sensor.iss.markdown @@ -42,11 +42,13 @@ If you set `show_on_map` `True` then the location attributes are named `latitude The [generic camera platform](/components/camera.mjpeg/) offers the possibility to show the location of the ISS on Google Maps. +{% raw %} ```yaml # Example configuration.yaml entry camera: - platform: generic name: ISS - still_image_url: {% raw %}https://maps.googleapis.com/maps/api/staticmap?center={{ states.binary_sensor.iss.attributes.lat }},{{ states.binary_sensor.iss.attributes.long }}&zoom=5&size=500x500&maptype=roadmap&markers=color:blue%7Clabel:P%7C{{ states.binary_sensor.iss.attributes.lat }},{{ states.binary_sensor.iss.attributes.long }}{% endraw %} - limit_refetch_to_url_change: true + still_image_url: http://staticmap.openstreetmap.de/staticmap.php?center={{ states.binary_sensor.iss.attributes.lat }},{{ states.binary_sensor.iss.attributes.long }}&zoom=4&size=865x512&maptype=mapnik&markers={{ states.binary_sensor.iss.attributes.lat }},{{ states.binary_sensor.iss.attributes.long }},lightblue + limit_refetch_to_url_change: true ``` +{% endraw %} diff --git a/source/_components/binary_sensor.isy994.markdown b/source/_components/binary_sensor.isy994.markdown index 1318ef67d10..2cb7345d0eb 100644 --- a/source/_components/binary_sensor.isy994.markdown +++ b/source/_components/binary_sensor.isy994.markdown @@ -1,7 +1,7 @@ --- layout: page title: "ISY994 Binary Sensor" -description: "Instructions how to integrate ISY994 binary sensors into Home Assistant." +description: "Instructions on how to integrate ISY994 binary sensors into Home Assistant." date: 2016-09-03 23:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.knx.markdown b/source/_components/binary_sensor.knx.markdown index 73c747601ad..d51c9effbb4 100644 --- a/source/_components/binary_sensor.knx.markdown +++ b/source/_components/binary_sensor.knx.markdown @@ -1,7 +1,7 @@ --- layout: page title: "KNX Binary Sensor" -description: "Instructions how to setup the KNX binary sensors within Home Assistant." +description: "Instructions on how to setup the KNX binary sensors within Home Assistant." date: 2016-07-13 07:00 sidebar: true comments: false @@ -25,14 +25,16 @@ binary_sensor: address: '6/0/2' device_class: 'motion' #significant_bit: 2 + #reset_after: 100 ``` Configuration variables: - **name** (*Optional*): A name for this device used within Home Assistant. - **address**: KNX group address of the binary sensor. -- **device_class** (Optional): HASS device class e.g. "motion". +- **device_class** (Optional): HASS device class e.g., "motion". - **significant_bit** (Optional): Specify which significant bit of the KNX value should be used. Default is 1. +- **reset_after** (Optional): Reset back to OFF state after specified milliseconds. You can also attach actions to binary sensors (e.g., to switch on a light when a switch was pressed). In this example, one light is switched on when the button was pressed once and two others when the button was pressed a second time. diff --git a/source/_components/binary_sensor.konnected.markdown b/source/_components/binary_sensor.konnected.markdown new file mode 100644 index 00000000000..b530f097158 --- /dev/null +++ b/source/_components/binary_sensor.konnected.markdown @@ -0,0 +1,21 @@ +--- +layout: page +title: "Konnected Binary Sensor" +description: "Connect wired open/close sensors to Home Assistant with Konnected and a NodeMCU ESP8266" +date: 2018-04-03 12:30 +sidebar: true +comments: false +sharing: true +footer: true +logo: konnected.png +ha_category: Binary Sensor +ha_release: "0.70" +ha_iot_class: "Local Push" +--- + +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). + +See the [`konnected`](/components/konnected/) component for configuration and setup instructions. + +This component supports all of the built-in device classes of the generic [Binary Sensor](/components/binary_sensor/) component. + diff --git a/source/_components/binary_sensor.markdown b/source/_components/binary_sensor.markdown index c25e0fb6b60..fe8f4a51078 100644 --- a/source/_components/binary_sensor.markdown +++ b/source/_components/binary_sensor.markdown @@ -11,26 +11,38 @@ footer: true Binary sensors gather information about the state of devices which have a "digital" return value (either 1 or 0). These can be switches, contacts, pins, etc. These sensors only have two states: **0/off/low/closed/false** and **1/on/high/open/true**. Knowing that there are only two states allows Home Assistant to represent these sensors in a better way in the frontend according to their functionality. +### {% linkable_title Device Class %} + The way these sensors are displayed in the frontend can be modified in the [customize section](/getting-started/customizing-devices/). The following device classes are supported for binary sensors: - **None**: Generic on/off. This is the default and doesn't need to be set. - **battery**: `On` means low, `Off` means normal -- **cold**: `On` means cold -- **connectivity**: `On` means connection present, `Off` means no connection -- **gas**: `On` means gas detected -- **heat**: `On` means hot -- **light**: Lightness threshold -- **moisture**: `On` means wet -- **motion**: `On` means motion detected -- **moving**: `On` means moving, `Off` means stopped -- **occupancy**: `On` means occupied, `Off` means not occupied +- **cold**: `On` means cold, `Off` means normal +- **connectivity**: `On` means connected, `Off` means disconnected +- **door**: `On` means open, `Off` means closed +- **garage_door**: `On` means open, `Off` means closed +- **gas**: `On` means gas detected, `Off` means no gas (clear) +- **heat**: `On` means hot, `Off` means normal +- **light**: `On` means light detected, `Off` means no light +- **lock**: `On` means open (unlocked), `Off` means closed (locked) +- **moisture**: `On` means moisture detected (wet), `Off` means no moisture (dry) +- **motion**: `On` means motion detected, `Off` means no motion (clear) +- **moving**: `On` means moving, `Off` means not moving (stopped) +- **occupancy**: `On` means occupied, `Off` means not occupied (clear) - **opening**: `On` means open, `Off` means closed - **plug**: `On` means device is plugged in, `Off` means device is unplugged -- **power**: Power, over-current, etc. -- **presence**: `On` means Home, `Off` means Away +- **power**: `On` means power detected, `Off` means no power +- **presence**: `On` means home, `Off` means away +- **problem**: `On` means problem detected, `Off` means no problem (OK) - **safety**: `On` means unsafe, `Off` means safe -- **smoke**: `On` means smoke detected -- **sound**: `On` means sound detected, `Off` means no sound -- **vibration**: `On` means vibration detected, `Off` means no vibration +- **smoke**: `On` means smoke detected, `Off` means no smoke (clear) +- **sound**: `On` means sound detected, `Off` means no sound (clear) +- **vibration**: `On` means vibration detected, `Off` means no vibration (clear) +- **window**: `On` means open, `Off` means closed -For analog sensors please check the [component overview](https://home-assistant.io/components/#sensor). +For analog sensors please check the [component overview](/components/#sensor). + +
+
+Example of various device classes icons in `On` and `Off` state.
+
-The firmware version 2.26 doesn't support TLS/SSL. This means that you are only able to use the WiFi Buttons if you are using plain-text communication between Home Assistant and the clients/entities. +The firmware version 2.56 doesn't support TLS/SSL. This means that you are only able to use the WiFi Buttons if you are using plain-text communication between Home Assistant and the clients/entities.
diff --git a/source/_components/binary_sensor.nest.markdown b/source/_components/binary_sensor.nest.markdown index fa0a264474d..6949c6d2b55 100644 --- a/source/_components/binary_sensor.nest.markdown +++ b/source/_components/binary_sensor.nest.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Nest Binary Sensor" -description: "Instructions how to integrate Nest binary sensors within Home Assistant." +description: "Instructions on how to integrate Nest binary sensors within Home Assistant." date: 2016-01-26 08:00 sidebar: true comments: false @@ -10,7 +10,7 @@ footer: true logo: nest.png ha_category: Binary Sensor ha_release: pre 0.7 -ha_iot_class: "Cloud Polling" +ha_iot_class: "Cloud Push" --- @@ -39,6 +39,8 @@ Configuration variables: The following conditions are available by device: +- Nest Home: + - away - Nest Thermostat: - online - fan diff --git a/source/_components/binary_sensor.netatmo.markdown b/source/_components/binary_sensor.netatmo.markdown index 57d01bbd088..da2f8ab1fe1 100644 --- a/source/_components/binary_sensor.netatmo.markdown +++ b/source/_components/binary_sensor.netatmo.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Netatmo Binary Sensor" -description: "Instructions how to integrate Netatmo binary sensor into Home Assistant." +description: "Instructions on how to integrate Netatmo binary sensor into Home Assistant." date: 2016-09-19 15:10 sidebar: true comments: false diff --git a/source/_components/binary_sensor.octoprint.markdown b/source/_components/binary_sensor.octoprint.markdown index c4bf736c3b1..369205ad94a 100644 --- a/source/_components/binary_sensor.octoprint.markdown +++ b/source/_components/binary_sensor.octoprint.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OctoPrint Binary Sensor" -description: "Instructions how to integrate OctoPrint binary sensors within Home Assistant." +description: "Instructions on how to integrate OctoPrint binary sensors within Home Assistant." date: 2016-05-05 08:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.pilight.markdown b/source/_components/binary_sensor.pilight.markdown index 4ccf5273920..ee7a729196a 100644 --- a/source/_components/binary_sensor.pilight.markdown +++ b/source/_components/binary_sensor.pilight.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Pilight Binary Sensor" -description: "Instructions how to integrate Pilight binary sensors within Home Assistant." +description: "Instructions on how to integrate Pilight binary sensors within Home Assistant." date: 2017-03-24 20:41 sidebar: true comments: false @@ -15,10 +15,12 @@ ha_iot_class: "Local Polling" The `pilight` binary sensor platform implement the [pilight hub](/components/pilight/) binary sensor functionality. Two type of Pilight binary sensor configuration available. A normal sensor which send the on and off state cyclical and a trigger sensor which send only a trigger when an event happened (for example lots of cheap PIR motion detector). + + To enable a Pilight binary sensor in your installation, add the following to your `configuration.yaml` file: ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry binary_sensor: - platform: pilight variable: 'state' diff --git a/source/_components/binary_sensor.ping.markdown b/source/_components/binary_sensor.ping.markdown index 613e64316b1..b0be6271369 100644 --- a/source/_components/binary_sensor.ping.markdown +++ b/source/_components/binary_sensor.ping.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Ping (ICMP) Binary sensor" -description: "Instructions how to integrate Ping (ICMP)-based binary sensors into Home Assistant." +description: "Instructions on how to integrate Ping (ICMP)-based binary sensors into Home Assistant." date: 2017-04-11 08:00 sidebar: true comments: false @@ -37,6 +37,17 @@ The sensor exposes the different round trip times values measured by `ping` as a - `round trip time min` - `round trip time max` +The default polling interval is 5 minutes. As many components [based on the entity class](/docs/configuration/platform_options), it is possible to overwrite this scan interval by specifying a `scan_interval` configuration key (value in seconds). In the example below we setup the `ping` binary sensor to poll the devices every 30 seconds. + +```yaml +# Example configuration.yaml entry to ping host 192.168.0.1 with 2 packets every 30 seconds. +binary_sensor: + - platform: ping + host: 192.168.0.1 + count: 2 + scan_interval: 30 +``` +When run on Windows systems, the round trip time attributes are rounded to the nearest millisecond and the mdev value is unavailable.
diff --git a/source/_components/binary_sensor.qwikswitch.markdown b/source/_components/binary_sensor.qwikswitch.markdown new file mode 100644 index 00000000000..e3fd446a3ba --- /dev/null +++ b/source/_components/binary_sensor.qwikswitch.markdown @@ -0,0 +1,18 @@ +--- +layout: page +title: "QwikSwitch Binary Sensor" +description: "Instructions on how to integrate Qwikswitch dimmers and relays as sensors into Home Assistant." +date: 2016-05-04 00:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: qwikswitch.png +ha_category: Sensor +ha_iot_class: "Local Push" +ha_release: "0.68" +--- + +The `qwikswitch` binary_sensor platform allows you to use your [QwikSwitch](http://www.qwikswitch.co.za/) sensors within Home Assistant. + +The platform is configured through the [QwikSwitch component](/components/qwikswitch/). diff --git a/source/_components/binary_sensor.rachio.markdown b/source/_components/binary_sensor.rachio.markdown new file mode 100644 index 00000000000..568e9e0c558 --- /dev/null +++ b/source/_components/binary_sensor.rachio.markdown @@ -0,0 +1,31 @@ +--- +layout: page +title: "Rachio Binary Sensor" +description: "Instructions on how to use Rachio binary sensors with Home Assistant." +date: 2018-06-23 16:15 +sidebar: true +comments: false +sharing: true +footer: true +logo: rachio.png +ha_category: Hub +ha_iot_class: "Cloud Push" +ha_release: 0.73 +--- + +The `rachio` binary sensor platform allows you to view the status of your [Rachio irrigation system](http://rachio.com/). + +Once configured, a binary sensor will be added that shows whether or not each controller in the account provided is online and reachable by Rachio's servers. + ++ You must have the [Rachio component](/components/rachio/) configured to use this switch. +
+ + +To add this platform to your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +binary_sensor: + - platform: rachio +``` diff --git a/source/_components/binary_sensor.rainmachine.markdown b/source/_components/binary_sensor.rainmachine.markdown new file mode 100644 index 00000000000..175a2d27bba --- /dev/null +++ b/source/_components/binary_sensor.rainmachine.markdown @@ -0,0 +1,23 @@ +--- +layout: page +title: "RainMachine Binary Sensor" +description: "Instructions on how to use RainMachine binary sensors with Home Assistant." +date: 2018-05-06 21:26 +sidebar: true +comments: false +sharing: true +footer: true +logo: rainmachine.png +ha_category: Binary Sensor +ha_iot_class: "Cloud Polling" +ha_release: 0.71 +--- + +The `rainmachine` binary sensor platform allows you to view crucial sensor data +within a [RainMachine smart Wi-Fi sprinkler controller](http://www.rainmachine.com/). + ++You must have the [RainMachine component](https://www.home-assistant.io/components/rainmachine/) +configured to use this platform. After configuring that component, binary +sensors automatically appear. +
diff --git a/source/_components/binary_sensor.random.markdown b/source/_components/binary_sensor.random.markdown index ea8de4b90cc..b1208681a8a 100644 --- a/source/_components/binary_sensor.random.markdown +++ b/source/_components/binary_sensor.random.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Random Binary Sensor" -description: "Instructions how to integrate random state sensors into Home Assistant." +description: "Instructions on how to integrate random state sensors into Home Assistant." date: 2017-10-27 08:00 sidebar: true comments: false @@ -16,6 +16,8 @@ ha_release: 0.57 The `random` binary sensor platform is creating random states (`True`, 1, `on` or `False`, 0, `off`). This can be useful if you want to test automation rules. It generates a new state every time it is polled. +## {% linkable_title Configuration %} + To enable the random binary sensor, add the following lines to your `configuration.yaml`: ```yaml diff --git a/source/_components/binary_sensor.raspihats.markdown b/source/_components/binary_sensor.raspihats.markdown index 4815aa2de7b..50d031c4574 100644 --- a/source/_components/binary_sensor.raspihats.markdown +++ b/source/_components/binary_sensor.raspihats.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Raspihats Binary Sensor" -description: "Instructions how to integrate Raspihats add-on boards for Raspberry PI into Home Assistant as a binary_sensor." +description: "Instructions on how to integrate Raspihats add-on boards for Raspberry Pi into Home Assistant as a binary_sensor." date: 2017-05-01 04:09 sidebar: true comments: false @@ -87,4 +87,4 @@ It will output a table like this: 70: -- -- -- -- -- -- -- 77 ``` -For more details about the `raspihats` add-on boards for Raspberry PI, visit [raspihats.com](http://www.raspihats.com/). +For more details about the `raspihats` add-on boards for Raspberry Pi, visit [raspihats.com](http://www.raspihats.com/). diff --git a/source/_components/binary_sensor.rest.markdown b/source/_components/binary_sensor.rest.markdown index 0a5c789d36e..d882e5b4064 100644 --- a/source/_components/binary_sensor.rest.markdown +++ b/source/_components/binary_sensor.rest.markdown @@ -1,7 +1,7 @@ --- layout: page title: "RESTful Binary Sensor" -description: "Instructions how to integrate REST binary sensors into Home Assistant." +description: "Instructions on how to integrate REST binary sensors into Home Assistant." date: 2015-12-17 19:10 sidebar: true comments: false @@ -47,25 +47,61 @@ binary_sensor: method: POST ``` -Configuration variables: - -- **resource** (*Required*): The resource or endpoint that contains the value. -- **method** (*Optional*): The method of the request. Default is GET. -- **name** (*Optional*): Name of the REST binary sensor. -- **device_class** (*Optional*): The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend. -- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value. -- **payload** (*Optional*): The payload to send with a POST request. Usually formed as a dictionary. -- **verify_ssl** (*Optional*): Verify the certification of the endpoint. Default to True. -- **authentication** (*Optional*): Type of the HTTP authentication. `basic` or `digest`. -- **username** (*Optional*): The username for accessing the REST endpoint. -- **password** (*Optional*): The password for accessing the REST endpoint. -- **headers** (*Optional*): The headers for the requests. +{% configuration %} +resource: + description: The resource or endpoint that contains the value. + required: true + type: string + default: string +method: + description: The method of the request. + required: false + type: string + default: GET +name: + description: Name of the REST binary sensor. + required: false + type: string + default: REST Binary Sensor +device_class: + description: "The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend." + required: false + type: string +value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the value." + required: false + type: template +payload: + description: The payload to send with a POST request. Usually formed as a dictionary. + required: false + type: string +verify_ssl: + description: Verify the certification of the endpoint. + required: false + type: boolean + default: True +authentication: + description: Type of the HTTP authentication. `basic` or `digest`. + required: false + type: string +username: + description: The username for accessing the REST endpoint. + required: false + type: string +password: + description: The password for accessing the REST endpoint. + required: false + type: string +headers: + description: The headers for the requests. + required: false + type: list, string +{% endconfiguration %}Make sure that the URL exactly matches your endpoint or resource.
- ## {% linkable_title Examples %} In this section you find some real life examples of how to use this sensor. diff --git a/source/_components/binary_sensor.rfxtrx.markdown b/source/_components/binary_sensor.rfxtrx.markdown index c676c46cec0..0aaefbad7d6 100644 --- a/source/_components/binary_sensor.rfxtrx.markdown +++ b/source/_components/binary_sensor.rfxtrx.markdown @@ -1,7 +1,7 @@ --- layout: page title: "RFXtrx Binary Sensor" -description: "Instructions how to integrate RFXtrx binary sensors into Home Assistant." +description: "Instructions on how to integrate RFXtrx binary sensors into Home Assistant." date: 2017-03-26 12:45 sidebar: true comments: false @@ -38,7 +38,7 @@ binary_sensor: name: device_name ``` -Do not forget to tweak the configuration variables: +Configuration variables: - **automatic_add** (*Optional*): To enable the automatic addition of new binary sensors. - **device_class** (*Optional*): The [type or class of the sensor](/components/binary_sensor/) to set the icon in the frontend. @@ -48,6 +48,11 @@ Do not forget to tweak the configuration variables: This component and the [rfxtrx switch](/components/switch/rfxtrx/) can steal each other's devices when setting the `automatic_add` configuration parameter to `true`. Set `automatic_add` only when you have some devices to add to your installation, otherwise leave it to `False`. ++If a device ID consists of only numbers, please make sure to surround it with quotes. +This is a known limitation in YAML, because the device ID will be interpreted as a number otherwise. +
+ Binary sensors have only two states - "on" and "off". Many door or window opening sensors will send a signal each time the door/window is open or closed. However, depending on their hardware or on their purpose, some sensors are only able to signal their "on" state: - Most motion sensors send a signal each time they detect motion. They stay "on" for a few seconds and go back to sleep, ready to signal other motion events. Usually, they do not send a signal when they go back to sleep. @@ -55,7 +60,6 @@ Binary sensors have only two states - "on" and "off". Many door or window openin For those devices, use the *off_delay* parameter. It defines a delay after which a device will go back to an "Off" state. That "Off" state will be fired internally by Home Assistant, just as if the device fired it by itself. If a motion sensor can only send signals once every 5 seconds, sets the *off_delay* parameter to *seconds: 5*. - Example configuration: ```yaml @@ -83,7 +87,7 @@ Let's try to add a new PT-2262 sensor using the "automatic_add" option and have Have your sensor trigger the "On" state for the first time. Some messages will appear: -``` +```text INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sensor 0913000022670e013970 (Device_id: 22670e Class: LightingDevice Sub: 0) ``` @@ -91,7 +95,7 @@ Here the sensor has the id *22670e*. Now have your sensor trigger the "Off" state and look for the following message in the Home Assistant log. You should see that your device has been detected as a *new* device when triggering its "Off" state: -``` +```text INFO (Thread-6) [homeassistant.components.binary_sensor.rfxtrx] Added binary sensor 09130000226707013d70 (Device_id: 226707 Class: LightingDevice Sub: 0) ``` @@ -115,7 +119,7 @@ devices: The *automatic_add* option makes the rfxtrx binary sensor component calculate and display the configuration options for you in the Home Assistant logs: -``` +```text INFO (Thread-6) [homeassistant.components.rfxtrx] rfxtrx: found possible device 226707 for 22670e with the following configuration: data_bits=4 command_on=0xe diff --git a/source/_components/binary_sensor.rpi_gpio.markdown b/source/_components/binary_sensor.rpi_gpio.markdown index 99a7eda5eb4..a59333d82cb 100644 --- a/source/_components/binary_sensor.rpi_gpio.markdown +++ b/source/_components/binary_sensor.rpi_gpio.markdown @@ -1,7 +1,7 @@ --- layout: page -title: "Raspberry PI GPIO Binary Sensor" -description: "Instructions how to integrate the GPIO sensor capability of a Raspberry PI into Home Assistant." +title: "Raspberry Pi GPIO Binary Sensor" +description: "Instructions on how to integrate the GPIO sensor capability of a Raspberry Pi into Home Assistant." date: 2015-08-30 19:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.rpi_pfio.markdown b/source/_components/binary_sensor.rpi_pfio.markdown index 84404f4d783..d02cfaf2dab 100644 --- a/source/_components/binary_sensor.rpi_pfio.markdown +++ b/source/_components/binary_sensor.rpi_pfio.markdown @@ -1,7 +1,7 @@ --- layout: page title: "PiFace Digital I/O Binary Sensor" -description: "Instructions how to integrate the PiFace Digital I/O module into Home Assistant as a binary sensor." +description: "Instructions on how to integrate the PiFace Digital I/O module into Home Assistant as a binary sensor." date: 2016-05-08 15:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.satel_integra.markdown b/source/_components/binary_sensor.satel_integra.markdown index 84744aaa9e2..5d879e49664 100644 --- a/source/_components/binary_sensor.satel_integra.markdown +++ b/source/_components/binary_sensor.satel_integra.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Satel Integra Binary Sensor" -description: "Instructions how to integrate Satel Integra binary sensors into Home Assistant." +description: "Instructions on how to integrate Satel Integra binary sensors into Home Assistant." date: 2017-09-07 13:28 sidebar: true comments: false diff --git a/source/_components/binary_sensor.spc.markdown b/source/_components/binary_sensor.spc.markdown index 507f568dd92..624bebfff2a 100644 --- a/source/_components/binary_sensor.spc.markdown +++ b/source/_components/binary_sensor.spc.markdown @@ -1,7 +1,7 @@ --- layout: page title: "SPC Binary Sensor" -description: "Instructions how to integrate Vanderbilt SPC binary sensors into Home Assistant." +description: "Instructions on how to integrate Vanderbilt SPC binary sensors into Home Assistant." date: 2017-05-18 22:05 sidebar: true comments: false diff --git a/source/_components/binary_sensor.tahoma.markdown b/source/_components/binary_sensor.tahoma.markdown new file mode 100644 index 00000000000..1ba160f706d --- /dev/null +++ b/source/_components/binary_sensor.tahoma.markdown @@ -0,0 +1,17 @@ +--- +layout: page +title: "Tahoma Binary Sensor" +description: "Instructions on how to integrate Tahoma binary sensors into Home Assistant." +date: 2018-06-14 21:57 +sidebar: true +comments: false +sharing: true +footer: true +logo: tahoma.png +ha_category: Binary Sensor +ha_release: 0.73 +--- + +The `tahoma` binary sensor platform lets you see binary sensors added to your Tahoma Box in Home Assistant. For example smoke detectors. + +Binary sensors will be added automatically. Please refer to the [component](/components/tahoma/) configuration on how to setup Tahoma. diff --git a/source/_components/binary_sensor.tapsaff.markdown b/source/_components/binary_sensor.tapsaff.markdown index b8e8636af66..233596e6bd1 100644 --- a/source/_components/binary_sensor.tapsaff.markdown +++ b/source/_components/binary_sensor.tapsaff.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Taps Aff" -description: "Instructions how to use the Taps Aff binary sensor in Home Assistant." +description: "Instructions on how to use the Taps Aff binary sensor in Home Assistant." date: 2017-05-28 18:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.tellduslive.markdown b/source/_components/binary_sensor.tellduslive.markdown index 2a73bea7f46..fc0b988bbf2 100644 --- a/source/_components/binary_sensor.tellduslive.markdown +++ b/source/_components/binary_sensor.tellduslive.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Telldus Binary Sensor" -description: "Instructions how to integrate Telldus Live binary sensors into Home Assistant." +description: "Instructions on how to integrate Telldus Live binary sensors into Home Assistant." date: 2017-10-24 10:09 sidebar: true comments: false diff --git a/source/_components/binary_sensor.template.markdown b/source/_components/binary_sensor.template.markdown index 009f4131ddd..7cc7af6285f 100644 --- a/source/_components/binary_sensor.template.markdown +++ b/source/_components/binary_sensor.template.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Template Binary Sensor" -description: "Instructions how to integrate Template Binary Sensors into Home Assistant." +description: "Instructions on how to integrate Template Binary Sensors into Home Assistant." date: 2016-02-25 15:00 sidebar: true comments: false @@ -49,7 +49,7 @@ binary_sensor: required: false type: string entity_id: - description: Add a list of entity IDs so the sensor only reacts to state changes of these entities. This will reduce the number of times the sensor will try to update its state. + description: A list of entity IDs so the sensor only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. required: false type: string, list device_class: @@ -61,6 +61,14 @@ binary_sensor: description: Defines a template to set the state of the sensor. required: true type: template + icon_template: + description: Defines a template for the icon of the sensor. + required: false + type: template + entity_picture_template: + description: Defines a template for the entity picture of the sensor. + required: false + type: template delay_on: description: The amount of time the template state must be ***met*** before this sensor will switch to `on`. required: false @@ -126,13 +134,11 @@ binary_sensor: ``` {% endraw %} -### {% linkable_title Combining Multiple Sensors, and Using `entity_id` %} +### {% linkable_title Combining Multiple Sensors %} This example combines multiple CO sensors into a single overall status. When using templates with binary sensors, you need to return -`true` or `false` explicitly. `entity_id` is used to limit which -sensors are being monitored to update the state, making computing this -sensor far more efficient. +`true` or `false` explicitly. {% raw %} ```yaml @@ -142,10 +148,6 @@ binary_sensor: co: friendly_name: "CO" device_class: gas - entity_id: - - sensor.bedroom_co_status - - sensor.kitchen_co_status - - sensor.wardrobe_co_status value_template: >- {{ is_state('sensor.bedroom_co_status', 'Ok') and is_state('sensor.kitchen_co_status', 'Ok') @@ -158,7 +160,7 @@ binary_sensor: This example creates a washing machine "load running" sensor by monitoring an energy meter connected to the washer. During the washer's operation, the energy meter will fluctuate wildly, hitting zero frequently even before the load is -finished. By utilizing `off_delay`, we can have this sensor only turn off if +finished. By utilizing `delay_off`, we can have this sensor only turn off if there has been no washer activity for 5 minutes. {% raw %} @@ -190,14 +192,6 @@ binary_sensor: - platform: template sensors: people_home: - entity_id: - - device_tracker.sean - - device_tracker.susan - - binary_sensor.office_124 - - binary_sensor.hallway_134 - - binary_sensor.living_room_139 - - binary_sensor.porch_ms6_1_129 - - binary_sensor.family_room_144 value_template: >- {{ is_state('device_tracker.sean', 'home') or is_state('device_tracker.susan', 'home') diff --git a/source/_components/binary_sensor.threshold.markdown b/source/_components/binary_sensor.threshold.markdown index c2e9e875b39..21cc02b9fd6 100644 --- a/source/_components/binary_sensor.threshold.markdown +++ b/source/_components/binary_sensor.threshold.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Threshold Binary Sensor" -description: "Instructions how to integrate threshold binary sensors into Home Assistant." +description: "Instructions on how to integrate threshold binary sensors into Home Assistant." date: 2016-11-26 12:10 sidebar: true comments: false @@ -14,15 +14,17 @@ ha_release: 0.34 --- -The `threshold` binary sensor platform observes the state of another sensor. If the value is below (`lower`) or higher (`upper`) than the given threshold then state of the threshold sensor is changed. +The `threshold` binary sensor platform observes the state of another sensor. If the value is below (`lower`) or higher (`upper`) than the given threshold then state of the threshold sensor is changed. It support also a range if `lower` and `upper` are given. If the sensor is configured with no hysteresis and the sensor value is equal to the threshold, the sensor is turned off since it is not `lower` or `upper` with respect to the threshold. It's an alternative to the template binary sensor's `value_template:` to get the abnormal/too high/too low states. +{% raw %} ```yaml -{% raw %}{{ states.sensor.furnace.state > 2.5 }}{% endraw %} +{{ states.sensor.furnace.state > 2.5 }} ``` +{% endraw %} To enable the threshold sensor, add the following lines to your `configuration.yaml`: @@ -30,15 +32,32 @@ To enable the threshold sensor, add the following lines to your `configuration.y # Example configuration.yaml entry binary_sensor: - platform: threshold - threshold: 15 - type: lower entity_id: sensor.random + lower: 20 ``` -Configuration variables: +{% configuration %} +entity_id: + description: "The entity to monitor. Only [sensors](/components/sensor/) are supported." + required: true + type: entity_id +lower: + description: The lower threshold which the observed value is compared against. + required: false + type: float +upper: + description: The upper threshold which the observed value is compared against. + required: false + type: float +hysteresis: + description: The distance the observed value must be from the threshold before the state is changed. + required: false + type: float + default: 0.0 +name: + description: Name of the sensor to use in the frontend. + required: false + type: string + default: +{% endconfiguration %} -- **entity_id** (*Required*): The entity to monitor. Only [sensors](/components/sensor/) are supported. -- **threshold** (*Required*): The threshold which the observed value is compared against. -- **type** (*Required*): `lower` if the value needs to be below the threshold or `upper` if higher. -- **hysteresis** (*Optional*): The distance the observed value must be from the threshold before the state is changed. Defaults to `0.0` -- **name** (*Optional*): Name of the sensor to use in the frontend. Defaults to `Stats`. diff --git a/source/_components/binary_sensor.trend.markdown b/source/_components/binary_sensor.trend.markdown index 41ac39437eb..dae3d1c9ed7 100644 --- a/source/_components/binary_sensor.trend.markdown +++ b/source/_components/binary_sensor.trend.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Trend Binary Sensor" -description: "Instructions how to integrate Trend binary sensors into Home Assistant." +description: "Instructions on how to integrate Trend binary sensors into Home Assistant." date: 2016-09-05 10:00 sidebar: true comments: false @@ -22,8 +22,8 @@ To enable Trend binary sensors in your installation, add the following to your ` binary_sensor: - platform: trend sensors: - solar_angle: - entity_id: sun.sun + cpu_speed: + entity_id: sensor.cpu_speed ``` Configuration variables: @@ -33,9 +33,9 @@ Configuration variables: - **attribute** (*Optional*): The attribute of the entity that this sensor tracks. If no attribute is specified then the sensor will track the state. - **device_class** (*Optional*): The [type/class](/components/binary_sensor/) of the sensor to set the icon in the frontend. - **friendly_name** (*Optional*): Name to use in the Frontend. - - **invert** (*Optional*): Invert the result (so `true` means descending rather than ascending). Defaults to `False` + - **invert** (*Optional*): Invert the result. A `true` value would mean descending rather than ascending. Defaults to `False` - **max_samples** (*Optional*): Limit the maximum number of stored samples. Defaults to `2`. - - **min_gradient** (*Optional*): The minimum rate at which the observed value must be changing for this sensor to switch on. Defaults to `0.0` + - **min_gradient** (*Optional*): The minimum rate at which the observed value must be changing for this sensor to switch on. The gradient is measured in sensor units per second. Defaults to `0.0` - **sample_duration** (*Optional*): The duration **in seconds** to store samples for. Samples older than this value will be discarded. Defaults to `0` ## {% linkable_title Using Multiple Samples %} @@ -60,8 +60,10 @@ binary_sensor: sensors: sun_rising: entity_id: sun.sun + attribute: elevation ``` + This example creates two sensors to indicate whether the temperature is rising or falling at a rate of at least 3 degrees an hour, and collects samples over a two hour period: ```yaml diff --git a/source/_components/binary_sensor.upcloud.markdown b/source/_components/binary_sensor.upcloud.markdown new file mode 100644 index 00000000000..6cae22e876c --- /dev/null +++ b/source/_components/binary_sensor.upcloud.markdown @@ -0,0 +1,34 @@ +--- +layout: page +title: UpCloud Binary Sensor +description: Instructions on how to set up UpCloud binary sensors within Home Assistant. +date: 2018-01-28 20:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: System Monitor +logo: upcloud.png +ha_release: 0.65 +ha_iot_class: Cloud Polling +--- + +The `upcloud` binary sensor platform allows you to monitor your UpCloud servers. + +To use your UpCloud servers, you first have to set up your [UpCloud hub](/components/upcloud/) and then add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +binary_sensor: + - platform: upcloud + servers: + - 002167b7-4cb1-44b7-869f-e0900ddeeae1 + - 00886296-6137-4074-afe3-068e16d89d00 +``` + +{% configuration %} +servers: + description: List of servers you want to monitor. + required: true + type: list +{% endconfiguration %} diff --git a/source/_components/binary_sensor.uptimerobot.markdown b/source/_components/binary_sensor.uptimerobot.markdown new file mode 100644 index 00000000000..7b37252f399 --- /dev/null +++ b/source/_components/binary_sensor.uptimerobot.markdown @@ -0,0 +1,35 @@ +--- +layout: page +title: "Uptime Robot" +description: "Instructions on how to set up Uptime Robot within Home Assistant." +date: 2018-05-29 21:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: uptimerobot.png +ha_category: Binary Sensor +ha_release: "0.72" +ha_iot_class: "Cloud Polling" +--- + +The `uptimerobot` binary_sensor platform allows you get the status for all of your monitors from your account on [Uptime Robot.]( https://uptimerobot.com) + +## Example for `configuration.yaml` : + +```yaml +binary_sensor: + - platform: uptimerobot + api_key: u432898-d2507e493b31217e6c64fd35 +``` + +{% configuration %} +api_key: + description: Your Uptime Robot API key. + required: true + type: string +{% endconfiguration %} + +All the data will be fetch from [Uptime Robot](https://uptimerobot.com). + +To get your API key, go to [My Settings](https://uptimerobot.com/dashboard#mySettings) on the Uptime Robot website, at the bottom you will find your "Main API Key". diff --git a/source/_components/binary_sensor.velbus.markdown b/source/_components/binary_sensor.velbus.markdown index 7c9c9ef62dd..dc476b53f12 100644 --- a/source/_components/binary_sensor.velbus.markdown +++ b/source/_components/binary_sensor.velbus.markdown @@ -15,28 +15,47 @@ ha_release: "0.50" The `velbus` binary_sensor allows you to control [Velbus](http://www.velbus.eu) connected wall switches. +## {% linkable_title Configuration %} + To use your Velbus wall switches in your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry - binary_sensor: - platform: velbus devices: - - name: Wall Switch 1 - module: 0xda - channel: 4 - - name: Wall Switch 2 - module: 0xbc - channel: 1 - is_pushbutton: true + - name: Wall Switch 1 + module: 0xda + channel: 4 + - name: Wall Switch 2 + module: 0xbc + channel: 1 + is_pushbutton: true ``` -Configuration variables: -- **devices** array (*Required*): The array contains the binary sensors to configure - - **name** (*Required*): Name of the binary sensor. - - **module** (*Required*): The hexadecimal module address - - **channel** (*Required*): The channel number in the module. - - **is_pushbutton** (*Optional*): Boolean to indicate if a wall switch is a push button or not (default: false) +{% configuration %} +devices: + description: The list contains the binary sensors to configure. + required: true + type: map + keys: + name: + description: Name to use in the frontend. + required: true + type: string + module: + description: The hexadecimal module address. + required: true + type: string + channel: + description: The channel number in the module. + required: true + type: string + is_pushbutton: + description: Set to indicate if a wall switch is a push button or not. + required: false + type: boolean + default: false +{% endconfiguration %} For hub configuration, see [the Velbus component](/components/velbus/). diff --git a/source/_components/binary_sensor.vera.markdown b/source/_components/binary_sensor.vera.markdown index f28c1978fae..d5e5d9fb14d 100644 --- a/source/_components/binary_sensor.vera.markdown +++ b/source/_components/binary_sensor.vera.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Vera Binary Sensor" -description: "Instructions how to integrate Vera binary sensors into Home Assistant." +description: "Instructions on how to integrate Vera binary sensors into Home Assistant." date: 2016-03-26 23:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.verisure.markdown b/source/_components/binary_sensor.verisure.markdown index 026ad16ab46..1f9b9f0f4e3 100644 --- a/source/_components/binary_sensor.verisure.markdown +++ b/source/_components/binary_sensor.verisure.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Verisure Binary Sensor" -description: "Instructions how to integrate Verisure binary sensors into Home Assistant." +description: "Instructions on how to integrate Verisure binary sensors into Home Assistant." date: 2016-02-23 21:31 +0100 sidebar: true comments: false diff --git a/source/_components/binary_sensor.wink.markdown b/source/_components/binary_sensor.wink.markdown index 862a6b258ec..1d23f5bf7c1 100644 --- a/source/_components/binary_sensor.wink.markdown +++ b/source/_components/binary_sensor.wink.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Wink Binary Sensor" -description: "Instructions how to setup the Wink binary sensors within Home Assistant." +description: "Instructions on how to setup the Wink binary sensors within Home Assistant." date: 2015-01-20 22:36 sidebar: true comments: false diff --git a/source/_components/binary_sensor.wirelesstag.markdown b/source/_components/binary_sensor.wirelesstag.markdown new file mode 100644 index 00000000000..efe3eae81f4 --- /dev/null +++ b/source/_components/binary_sensor.wirelesstag.markdown @@ -0,0 +1,48 @@ +--- +layout: page +title: "WirelessTag Binary Sensor" +description: "Instructions on how to integrate Wireless Tags sensors within Home Assistant." +date: 2018-03-26 21:49 +comments: false +sidebar: true +sharing: true +footer: true +logo: wirelesstag.png +ha_category: Binary Sensor +ha_iot_class: "Local Push and Cloud Polling" +ha_release: 0.68 +--- + +To get your [wirelesstag.net](http://wirelesstag.net) binary sensors working within Home Assistant, please follow the instructions for the general [WirelessTag component](/components/wirelesstag). + +To enable tags set up with your [wirelesstag.net](http://wirelesstag.net) account, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +binary_sensor: + - platform: wirelesstag + monitored_conditions: + - presence + - door + - low_battery +``` + +{% configuration %} + monitored_conditions: + description: The conditions types to monitor; valid values are specified below + required: true + type: list +{% endconfiguration %} + +The following conditions can be monitored: + +* (`presence`): On means in range, Off means out of range. +* (`motion`): On when a movement was detected, Off when clear. +* (`door`): On when a door is open, Off when the door is closed. +* (`cold`): On means temperature become too cold, Off means normal. +* (`heat`): On means hot, Off means normal. +* (`dry`): On means too dry (humidity), Off means normal. +* (`wet`): On means too wet (humidity), Off means normal. +* (`light`): On means light detected, Off means no light. +* (`moisture`): On means moisture detected (wet), Off means no moisture (dry). +* (`low_battery`): On means tag battery is low, Off means normal. diff --git a/source/_components/binary_sensor.workday.markdown b/source/_components/binary_sensor.workday.markdown index 45f1d2386cc..1ba1f8bd8c7 100644 --- a/source/_components/binary_sensor.workday.markdown +++ b/source/_components/binary_sensor.workday.markdown @@ -15,6 +15,10 @@ ha_release: 0.41 The `workday` binary sensor indicates, whether the current day is a workday or not. It allows specifying, which days of the week counts as workdays and also uses the python module [holidays](https://pypi.python.org/pypi/holidays) to incorporate information about region-specific public holidays. +## {% linkable_title Configuration %} + +Check the [country list](https://github.com/dr-prodigy/python-holidays#available-countries) for available province. + To enable the `workday` sensor in your installation, add the following to your `configuration.yaml` file: ```yaml @@ -22,12 +26,14 @@ To enable the `workday` sensor in your installation, add the following to your ` binary_sensor: - platform: workday country: DE + workdays: [mon, wed, fri] ``` Configuration variables: -- **country** (*Required*): Country code according to [holidays](https://pypi.python.org/pypi/holidays/0.8.1) notation. -- **province** (*Optional*): Province code according to [holidays](https://pypi.python.org/pypi/holidays/0.8.1) notation. Defaults to None. +- **name** (*Optional*): A name for this sensor. Defaults to *Workday Sensor* +- **country** (*Required*): Country code according to [holidays](https://pypi.python.org/pypi/holidays/0.9.4) notation. +- **province** (*Optional*): Province code according to [holidays](https://pypi.python.org/pypi/holidays/0.9.4) notation. Defaults to None. - **workdays** (*Optional*): List of workdays. Defaults to `mon`, `tue`, `wed`, `thu`, `fri`. - **excludes** (*Optional*): List of workday excludes. Defaults to `sat`, `sun`, `holiday`. - **days_offset** (*Optional*): Set days offset. Defaults to `0`. @@ -35,6 +41,7 @@ Configuration variables: Days are specified as follows: `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun`. The keyword `holiday` is used for public holidays identified by the holidays module.+If you use the sensor for Norway (`NO`) you need to wrap `NO`in quotes or write the name in full. Otherwise the value is evaluated as `False`. If you use the sensor for Canada (`CA`) with Ontario (`ON`) as `province:` then you need to wrap `ON` in quotes. Otherwise the value is evaluated as `True` (check the YAML documentation for further details) and the sensor will not work.
diff --git a/source/_components/binary_sensor.xiaomi_aqara.markdown b/source/_components/binary_sensor.xiaomi_aqara.markdown index a6eb4e95d8e..6f33659f78b 100644 --- a/source/_components/binary_sensor.xiaomi_aqara.markdown +++ b/source/_components/binary_sensor.xiaomi_aqara.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Xiaomi Binary Sensor" -description: "Instructions how to setup the Xiaomi binary sensors within Home Assistant." +description: "Instructions on how to setup the Xiaomi binary sensors within Home Assistant." date: 2017-07-21 16:34 sidebar: true comments: false @@ -21,20 +21,20 @@ The requirement is that you have setup the [`xiaomi aqara` component](/component ### {% linkable_title Type of sensors supported %} -| Name | ZigBee entity | Model no. | States | Event | Event key | Event values | -|-----------------------------------|---------------------|----------------------|----------------------------------------------------|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------| -| Motion Sensor (1st gen) | motion | RTCGQ01LM | on, off | `motion` | | | -| Motion Sensor (2nd gen) | sensor_motion.aq2 | RTCGQ11LM | on, off | `motion` | | | -| Door and Window Sensor (1st gen) | magnet | WSDCGQ01LM | on, off | | | | -| Door and Window Sensor (2nd gen) | sensor_magnet.aq2 | MCCGQ11LM | on, off | | | | -| Smoke Detector | smoke | JTYJ-GD-01LM/BW | on, off | | | | -| Gas Leak Detector | natgas | JTQJ-BF-01LM/BW | on, off | | | | -| Water Leak Sensor | sensor_wleak.aq1 | SJCGQ11LM | on, off | | | | -| Button (1st gen) | switch | WXKG01LM | on (thru long_click_press), off | `click` | `click_type` | `long_click_press`, `long_click_release`, `hold`, `single`, `double` | -| Button (2nd gen) | sensor_switch.aq2 | WXKG11LM | off (always) | `click` | `click_type` | `single`, `double` | -| Aqara Wireless Switch (Single) | 86sw1 | WXKG03LM | off (always) | `click` | `click_type` | `single` | -| Aqara Wireless Switch (Double) | 86sw2 | WXKG02LM | off (always) | `click` | `click_type` | `single`, `both` | -| Cube | cube | MFKZQ01LM | off (always) | `cube_action` | `action_type`, `action_value` (rotate) | `flip90`, `flip180`, `move`, `tap_twice`, `shake_air`, `swing`, `alert`, `free_fall`, `rotate` (degrees at action_value) | +| Name | ZigBee entity | Model no. | States | Event | Event key | Event values | +| ---- | ------------- | --------- | ------ | ----- | --------- | ------------ | +| Motion Sensor (1st gen) | motion | RTCGQ01LM | on, off | `motion` | | | +| Motion Sensor (2nd gen) | sensor_motion.aq2 | RTCGQ11LM | on, off | `motion` | | | +| Door and Window Sensor (1st gen) | magnet | WSDCGQ01LM | on, off | | | | +| Door and Window Sensor (2nd gen) | sensor_magnet.aq2 | MCCGQ11LM | on, off | | | | +| Smoke Detector | smoke | JTYJ-GD-01LM/BW | on, off | | | | +| Gas Leak Detector | natgas | JTQJ-BF-01LM/BW | on, off | | | | +| Water Leak Sensor | sensor_wleak.aq1 | SJCGQ11LM | on, off | | | | +| Button (1st gen) | switch | WXKG01LM | on (through long_click_press), off | `click`| `click_type`| `long_click_press`, `long_click_release`, `hold`, `single`, `double` | +| Button (2nd gen) | sensor_switch.aq2 | WXKG11LM | off (always) | `click` | `click_type` | `single`, `double` | +| Aqara Wireless Switch (Single) | 86sw1 | WXKG03LM | off (always) | `click` | `click_type` | `single` | +| Aqara Wireless Switch (Double) | 86sw2 | WXKG02LM | off (always) | `click` | `click_type` | `single`, `both` | +| Cube | cube | MFKZQ01LM | off (always) | `cube_action` | `action_type`, `action_value` (rotate) | `flip90`, `flip180`, `move`, `tap_twice`, `shake_air`, `swing`, `alert`, `free_fall`, `rotate` (degrees at action_value) | ### {% linkable_title Automation examples %} diff --git a/source/_components/binary_sensor.zha.markdown b/source/_components/binary_sensor.zha.markdown index 755e4396ed6..df5853d6700 100644 --- a/source/_components/binary_sensor.zha.markdown +++ b/source/_components/binary_sensor.zha.markdown @@ -1,7 +1,7 @@ --- layout: page title: "ZigBee Home Automation Binary Sensor" -description: "Instructions how to setup ZigBee Home Automation binary sensors within Home Assistant." +description: "Instructions on how to setup ZigBee Home Automation binary sensors within Home Assistant." date: 2017-02-22 00:00 sidebar: true comments: false diff --git a/source/_components/binary_sensor.zigbee.markdown b/source/_components/binary_sensor.zigbee.markdown index 213721cb65d..233ebb2a91a 100644 --- a/source/_components/binary_sensor.zigbee.markdown +++ b/source/_components/binary_sensor.zigbee.markdown @@ -13,7 +13,7 @@ ha_release: 0.12 ha_iot_class: "Local Polling" --- -A `zigbee` binary sensor in this context is a device connected to one of the digital input pins on a [ZigBee](http://www.zigbee.org/) module. The states reported by such a device are limited to `on` or `off`. By default, a binary sensor is considered `on` when the ZigBee device's digital input pin is held 'high' and considered `off` when it is held `low`. This behaviour can be inverted by setting the `on_state` configuration variable to `low`. +A `zigbee` binary sensor in this context is a device connected to one of the digital input pins on a [ZigBee](http://www.zigbee.org/) module. The states reported by such a device are limited to `on` or `off`. By default, a binary sensor is considered `on` when the ZigBee device's digital input pin is held 'high' and considered `off` when it is held `low`. This behavior can be inverted by setting the `on_state` configuration variable to `low`. To enable a digital input pin as binary sensor in your installation, add the following lines to your `configuration.yaml`: diff --git a/source/_components/binary_sensor.zwave.markdown b/source/_components/binary_sensor.zwave.markdown index 233411d4f2e..85c4cc30bba 100644 --- a/source/_components/binary_sensor.zwave.markdown +++ b/source/_components/binary_sensor.zwave.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Z-Wave Binary Sensor" -description: "Instructions how to setup the Z-Wave binary sensors within Home Assistant." +description: "Instructions on how to setup the Z-Wave binary sensors within Home Assistant." date: 2016-02-22 07:00 sidebar: true comments: false diff --git a/source/_components/bloomsky.markdown b/source/_components/bloomsky.markdown index 25ab683a228..620b390e69b 100644 --- a/source/_components/bloomsky.markdown +++ b/source/_components/bloomsky.markdown @@ -1,7 +1,7 @@ --- layout: page title: "BloomSky" -description: "Instructions how to integrate the BloomSky within Home Assistant." +description: "Instructions on how to integrate the BloomSky within Home Assistant." date: 2016-02-03 20:00 sidebar: true comments: false @@ -13,7 +13,6 @@ ha_release: 0.14 ha_iot_class: "Cloud Polling" --- - The `bloomsky` component allows you to access your [BloomSky](https://www.bloomsky.com/) weather station's [sensors](/components/sensor.bloomsky), [binary sensors](/components/binary_sensor.bloomsky), and [camera](/components/camera.bloomsky) from Home Assistant. Obtain your API key from your [BloomSky dashboard](https://dashboard.bloomsky.com). Click `developers` in the bottom left of the screen. diff --git a/source/_components/bmw_connected_drive.markdown b/source/_components/bmw_connected_drive.markdown new file mode 100644 index 00000000000..94f493ff242 --- /dev/null +++ b/source/_components/bmw_connected_drive.markdown @@ -0,0 +1,89 @@ +--- +layout: page +title: "BMW Connected Drive" +description: "Instructions on how to setup your BMW Connected Drive account with Home Assistant." +date: 2018-01-10 23:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: bmw.png +ha_category: Hub +ha_release: 0.64 +--- + +This component lets you retrieve data on your BMW vehicle from the BMW Connected Drive portal. You need to have a working BMW Connected Drive account, and a Connected Drive enabled vehicle for this to work. + +For compatibility with your BMW vehicle check the [bimmer_connected page](https://github.com/m1n3rva/bimmer_connected) on github. + +To enable this component in your installation, add the following to your +`configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +bmw_connected_drive: + name: + username: USERNAME_BMW_CONNECTED_DRIVE + password: PASSWORD_BMW_CONNECTED_DRIVE + region: one of "north_america", "china" , "rest_of_world" +``` + +{% configuration %} +bmw_connected_drive: + description: configuration + required: true + type: map + keys: + name: + description: Name of your account in Home Assistant. + required: true + type: string + username: + description: Your BMW Connected Drive username. + required: true + type: string + password: + description: Your BMW Connected Drive password. + required: true + type: string + region: + description: "The region of your Connected Drive account. Please use of these values: `north_america`, `china`, `rest_of_world`" + required: true + type: string +{% endconfiguration %} + +## {% linkable_title Services %} + +The `bmw_connected_drive` component offers several services. In case you need to provide the vehicle identification number (VIN) as a parameter, you can see the VIN in the attributes of the device tracker for the vehicle. The VIN is a 17 digit alphanumeric string, e.g., `WBANXXXXXX1234567`. + +Using these services will impact the state of your vehicle. So use these services with care! + +### {% linkable_title Locking and unlocking %} + +The vehicle can be locked and unlocked via the lock component that is created automatically for each vehicle. Before invoking these services, make sure it's safe to lock/unlock the vehicle in the current situation. + +### {% linkable_title Air condition %} + +The air condition of the vehicle can be activated with the service `bmw_connected_drive.activate_air_conditioning`. + +What exactly is started here depends on the type of vehicle. It might range from just ventilation over auxiliary heating to real air conditioning. If your vehicle is equipped with auxiliary heating, only trigger this service if the vehicle is parked in a location where it is safe to use it (e.g., not in an underground parking or closed garage). + +The vehicle is identified via the parameter `vin`. + +### {% linkable_title Sound the horn %} + +The service `bmw_connected_drive.sound_horn` sounds the horn of the vehicle. Use this feature responsibly, as it might annoy your neighbors. The vehicle is identified via the parameter `vin`. + +### {% linkable_title Flash the lights %} + +The service `bmw_connected_drive.light_flash' flashes the lights of the vehicle. The vehicle is identified via the parameter `vin`. + +### {% linkable_title Update the state %} + +The service `bmw_connected_drive.update_state`fetches the last state of the vehicles of all your accounts from the BMW server. This does *not* trigger an update from the vehicle; it gets the data from the BMW servers. So this service does *not* interact with your vehicles. + +This service does not require any attributes. + +## {% linkable_title Disclaimer %} + +This software is not affiliated with or endorsed by BMW Group. diff --git a/source/_components/browser.markdown b/source/_components/browser.markdown index c5fa4b424eb..6325fef367a 100644 --- a/source/_components/browser.markdown +++ b/source/_components/browser.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Browser" -description: "Instructions how to setup the browser component with Home Assistant." +description: "Instructions on how to setup the browser component with Home Assistant." date: 2015-01-24 14:39 sidebar: true comments: false diff --git a/source/_components/calendar.caldav.markdown b/source/_components/calendar.caldav.markdown new file mode 100644 index 00000000000..8ea6b6ad087 --- /dev/null +++ b/source/_components/calendar.caldav.markdown @@ -0,0 +1,169 @@ +--- +layout: page +title: "CalDav" +description: "Instructions on how to integrate a WebDav calendar into Home Assistant." +date: 2017-11-27 23:14 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Calendar +ha_iot_class: "Cloud Polling" +ha_release: "0.60" +--- + + +The `caldav` platform allows you to connect to your WebDav calendar and generate binary sensors. A different sensor will be created for each individual calendar, or you can specify custom calendars which match a criteria you define (more on that below). These sensors will be `on` if you have an on going event in that calendar or `off` if the event is later in time, or if there is no event at all. The WebDav calendar get updated roughly every 15 minutes. + +### {% linkable_title Prerequisites %} + +You need to have a CalDav server and credentials for it. This component was tested against [Baikal](http://sabre.io/baikal/) but any component complying with the RFC4791 should work. [Nextcloud](https://nextcloud.com/) and [Owncloud](https://owncloud.org/) work fine. + +You might need some additional system packages to compile the Python caldav library. On a Debian based system, install them by: + +```bash +$ sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev +``` + +### {% linkable_title Basic Setup %} + +To integrate a WebDav calendar in Home Assistant, add the following section to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry for baikal +calendar: + - platform: caldav + username: john.doe@test.com + password: !secret caldav + url: https://baikal.my-server.net/cal.php/calendars/john.doe@test.com/default +``` + +```yaml +# Example configuration.yaml entry for nextcloud, calendars will be found automatically +calendar: + - platform: caldav + username: john.doe + password: !secret caldav + url: https://nextcloud.example.com/remote.php/dav +``` + +This example will generate default binary sensors for each calendar you have in your account. Those calendars will be `on` when there is an ongoing event and `off` if not. Events that last a whole day are ignored in those calendars. You have to setup custom calendars in order to take them into account or for advanced event filtering. + + +### {% linkable_title Custom calendars %} + +You have the possibility to create multiple binary sensors for events that match certain conditions. + +```yaml +# Example configuration.yaml entry +calendar: + - platform: caldav + username: john.doe@test.com + password: !secret caldav + url: https://baikal.my-server.net/cal.php/calendars/john.doe@test.com/default + custom_calendars: + - name: 'HomeOffice' + calendar: 'Agenda' + search: 'HomeOffice' + - name: 'WarmupFlat' + calendar: 'Agenda' + search: 'Warmup' +``` + +This will create two binary sensors for the calendar name Agenda: "HomeOffice" and "WarmupFlat". Those sensors will be `on` if there is an ongoing event matching the regular expression specified in `search`. In custom calendars, events that last a whole day are taken into account. + +Please note that when you configure custom calendars, the default ones are not created anymore. + +{% configuration %} +url: + required: true + description: The full URL to your calendars. + type: string +username: + required: false + description: Username for authentication. + type: string +password: + required: false + description: Password for authentication. + type: string +calendars: + required: false + description: List of the calendars to filter. Empty or absent means no filtering, i.e. all calendars will be added. + type: list +custom_calendars: + required: false + description: Details on any custom binary sensor calendars you want to create. + type: list + keys: + name: + required: true + description: The name of your custom calendar. + type: string + calendar: + required: true + description: The source calendar to search on. + type: string + search: + required: true + description: Regular expression for filtering the events based on the content of their summary, description or location. + type: string +{% endconfiguration %} + + +### {% linkable_title Sensor attributes %} + + - **offset_reached**: If set in the event title and parsed out will be on/off once the offset in the title in minutes is reached. So the title Very important meeting !!-10 would trigger this attribute to be on 10 minutes before the event starts. + - **all_day**: `True/False` if this is an all day event. Will be `False` if there is no event found. + - **message**: The event title with the `search` values extracted. So in the above example for `offset_reached` the message would be set to Very important meeting + - **description**: The event description. + - **location**: The event Location. + - **start_time**: Start time of event. + - **end_time**: End time of event. + +### {% linkable_title Examples %} + +All events of the calendars "private" and "holidays". Note that all day events are not included. +```yaml +# Example configuration.yaml entry for nextcloud +calendar: + - platform: caldav + url: https://nextcloud.example.com/remote.php/dav + username: 'me' + password: !secret caldav + calendars: + - private + - holidays +``` + +Full example with automation to wake up to music if not holiday. Prerequisite: you have a calendar named "work" where you create calendar entries containing "Holiday". + +Custom calendar names are built from the main calendar + name of the custom calendar. + +```yaml +# configuration.yaml +calendar: + - platform: caldav + url: https://nextcloud.example.com/remote.php/dav + username: 'me' + password: !secret caldav + custom_calendars: + - name: holiday + calendar: work + search: 'Holiday' + +# automations.yaml +- id: wakeup + alias: worktime wakeup + trigger: + platform: time + at: 06:40:00 + action: + - service: media_player.media_play + entity_id: media_player.bedroom + condition: + - condition: state + entity_id: calendar.work_holiday + state: 'off' + +``` diff --git a/source/_components/calendar.google.markdown b/source/_components/calendar.google.markdown index 658dae1f2bc..73860367c8c 100644 --- a/source/_components/calendar.google.markdown +++ b/source/_components/calendar.google.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Google Calendar Event" -description: "Instructions how to use Google Calendars in Home Assistant." +description: "Instructions on how to use Google Calendars in Home Assistant." date: 2015-05-08 17:15 sidebar: true comments: false @@ -14,55 +14,66 @@ ha_release: 0.33 --- -This platform allows you to connect to your [Google Calendars](https://calendar.google.com) and generate binary sensors. The sensors created can trigger based on any event on the calendar or only for matching events. When you first setup this component it will generate a new configuration file *google_calendars.yaml* that will contain information about all of the calendars you can see. +The `google` calendar platform allows you to connect to your [Google Calendars](https://calendar.google.com) and generate binary sensors. The sensors created can trigger based on any event on the calendar or only for matching events. When you first setup this component it will generate a new configuration file `google_calendars.yaml` that will contain information about all of the calendars you can see. -### {% linkable_title Prerequisites %} +## {% linkable_title Prerequisites %} Generate a Client ID and Client Secret on [Google Developers Console](https://console.developers.google.com/start/api?id=calendar). 1. Follow the wizard using the following information. 1. When it gets to the point of asking _Which API are you using?_ just click cancel. -1. Click on the tab 'OAuth consent screen'. +1. Under APIs & Services > Credentials, click on the tab 'OAuth consent screen'. 1. Set 'Product name shown to users' to anything you want. We suggest Home-Assistant. 1. Save this page. You don't have to fill out anything else there. 1. Click 'Create credentials' -> OAuth client ID. 1. Set the Application type to 'Other' and give this credential set a name then click Create. -1. Save the client ID and secret as you will need to put these in your configuration.yaml file. +1. Save the client ID and secret as you will need to put these in your `configuration.yaml` file. +1. Click on "Library", search for "Google Calendar API" and enable it. -### {% linkable_title Basic Setup %} +## {% linkable_title Configuration %} To integrate Google Calendar in Home Assistant, add the following section to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry google: - client_id: *Value_created_from_steps_above* - client_secret: *Value_created_from_steps_above* + client_id: YOUR_CLIENT_ID + client_secret: YOUR_CLIENT_SECRET ``` -Configuration variables: - -- **client_id** (*Required*): Use the value you generated in the Prerequisites stage. -- **client_secret** (*Required*): Use the value you generated in the Prerequisites stage. -- **track_new_calendar** (*Optional*): Will automatically generate a binary sensor when a new calendar is detected. The system scans for new calendars on startup. By default this is set to `True`. +{% configuration %} +client_id: + description: Use the value you generated in the Prerequisites stage. + required: true + type: string +client_secret: + description: Use the value you generated in the Prerequisites stage. + required: true + type: string +track_new_calendar: + description: Will automatically generate a binary sensor when a new calendar is detected. The system scans for new calendars only on startup. + required: false + type: boolean + default: true +{% endconfiguration %} The next steps will require you to have Home Assistant running. After you have it running complete the Google authentication that pops up. It will give you a URL and a code to enter. This will grant your Home Assistant service access to all the Google Calendars that the account you authenticate with can read. This is a Read-Only view of these calendars. +## {% linkable_title Calendar Configuration %} -### {% linkable_title Calendar Configuration %} -Editing `google_calendars.yaml` +Editing the `google_calendars.yaml` file. A basic entry for a single calendar looks like: ```yaml -- cal_id: "***************************@group.calendar.google.com" +- cal_id: "*****@group.calendar.google.com" entities: - device_id: test_everything name: Give me everything track: true -- cal_id: "***************************@group.calendar.google.com" +- cal_id: "*****@group.calendar.google.com" entities: - device_id: test_important name: Important Stuff @@ -78,38 +89,28 @@ A basic entry for a single calendar looks like: Variables: - **cal_id**: The Google generated unique id for this calendar. **DO NOT CHANGE** - - **entities**: Yes, you can have multiple sensors for a calendar! - - **device_id**: (*Required*): The name that all your automations/scripts will use to reference this device. - - **name**: (*Required*): What is the name of your sensor that you'll see in the frontend. - - **track**: (*Required*): Should we create a sensor `True` or ignore it `False`? - - **search**: (*Optional*): If set will only trigger for matched events. - - **offset**: (*Optional*): A set of characters that precede a number in the event title for designating a pre-trigger state change on the sensor. (Default: `!!`) - + - **ignore_availability**: (*Optional*): Should we respect `free`/`busy` flags? (Defaults to `true`) + From this we will end up with the binary sensors `calendar.test_unimportant` and `calendar.test_important` which will toggle themselves on/off based on events on the same calendar that match the search value set for each. You'll also have a sensor `calendar.test_everything` that will not filter events out and always show the next event available. But what if you only wanted it to toggle based on all events? Just leave out the *search* parameter. -**Note**: If you use a `#` sign for `search` then wrap the whole search term in quotes. Otherwise everything following the hash sign would be considered a YAML comment. - ++If you use a `#` sign for `search` then wrap the whole search term in quotes. Otherwise everything following the hash sign would be considered a YAML comment. +
### {% linkable_title Sensor attributes %} - **offset_reached**: If set in the event title and parsed out will be `on`/`off` once the offset in the title in minutes is reached. So the title `Very important meeting #Important !!-10` would trigger this attribute to be `on` 10 minutes before the event starts. - - **all_day**: `True`/`False` if this is an all day event. Will be `False` if there is no event found. - - **message**: The event title with the `search` and `offset` values extracted. So in the above example for **offset_reached** the **message** would be set to `Very important meeting` - - **description**: The event description. - - **location**: The event Location. - - **start_time**: Start time of event. - - **end_time**: End time of event. diff --git a/source/_components/calendar.markdown b/source/_components/calendar.markdown index f18e94902c3..4b69b5e6fe8 100644 --- a/source/_components/calendar.markdown +++ b/source/_components/calendar.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Calendar" -description: "Instructions how to integrate calendars within Home Assistant." +description: "Instructions on how to integrate calendars within Home Assistant." date: 2016-11-19 08:36 sidebar: true comments: false diff --git a/source/_components/calendar.todoist.markdown b/source/_components/calendar.todoist.markdown index 65401ebc643..c416ddb50d7 100644 --- a/source/_components/calendar.todoist.markdown +++ b/source/_components/calendar.todoist.markdown @@ -63,7 +63,7 @@ calendar: - Calculus II ``` -(See [here](https://home-assistant.io/docs/configuration/secrets/) for more details about what that `!secret` does -- it's not exclusive to Todoist, and can help keep your API keys and passwords a little safer!) +(See [here](/docs/configuration/secrets/) for more details about what that `!secret` does -- it's not exclusive to Todoist, and can help keep your API keys and passwords a little safer!) As you can see, there are 4 custom projects here: @@ -109,9 +109,9 @@ Home Assistant does its best to determine what task in each project is "most" im ### {% linkable_title Services %} -Todoist also comes with access to a service, `todoist.new_task`. This service can be used to create a new Todoist task. You can specify labels and a project, or you can leave them blank, and the task will go to your "Inbox" project. +Todoist also comes with access to a service, `calendar.todoist_new_task`. This service can be used to create a new Todoist task. You can specify labels and a project, or you can leave them blank, and the task will go to your "Inbox" project. -Here's an example JSON payload: +Here are two example JSON payloads resulting in the same task: ```json { @@ -123,6 +123,17 @@ Here's an example JSON payload: } ``` +```json +{ + "content": "Pick up the mail", + "project": "Errands", + "labels":"Homework,School", + "priority":3, + "due_date_string":"tomorrow at 14:00", + "due_date_lang":"en" +} +``` + - **content** (*Required*): The name of the task you want to create. - **project** (*Optional*): The project to put the task in. @@ -131,6 +142,11 @@ Here's an example JSON payload: - **priority** (*Optional*): The priority of the task, from 1-4. Again, 1 means least important, and 4 means most important. -- **due_date** (*Optional*): When the task should be due, in either YYYY-MM-DD format or YYYY-MM-DD HH:MM format. +- **due_date_string** (*Optional*): When the task should be due, in [natural language](https://support.todoist.com/hc/en-us/articles/205325931-Dates-and-Times). Mutually exclusive with `due_date` + +- **due_date_lang** (*Optional*): When `due_date_string` is set, it is posisble to set the language. + Valid languages are: `en`, `da`, `pl`, `zh`, `ko`, `de`, `pt`, `ja`, `it`, `fr`, `sv`, `ru`, `es`, `nl` + +- **due_date** (*Optional*): When the task should be due, in either YYYY-MM-DD format or YYYY-MM-DD HH:MM format. Mutually exclusive with `due_date_string`. Note that there's (currently) no way to mark tasks as done through Home Assistant; task names do not necessarily have to be unique, so you could find yourself in a situation where you close the wrong task. diff --git a/source/_components/camera.abode.markdown b/source/_components/camera.abode.markdown index a95b6d2fcfb..2aa3da2313c 100644 --- a/source/_components/camera.abode.markdown +++ b/source/_components/camera.abode.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Abode Camera" -description: "Instructions how to integrate Abode cameras into Home Assistant." +description: "Instructions on how to integrate Abode cameras into Home Assistant." date: 2017-08-26 13:28 sidebar: true comments: false diff --git a/source/_components/camera.amcrest.markdown b/source/_components/camera.amcrest.markdown index 2c1a042c877..73a6ca444f0 100644 --- a/source/_components/camera.amcrest.markdown +++ b/source/_components/camera.amcrest.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Amcrest IP Camera" -description: "Instructions how to integrate Amcrest IP cameras within Home Assistant." +description: "Instructions on how to integrate Amcrest IP cameras within Home Assistant." date: 2016-11-24 10:00 sidebar: true comments: false diff --git a/source/_components/camera.android_ip_webcam.markdown b/source/_components/camera.android_ip_webcam.markdown index 04c6e41d8e8..8aa3455faa8 100644 --- a/source/_components/camera.android_ip_webcam.markdown +++ b/source/_components/camera.android_ip_webcam.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Android IP Webcam Camera" -description: "Instructions how to integrate Android IP Webcam cameras within Home Assistant." +description: "Instructions on how to integrate Android IP Webcam cameras within Home Assistant." date: 2015-07-11 0:36 sidebar: true comments: false diff --git a/source/_components/camera.arlo.markdown b/source/_components/camera.arlo.markdown index 1d66a90bbf0..a634e8d8d91 100644 --- a/source/_components/camera.arlo.markdown +++ b/source/_components/camera.arlo.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Arlo Camera" -description: "Instructions how to integrate your Netgear Arlo cameras within Home Assistant." +description: "Instructions on how to integrate your Netgear Arlo cameras within Home Assistant." date: 2016-05-30 10:00 sidebar: true comments: false @@ -30,4 +30,4 @@ Configuration variables: - **ffmpeg_arguments**: (*Optional*): Extra options to pass to ffmpeg, e.g., image quality or video filter options. -**Note:** To be able to playback the last capture, it is required to install the `ffmpeg` component. Make sure to follow the steps mentioned at [FFMPEG](https://home-assistant.io/components/ffmpeg/) documentation. +**Note:** To be able to playback the last capture, it is required to install the `ffmpeg` component. Make sure to follow the steps mentioned at [FFMPEG](/components/ffmpeg/) documentation. diff --git a/source/_components/camera.august.markdown b/source/_components/camera.august.markdown new file mode 100644 index 00000000000..660a9504c5e --- /dev/null +++ b/source/_components/camera.august.markdown @@ -0,0 +1,18 @@ +--- +layout: page +title: "August Camera" +description: "Instructions on how to integrate your August devices into Home Assistant." +date: 2018-02-17 22:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: august.png +ha_category: Camera +ha_release: "0.64" +ha_iot_class: "Cloud Polling" +--- + +The `august` camera platform allows you to view the latest camera image (triggered by motion) by your [August](http://august.com) device in Home Assistant. + +To add `august` camera to your installation, follow instructions in [August component](/components/august/). diff --git a/source/_components/camera.axis.markdown b/source/_components/camera.axis.markdown index 23695c7905f..ec725b06ec7 100644 --- a/source/_components/camera.axis.markdown +++ b/source/_components/camera.axis.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Axis Camera" -description: "Instructions how to setup Axis cameras within Home Assistant." +description: "Instructions on how to setup Axis cameras within Home Assistant." date: 2017-05-01 19:09 sidebar: true comments: false diff --git a/source/_components/camera.bloomsky.markdown b/source/_components/camera.bloomsky.markdown index 8661690eb65..bd6f8a58b9e 100644 --- a/source/_components/camera.bloomsky.markdown +++ b/source/_components/camera.bloomsky.markdown @@ -1,7 +1,7 @@ --- layout: page title: "BloomSky Camera" -description: "Instructions how to integrate the BloomSky camera within Home Assistant." +description: "Instructions on how to integrate the BloomSky camera within Home Assistant." date: 2016-02-03 20:00 sidebar: true comments: false diff --git a/source/_components/camera.canary.markdown b/source/_components/camera.canary.markdown new file mode 100644 index 00000000000..8e5f07f461f --- /dev/null +++ b/source/_components/camera.canary.markdown @@ -0,0 +1,32 @@ +--- +layout: page +title: "Canary Camera" +description: "Instructions on how to integrate your Canary devices into Home Assistant." +date: 2017-12-07 22:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: canary.png +ha_category: Camera +ha_release: "0.60" +ha_iot_class: "Cloud Polling" +--- + +The `canary` camera platform allows you to watch the live stream of your [Canary](https://canary.is) camera in Home Assistant. This requires the [`ffmpeg` component](/components/ffmpeg/) to be already configured. + +To add `canary` camera to your installation, follow instructions in [Canary component](/components/canary/). Once you have [Canary component](/components/canary/) setup, your [Canary](https://canary.is) camera(s) should show up automatically. + +You can add the following to your `configuration.yaml` file to configure `canary` camera with optional settings: + +```yaml +camera: + - platform: canary +``` + +{% configuration %} + ffmpeg_arguments: + description: Extra options to pass to `ffmpeg`, e.g., image quality or video filter options. More details in [FFmpeg component](/components/ffmpeg). + required: false + type: string +{% endconfiguration %} diff --git a/source/_components/camera.dispatcher.markdown b/source/_components/camera.dispatcher.markdown index 62395dc993e..26eb74febcd 100644 --- a/source/_components/camera.dispatcher.markdown +++ b/source/_components/camera.dispatcher.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Dispatcher IP Camera" -description: "Instructions how to integrate internal dispatcher cameras within Home Assistant." +description: "Instructions on how to integrate internal dispatcher cameras within Home Assistant." date: 2017-03-08 00:00 sidebar: true comments: false @@ -9,7 +9,7 @@ sharing: true footer: true ha_category: Camera logo: camcorder.png -ha_release: 0.40 +ha_release: "0.40" ha_iot_class: "depends" --- diff --git a/source/_components/camera.doorbird.markdown b/source/_components/camera.doorbird.markdown index 55fcb419f8c..ce23d946725 100644 --- a/source/_components/camera.doorbird.markdown +++ b/source/_components/camera.doorbird.markdown @@ -1,7 +1,7 @@ --- layout: page title: "DoorBird Camera" -description: "Instructions how to integrate DoorBird video doorbell images into Home Assistant." +description: "Instructions on how to integrate DoorBird video doorbell images into Home Assistant." date: 2017-08-06 11:30 sidebar: true comments: false @@ -13,7 +13,7 @@ ha_release: "0.54" ha_iot_class: "Local Polling" --- -The `doorbird` implementation allows you to view the live video and saved images from your [DoorBird](http://www.doorbird.com/) device in Home Assistant. +The `doorbird` implementation allows you to view the live video and previous images from your [DoorBird](http://www.doorbird.com/) device in Home Assistant.You must have the [DoorBird component](/components/doorbird/) configured to use this camera. @@ -26,7 +26,3 @@ To enable the camera, add the following to your `configuration.yaml` file: camera: - platform: doorbird ``` - -Configuration variables: - -- **last_visitor** (*Optional*): Adds a second camera that shows the last picture taken when someone rang the doorbell. Default is `false`. diff --git a/source/_components/camera.familyhub.markdown b/source/_components/camera.familyhub.markdown new file mode 100644 index 00000000000..20f888a63d9 --- /dev/null +++ b/source/_components/camera.familyhub.markdown @@ -0,0 +1,34 @@ +--- +layout: page +title: "Family Hub Camera" +description: "Instructions on how to integrate Samsung Family Hub refrigerator cameras within Home Assistant." +date: 2018-05-04 09:44 +sidebar: true +comments: false +sharing: true +footer: true +logo: familyhub.png +ha_category: Camera +ha_release: "0.70" +ha_iot_class: "Local Polling" +--- + +The `familyhub` platform allows you to get images of the inside of your [Samsung Family Hub refrigerator](https://www.samsung.com/us/explore/family-hub-refrigerator/connected-hub/) in Home Assistant. + +## {% linkable_title Configuration %} + +To enable your Family Hub camera in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +camera: + - platform: familyhub + ip_address: 'IP_ADDRESS' +``` + +{% configuration %} +ip_address: + description: The IP address of your refrigerator. + required: true + type: string +{% endconfiguration %} diff --git a/source/_components/camera.ffmpeg.markdown b/source/_components/camera.ffmpeg.markdown index 86e6355c8d3..481c835a153 100644 --- a/source/_components/camera.ffmpeg.markdown +++ b/source/_components/camera.ffmpeg.markdown @@ -29,7 +29,7 @@ Configuration variables: - **input** (*Required*): An FFmpeg-compatible input file, stream, or feed. - **name** (*Optional*): Override the name of your camera. -- **extra_arguments** (*Optional*): Extra options to pass to `ffmpeg`, e.g. image quality or video filter options. +- **extra_arguments** (*Optional*): Extra options to pass to `ffmpeg`, e.g., image quality or video filter options. ### {% linkable_title Image quality %} diff --git a/source/_components/camera.foscam.markdown b/source/_components/camera.foscam.markdown index ea90a82984b..c9d1aabd505 100644 --- a/source/_components/camera.foscam.markdown +++ b/source/_components/camera.foscam.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Foscam IP Camera" -description: "Instructions how to integrate Foscam IP cameras within Home Assistant." +description: "Instructions on how to integrate Foscam IP cameras within Home Assistant." date: 2015-09-17 08:01 sidebar: true comments: false @@ -15,6 +15,8 @@ ha_iot_class: "Local Polling" The `foscam` platform allows you to watch the live stream of your [Foscam](http://www.foscam.com/) IP camera in Home Assistant. +## {% linkable_title Configuration %} + To enable your Foscam IP camera in your installation, add the following to your `configuration.yaml` file: ```yaml @@ -22,8 +24,8 @@ To enable your Foscam IP camera in your installation, add the following to your camera: - platform: foscam ip: IP_ADDRESS - username: USERNAME - password: PASSWORD + username: YOUR_USERNAME + password: YOUR_PASSWORD ``` Configuration variables: @@ -39,4 +41,5 @@ There seems to be some issues within Foscam with lengthy passwords and passwords
### {% linkable_title Control Foscam PTZ (Pan/Tilt/Zoom) - Home/Away %} + Foscam Webcams which support CGI Commands can be controlled by Home Assistant ([Source](http://www.ipcamcontrol.net/files/Foscam%20IPCamera%20CGI%20User%20Guide-V1.0.4.pdf)). For an example of how this can be done, see the [Foscam IP Camera Pan, Tilt, Zoom Control](/cookbook/foscam_away_mode_PTZ/) Cookbook entry. diff --git a/source/_components/camera.generic.markdown b/source/_components/camera.generic.markdown index 69637387a44..b9bf15bf46a 100644 --- a/source/_components/camera.generic.markdown +++ b/source/_components/camera.generic.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Generic IP Camera" -description: "Instructions how to integrate IP cameras within Home Assistant." +description: "Instructions on how to integrate IP cameras within Home Assistant." date: 2015-07-11 0:36 sidebar: true comments: false @@ -16,7 +16,7 @@ ha_iot_class: "depends" The `generic` camera platform allows you to integrate any IP camera or other URL into Home Assistant. Templates can be used to generate the URLs on the fly. -Home Assistant will serve the images via its server, making it possible to view your IP camera's while outside of your network. The endpoint is `/api/camera_proxy/camera.[name]`. +Home Assistant will serve the images via its server, making it possible to view your IP cameras while outside of your network. The endpoint is `/api/camera_proxy/camera.[name]`. To enable this camera in your installation, add the following to your `configuration.yaml` file: @@ -36,6 +36,7 @@ Configuration variables: - **authentication** (*Optional*): Type for authenticating the requests `basic` (default) or `digest`. - **limit_refetch_to_url_change** (*Optional*): True/false value (default: false). Limits re-fetching of the remote image to when the URL changes. Only relevant if using a template to fetch the remote image. - **content_type** (*Optional*): Set the content type for the IP camera if it is not a jpg file (default: `image/jpeg`). Use `image/svg+xml` to add a dynamic svg file. +- **framerate** (*Optional*): The number of frames-per-second (FPS) of the stream (setting this too high may cause too much traffic on the network or be heavy on the camera). +### {% linkable_title Configuration %} + To use an ASUSWRT router in your installation, add the following to your `configuration.yaml` file: ```yaml @@ -29,15 +31,44 @@ device_tracker: username: YOUR_ADMIN_USERNAME ``` -Configuration variables: - -- **host** (*Required*): The IP address of your router, eg. `192.168.1.1`. -- **username** (*Required*: The username of an user with administrative privileges, usually `admin`. -- **password** (*Optional*): The password for your given admin account (use this if no SSH key is given). -- **protocol** (*Optional*): The protocol (`ssh` or `telnet`) to use. Defaults to `ssh`. -- **port** (*Optional*): SSH port to use. Defaults to `22`. -- **mode** (*Optional*): The operating mode of the router (`router` or `ap`). Defaults to `router`. -- **ssh_key** (*Optional*): The path to your SSH private key file associated with your given admin account (instead of password). +{% configuration %} +host: + description: "The IP address of your router, eg. `192.168.1.1`." + required: true + type: string +username: + description: "The username of an user with administrative privileges, usually `admin`." + required: true + type: string +password: + description: "The password for your given admin account (use this if no SSH key is given)." + required: false + type: string +protocol: + description: "The protocol (`ssh` or `telnet`) to use." + required: false + type: string + default: ssh +port: + description: SSH port to use. + required: false + type: int + default: 22 +mode: + description: "The operating mode of the router (`router` or `ap`)." + required: false + type: string + default: router +ssh_key: + description: The path to your SSH private key file associated with your given admin account (instead of password). + required: false + type: string +require_ip: + description: If the router is in access point mode. + required: false + type: boolean + default: true +{% endconfiguration %}
+ Screenshot of the conversation interface in Home Assistant.
+
You need to [enable telnet](https://www.asus.com/support/faq/1005449/) on your router if you choose to use `protocol: telnet`. diff --git a/source/_components/device_tracker.automatic.markdown b/source/_components/device_tracker.automatic.markdown index dff0b45fec9..f3e63a648dd 100644 --- a/source/_components/device_tracker.automatic.markdown +++ b/source/_components/device_tracker.automatic.markdown @@ -56,5 +56,8 @@ automation: action: - service: light.turn_off ``` +
+ You can obtain the correct ID for your vehicle from your known_devices.yaml file. Be sure to lower-case any letters contained in your vehicle's ID when using it in an automation trigger. +
See the [device tracker component page](/components/device_tracker/) for instructions how to configure the cars to be tracked. diff --git a/source/_components/device_tracker.bbox.markdown b/source/_components/device_tracker.bbox.markdown index 7a5cc91649c..35bae013f02 100644 --- a/source/_components/device_tracker.bbox.markdown +++ b/source/_components/device_tracker.bbox.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Bbox" -description: "Instructions how to integrate Bouygues Bbox routers into Home Assistant." +description: "Instructions on how to integrate Bouygues Bbox routers into Home Assistant." date: 2016-10-13 23:00 sidebar: true comments: false diff --git a/source/_components/device_tracker.bluetooth_le_tracker.markdown b/source/_components/device_tracker.bluetooth_le_tracker.markdown index e0da81a826a..ce1dab50002 100644 --- a/source/_components/device_tracker.bluetooth_le_tracker.markdown +++ b/source/_components/device_tracker.bluetooth_le_tracker.markdown @@ -30,7 +30,7 @@ $ sudo apt install bluetooth libbluetooth-dev pkg-config libboost-python-dev lib Before you get started with this platform, please note that: - This platform is incompatible with Windows - - This platform requires root privileges + - This platform requires access to the bluetooth stack, see [Rootless Setup section](#rootless-setup) for further information To use the Bluetooth tracker in your installation, add the following to your `configuration.yaml` file: @@ -43,11 +43,16 @@ device_tracker: Configuration variables: - **device_id** (*Optional*): The device ID for the Bluetooth device to be used for tracking. Defaults to `hci0`. +- **track_new_devices** (*Optional*): If new discovered devices are tracked by default. Defaults to `True`. +- **scan_duration** (*Optional*): How long should the scanner be looking for BLE devices. Defaults to `10` seconds. +- **interval_seconds** (*Optional*): Seconds between each scan for new devices. Defaults to `12` seconds. As some BT LE devices change their MAC address regularly, a new device is only discovered when it has been seen 5 times. -Some BTLE devices (e.g. fitness trackers) are only visible to the devices that they are paired with. In this case, the BTLE tracker won't see this device. +Some BTLE devices (e.g., fitness trackers) are only visible to the devices that they are paired with. In this case, the BTLE tracker won't see this device. -For running Home Assistant as non root user we can give python3 the missing capabilities to access the Bluetooth stack. Quite like setting the setuid bit (see [Stack Exchange](http://unix.stackexchange.com/questions/96106/bluetooth-le-scan-as-non-root) for more information). +## {% linkable_title Rootless Setup %} + +Normally accessing the Bluetooth stack is reserved for root, but running programs that are networked as root is a bad security wise. To allow non-root access to the Bluetooth stack we can give Python 3 the missing capabilities to access the Bluetooth stack. Quite like setting the setuid bit (see [Stack Exchange](http://unix.stackexchange.com/questions/96106/bluetooth-le-scan-as-non-root) for more information). ```bash $ sudo apt-get install libcap2-bin diff --git a/source/_components/device_tracker.bluetooth_tracker.markdown b/source/_components/device_tracker.bluetooth_tracker.markdown index 0a2a2d06323..fd79f3c3f04 100644 --- a/source/_components/device_tracker.bluetooth_tracker.markdown +++ b/source/_components/device_tracker.bluetooth_tracker.markdown @@ -15,10 +15,6 @@ ha_release: 0.18 This tracker discovers new devices on boot and tracks Bluetooth devices periodically based on `interval_seconds` value. It is not required to pair the devices with each other! Devices discovered are stored with 'bt_' as the prefix for device MAC addresses in `known_devices.yaml`. --[Hass.io](/hassio/) only supports Bluetooth on Raspberry Pi 3 via the Bluetooth BCM43xx (/addons/bluetooth_bcm43xx/) addon. [Hass.io](/hassio/) doesn't support external Bluetooth dongles. -
- To use the Bluetooth tracker in your installation, add the following to your `configuration.yaml` file: ```yaml @@ -27,6 +23,14 @@ device_tracker: - platform: bluetooth_tracker ``` +{% configuration %} +request_rssi: + description: Performs a request for the "Received signal strength indication" (RSSI) of each tracked device + required: false + type: boolean + default: False +{% endconfiguration %} + In some cases it can be that your device is not discovered. In that case let your phone scan for Bluetooth devices while you restart Home Assistant. Just hit `Scan` on your phone all the time until Home Assistant is fully restarted and the device should appear in `known_devices.yaml`. For additional configuration variables check the [Device tracker page](/components/device_tracker/). diff --git a/source/_components/device_tracker.bmw_connected_drive.markdown b/source/_components/device_tracker.bmw_connected_drive.markdown new file mode 100644 index 00000000000..4f390c5fa3a --- /dev/null +++ b/source/_components/device_tracker.bmw_connected_drive.markdown @@ -0,0 +1,20 @@ +--- +layout: page +title: "BMW Connected Drive Device Tracker" +description: "Instructions on how to setup your BMW Connected Drive account with Home Assistant." +date: 2018-01-10 23:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: bmw.png +ha_category: Presence Detection +ha_release: 0.64 +--- + + +The `bmw_connected_drive` platform allows you to import data on your BMW into Home Assistant. + +The device tracker platform will be automatically configured if the `bmw_connected_drive` component is configured. + +For more configuration information see the [`bmw_connected_drive` component](/components/bmw_connected_drive/) documentation. diff --git a/source/_components/device_tracker.bt_home_hub_5.markdown b/source/_components/device_tracker.bt_home_hub_5.markdown index 9fd185eadd8..106ba06083d 100644 --- a/source/_components/device_tracker.bt_home_hub_5.markdown +++ b/source/_components/device_tracker.bt_home_hub_5.markdown @@ -1,7 +1,7 @@ --- layout: page title: "BT Home Hub 5" -description: "Instructions how to integrate BT Home Hub 5 router into Home Assistant." +description: "Instructions on how to integrate BT Home Hub 5 router into Home Assistant." date: 2016-06-13 13:00 sidebar: true comments: false @@ -25,6 +25,6 @@ device_tracker: Configuration variables: -- **host** (*Required*): The IP address of your router, e.g. 192.168.1.254. +- **host** (*Required*): The IP address of your router, e.g., 192.168.1.254. See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. diff --git a/source/_components/device_tracker.cisco_ios.markdown b/source/_components/device_tracker.cisco_ios.markdown index 1402e840649..589241b8eb6 100644 --- a/source/_components/device_tracker.cisco_ios.markdown +++ b/source/_components/device_tracker.cisco_ios.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Cisco IOS" -description: "Instructions how to integrate Cisco IOS routers into Home Assistant." +description: "Instructions on how to integrate Cisco IOS routers into Home Assistant." date: 2016-11-07 19:59 sidebar: true comments: false @@ -59,7 +59,7 @@ device_tracker: Configuration variables: -- **host** (*Required*): The IP address of your router, e.g. 192.168.1.1. +- **host** (*Required*): The IP address of your router, e.g., 192.168.1.1. - **username** (*Required*): The username of an user with administrative privileges. - **password** (*Required*): The password for your given admin account. diff --git a/source/_components/device_tracker.ddwrt.markdown b/source/_components/device_tracker.ddwrt.markdown index 4fa4fe0af4a..826046d029f 100644 --- a/source/_components/device_tracker.ddwrt.markdown +++ b/source/_components/device_tracker.ddwrt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "DD-WRT" -description: "Instructions how to integrate DD-WRT based routers into Home Assistant." +description: "Instructions on how to integrate DD-WRT based routers into Home Assistant." date: 2015-05-11 09:00 sidebar: true comments: false @@ -27,7 +27,7 @@ device_tracker: Configuration variables: -- **host** (*Required*): The IP address of your router, e.g. `192.168.1.1`. +- **host** (*Required*): The IP address of your router, e.g., `192.168.1.1`. - **username** (*Required*: The username of an user with administrative privileges, usually `admin`. - **password** (*Required*): The password for your given admin account. diff --git a/source/_components/device_tracker.freebox.markdown b/source/_components/device_tracker.freebox.markdown new file mode 100644 index 00000000000..fa2a2dd6181 --- /dev/null +++ b/source/_components/device_tracker.freebox.markdown @@ -0,0 +1,67 @@ +--- +layout: page +title: "Freebox" +description: "Instructions on how to integrate Freebox routers into Home Assistant." +date: 2018-05-16 23:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: freebox.svg +ha_category: Presence Detection +ha_release: "0.70" +ha_iot_class: "Local Polling" +--- + + +The `freebox` platform offers presence detection by keeping track of the +devices connected to a [Freebox](http://www.free.fr/) router. + +### {% linkable_title Configuration %} + +If you have enabled the [discovery component](/components/discovery/), +your Freebox should be detected automatically. Otherwise, you can set it +up manually in your `configuration.yaml` file: + +```yaml +device_tracker: + - platform: freebox + host: foobar.fbox.fr + port: 1234 +``` + +{% configuration %} +host: + description: The url of the Freebox. + required: true + type: string +port: + description: The https port the Freebox is listening on. + required: true + type: string +{% endconfiguration %} + +You can find out your Freebox host and port by opening +[this address](http://mafreebox.freebox.fr/api_version) in your browser. The +returned json should contain an api_domain (`host`) and a https_port (`port`). + +### {% linkable_title Initial setup %} + +The first time Home Assistant will connect to your Freebox, you will need to +authorize it by pressing the right button on the facade of the Freebox when +prompted to do so. + +### {% linkable_title Notes %} + +Note that the Freebox waits for some time before marking a device as +inactive, meaning that there will be a small delay (1 or 2 minutes) +between the time you disconnect a device and the time it will appear +as "away" in Home Assistant. You should take this into account when specifying +the `consider_home` parameter. +On the contrary, the Freebox immediately reports devices newly connected, so +they should appear as "home" almost instantly, as soon as Home Assistant +refreshes the devices states. + +See the [device tracker component page](/components/device_tracker/) for +instructions how to configure the devices to be tracked. + diff --git a/source/_components/device_tracker.fritz.markdown b/source/_components/device_tracker.fritz.markdown index 40d7bfa985d..ed813ae1c37 100644 --- a/source/_components/device_tracker.fritz.markdown +++ b/source/_components/device_tracker.fritz.markdown @@ -1,7 +1,7 @@ --- layout: page title: "FRITZ!Box" -description: "Instructions how to integrate AVM FRITZ!Box based routers into Home Assistant." +description: "Instructions on how to integrate AVM FRITZ!Box based routers into Home Assistant." date: 2015-12-13 19:00 sidebar: true comments: false @@ -15,9 +15,13 @@ ha_release: "0.10" The `fritz` platform offers presence detection by looking at connected devices to a [AVM Fritz!Box](http://avm.de/produkte/fritzbox/) based router. +## {% linkable_title Setup %} +
-It might be necessary to install additional packages: $ sudo apt-get install libxslt-dev libxml2-dev python3-lxml
-If you are working with the All-in-One installation, you may also need to execute also within your virtual environment the command pip install lxml; be patient this will take a while.
$ sudo apt-get install python3-lxml
+If you installed Home Assistant in a virtualenv, run the following commands inside it: $ sudo apt-get install libxslt-dev libxml2-dev zlib1g-dev; pip install lxml; be patient this will take a while.
+
+## {% linkable_title Configuration %}
To use an Fritz!Box router in your installation, add the following to your `configuration.yaml` file:
diff --git a/source/_components/device_tracker.geofency.markdown b/source/_components/device_tracker.geofency.markdown
index 320b59d4883..be09d277a1b 100644
--- a/source/_components/device_tracker.geofency.markdown
+++ b/source/_components/device_tracker.geofency.markdown
@@ -39,8 +39,8 @@ device_tracker:
To configure Geofency, you must configure (via the Webhook feature) to send a POST request to your Home Assistant server at `http://+Since this platform is using an unofficial API with the help of [locationsharinglib](https://github.com/costastf/locationsharinglib), Google seems to block access to your data the first time you've logged in with this platform. +This issue can be fixed by logging in with your new account and approving your login on the [Device Activity](https://myaccount.google.com/device-activity) page. +
+ +To integrate Google Maps Location Sharing in Home Assistant, add the following section to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +device_tracker: + - platform: google_maps + username: YOUR_USERNAME + password: YOUR_PASSWORD +``` + +{% configuration %} +username: + description: The email address for the Google account that has access to your shared location. + required: true + type: string +password: + description: The password for your given username. + required: true + type: string +{% endconfiguration %} diff --git a/source/_components/device_tracker.gpslogger.markdown b/source/_components/device_tracker.gpslogger.markdown index 6b6a439cdee..6d1b2d5446a 100644 --- a/source/_components/device_tracker.gpslogger.markdown +++ b/source/_components/device_tracker.gpslogger.markdown @@ -1,7 +1,7 @@ --- layout: page title: "GPSLogger" -description: "Instructions how to use GPSLogger to track devices in Home Assistant." +description: "Instructions on how to use GPSLogger to track devices in Home Assistant." date: 2016-11-25 15:00 sidebar: true comments: false @@ -19,7 +19,14 @@ To integrate GPSLogger in Home Assistant, add the following section to your `con # Example configuration.yaml entry device_tracker: - platform: gpslogger + password: !secret gpslogger_password ``` +{% configuration %} +password: + description: Separate password for GPS Logger endpoint. If provided using regular API password to contact endpoint will result in 401 response. + required: false + type: string +{% endconfiguration %} ## {% linkable_title Setup on your smartphone %} @@ -32,7 +39,7 @@ After the launch, go to **General Options**. Enable **Start on bootup** and **St GPSLogger Settings -Go to **Logging details** and disable **Log to GPX**. **Log to KML**, and **Log to NMEA**. Enable **Log to custom URL**. +Go to **Logging details** and disable **Log to GPX**, **Log to KML** and **Log to NMEA**. Enable **Log to custom URL**.
@@ -49,7 +56,7 @@ Right after enabling, the app will take you to the **Log to custom URL** setting
The relevant endpoint is: `/api/gpslogger`
```text
-http://[IP address Home Assistant]:[Port]/api/gpslogger?
+https://YOUR.DNS.HOSTNAME:PORT/api/gpslogger?
latitude=%LAT&longitude=%LON&device=%SER&accuracy=%ACC
&battery=%BATT&speed=%SPD&direction=%DIR
&altitude=%ALT&provider=%PROV&activity=%ACT
@@ -58,17 +65,17 @@ http://[IP address Home Assistant]:[Port]/api/gpslogger?
Add the above URL after you modified it with your settings into the **URL** field. Remove the line breaks as they are only there to make the URL readable here.
- It's HIGHLY recommended to use SSL/TLS.
-- Use the domain that Home Assistant is available on the internet or the public IP address. Can be a local IP address if you are using a VPN setup.
-- Only remove `[Port]` if your Home Assistant instance is using port 80. Otherwise set it to 8123.
-- Click on **Parameters** in the app and you will see all available parameters for the URL. For Home Assistant only the above URL will work.
-- Make sure to include your [API password](/components/http/) if you have configured a password. Add `&api_password=[Your pasword]` to the end of the URL.
-- You can change the name of your device name by replacing `&device=%SER` with `&device=[Devicename]`.
+- Use the domain that Home Assistant is available on the internet (or the public IP address if you have a static IP address). This can be a local IP address if you are using an always on VPN from your mobile device to your home network.
+- Only remove `PORT` if your Home Assistant instance is using port 443. Otherwise set it to the port you're using.
+- For Home Assistant only the above URL, as written, will work - do not add, remove, or change the order of any of the parameters.
+- Make sure to include your [API password](/components/http/) if you have configured a password. Add `&api_password=YOUR_PASSWORD` to the end of the URL.
+- You can change the name of your device name by replacing `&device=%SER` with `&device=DEVICE_NAME`.
-If your battery drains fast then you can tune the performence of GPSLogger under **Performance** -> **Location providers**
+If your battery drains fast then you can tune the performance of GPSLogger under **Performance** -> **Location providers**
Performance
-This may cause battery drainage as it wakes up your device to get the current location. +Low `max_interval` may cause battery drainage as it wakes up your device to get the current location.
@@ -48,7 +50,7 @@ To disable the drainage of the battery, a dynamic interval is being used for eac 2 Factor Authentication is the improved version of 2 Steps Authentication, this is still not supported by the pyicloud library. Therefore it's not possible to use it with the device_tracker yet. 4 services are available for this component: -- **icloud_update**: This service can be used to ask for an update of a certain iDevice. The `account_name` and `device_name` are optional. +- **icloud_update**: This service can be used to ask for an update of a certain iDevice. The `account_name` and `device_name` are optional. Request will result in new Home Assistant [state_changed](/docs/configuration/events/#event-state_changed) event describing current iphone location. Can be used in automations when manual location update is needed, e.g. to check if anyone is home when door's been opened. - **icloud_lost_iphone**: This service will play the Lost iPhone sound on a certain iDevice. The `account_name` and `device_name` are optional. -- **icloud_set_interval**: This service will change the dynamic interval of an iDevice. The `account_name` and `device_name` are optional. If `interval` is used in the service_data, the iDevice will be updated with that new interval. That interval will be fixed until the iDevice changes zone or if this service is called again. If `interval` isn't used in the service_data, the interval for that iDevice will revert back to it's default dynamic interval based on it's current zone, it's distance towards home and it's battery level. +- **icloud_set_interval**: This service will change the dynamic interval of an iDevice. The `account_name` and `device_name` are optional. If `interval` is used in the service_data, the iDevice will be updated with that new interval. That interval will be fixed until the iDevice changes zone or if this service is called again. If `interval` isn't used in the service_data, the interval for that iDevice will revert back to its default dynamic interval based on its current zone, its distance towards home and its battery level. - **icloud_reset_account**: This service can be used to reset an iCloud account. This is helpful when not all devices are being found by the component or if you have added a new iDevice to your account. The `account_name` is optional. diff --git a/source/_components/device_tracker.keenetic_ndms2.markdown b/source/_components/device_tracker.keenetic_ndms2.markdown index 3dbd197b771..aec5ac8a522 100644 --- a/source/_components/device_tracker.keenetic_ndms2.markdown +++ b/source/_components/device_tracker.keenetic_ndms2.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Keenetic NDMS2 Routers" -description: "Instructions how to integrate Keenetic NDMS2 Routers into Home Assistant." +description: "Instructions on how to integrate Keenetic NDMS2 Routers into Home Assistant." date: 2017-09-15 15:40 sidebar: true comments: false @@ -28,7 +28,7 @@ device_tracker: Configuration variables: -- **host** (*Required*): The IP address of your router, e.g. 192.168.1.1. +- **host** (*Required*): The IP address of your router, e.g., 192.168.1.1. - **username** (*Required*): The username to login into the router (user should have read access to web interface of the router). - **password** (*Required*): The password for the specified username. - **interface** (*Optional*): Ihe internal name of the interface to get devices connected to. Default is 'Home'. For expert users only. diff --git a/source/_components/device_tracker.linksys_ap.markdown b/source/_components/device_tracker.linksys_ap.markdown index b9821eb5227..6cdc3984b2e 100644 --- a/source/_components/device_tracker.linksys_ap.markdown +++ b/source/_components/device_tracker.linksys_ap.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Linksys Access Points" -description: "Instructions how to integrate Linksys Access Points into Home Assistant." +description: "Instructions on how to integrate Linksys Access Points into Home Assistant." date: 2016-12-16 01:40 sidebar: true comments: false diff --git a/source/_components/device_tracker.linksys_smart.markdown b/source/_components/device_tracker.linksys_smart.markdown index 0e1827c6806..0b9875e5f23 100644 --- a/source/_components/device_tracker.linksys_smart.markdown +++ b/source/_components/device_tracker.linksys_smart.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Linksys Smart Wifi Router" -description: "Instructions how to integrate Linksys Smart Wifi Router into Home Assistant." +description: "Instructions on how to integrate Linksys Smart Wifi Router into Home Assistant." date: 2017-06-22 01:40 sidebar: true comments: false @@ -12,12 +12,11 @@ logo: linksys.png ha_release: 0.48 --- -The `linksys_smart` platform offers presence detection by looking at connected devices to a Linksys Smart Wifi based router. +The `linksys_smart` platform offers presence detection by looking at connected devices to a Linksys Smart Wifi based router. -Tested routers: +Tested routers: LINKSYS WRT3200ACM MU-MIMO Gigabit Wi-Fi Wireless Router LINKSYS WRT1900ACS Dual-band Wi-Fi Router -
For this platform to work correctly, it is necessary to disable the "Access via wireless" feature in the Local Management Access section of the router administration page. If "Access via wireless" is not disabled, a connectivity conflict arises because the Home Assistant integration is trying to pass userid and password, but the router is only expecting a password. diff --git a/source/_components/device_tracker.locative.markdown b/source/_components/device_tracker.locative.markdown index 2a185c924e4..02d932a7a42 100644 --- a/source/_components/device_tracker.locative.markdown +++ b/source/_components/device_tracker.locative.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Locative" -description: "Instructions how to use Locative to track devices in Home Assistant." +description: "Instructions on how to use Locative to track devices in Home Assistant." date: 2015-10-13 19:00 sidebar: true comments: false diff --git a/source/_components/device_tracker.luci.markdown b/source/_components/device_tracker.luci.markdown index 937193752e5..c95813e3478 100644 --- a/source/_components/device_tracker.luci.markdown +++ b/source/_components/device_tracker.luci.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenWRT (luci)" -description: "Instructions how to integrate OpenWRT routers into Home Assistant." +description: "Instructions on how to integrate OpenWRT routers into Home Assistant." date: 2015-03-23 19:59 sidebar: true comments: false @@ -12,10 +12,14 @@ ha_category: Presence Detection ha_release: pre 0.7 --- -_This is one of the two ways we support OpenWRT. If you encounter problems, try [ubus](/components/device_tracker.ubus/)._ +_This is one of multiple ways we support OpenWRT. For an overview, see [openwrt](/components/device_tracker.openwrt/)._ This is a presence detection scanner for OpenWRT using [luci](http://wiki.openwrt.org/doc/techref/luci). +
+This component requires a [workaround](https://github.com/home-assistant/home-assistant/issues/1258#issuecomment-252469880) when using luci with HTTPS and a self-signed certificate. +
+ Before this scanner can be used you have to install the luci RPC package on OpenWRT: ```bash @@ -35,9 +39,10 @@ device_tracker: Configuration variables: -- **host** (*Required*): The IP address of your router, e.g. `192.168.1.1`. +- **host** (*Required*): The IP address of your router, e.g., `192.168.1.1`. - **username** (*Required*): The username of an user with administrative privileges, usually `admin`. - **password** (*Required*): The password for your given admin account. +- **ssl** (*Optional*): If your router enforces SSL connections, set to `true`. Defaults to `false`. See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. diff --git a/source/_components/device_tracker.markdown b/source/_components/device_tracker.markdown index 105dec1e7f3..41fd9b25a54 100644 --- a/source/_components/device_tracker.markdown +++ b/source/_components/device_tracker.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Device Tracker" -description: "Instructions how to setup device tracking within Home Assistant." +description: "Instructions on how to setup device tracking within Home Assistant." date: 2015-01-20 22:36 sidebar: true comments: false @@ -13,7 +13,7 @@ Home Assistant can get information from your wireless router or third party serv There are also trackers available which use different technologies like [MQTT](/components/mqtt/) or [Nmap](/components/device_tracker.nmap_tracker/) to scan the network for devices. -An [event](/getting-started/automation-trigger/#event-trigger) (`device_tracker_new_device`) will be fired when a device is discovered for the first time. +An [event](/getting-started/automation-trigger/#event-trigger) (`device_tracker_new_device`) will be fired when a device is discovered for the first time. ## {% linkable_title Configuring a `device_tracker` platform %} @@ -26,15 +26,23 @@ device_tracker: host: 192.168.1.1 username: admin password: YOUR_PASSWORD + new_device_defaults: + track_new_devices: True + hide_if_away: False + ``` The following optional parameters can be used with any platform. However device tracker will only look for global settings under the configuration of the first configured platform: | Parameter | Default | Description | -|---------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `track_new_devices` | True | If new discovered devices are tracked by default | -| `interval_seconds` | 12 | Seconds between each scan for new devices | -| `consider_home` | 180 | Seconds to wait till marking someone as not home after not being seen. This parameter is most useful for households with Apple iOS devices that go into sleep mode while still at home to conserve battery life. iPhones will occasionally drop off the network and then re-appear. `consider_home` helps prevent false alarms in presence detection when using IP scanners such as Nmap. `consider_home` accepts various time representations, (E.g. the following all represents 3 minutes: `180`, `0:03`, `0:03:00`) | +|----------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `interval_seconds` | 12 | Seconds between each scan for new devices | +| `consider_home` | 180 | Seconds to wait till marking someone as not home after not being seen. This parameter is most useful for households with Apple iOS devices that go into sleep mode while still at home to conserve battery life. iPhones will occasionally drop off the network and then re-appear. `consider_home` helps prevent false alarms in presence detection when using IP scanners such as Nmap. `consider_home` accepts various time representations, (e.g., the following all represents 3 minutes: `180`, `0:03`, `0:03:00`) | +| `new_device_defaults`| | Default values for new discovered devices. Available options `track_new_devices` (default: `True`), `hide_if_away` (default: `False`) | + ++ Note that setting `track_new_devices: False` will still result in new devices being recorded in `known_devices.yaml`, but they won't be tracked (`track: no`). +
The extended example from above would look like the following sample: @@ -61,11 +69,15 @@ Here's an example configuration for a single device: devicename: name: Friendly Name mac: EA:AA:55:E7:C6:94 - picture: https://home-assistant.io/images/favicon-192x192.png + picture: https://www.home-assistant.io/images/favicon-192x192.png track: yes hide_if_away: no ``` ++ In the example above, `devicename` refers to the detected name of the device. For instance, `my_iphone`. +
+ | Parameter | Default | Description | |----------------|-------------------------------|---------------------------------------------------------------------------------------------------------| | `name` | Host name or "Unnamed Device" | The friendly name of the device. | @@ -76,3 +88,7 @@ devicename: | `track` | [uses platform setting] | If `yes`/`on`/`true` then the device will be tracked. Otherwise its location and state will not update. | | `hide_if_away` | False | If `yes`/`on`/`true` then the device will be hidden if it is not at home. | | `consider_home` | [uses platform setting] | Seconds to wait till marking someone as not home after not being seen. Allows you to override the global `consider_home` setting from the platform configuration on a per device level. | + +## {% linkable_title Device states %} + +The state of your tracked device will be `'home'` if it is in the [home zone](/components/zone#home-zone), detected by your network or Bluetooth based presence detection. If you're using a presence detection method that includes coordinates then when it's in a zone the state will be the name of the zone (in lower case). When a device isn't at home and isn't in any zone, the state will be `'not_home'`. diff --git a/source/_components/device_tracker.meraki.markdown b/source/_components/device_tracker.meraki.markdown new file mode 100644 index 00000000000..cbe481d39ee --- /dev/null +++ b/source/_components/device_tracker.meraki.markdown @@ -0,0 +1,49 @@ +--- +layout: page +title: "Meraki" +description: "Instructions on how to integrate Meraki-based presence detection into Home Assistant." +date: 2017-11-22 08:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: meraki.png +ha_category: Presence Detection +ha_release: "0.60" +--- + +Use your Meraki AP as device tracker. Note that Meraki will see all devices, not only connected to the network. + +### {% linkable_title Prerequisites %} + +1. Go to Network-wide/General page, and find the Location and scanning section. +1. Make sure analytics and Scanning API are both enabled. +1. Make note of the Validator string, which will be used in the `device_tracker` configuration. +1. Click **Add a Post URL**: + 1. Set the Post URL to `https://YOUR_HOSTNAME/api/meraki?api_password=YOUR_HASS_PASSWORD` + 1. Set the Secret to a randomly generated string, and make note of it for the `device_tracker` configuration. + 1. Make sure the API Version is set to `2.0`. + 1. Hit **Save** in the bottom right of the page. + +## {% linkable_title Configuration %} + +After you configure access to the Meraki CMX API, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +device_tracker: + - platform: meraki + secret: your_secret + validator: meraki_validator +``` + +{% configuration %} + secret: + description: Secret code added in Meraki. + required: true + type: string + validator: + description: Validation string from Meraki. + required: true + type: string +{% endconfiguration %} diff --git a/source/_components/device_tracker.mercedesme.markdown b/source/_components/device_tracker.mercedesme.markdown new file mode 100644 index 00000000000..ad59c95e0d5 --- /dev/null +++ b/source/_components/device_tracker.mercedesme.markdown @@ -0,0 +1,19 @@ +--- +layout: page +title: "Mercedes me" +description: "Instructions on for how to integrate Mercedes me into Home Assistant." +date: 2018-01-27 10:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mercedesme.png +ha_category: Presence Detection +ha_release: 0.63 +--- + +The `Mercedes me` platform allows you to get data about the location of your [Mercedes me connected car](https://www.mercedes-benz.com/en/mercedes-me/) car within Home Assistant. + +The device tracker platform will be automatically configured if Mercedes me component is configured. + +For more configuration information see the [Mercedes me component](/components/mercedesme/) documentation. diff --git a/source/_components/device_tracker.mikrotik.markdown b/source/_components/device_tracker.mikrotik.markdown index e3e49c48469..da1dceee4d9 100644 --- a/source/_components/device_tracker.mikrotik.markdown +++ b/source/_components/device_tracker.mikrotik.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Mikrotik" -description: "Instructions how to integrate Mikrotik/Routerboard based routers into Home Assistant." +description: "Instructions on how to integrate Mikrotik/Routerboard based routers into Home Assistant." date: 2017-04-28 16:03 sidebar: true comments: false diff --git a/source/_components/device_tracker.mqtt.markdown b/source/_components/device_tracker.mqtt.markdown index d60b895c50e..cf8f006de1f 100644 --- a/source/_components/device_tracker.mqtt.markdown +++ b/source/_components/device_tracker.mqtt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MQTT Device Tracker" -description: "Instructions how to use MQTT to track devices in Home Assistant." +description: "Instructions on how to use MQTT to track devices in Home Assistant." date: 2015-09-19 20:41 sidebar: true comments: false @@ -32,11 +32,11 @@ Configuration variables: - **qos** (*Optional*): The QoS level of the topic. -Example JSON you can publish to the topic (e.g. via mqtt.publish service): +Example JSON you can publish to the topic (e.g., via mqtt.publish service): ```json { - "topic": "/location/paulus", + "topic": "location/paulus", "payload": "home" } ``` diff --git a/source/_components/device_tracker.mqtt_json.markdown b/source/_components/device_tracker.mqtt_json.markdown index d7a515588c9..cc0e4783ec3 100644 --- a/source/_components/device_tracker.mqtt_json.markdown +++ b/source/_components/device_tracker.mqtt_json.markdown @@ -1,7 +1,7 @@ --- layout: page title: "JSON MQTT Device Tracker" -description: "Instructions how to use JSON MQTT to track devices in Home Assistant." +description: "Instructions on how to use JSON MQTT to track devices in Home Assistant." date: 2017-04-12 20:41 sidebar: true comments: false @@ -9,11 +9,10 @@ sharing: true footer: true logo: mqtt.png ha_category: Presence Detection -ha_version: 0.44 ha_iot_class: depends +ha_release: 0.44 --- - The `mqtt_json` device tracker platform allows you to detect presence by monitoring an MQTT topic for new locations. To use this platform, you specify a unique topic for each device. To use this device tracker in your installation, add the following to your `configuration.yaml` file: @@ -27,10 +26,16 @@ device_tracker: annetherese_n4: location/annetherese ``` -Configuration variables: - -- **devices** (*Required*): List of devices with their topic. -- **qos** (*Optional*): The QoS level of the topic. +{% configuration %} +devices: + description: List of devices with their topic. + required: true + type: list +qos: + description: The QoS level of the topic. + required: false + type: string +{% endconfiguration %} This platform receives JSON formatted payloads containing GPS information, for example: diff --git a/source/_components/device_tracker.mysensors.markdown b/source/_components/device_tracker.mysensors.markdown index 14db68931ad..5366c68ea78 100644 --- a/source/_components/device_tracker.mysensors.markdown +++ b/source/_components/device_tracker.mysensors.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MySensors Device Tracker" -description: "Instructions how to use MySensors to track devices in Home Assistant." +description: "Instructions on how to use MySensors to track devices in Home Assistant." date: 2017-02-06 15:00 +0100 sidebar: true comments: false diff --git a/source/_components/device_tracker.netgear.markdown b/source/_components/device_tracker.netgear.markdown index 70dbbce1025..8bdcacc8cde 100644 --- a/source/_components/device_tracker.netgear.markdown +++ b/source/_components/device_tracker.netgear.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Netgear" -description: "Instructions how to integrate Netgear routers into Home Assistant." +description: "Instructions on how to integrate Netgear routers into Home Assistant." date: 2015-03-23 19:59 sidebar: true comments: false @@ -13,7 +13,6 @@ ha_iot_class: "Local Polling" ha_release: pre 0.7 --- - This platform allows you to detect presence by looking at connected devices to a [Netgear](http://www.netgear.com/) device. To use this device tracker in your installation, add the following to your `configuration.yaml` file: @@ -29,10 +28,18 @@ device_tracker: Configuration variables: -- **host** (*Optional*): The IP address of your router, e.g. `192.168.1.1`. If not provided `routerlogin.net` will be used. -- **username** (*Optional*): The username of an user with administrative privileges. If not provided `admin` will be used. -- **port** (*Optional*): The port your router communicates with (defaults to `5000`, but `80` is also known to be used on some models). +- **url** (*Optional*): The base URL, e.g., `http://routerlogin.com:5000` for example. If not provided `host` and `port` are used. If none provided autodetection of the URL will be used. +- **host** (*Optional*): The IP address of your router, e.g., `192.168.1.1`. +- **port** (*Optional*): The port your router communicates with. +- **username** (*Optional*): The username of a user with administrative privileges. If not provided `admin` will be used. - **password** (*Required*): The password for your given admin account. +- **devices** (*Optional*): If provided only specified devices will be reported. Can be MAC address or the device name as reported in the Netgear UI. +- **exclude** (*Optional*): Devices to exclude from the scan. +- **accesspoints** (*Optional*): Also track devices on the specified APs. Only supports MAC address. + +When `accesspoints` is specified an extra device will be reported for each device connected to the APs specified here, as `MY-LAPTOP on RBS40`. `Router` will be reported as AP name for the main AP. Only tested with Orbi. + +The use of `devices` or `exclude` is recommended when using `accesspoints` to avoid having a lot of entries. List of models that are known to use port 80: - Nighthawk X4S - AC2600 (R7800) diff --git a/source/_components/device_tracker.nmap_tracker.markdown b/source/_components/device_tracker.nmap_tracker.markdown index 0ce79dfc3a9..74ace37e238 100644 --- a/source/_components/device_tracker.nmap_tracker.markdown +++ b/source/_components/device_tracker.nmap_tracker.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Nmap" -description: "Instructions how to integrate Nmap into Home Assistant." +description: "Instructions on how to integrate Nmap into Home Assistant." date: 2015-03-23 19:59 sidebar: true comments: false diff --git a/source/_components/device_tracker.openwrt.markdown b/source/_components/device_tracker.openwrt.markdown new file mode 100644 index 00000000000..2f4b0f5a18e --- /dev/null +++ b/source/_components/device_tracker.openwrt.markdown @@ -0,0 +1,48 @@ +--- +layout: page +title: "OpenWRT" +description: "Instructions on how to integrate OpenWRT routers into Home Assistant." +date: 2018-03-09 12:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: openwrt.png +ha_category: Presence Detection +ha_release: pre 0.7 +--- + +There are _multiple_ ways of integrating an OpenWRT router for presence detection. A broad distinction can be made between presence detection methods which actively scan for devices (by default every 12 seconds) and those that are notified by some external service on changes. It is essentially a problem of synchronizing states between two remote machines. + +* __active scanning__ + Scan for devices regularly. + * Advantages: + * robust on an unreliable set-up where the the router may not be reachable occasionally + * Disadvantages: + * average six-second delay between connecting and being registered as `home` + * lots of unnecessary network requests + * Examples: + * [ubus](/components/device_tracker.ubus/) + * [luci](/components/device_tracker.luci/) +* __passive/event-based__ + External services which notify Home Assistant of devices via the [REST API endpoint](/developers/rest_api.markdown). + * Advantages: + * devices typically registered in under one second when they connect + * very few network requests + * Disadvantages: + * prone to missed events when connectivity between Home Assistant and the router is not guaranteed + * Examples: + * [openwrt_hass_devicetracker](https://github.com/mueslo/openwrt_hass_devicetracker) + * your own custom script + +### {% linkable_title Event-based device tracker %} + +This can be achieved by running a simple shell script on the OpenWRT router which calls the appropriate Home Assistant service. An OpenWRT package which does this is listed above. As this method directly calls the [service API](/developers/rest_api.markdown#post-apiservicesltdomainltservice), no special configuration is necessary on the Home Assistant side, except for ensuring the device_tracker API is running, which is achieved by adding the following to your `configuration.yaml` file: + +```yaml +device_tracker: +``` + +To get the best of both worlds, you can combine the two approaches, running both a periodic device scanner and an event-based device tracker. + +See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. diff --git a/source/_components/device_tracker.owntracks.markdown b/source/_components/device_tracker.owntracks.markdown index 20cf68ab97a..a3de574f912 100644 --- a/source/_components/device_tracker.owntracks.markdown +++ b/source/_components/device_tracker.owntracks.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Owntracks" -description: "Instructions how to use Owntracks to track devices in Home Assistant." +description: "Instructions on how to use Owntracks to track devices in Home Assistant." date: 2015-09-22 07:00 sidebar: true comments: false @@ -13,8 +13,7 @@ featured: false ha_release: 0.7.4 --- - -This platform allows you to detect presence using [Owntracks](http://owntracks.org/). OwnTracks allows users to track their location on Android and iOS phones and publish it to an MQTT broker. This platform will connect to the broker and monitor for new locations. +This platform allows you to detect presence using [Owntracks](http://owntracks.org/). OwnTracks allows users to track their location on iOS and Android phones and publish it to an MQTT broker. This platform will connect to the broker and monitor for new locations. This component requires [the MQTT component](/components/mqtt/) to be set up and works very well together with [the zone component](/components/zone/). @@ -30,8 +29,11 @@ Configuration variables: - **max_gps_accuracy** (*Optional*): Sometimes Owntracks can report GPS location with a very low accuracy (few kilometers). That can trigger false zoning in your Home Assistant installation. With the parameter, you can filter these GPS reports. The number has to be in meter. For example, if you put 200 only GPS report with an accuracy under 200 will be take in account. - **waypoints** (*Optional*): Owntracks users can define [waypoints](http://owntracks.org/booklet/features/waypoints/) (a.k.a regions) which are similar in spirit to Home Assistant zones. If this configuration variable is `True`, the Owntracks users who are in `waypoint_whitelist` can export waypoints from the device and Home Assistant will import them as zone definitions. Defaults to `True`. -- **waypoint_whitelist** (*Optional*): A list of user names (as defined for [Owntracks](/components/device_tracker.owntracks/)) who can export their waypoints from Owntracks to Home Assistant. This would be the `username` portion of the Base Topic Name, (e.g. owntracks/**username**/iPhone). Defaults to all users who are connected to Home Assistant via Owntracks. +- **waypoint_whitelist** (*Optional*): A list of user names (as defined for [Owntracks](/components/device_tracker.owntracks/)) who can export their waypoints from Owntracks to Home Assistant. This would be the `username` portion of the Base Topic Name, (e.g., owntracks/**username**/iPhone). Defaults to all users who are connected to Home Assistant via Owntracks. - **secret** (*Optional*): [Payload encryption key](http://owntracks.org/booklet/features/encrypt/). This is usable when communicating with a third-party untrusted server or a public server (where anybody can subscribe to any topic). By default the payload is assumed to be unencrypted (although the communication between Home Assistant and the server might still be encrypted). This feature requires the `libsodium` library to be present. +- **mqtt_topic** (*Optional*): The topic to subscribe for Owntracks updates on your MQTT instance (defaults to `owntracks/#`). +- **events_only** (*Optional*): Home Assistant will ignore all location updates and rely solely on geofence enter/leave events. +- **region_mapping** (*Optional*): Dictionary to remap names of regions as configured in the Owntracks app to Home Assistant zones. Use this if you have multiple homes or Home Assistant instances and want to map a different label to 'home'. `key: value` maps Owntracks region `key` to Home Assistant zone `value`. A full sample configuration for the `owntracks` platform is shown below: @@ -41,12 +43,18 @@ device_tracker: - platform: owntracks max_gps_accuracy: 200 waypoints: True + mqtt_topic: "owntracks/#" + events_only: True waypoint_whitelist: - jon - ram + region_mapping: + cabin: home + office: work ``` ### {% linkable_title Using Owntracks with other device trackers %} + Owntracks can also be used with other device trackers, such as [Nmap](/components/device_tracker.nmap_tracker/) or [Netgear](/components/device_tracker.netgear/). To do this, fill in the `mac` field to the Owntracks entry in `known_devices.yaml` with the MAC address of the device you want to track. This way the state of the device will be determined by the source that reported last. The naming convention for known device list is `TP-Link devices typically only allow one login at a time to the admin console. This component will count towards your one allowed login. Depending on how aggressively you configure device_tracker you may not be able to access the admin console of your TP-Link device without first stopping Home Assistant. Home Assistant takes a few seconds to login, collect data, and log out. If you log into the admin console manually, remember to log out so that Home Assistant can log in again. @@ -31,8 +38,8 @@ device_tracker: Configuration variables: -- **host** (*Required*): The IP address of your router, e.g. 192.168.1.1. -- **username** (*Required*: The username of an user with administrative privileges, usually *admin*. +- **host** (*Required*): The IP address of your router, e.g., 192.168.1.1. +- **username** (*Required*): The username of a user with administrative privileges, usually *admin*. The Archer D9 last firmware does not require a username. - **password** (*Required*): The password for your given admin account. For Archer C9 models running firmware version 150811 or later please use the encrypted password you can retrieve like this: @@ -41,7 +48,12 @@ For Archer C9 models running firmware version 150811 or later please use the enc 2. Type in the password you use to login into the password field. 3. Click somewhere else on the page so that the password field is not selected anymore. 4. Open the JavaScript console of your browser (usually by pressing F12 and then clicking on "Console"). -5. Type ```document.getElementById("login-password").value;```. +5. Type `document.getElementById("login-password").value;` or `document.getElementById("pcPassword").value;`, depending on your firmware version. 6. Copy the returned value to your Home Assistant configuration as password. See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. + +For Archer D9 model the default ip is 192.168.1.1, the username is not necessary and you can leave that field blank. + + + diff --git a/source/_components/device_tracker.trackr.markdown b/source/_components/device_tracker.trackr.markdown index 6337b8f7870..962300ed1ea 100644 --- a/source/_components/device_tracker.trackr.markdown +++ b/source/_components/device_tracker.trackr.markdown @@ -1,7 +1,7 @@ --- layout: page title: "TrackR" -description: "Instructions how to use TrackR to track devices in Home Assistant." +description: "Instructions on how to use TrackR to track devices in Home Assistant." date: 2016-12-22 1000 sidebar: true comments: false @@ -24,11 +24,18 @@ To integrate TrackR in Home Assistant, add the following section to your `config # Example configuration.yaml entry device_tracker: platform: trackr - username: USERNAME - password: PASSWORD + username: YOUR_USERNAME + password: YOUR_PASSWORD ``` -Configuration variables: +{% configuration %} +username: + description: The email address for the TrackR account. + required: true + type: string +password: + description: The password for your given username. + required: true + type: string +{% endconfiguration %} -- **username** (*Required*): The email address for the TrackR account. -- **password** (*Required*): The password for your given username. diff --git a/source/_components/device_tracker.ubus.markdown b/source/_components/device_tracker.ubus.markdown index d408fec5448..ba38f2f1b64 100644 --- a/source/_components/device_tracker.ubus.markdown +++ b/source/_components/device_tracker.ubus.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenWRT (ubus)" -description: "Instructions how to integrate OpenWRT routers into Home Assistant." +description: "Instructions on how to integrate OpenWRT routers into Home Assistant." date: 2015-03-23 19:59 sidebar: true comments: false @@ -12,7 +12,7 @@ ha_category: Presence Detection ha_release: 0.7.6 --- -_This is one of the two ways we support OpenWRT. If you encounter problems, try [luci](/components/device_tracker.luci/)._ +_This is one of multiple ways we support OpenWRT. For an overview, see [openwrt](/components/device_tracker.openwrt/)._ This is a presence detection scanner for [OpenWRT](https://openwrt.org/) using [ubus](http://wiki.openwrt.org/doc/techref/ubus). It scans for changes in `hostapd.*`, which will detect and report changes in devices connected to the access point on the router. @@ -68,16 +68,15 @@ Configuration variables: - **host** (*Required*): The IP address of your router, eg. 192.168.1.1. - **username** (*Required*): The username of an user with administrative privileges, usually *root*. - **password** (*Required*): The password for your given account. -- **dhcp_software** (*Optional*): The DHCP software used in your router: `dnsmasq` or `dhcpd`. Defaults to `dnsmasq`. - +- **dhcp_software** (*Optional*): The DHCP software used in your router: `dnsmasq`, `dhcpd`, or `none`. Defaults to `dnsmasq`. See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. -## Troubleshooting +## {% linkable_title Troubleshooting %} If you find that this never creates `known_devices.yaml`, or if you need more information on the communication chain between Home Assistant and OpenWRT, follow these steps to grab the packet stream and gain insight into what's happening. -### Increase Log Level +### {% linkable_title Increase Log Level %} 1. On your Home Assistant device, stop Home Assistant 2. Adjust `configuration.yaml` to log more detail for the `device_tracker` component @@ -167,6 +166,6 @@ Connection: keep-alive ``` 11. In this case we are actually receiving a valid response with no data. The request says that we are looking for ARP information from `hostapd.*`, which is the access point on the router. In my environment I don't use the AP on the router, and so it was correctly returning no data. Armed with this information, I know that I cannot use this component for device tracking or presence. -### Cleanup +### {% linkable_title Cleanup %} When you're done troubleshooting, remember to reset your logging configuration and delete any capture files that contain sensitive information. diff --git a/source/_components/device_tracker.unifi.markdown b/source/_components/device_tracker.unifi.markdown index 004d92679d7..e9410667707 100644 --- a/source/_components/device_tracker.unifi.markdown +++ b/source/_components/device_tracker.unifi.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Ubiquiti Unifi WAP" -description: "Instructions how to use a Unifi WAP controller as a device tracker module." +description: "Instructions on how to use a Unifi WAP controller as a device tracker module." date: 2016-02-19 20:59 sidebar: true comments: false @@ -12,7 +12,6 @@ ha_category: Presence Detection ha_release: 0.14 --- - This platform allows you to detect presence by looking at devices connected to a [Ubiquiti](http://ubnt.com/) [Unifi](https://www.ubnt.com/enterprise/#unifi) controller. To use this device tracker in your installation, add the following to your `configuration.yaml` file: @@ -21,24 +20,72 @@ To use this device tracker in your installation, add the following to your `conf # Example configuration.yaml entry device_tracker: - platform: unifi - username: YOUR_ADMIN_USERNAME - password: YOUR_ADMIN_PASSWORD + host: unifi + username: username + password: password + ssid_filter: + - 'HomeSSID' + - 'IoTSSID' ``` -Configuration variables: +{% configuration %} +username: + description: A user on the controller + type: string + required: true +password: + description: The password for the account + type: string + required: true +host: + description: The hostname or IP address of your controller + default: localhost + type: string + required: false +port: + description: The port of your controller's web interface + default: 8443 + type: int + required: false +site_id: + description: For multisite installations, you can specify `site_id` to specify which is used + type: string + required: false + default: default +verify_ssl: + description: Whether to do strict validation on SSL certificates of the Unifi controller. This can be true/false or the path to a locally trusted certificate to use for verification (i.e. "/path/to/custom_cert.pm") + type: boolean or filename + required: false + default: true +detection_time: + description: How long since the last seen time before the device is marked away, specified in seconds. + type: int + required: false + default: 300 +ssid_filter: + description: Filter the SSIDs that tracking will occur on. + type: list of strings + required: false + default: None -- **host** (*Optional*): The hostname or IP address of your controller. Defaults to `localhost`. -- **port** (*Optional*): The port of your controller's web interface. Defaults to `8443`. -- **username** (*Required*: The username of an user with administrative privileges, usually `admin`. -- **password** (*Required*): The password for your given admin account. -- **site_id** (*Optional*): Allows you to specify a `site_id` for device tracking. Defaults to `default`. Found in the URL of the controller (i.e. https://CONTROLLER:PORT/manage/site/SITE_ID/dashboard). -- **verify_ssl** (*Optional*): Controls if the SSL certificate running on your Unifi webserver must be trusted by a known Certificate Authority on the server running Home Assistant. Defaults to 'True' but can also be a value that points to your custom cert "path/to/custom_cert.pem". -- **detection_time** (*Optional*): The Unifi component will not return a device that has not been seen by the controller in the last 180 seconds. You can adjust this threshold with this variable and accepts seconds or `00:00:00` time formats. +{% endconfiguration %} See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. -
-If you decide to install the Unifi Controller on the same system as your Home Assistant, be aware there may be overlap in ports if you have the MQTT component as well. +### {% linkable_title Configuring Users %} + +The Unifi controller allows you to create multiple users on it besides the main administrator. It is recommended that you create a limited user that has `read-only` permissions for the Unifi device tracker. + +### {% linkable_title Conflicts with MQTT %} + +The Unifi controller can either be a dedicated hardware device (Unifi's cloud key), or as software any Linux system. If you run the the Unifi controller on the same operating system as Home Assistant there may be conflicts in ports if you have the MQTT component as well. + +It is recommended that you run the Unifi controller in a dedicated virtual machine to avoid that situation. + +### {% linkable_title Troubleshooting and Time Synchronization %} + +Presence detection depends on accurate time configuration between Home Assistant and the Unifi controller. + +If Home Assistant and the Unifi controller are running on separate machines or VMs ensure that all clocks are syncronized. Failing to have syncronized clocks will lead to Home Assistant failing to mark a device as home. [Related Issue](https://github.com/home-assistant/home-assistant/issues/10507) -
diff --git a/source/_components/device_tracker.unifi_direct.markdown b/source/_components/device_tracker.unifi_direct.markdown index 24124d3cbc2..4816832b8e1 100644 --- a/source/_components/device_tracker.unifi_direct.markdown +++ b/source/_components/device_tracker.unifi_direct.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Ubiquiti Unifi direct AP" -description: "Instructions how to use a Unifi WAP as a device tracker." +description: "Instructions on how to use a Unifi WAP as a device tracker." date: 2017-11-17 14:59 sidebar: true comments: false @@ -13,7 +13,7 @@ ha_release: 0.59 --- -This platform allows you to detect presence by looking at devices connected to a [UniFi AP](http://ubnt.com/unifi-ap/). This device tracker differs form [Ubiquiti Unifi WAP](https://home-assistant.io/components/device_tracker.unifi/) because it doesn't require the Unifi controller software. +This platform allows you to detect presence by looking at devices connected to a [UniFi AP](https://www.ubnt.com/products/#unifi). This device tracker differs form [Ubiquiti Unifi WAP](/components/device_tracker.unifi/) because it doesn't require the Unifi controller software. To use this device tracker in your installation, add the following to your `configuration.yaml` file: @@ -32,11 +32,11 @@ host: required: true type: string username: - description: The username used to connect to your Unifi AP. + description: The SSH device username used to connect to your Unifi AP. required: true type: string password: - description: The password used to connect to your Unifi AP. + description: The SSH device password used to connect to your Unifi AP. required: true type: string {% endconfiguration %} diff --git a/source/_components/device_tracker.upc_connect.markdown b/source/_components/device_tracker.upc_connect.markdown index d58a1878e93..1f77bc8d869 100644 --- a/source/_components/device_tracker.upc_connect.markdown +++ b/source/_components/device_tracker.upc_connect.markdown @@ -1,7 +1,7 @@ --- layout: page title: "UPC ConnectBox" -description: "Instructions how to integrate UPC ConnectBox into Home Assistant." +description: "Instructions on how to integrate UPC ConnectBox into Home Assistant." date: 2016-12-30 00:00 sidebar: true comments: false @@ -32,4 +32,5 @@ See the [device tracker component page](/components/device_tracker/) for instruc Also known to be working with the following devices: - Irish Virgin Media Super Hub 3.0 - Ziggo Connectbox NL + - Unitymedia Connect Box (DE) diff --git a/source/_components/device_tracker.xiaomi.markdown b/source/_components/device_tracker.xiaomi.markdown index 9a8f6a43fd1..d38571007cb 100644 --- a/source/_components/device_tracker.xiaomi.markdown +++ b/source/_components/device_tracker.xiaomi.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Xiaomi Router" -description: "Instructions how to integrate Xiaomi routers into Home Assistant." +description: "Instructions on how to integrate Xiaomi routers into Home Assistant." date: 2017-01-12 12:04 sidebar: true comments: false diff --git a/source/_components/device_tracker.xiaomi_miio.markdown b/source/_components/device_tracker.xiaomi_miio.markdown new file mode 100644 index 00000000000..54f4cf9d5de --- /dev/null +++ b/source/_components/device_tracker.xiaomi_miio.markdown @@ -0,0 +1,38 @@ +--- +layout: page +title: "Xiaomi Mi WiFi Repeater 2" +description: "Instructions how to integrate your Xiaomi Mi WiFi Repeater 2 within Home Assistant." +date: 2018-04-01 21:06 +sidebar: true +comments: false +sharing: true +footer: true +logo: xiaomi.png +ha_category: Presence Detection +ha_iot_class: "Local Polling" +ha_release: 0.67 +--- + +The `xiaomi_miio` device tracker platform is observing your Xiaomi Mi WiFi Repeater 2 and reporting all associated WiFi clients. + +Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi_miio/#retrieving-the-access-token) to get the API token. + +To add a Xiaomi Mi Air Quality Monitor to your installation, add the following to your `configuration.yaml` file: + +```yaml +device_tracker: + - platform: xiaomi_miio + host: 192.168.130.73 + token: YOUR_TOKEN +``` + +{% configuration %} +host: + description: The IP address of your miio device. + required: true + type: string +token: + description: The API token of your miio device. + required: true + type: string +{% endconfiguration %} diff --git a/source/_components/dialogflow.markdown b/source/_components/dialogflow.markdown index a034f72e28c..bf2cc4b4e61 100644 --- a/source/_components/dialogflow.markdown +++ b/source/_components/dialogflow.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Dialogflow" -description: "Instructions how integrate Dialogflow with Home Assistant." +description: "Instructions on how integrate Dialogflow with Home Assistant." date: 2017-01-27 11:28 sidebar: true comments: false @@ -47,10 +47,10 @@ To use this integration, you should define a conversation (intent) in Dialogflow - Select name, language (if you are planning to use Google Actions check their [supported languages](https://support.google.com/assistant/answer/7108196?hl=en)) and time zone - Click "Save" - Go to "Fulfillment" (in the left menu) -- Enable Webhook and set your Home Assistant URL with the Dialogflow endpoint, e.g. `https://myhome.duckdns.org/api/dialogflow?api_password=HA_PASSWORD` +- Enable Webhook and set your Home Assistant URL with the Dialogflow endpoint, e.g., `https://myhome.duckdns.org/api/dialogflow?api_password=HA_PASSWORD` - Click "Save" - Create a new intent -- Below "User says" write one phrase that you, the user, will tell Dialogflow, e.g. `What is the temperature at home?` +- Below "User says" write one phrase that you, the user, will tell Dialogflow, e.g., `What is the temperature at home?` - In "Action" set some key (this will be the bind with Home Assistant configuration), eg.: GetTemperature - In "Response" set "Cannot connect to Home Assistant or it is taking to long" (fall back response) - At the end of the page, click on "Fulfillment" and check "Use webhook" diff --git a/source/_components/digital_ocean.markdown b/source/_components/digital_ocean.markdown index c2e26b9aa3b..4554819ee2a 100644 --- a/source/_components/digital_ocean.markdown +++ b/source/_components/digital_ocean.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Digital Ocean" -description: "Instructions how to integrate the Digital Ocean within Home Assistant." +description: "Instructions on how to integrate the Digital Ocean within Home Assistant." date: 2016-09-24 20:00 sidebar: true comments: false diff --git a/source/_components/discoverable.markdown b/source/_components/discoverable.markdown index 19c16ce0ac3..12c170a1eee 100644 --- a/source/_components/discoverable.markdown +++ b/source/_components/discoverable.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Discoverable" -description: "Instructions how to setup the discoverable component with Home Assistant." +description: "Instructions on how to setup the discoverable component with Home Assistant." date: 2016-03-01 07:00 sidebar: true comments: false @@ -23,7 +23,7 @@ for state in hass.states(): To enable `discovery` in your installation, add the following to your `configuration.yaml` file: ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry discoverable: expose_password: yes ``` diff --git a/source/_components/discovery.markdown b/source/_components/discovery.markdown index 62f9c0c1b34..e148bfdac29 100644 --- a/source/_components/discovery.markdown +++ b/source/_components/discovery.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Discovery" -description: "Instructions how to setup Home Assistant to discover new devices." +description: "Instructions on how to setup Home Assistant to discover new devices." date: 2015-01-24 14:39 sidebar: true comments: false @@ -14,29 +14,34 @@ ha_category: Other Home Assistant can discover and automatically configure [zeroconf](https://en.wikipedia.org/wiki/Zero-configuration_networking)/[mDNS](https://en.wikipedia.org/wiki/Multicast_DNS) and [uPnP](https://en.wikipedia.org/wiki/Universal_Plug_and_Play) devices on your network. Currently the `discovery` component can detect: - * [Apple TV](https://home-assistant.io/components/apple_tv/) - * [Axis Communications security devices](https://home-assistant.io/components/axis/) - * [Belkin WeMo switches](https://home-assistant.io/components/wemo/) - * [Bluesound speakers](https://home-assistant.io/components/media_player.bluesound/) - * [Bose Soundtouch speakers](https://home-assistant.io/components/media_player.soundtouch/) - * [Denon network receivers](https://home-assistant.io/components/media_player.denonavr/) - * [DirecTV receivers](https://home-assistant.io/components/media_player.directv/) - * [Frontier Silicon internet radios](https://home-assistant.io/components/media_player.frontier_silicon/) - * [Google Cast](https://home-assistant.io/components/media_player.cast/) - * [IKEA Trådfri (Tradfri)](https://home-assistant.io/components/tradfri/) - * [Linn / Openhome](https://home-assistant.io/components/media_player.openhome/) - * [Logitech Harmony Hub](https://home-assistant.io/components/remote.harmony/) - * [Logitech media server (Squeezebox)](https://home-assistant.io/components/media_player.squeezebox/) - * [Netgear routers](https://home-assistant.io/components/device_tracker.netgear/) - * [Panasonic Viera](https://home-assistant.io/components/media_player.panasonic_viera/) - * [Philips Hue](https://home-assistant.io/components/light.hue/) - * [Plex media server](https://home-assistant.io/components/media_player.plex/) - * [Roku media player](https://home-assistant.io/components/media_player.roku/) - * [SABnzbd downloader](https://home-assistant.io/components/sensor.sabnzbd/) - * [Samsung TVs](https://home-assistant.io/components/media_player.samsungtv/) - * [Sonos speakers](https://home-assistant.io/components/media_player.sonos/) - * [Yamaha media player](https://home-assistant.io/components/media_player.yamaha/) - * [Yeelight Sunflower bulb](https://home-assistant.io/components/light.yeelightsunflower/) + * [Apple TV](/components/apple_tv/) + * [Axis Communications security devices](/components/axis/) + * [Belkin WeMo switches](/components/wemo/) + * [Bluesound speakers](/components/media_player.bluesound/) + * [Bose Soundtouch speakers](/components/media_player.soundtouch/) + * [Denon network receivers](/components/media_player.denonavr/) + * [DirecTV receivers](/components/media_player.directv/) + * [Frontier Silicon internet radios](/components/media_player.frontier_silicon/) + * [Google Cast](/components/media_player.cast/) + * [HomeKit](/components/homekit_controller/) + * [IKEA Trådfri (Tradfri)](/components/tradfri/) + * [Linn / Openhome](/components/media_player.openhome/) + * [Logitech Harmony Hub](/components/remote.harmony/) + * [Logitech media server (Squeezebox)](/components/media_player.squeezebox/) + * [Netgear routers](/components/device_tracker.netgear/) + * [Panasonic Viera](/components/media_player.panasonic_viera/) + * [Philips Hue](/components/light.hue/) + * [Plex media server](/components/media_player.plex/) + * [Roku media player](/components/media_player.roku/) + * [SABnzbd downloader](/components/sensor.sabnzbd/) + * [Samsung SyncThru Printer](/components/sensor.syncthru/) + * [Samsung TVs](/components/media_player.samsungtv/) + * [Sonos speakers](/components/media_player.sonos/) + * [Telldus Live](/components/tellduslive/) + * [Wink](/components/wink/) + * [Yamaha media player](/components/media_player.yamaha/) + * [Yeelight Sunflower bulb](/components/light.yeelightsunflower/) + * [Xiaomi Gateway (Aqara)](/components/xiaomi_aqara/) It will be able to add Google Chromecasts and Belkin WeMo switches automatically, for Philips Hue it will require some configuration from the user. @@ -48,11 +53,22 @@ discovery: ignore: - sonos - samsung_tv + enable: + - homekit ``` -Configuration variables: +{% linkable_title Configuration variables: %} -- **ignore** (*Optional*): A list of platforms that never will be automatically configured by `discovery`. +{% configuration discovery %} +ignore: + description: A list of platforms that never will be automatically configured by `discovery`. + required: false + type: string +enable: + description: A list of platforms not enabled by default that `discovery` should discover. + required: false + type: string +{% endconfiguration %} Valid values for ignore are: @@ -75,26 +91,44 @@ Valid values for ignore are: * `plex_mediaserver`: Plex media server * `roku`: Roku media player * `sabnzbd`: SABnzbd downloader + * `samsung_printer`: Samsung SyncThru Printer * `samsung_tv`: Samsung TVs * `sonos`: Sonos speakers + * `songpal` : Songpal + * `tellstick`: Telldus Live + * `wink`: Wink Hub * `yamaha`: Yamaha media player * `yeelight`: Yeelight Sunflower bulb - -+ * `xiaomi_gw`: Xiaomi Aqara gateway + +Valid values for enable are: + + * `homekit`: HomeKit accessories + +## {% linkable_title Troubleshooting %} + +### {% linkable_title UPnP %} + Home Assistant must be on the same network as the devices for uPnP discovery to work. If running Home Assistant in a [Docker container](/docs/installation/docker/) use switch `--net=host` to put it on the host's network. -
-+### {% linkable_title Windows %} + +#### {% linkable_title 64-bit Python %} There is currently a known issue with running this component on a 64-bit version of Python and Windows. -
-+#### {% linkable_title Python 3.5 %} + If you are on Windows and you're using Python 3.5, download the [Netifaces](http://www.lfd.uci.edu/~gohlke/pythonlibs/#netifaces) dependency. -
--If you see `Not initializing discovery because could not install dependency netdisco==0.6.1` in the logs, you will need to install the `python3-dev` or `python3-devel` package on your system manually (eg. `sudo apt-get install python3-dev` or `sudo dnf -y install python3-devel`). On the next restart of home-assistant, discovery should work. If you still get an error, check if you have a compiler (`gcc`) available on your system. -
+### {% linkable_title could not install dependency netdisco %} + +If you see `Not initializing discovery because could not install dependency netdisco==0.6.1` in the logs, you will need to install the `python3-dev` or `python3-devel` package on your system manually (eg. `sudo apt-get install python3-dev` or `sudo dnf -y install python3-devel`). On the next restart of Home Assistant, the discovery should work. If you still get an error, check if you have a compiler (`gcc`) available on your system. + +### {% linkable_title DSM and Synology %} + +For DSM/Synology, install via debian-chroot [see this forum post](https://community.home-assistant.io/t/error-starting-home-assistant-on-synology-for-first-time/917/15). + +## {% linkable_title New platforms %} If you are developing a new platform, please read [how to make your platform discoverable](/developers/component_discovery/) for further details. diff --git a/source/_components/dominos.markdown b/source/_components/dominos.markdown index a7b70d7fafb..4f1d1618915 100644 --- a/source/_components/dominos.markdown +++ b/source/_components/dominos.markdown @@ -9,13 +9,16 @@ sharing: true footer: true logo: dominos.png ha_category: Other -ha_version: 0.59 +ha_iot_class: "Cloud Polling" +ha_release: 0.59 --- -The `Dominos` component allows you to order Dominos Pizza from within your Home Assistant scripts and automations. +The `dominos` component allows you to order Dominos Pizza from within your Home Assistant scripts and automations. At present, this component only supports ordering within Canada and the US. +## {% linkable_title Configuration %} + To enable the component, you need to set up your customer information and define some orders. Orders are a group of product codes. You can get these product codes by inspecting an order request from the Dominos web app, or you can [add this custom panel by following this readme](https://github.com/wardcraigj/hass-dominos-panel) to see the available product codes in a separate panel in your install. @@ -25,11 +28,11 @@ Currently, there is no support in this component for toppings, coupons or order ```yaml dominos: country_code: ca - first_name: Justin - last_name: Trudeau - email: justin.trudeau@parl.gc.ca - phone: 6139950253 - address: 24 Sussex Dr, Ottawa, ON, K1M1M4 + first_name: John + last_name: Smith + email: john.smith@example.com + phone: 123456789 + address: 24 Housten Dr, Ottawa, ON, K2M2M2 orders: - name: Medium Pan codes: diff --git a/source/_components/doorbird.markdown b/source/_components/doorbird.markdown index 0b7f1e4120a..43f30816d94 100644 --- a/source/_components/doorbird.markdown +++ b/source/_components/doorbird.markdown @@ -20,13 +20,78 @@ To connect your device, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry doorbird: - host: IP_OR_HOSTNAME - username: abcdef0001 - password: xxxxxxxxxx + devices: + - host: DOORBIRD_IP_OR_HOSTNAME + username: YOUR_USERNAME + password: YOUR_PASSWORD + hass_url_override: HASS_URL + name: Front Door + - host: DOORBIRD_IP_OR_HOSTNAME + username: YOUR_USERNAME + password: YOUR_PASSWORD + name: Driveway Gate + monitored_conditions: + - doorbell + - motion ``` -Configuration variables: +{% configuration %} +devices: + description: List of doorbird devices. + required: true + type: list + keys: + host: + description: The LAN IP address or hostname of your device. You can find this by going to the [DoorBird Online check](http://www.doorbird.com/checkonline) and entering the information from the paper that was included in the box. + required: true + type: string + username: + description: The username of a non-administrator user account on the device. + required: true + type: string + password: + description: The password for the user specified. + required: true + type: string + name: + description: Custom name for this device. + required: false + type: string + hass_url_override: + description: If your DoorBird cannot connect to the machine running Home Assistant because you are using dynamic DNS or some other HTTP configuration (such as HTTPS), specify the LAN IP of the machine here to force a LAN connection. + required: false + type: string + monitored_conditions: + description: Monitor motion and/or doorbell events for this device. + required: false + type: string + keys: + doorbell: + description: Monitor doorbell events + motion: + description: Monitor motion events (Motion monitoring must be enabled on the doorstation via DoorBird app) -- **host** (*Required*): The LAN IP address or hostname of your device. You can find this by going to the [DoorBird Online check](http://www.doorbird.com/checkonline) and entering the information from the paper that was included in the box. -- **username** (*Required*): The username of a non-administrator user account on the device. -- **password** (*Required*): The password for the user specified. +{% endconfiguration %} + +The configuration above is also used by the following components: +- [Camera](../camera.doorbird) - View live and historical event based images +- [Switch](../switch.doorbird) - Enable control of relays and camera night vision + +## {% linkable_title Motion and Doorbell Events %} + +Home Assistant will fire an event any time a `monitored_condition` happens on a doorstation. Event names are created using the format `doorbird_{station}_{event}` (Examples: `doorbird_side_entry_button`, `doorbird_side_entry_motion`). You can verify the assigned event names in the Home Assistant log file. + ++Enabling any monitored condition will delete all registered notification services on the doorstation every time Home Assistant starts. This will not affect notifications delivered by the DoorBird mobile app. +
+ +### {% linkable_title Automation Example %} +```yaml +- alias: Doorbird Ring + trigger: + platform: event + event_type: doorbird_side_entry_button + action: + service: light.turn_on + entity_id: light.side_entry_porch +``` \ No newline at end of file diff --git a/source/_components/downloader.markdown b/source/_components/downloader.markdown index 53063587d69..beec2268765 100644 --- a/source/_components/downloader.markdown +++ b/source/_components/downloader.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Downloader" -description: "Instructions how to setup the downloader component with Home Assistant." +description: "Instructions on how to setup the downloader component with Home Assistant." date: 2015-01-24 14:39 sidebar: true comments: false @@ -42,3 +42,29 @@ This will download the file from the given URL. | `subdir` | yes | Download into subdirectory of **download_dir** | | `filename` | yes | Determine the filename. | | `overwrite` | yes | Whether to overwrite the file or not, defaults to `false`. | + +### {% linkable_title Download Status Events %} + +When a download finished successfully, Home Assistant will emit a 'downloader_download_completed' event to the event bus which you can use to write automations against. +In case download failed another event 'downloader_download_failed' is emitted to indicate that the download did not complete successfully. + +Along with the event the following payload parameters are available: + +| Parameter | Description | +|-----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `url` | The `url` that was requested.| +| `filename` | The `name` of the file that was being downloaded.| + +#### Example Automation: + +```yaml +- alias: Download Failed Notification + trigger: + platform: event + event_type: downloader_download_failed + action: + service: persistent_notification.create + data_template: + message: "{{trigger.event.data.filename}} download failed" + title: "Download Failed" + ``` diff --git a/source/_components/dyson.markdown b/source/_components/dyson.markdown index a3d015001ce..7c0e1ca2f36 100644 --- a/source/_components/dyson.markdown +++ b/source/_components/dyson.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Dyson" -description: "Instructions how to integrate Dyson into Home Assistant." +description: "Instructions on how to integrate Dyson into Home Assistant." date: 2017-05-27 10:00 sidebar: true comments: false @@ -15,29 +15,31 @@ ha_release: 0.47 The `dyson` component is the main component to integrate all [Dyson](https://dyson.com) related platforms: [Fans](/components/fan/dyson/) and [Robot vacuum](/components/vacuum/dyson/). +## {% linkable_title Configuration %} + To enable this component, add the following lines to your `configuration.yaml`: ```yaml +# Example configuration.yaml entry dyson: - username:
+
+If for whatever reason you delete and re-create your ecobee app at ecobee.com such that your developer API key changes, you will need to delete your `/conf/ecobee.conf file`. You will also need to update the `api_key:` in the `configuration.yaml` or `secrets.yaml` file.
diff --git a/source/_components/egardia.markdown b/source/_components/egardia.markdown
new file mode 100644
index 00000000000..50efce55a66
--- /dev/null
+++ b/source/_components/egardia.markdown
@@ -0,0 +1,121 @@
+---
+layout: page
+title: "Egardia"
+description: "Instructions on how to setup Egardia / Woonveilig within Home Assistant."
+date: 2018-03-13 09:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+ha_category: Hub
+ha_release: 0.65
+logo: egardia.png
+---
+
+The `egardia` platform enables the ability to control an [Egardia](http://egardia.com/)/[Woonveilig](http://woonveilig.nl) control panel. These alarm panels are known under different brand names across the world, including Woonveilig in the Netherlands. This was tested on the WL-1716, GATE-01, GATE-02 and GATE-03 versions of the Egardia/Woonveilig platform. Not only will you integrate your alarm control panel, supported sensors (door contacts at this moment) will be added automatically (hidden by default).
+
+You will need to know the IP of your alarm panel on your local network. Test if you can login to the panel by browsing to the IP address and log in using your Egardia/Woonveilig account.
+
+## {% linkable_title Basic configuration %}
+
+To enable the integration with your alarm panel, add the following lines to your `configuration.yaml` file:
+ ```yaml
+ # Example configuration.yaml entry
+ egardia:
+ host: YOUR_HOST
+ username: YOUR_USERNAME
+ password: YOUR_PASSWORD
+```
+
+{% configuration %}
+host:
+ description: The local IP address of the Egardia/Woonveilig alarm panel.
+ required: true
+ type: string
+username:
+ description: Username for the Egardia/Woonveilig account.
+ required: true
+ type: string
+password:
+ description: Password for Egardia/Woonveilig account.
+ required: true
+ type: string
+version:
+ description: The version of the Egardia system. `GATE-01`, `GATE-02` and `GATE-03` are currently supported.
+ required: false
+ type: string
+ default: 'GATE-01'
+port:
+ description: The port of the alarm panel.
+ required: false
+ type: int
+ default: 80
+report_server_enabled:
+ description: Enable reporting by server.
+ required: false
+ type: string
+ default: false
+report_server_port:
+ description: Port of the Egardia server.
+ required: false
+ type: int
+ default: 52010
+report_server_codes:
+ description: Map of list of codes for the different states.
+ required: false
+ type: map
+ keys:
+ arm:
+ description: List of codes for the 'arm' state.
+ required: false
+ type: list
+ disarm:
+ description: List of codes for the 'disarm' state.
+ required: false
+ type: list
+ armhome:
+ description: List of codes for the 'armhome' state.
+ required: false
+ type: list
+ triggered:
+ description: List of codes for the 'triggered' state.
+ required: false
+ type: list
+ ignore:
+ description: List of codes that will be ignored.
+ required: false
+ type: list
+{% endconfiguration %}
+
+Note that this basic configuration will only enable you to read the armed/armed away/disarmed status of your alarm and will **not** update the status if the alarm is triggered. This is because of how Egardia built their system. The alarm triggers normally go through their servers.
+You can change this, however, using the following procedure. This is a more advanced (and more useful) configuration.
+
++There seem to be multiple versions of software running on GATE-02 devices; we have received reports from GATE-02 users who successfully run this package in GATE-02 mode. Others have reported they needed to specify GATE-03 as their version to integrate their GATE-02. +
+ +## {% linkable_title Advanced configuration %} + +1. Log in to your alarm system's control panel. You will need to access http://[IP of your control panel]. You know this already since you need it in the basic configuration from above. Log in to the control panel with your Egardia/Woonveilig username and password. +2. Once logged in, go to *System Settings*, *Report* and change the Server Address for your primary server to the IP or hostname of your Home Assistant machine. You can leave the port number set to 52010 or change it to anything you like. **Make sure to change the settings of the primary server otherwise the messages will not come through. Note that this will limit (or fully stop) the number of alarm messages you will get through Egardia's / Woonveilig services.** Maybe, that is just what you want. Make sure to save your settings by selecting 'OK'. +3. The Egardia component relies on capturing the status codes that your alarm emits when something happens (status change or trigger). These codes will be unique for every situation - i.e. the code emitted by the alarm when a sensor is triggered is unique to that sensor. Also, if you have multiple users or remotes, each remote has unique codes that are emitted by the alarm when status is changed using that remote or by that user. For the Egardia component to work correctly you will need to capture the codes. To do this, on your Home Assistant machine run `$ sudo python3 egardiaserver.py`. Refer to the [python-egardia repository](https://github.com/jeroenterheerdt/python-egardia) for detailed documentation on parameters. This will receive status codes from your alarm control panel and display them. Record the codes shown as well as the status they relate to (see step 4 below). Make sure to change the status of your alarm to all states (disarm, arm, home) by all means possible (all users, remotes, web login, app) as well as trigger the alarm in all ways possible to get 100% coverage of all the codes the alarm system generates. You will need to run this script once and stop it once you have captured all the possible codes. Also, if you ever add users, remotes or sensors to your alarm system, make sure to re-run the script to capture the extra codes so you can update your configuration (see step 4 below). **For comfort, before triggering the alarm it might be good to disable the siren temporarily (can be done in Panel Settings).** +4. Once you have the codes, update your `configuration.yaml`: + ```yaml + # Example configuration.yaml entry + egardia: + host: YOUR_HOST + username: YOUR_USERNAME + password: YOUR_PASSWORD + report_server_enabled: True + report_server_port: PORT_OF_EGARDIASERVER (optional, defaults to 52010) + report_server_codes: + arm: XXXXXXXXXXXXXXXX, XXXXXXXXXXXXXXXX + disarm: XXXXXXXXXXXXXXXX, XXXXXXXXXXXXXXXX + armhome: XXXXXXXXXXXXXXXX + triggered: XXXXXXXXXXXXXXXX, XXXXXXXXXXXXXXXX, XXXXXXXXXXXXXXXX + ignore: XXXXXXXXXXXXXXXX + ``` + +Note that for all code groups (*arm*,*disarm*, etc) multiple codes can be entered since each sensor triggers with a different code and each user of the system has its own arm and disarm codes. Also note that your system will do regular system checks which will be reported as well. Since Home Assistant provides no way of handling them properly, you can enter those codes as *ignore* (again, multiple codes can be used here). The egardia component will ignore these codes and continue returning the old status if it receives any of the codes that are listed as ignore. This is useful for example when you have armed your alarm at night: normally a system check will occur at least once during the night and if that code is not specified anywhere Home Assistant will set the status of the alarm to its default, which is unarmed. This is in fact wrong. Listing the code as ignore changes this behavior and Home Assistant will continue to show the status the alarm is in (disarm, arm, home, triggered) even when system checks occur. + +5. Test your setup and enjoy. The component will update if the alarm status changes, including triggers. You can use this to build your own automations and send notifications as you wish. *Note*: previous versions required a separate egardiaserver to be set up. This is no longer necessary and corresponding system services can be removed (using systemctl). diff --git a/source/_components/eight_sleep.markdown b/source/_components/eight_sleep.markdown index 0d730e2f7ab..3a455d4ab50 100644 --- a/source/_components/eight_sleep.markdown +++ b/source/_components/eight_sleep.markdown @@ -15,6 +15,8 @@ ha_iot_class: "Cloud Polling" The `eight_sleep` component allows Home Assistant to fetch data from your [Eight Sleep](https://eightsleep.com/) smart cover or mattress. +## {% linkable_title Configuration %} + It's setup utilizing 'Sensor' components to convey the current state of your bed and results of your sleep sessions and a 'Binary Sensor' component to indicate your presence in the bed. A service is also provided to set the heating level and duration of the bed. You must have at least two sleep sessions recorded in the Eight Sleep app prior to setting up the Home Assistant component. @@ -24,15 +26,25 @@ To get started add the following information to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry eight_sleep: - username: "user@email.com" - password: "password" + username: YOUR_E_MAIL_ADDRESS + password: YOUR_PASSWORD ``` -Configuration variables: - -- **username** (*Required*): The email address associated with your Eight Sleep account. -- **password** (*Required*): The password associated with your Eight Sleep account. -- **partner** (*Optional*): Default is False. Defines if you'd like to fetch data for both sides of the bed. +{% configuration %} +username: + description: The email address associated with your Eight Sleep account. + required: true + type: string +password: + description: The password associated with your Eight Sleep account. + required: true + type: string +password: + description: Defines if you'd like to fetch data for both sides of the bed. + required: false + type: string + default: False +{% endconfiguration %} ### {% linkable_title Supported features %} diff --git a/source/_components/emulated_hue.markdown b/source/_components/emulated_hue.markdown index 1079a0f96b6..763baa46730 100644 --- a/source/_components/emulated_hue.markdown +++ b/source/_components/emulated_hue.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Emulated Hue Bridge" -description: "Instructions how to emulated Hue Bridge within Home Assistant." +description: "Instructions on how to emulated Hue Bridge within Home Assistant." date: 2016-08-26 08:00 sidebar: true comments: false @@ -13,13 +13,13 @@ ha_release: 0.27 ha_iot_class: "Local Push" --- --At this time `emulated_hue` doesn't appear to be working for new Google Home users. +
+Be aware that `emulated_hue` doesn't work for new **Google Home** users. If you're a new user of Google Home, use the [Google Assistant component](/components/google_assistant/).
-The `emulated_hue` component provides a virtual Philips Hue bridge, written entirely in software, that allows services that work with the Hue API to interact with Home Assistant -entities. The driving use case behind this functionality is to allow Home Assistant to work with an Amazon Echo or Google Home with no set up cost outside of configuration changes. -The virtual bridge has the ability to turn entities on or off, or change the brightness of dimmable lights. The volume level of media players can be controlled as brightness. +The `emulated_hue` component provides a virtual Philips Hue bridge, written entirely in software, which allows services that work with the Hue API to interact with Home Assistant +entities. The driving use case behind for functionality is to allow Home Assistant to work with an Amazon Echo or Google Home with no setup cost outside of configuration changes. +The virtual bridge can turn entities on/off or change the brightness of dimmable lights. The volume level of media players can be controlled as brightness.A physical Hue Bridge is required for Philips Hue lights to function - this virtual bridge will not replace a physical bridge. Instead, it allows Home Assistant to represent non-Philips Hue devices to Amazon Echo as Philips Hue devices, which Amazon Echo can control with built-in support. @@ -29,6 +29,10 @@ A physical Hue Bridge is required for Philips Hue lights to function - this virt It is recommended to assign a static IP address to the computer running Home Assistant. This is because the Amazon Echo discovers devices by IP addresses, and if the IP changes, the Echo won't be able to control it. This is easiest done from your router, see your router's manual for details.
++Both Google Home and Alexa use the device they were initially set up with for communication with emulated_hue. In other words: if you remove/replace this device you will also break emulated_hue. +
+ ### {% linkable_title Configuration %} To enable the emulated Hue bridge, add one of the following configs to your `configuration.yaml` file: @@ -47,14 +51,14 @@ emulated_hue: Configuration variables: -- **type** (*Optional*): The type of assistant who we are emulated for. Either `alexa` or `google_home`, defaults to `google_home`. **This configuration option is deprecated and will be removed in a future release. It is no longer necessary to define type.** +- **type** (*Optional*): The type of assistant which we are emulating. Either `alexa` or `google_home`, defaults to `google_home`. **This configuration option is deprecated and will be removed in a future release. It is no longer necessary to define type.** - **host_ip** (*Optional*): The IP address that your Home Assistant installation is running on. If you do not specify this option, the component will attempt to determine the IP address on its own. - **listen_port** (*Optional*): The port the Hue bridge API web server will run on. If not specified, this defaults to 8300. This can be any free port on your system. -- **advertise_ip** (*Optional*): If you need to override the IP address used for UPNP discovery. (For example, using network isolation in Docker) -- **advertise_port** (*Optional*): If you need to specifically override the advertised UPNP port. +- **advertise_ip** (*Optional*): If you need to override the IP address used for UPnP discovery. (For example, using network isolation in Docker) +- **advertise_port** (*Optional*): If you need to specifically override the advertised UPnP port. -- **upnp_bind_multicast** (*Optional*): Whether or not to bind the UPNP (SSDP) listener to the multicast address (239.255.255.250) or instead to the (unicast) host_ip address specified above (or automatically determined). The default is true, which will work for most situations. In special circumstances, like running in a FreeBSD or FreeNAS jail, you may need to disable this. +- **upnp_bind_multicast** (*Optional*): Whether or not to bind the UPnP (SSDP) listener to the multicast address (239.255.255.250) or instead to the (unicast) host_ip address specified above (or automatically determined). The default is true, which will work for most situations. In special circumstances, like running in a FreeBSD or FreeNAS jail, you may need to disable this. - **off_maps_to_on_domains** (*Optional*): The domains that maps an "off" command to an "on" command. @@ -75,6 +79,8 @@ Configuration variables: - `media_player` - `fan` +- **entities** (*Optional*): Customization for entities. + A full configuration sample looks like the one below. ```yaml @@ -90,26 +96,21 @@ emulated_hue: expose_by_default: true exposed_domains: - light -``` - -With additional customization you will be able to specify the behavior of the existing entities. - -```yaml -# Example customization -homeassistant: - customize: + entities: light.bedroom_light: - # Don't allow light.bedroom_light to be controlled by the emulated Hue bridge - emulated_hue_hidden: true - light.office_light: - # Address light.office_light as "back office light" - emulated_hue_name: "back office light" + name: "Bedside Lamp" + light.ceiling_lights: + hidden: true ``` -The following are attributes that can be applied in the `customize` section: +The following are attributes that can be applied in the `entities` section: -- **emulated_hue_hidden** (*Optional*): Whether or not the entity should be exposed by the emulated Hue bridge. Adding `emulated_hue_hidden: false` will expose the entity to Alexa. The default value for this attribute is controlled by the `expose_by_default` option. -- **emulated_hue_name** (*Optional*): The name that the emulated Hue will use. The default for this is the entity's friendly name. +- **name** (*Optional*): The name that the emulated Hue will use. The default for this is the entity's friendly name. +- **hidden** (*Optional*): Whether or not the emulated Hue bridge should expose the entity. Adding `hidden: false` will expose the entity to Alexa. The default value for this attribute is controlled by the `expose_by_default` option. + ++These attributes used to be found under the `customize` section of `homeassistant`, however, they have now been moved to `entities`. Emulated Hue configuration under `homeassistant.customize` will be deprecated in the near future. +
### {% linkable_title Troubleshooting %} @@ -118,14 +119,14 @@ You can verify that the `emulated_hue` component has been loaded and is respondi - `http://Make sure that your topics match exactly. `some-topic/` and `some-topic` are different topics. @@ -68,7 +157,7 @@ In this section you find some real life examples of how to use this fan. The example below shows a full configuration for a MQTT fan. ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry fan: - platform: mqtt name: "Bedroom Fan" diff --git a/source/_components/fan.template.markdown b/source/_components/fan.template.markdown new file mode 100644 index 00000000000..974eb7508e4 --- /dev/null +++ b/source/_components/fan.template.markdown @@ -0,0 +1,109 @@ +--- +layout: page +title: "Template Fan" +description: "Instructions how to setup the Template fans within Home Assistant." +date: 2018-05-03 09:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Fan +ha_release: 0.69 +ha_iot_class: "Local Push" +logo: home-assistant.png +--- + +The `template` platform creates fans that combine components and provides the +ability to run scripts or invoke services for each of the turn_on, turn_off, set_speed, +set_oscillating, and set_direction commands of a fan. + +To enable Template Fans in your installation, add the following to your +`configuration.yaml` file: + +{% raw %} +```yaml +# Example configuration.yaml entry +fan: + - platform: template + fans: + bedroom_fan: + friendly_name: "Bedroom fan" + value_template: "{{ states('input_boolean.state') }}" + speed_template: "{{ states('input_select.speed') }}" + oscillating_template: "{{ states('input_select.osc') }}" + direction_template: "{{ states('input_select.direction') }}" + turn_on: + service: script.fan_on + turn_off: + service: script.fan_off + set_speed: + service: script.fan_speed + data_template: + speed: "{{ speed }}" + set_oscillating: + service: script.fan_oscillating + data_template: + oscillating: "{{ oscillating }}" + set_direction: + service: script.fan_direction + data_template: + direction: "{{ direction }}" + speeds: + - '1' + - '2' + - '3' +``` +{% endraw %} + +{% configuration %} + fans: + description: List of your fans. + required: true + type: map + keys: + friendly_name: + description: Name to use in the frontend. + required: false + type: string + value_template: + description: "Defines a template to get the state of the fan. Valid value: 'on'/'off'" + required: true + type: template + speed_template: + description: Defines a template to get the speed of the fan. + required: false + type: template + oscillating_template: + description: "Defines a template to get the osc state of the fan. Valid value: True/False" + required: false + type: template + direction_template: + description: "Defines a template to get the direction of the fan. Valid value: 'forward'/'reverse'" + required: false + type: template + turn_on: + description: Defines an action to run when the fan is turned on. + required: true + type: action + turn_off: + description: Defines an action to run when the fan is turned off. + required: true + type: action + set_speed: + description: Defines an action to run when the fan is given a speed command. + required: false + type: action + set_oscillating: + description: Defines an action to run when the fan is given an osc state command. + required: false + type: action + set_direction: + description: Defines an action to run when the fan is given a direction command. + required: false + type: action + speeds: + description: List of speeds the fan is capable of running at. + required: false + type: string list + default: ['low', 'medium', 'high'] +{% endconfiguration %} diff --git a/source/_components/fan.tuya.markdown b/source/_components/fan.tuya.markdown new file mode 100644 index 00000000000..273a6f00729 --- /dev/null +++ b/source/_components/fan.tuya.markdown @@ -0,0 +1,23 @@ +--- +layout: page +title: "Tuya Fan" +description: "Instructions on how to setup the Tuya fan within Home Assistant." +date: 2018-07-17 09:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: tuya.png +ha_category: Fan +ha_iot_class: "Cloud Polling" +ha_release: 0.75 +--- + + +The `tuya` fan platform allows you to control your [Tuya Smart](https://www.tuya.com) fan. + +The platform supports most kinds of Tuya fans. + +
+Full configuration details can be found on the main [Tuya component](/components/tuya/) page. +
\ No newline at end of file diff --git a/source/_components/fan.velbus.markdown b/source/_components/fan.velbus.markdown index ff0652f233f..e1686e65642 100644 --- a/source/_components/fan.velbus.markdown +++ b/source/_components/fan.velbus.markdown @@ -15,27 +15,48 @@ ha_release: "0.50" The `velbus` fan allows you to control [Velbus](http://www.velbus.eu) connected fans. +## {% linkable_title Configuration %} + To use your Velbus fans in your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry - fan: - platform: velbus devices: - - name: Fan 1 - module: 0xda - channel_low: 4 - channel_medium: 3 - channel_high: 2 + - name: Fan 1 + module: 0xda + channel_low: 4 + channel_medium: 3 + channel_high: 2 ``` -Configuration variables: -- **devices** array (*Required*): The array contains the fans to configure - - **name** (*Required*): Name of the fan. - - **module** (*Required*): The hexadecimal module address - - **channel_low** (*Required*): The channel number in the module for low-speed. - - **channel_medium** (*Required*): The channel number in the module for medium-speed. - - **channel_high** (*Required*): The channel number in the module for high-speed. +{% configuration %} +devices: + description: The list contains the fans to configure. + required: true + type: map + keys: + name: + description: Name to use in the frontend. + required: true + type: string + module: + description: The hexadecimal module address. + required: true + type: string + channel_low: + description: The channel number in the module for low-speed. + required: true + type: string + channel_medium: + description: The channel number in the module for medium-speed. + required: true + type: string + channel_high: + description: The channel number in the module for high-speed. + required: true + type: string +{% endconfiguration %} For hub configuration, see [the Velbus component](/components/velbus/). diff --git a/source/_components/fan.wink.markdown b/source/_components/fan.wink.markdown index 23369dfad2e..129db4b4693 100644 --- a/source/_components/fan.wink.markdown +++ b/source/_components/fan.wink.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Wink Fan" -description: "Instructions how to setup the Wink fans within Home Assistant." +description: "Instructions on how to setup the Wink fans within Home Assistant." date: 2017-01-14 12:00 sidebar: true comments: false diff --git a/source/_components/fan.xiaomi_miio.markdown b/source/_components/fan.xiaomi_miio.markdown index 7acf1291e45..de4a07316da 100644 --- a/source/_components/fan.xiaomi_miio.markdown +++ b/source/_components/fan.xiaomi_miio.markdown @@ -1,45 +1,171 @@ --- layout: page -title: "Xiaomi Air Purifier 2" -description: "Instructions how to integrate your Xiaomi Air Purifier 2 within Home Assistant." +title: "Xiaomi Air Purifier" +description: "Instructions on how to integrate your Xiaomi Air Purifier and Xiaomi Air Humidifier within Home Assistant." date: 2017-10-13 12:35 sidebar: true comments: false sharing: true footer: true logo: xiaomi.png -ha_category: Switch -ha_version: 0.57 +ha_category: Fan ha_iot_class: "Local Polling" +ha_release: 0.57 --- -The `xiaomi_miio` fan platform allows you to control the Xiaomi Air Purifier 2. The Air Purifier Pro isn't supported right now. +The `xiaomi_miio` fan platform allows you to control the Xiaomi Air Purifier and Xiaomi Air Humidifier. -Currently, the supported features are +## Features -* On, Off -* Operation modes (auto, silent, favorite, idle) -* Buzzer (on, off) -* LED (on, off), LED brightness (bright, dim, off) -* Favorite Level -* States - - power - - aqi - - humidity +### Air Purifier 2 et al. + +- Power (on, off) +- Operation modes (auto, silent, favorite, idle) +- Buzzer (on, off) +- Child lock (on, off) +- LED (on, off), LED brightness (bright, dim, off) +- Favorite Level (0...16) +- Attributes + - model - temperature + - humidity + - aqi + - mode + - filter_hours_used + - filter_life_remaining + - favorite_level + - child_lock + - led + - motor_speed + - average_aqi + - purify_volume + - learn_mode + - sleep_time + - sleep_mode_learn_count + - extra_features + - turbo_mode_supported + - auto_detect + - use_time + - button_pressed + - buzzer + - led_brightness + - sleep_mode + +### Air Purifier Pro (zhimi.airpurifier.v6) + +- Power (on, off) +- Operation modes (auto, silent, favorite) +- Child lock (on, off) +- LED (on, off) +- Favorite Level (0...16) +- Attributes + - model + - temperature + - humidity + - aqi + - mode + - filter_hours_used + - filter_life_remaining + - favorite_level + - child_lock + - led + - motor_speed + - average_aqi + - purify_volume + - learn_mode + - sleep_time + - sleep_mode_learn_count + - extra_features + - turbo_mode_supported + - auto_detect + - use_time + - button_pressed + - filter_rfid_product_id + - filter_rfid_tag + - filter_type + - illuminance + - motor2_speed + - volume + +### Air Purifier V3 (zhimi.airpurifier.v3) + +- Power (on, off) +- Operation modes (auto, silent, favorite, idle, medium, high, strong) +- Child lock (on, off) +- LED (on, off) +- Attributes + - model + - aqi - mode - led - - led_brightness - buzzer - child_lock - - brightness - - favorite_level - - filter1_life - - f1_hour_used + - illuminance + - filter_hours_used + - filter_life_remaining + - motor_speed + - average_aqi + - volume + - motor2_speed + - filter_rfid_product_id + - filter_rfid_tag + - filter_type + - purify_volume + - learn_mode + - sleep_time + - sleep_mode_learn_count + - extra_features + - auto_detect - use_time - - motor1_speed + - button_pressed -## {% linkable_title Setup %} +### Air Humidifier (zhimi.humidifier.v1) + +- On, Off +- Operation modes (silent, medium, high) +- Buzzer (on, off) +- Child lock (on, off) +- LED brightness (bright, dim, off) +- Target humidity (30, 40, 50, 60, 70, 80) +- Attributes + - model + - temperature + - humidity + - mode + - buzzer + - child_lock + - trans_level + - target_humidity + - led_brightness + - button_pressed + - use_time + - hardware_version + +### Air Humidifier CA (zhimi.humidifier.ca1) + +- On, Off +- Operation modes (silent, medium, high, auto) +- Buzzer (on, off) +- Child lock (on, off) +- LED brightness (bright, dim, off) +- Target humidity (30, 40, 50, 60, 70, 80) +- Dry mode (on, off) +- Attributes + - model + - temperature + - humidity + - mode + - buzzer + - child_lock + - trans_level + - target_humidity + - led_brightness + - button_pressed + - use_time + - hardware_version + - speed + - depth + - dry Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi_miio/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file. @@ -47,65 +173,188 @@ To add a Xiaomi Air Purifier to your installation, add the following to your `co ```yaml fan: +# Example configuration.yaml entry - platform: xiaomi_miio - name: Xiaomi Air Purifier 2 host: 192.168.130.66 token: YOUR_TOKEN ``` -Configuration variables: -- **host** (*Required*): The IP of your plug. -- **token** (*Required*): The API token of your plug. -- **name** (*Optional*): The name of your plug. +{% configuration %} +host: + description: The IP address of your miio fan. + required: true + type: string +token: + description: The API token of your miio fan. + required: true + type: string +name: + description: The name of your miio fan. + required: false + type: string + default: Xiaomi Air Purifier +model: + description: The model of your miio fan. Valid values are `zhimi.airpurifier.v6`, `zhimi.airpurifier.v3`, `zhimi.humidifier.v1` and `zhimi.humidifier.ca1`. This setting can be used to bypass the device model detection and is recommended if your device isn't always available. + required: false + type: string +{% endconfiguration %} ## {% linkable_title Platform Services %} -### Service fan/xiaomi_miio_set_buzzer_on +### {% linkable_title Service `fan.set_speed` %} + +Set the fan speed/operation mode. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------------------| +| `entity_id` | yes | Only act on a specific air purifier. Else targets all. | +| `speed` | no | Fan speed. Valid values are 'Auto', 'Silent', 'Favorite' and 'Idle' | + +### {% linkable_title Service `fan.xiaomi_miio_set_buzzer_on` %} (Air Purifier Pro excluded) Turn the buzzer on. -| Service data attribute | Optional | Description | -|---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific air purifier. Else targets all. | +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | -### Service fan/xiaomi_miio_set_buzzer_off +### {% linkable_title Service `fan.xiaomi_miio_set_buzzer_off` %} (Air Purifier Pro excluded) Turn the buzzer off. -| Service data attribute | Optional | Description | -|---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific air purifier. Else targets all. | +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | -### Service fan/xiaomi_miio_set_led_on +### {% linkable_title Service `fan.xiaomi_miio_set_led_on` %} (Air Purifier only) Turn the led on. -| Service data attribute | Optional | Description | -|---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific air purifier. Else targets all. | +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | -### Service fan/xiaomi_miio_set_led_off +### {% linkable_title Service `fan.xiaomi_miio_set_led_off` %} (Air Purifier only) Turn the led off. -| Service data attribute | Optional | Description | -|---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific air purifier. Else targets all. | +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | -### Service fan/xiaomi_miio_set_led_brightness +### {% linkable_title Service `fan.xiaomi_miio_set_child_lock_on` %} + +Turn the child lock on. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | + +### {% linkable_title Service `fan.xiaomi_miio_set_child_lock_off` %} + +Turn the child lock off. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | + +### {% linkable_title Service `fan.xiaomi_miio_set_led_brightness` %} (Air Purifier Pro excluded) Set the led brightness. Supported values are 0 (Bright), 1 (Dim), 2 (Off). -| Service data attribute | Optional | Description | -|---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific air purifier. Else targets all. | -| `brightness` | no | Brightness, between 0 and 2. | +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | +| `brightness` | no | Brightness, between 0 and 2. | -### Service fan/xiaomi_miio_set_favorite_level +### {% linkable_title Service `fan.xiaomi_miio_set_favorite_level` %} (Air Purifier only) Set the favorite level of the operation mode "favorite". -| Service data attribute | Optional | Description | -|---------------------------|----------|-------------------------------------------------------| -| `entity_id` | yes | Only act on specific air purifier. Else targets all. | -| `level` | no | Level, between 0 and 16. | +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | +| `level` | no | Level, between 0 and 16. | + +### {% linkable_title Service `fan.xiaomi_miio_set_auto_detect_on` %} (Air Purifier Pro only) + +Turn the auto detect on. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | + +### {% linkable_title Service `fan.xiaomi_miio_set_auto_detect_off` %} (Air Purifier Pro only) + +Turn the auto detect off. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | + +### {% linkable_title Service `fan.xiaomi_miio_set_learn_mode_on` %} (Air Purifier 2 only) + +Turn the learn mode on. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | + +### {% linkable_title Service `fan.xiaomi_miio_set_learn_mode_off` %} (Air Purifier 2 only) + +Turn the learn mode off. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | + +### {% linkable_title Service `fan.xiaomi_miio_set_volume` %} (Air Purifier Pro only) + +Set the sound volume. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | +| `volume` | no | Volume, between 0 and 100. | + +### {% linkable_title Service `fan.xiaomi_miio_reset_filter` %} (Air Purifier 2 only) + +Reset the filter lifetime and usage. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | + +### {% linkable_title Service `fan.xiaomi_miio_set_extra_features` %} (Air Purifier only) + +Set the extra features. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | +| `features` | no | Integer, known values are 0 and 1. | + +### {% linkable_title Service `fan.xiaomi_miio_set_target_humidity` %} (Air Humidifier only) + +Set the target humidity. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-----------------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | +| `humidity` | no | Target humidity. Allowed values are 30, 40, 50, 60, 70 and 80 | + +### {% linkable_title Service `fan.xiaomi_miio_set_dry_on` %} (Air Humidifier CA only) + +Turn the dry mode on. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | + +### {% linkable_title Service `fan.xiaomi_miio_set_dry_off` %} (Air Humidifier CA only) + +Turn the dry mode off. + +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------| +| `entity_id` | yes | Only act on a specific Xiaomi miIO fan entity. Else targets all. | diff --git a/source/_components/fan.zha.markdown b/source/_components/fan.zha.markdown new file mode 100644 index 00000000000..536d9c78bd1 --- /dev/null +++ b/source/_components/fan.zha.markdown @@ -0,0 +1,16 @@ +--- +layout: page +title: "ZigBee Home Automation Fan" +description: "Instructions how to setup ZigBee Home Automation fans within Home Assistant." +date: 2018-02-10 00:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: zigbee.png +ha_category: Fan +ha_iot_class: "Local Polling" +ha_release: 0.66 +--- + +To get your ZigBee fans working with Home Assistant, follow the instructions for the general [ZigBee Home Automation component](/components/zha/). diff --git a/source/_components/fan.zwave.markdown b/source/_components/fan.zwave.markdown index 953620ed3bb..4e83a0b8a58 100644 --- a/source/_components/fan.zwave.markdown +++ b/source/_components/fan.zwave.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Z-Wave Fan" -description: "Instructions how to setup the Z-Wave Fans within Home Assistant." +description: "Instructions on how to setup the Z-Wave Fans within Home Assistant." date: 2017-05-25 17:00 sidebar: true comments: false diff --git a/source/_components/feedreader.markdown b/source/_components/feedreader.markdown index 15b72129655..b5a6b9b3ea5 100644 --- a/source/_components/feedreader.markdown +++ b/source/_components/feedreader.markdown @@ -1,7 +1,7 @@ --- layout: page title: Feedreader -description: "Instructions how to integrate RSS feeds into Home Assistant." +description: "Instructions on how to integrate RSS feeds into Home Assistant." date: 2016-04-18 22:00 sidebar: true comments: false @@ -20,14 +20,41 @@ To use RSS feeds in your installation, add the following to your `configuration. # Example configuration.yaml entry feedreader: urls: - - https://home-assistant.io/atom.xml + - https://www.home-assistant.io/atom.xml - https://github.com/blog.atom - https://hasspodcast.io/feed/podcast ``` -Configuration variables: +{% configuration %} + urls: + description: List of URLS for your feeds. + required: true + type: list + scan_interval: + description: Defines the update interval of the feeds. + required: false + default: 1 hour + type: interval + max_entries: + description: The maximum number of entries to extract from each feed. + required: false + default: 20 + type: int +{% endconfiguration %} -- **urls** (*Required*): List of URLS for your feeds. +The following configuration example shows how to configure update interval and maximum number of entries: + +```yaml +# Example configuration.yaml entry with optional parameters +feedreader: + urls: + - https://www.home-assistant.io/atom.xml + - https://github.com/blog.atom + - https://hasspodcast.io/feed/podcast + scan_interval: + minutes: 30 + max_entries: 5 +``` Feedreader events can be used out of the box to trigger automation actions, e.g.: @@ -67,4 +94,4 @@ hass.bus.listen(EVENT_FEEDREADER, event_listener) To get started developing custom components, please refer to the [developers](/developers) documentation -For a drop in packaged complete example of Feedreader, you can use the [PodCast notifier](https://github.com/CCOSTAN/Home-AssistantConfig/blob/master/packages/hasspodcast.yaml). +For a drop in packaged complete example of Feedreader, you can use the [PodCast notifier](https://github.com/CCOSTAN/Home-AssistantConfig/blob/master/config/packages/hasspodcast.yaml). diff --git a/source/_components/folder_watcher.markdown b/source/_components/folder_watcher.markdown new file mode 100644 index 00000000000..fffd1a68f8d --- /dev/null +++ b/source/_components/folder_watcher.markdown @@ -0,0 +1,82 @@ +--- +layout: page +title: "Folder Watcher" +description: "Component for monitoring changes within the filesystem." +date: 2018-03-11 14:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: home-assistant.png +ha_category: System Monitor +ha_iot_class: "Local Polling" +ha_release: 0.67 +--- + +This component adds [Watchdog](https://pythonhosted.org/watchdog/) file system monitoring, publishing events on the Home Assistant bus on the creation/deletion/modification of files within configured folders. The monitored `event_type` are: + +* `created` +* `deleted` +* `modified` +* `moved` + +Configured folders must be added to [whitelist_external_dirs](/docs/configuration/basic/). Note that by default folder monitoring is recursive, meaning that the contents of sub-folders are also monitored. + +To enable the Folder Watcher component in your installation, add the following to your `configuration.yaml` file: + +{% raw %} +```yaml +folder_watcher: + - folder: /config +``` +{% endraw %} + +{% configuration %} +folder: + description: The folder path + required: true + type: string +patterns: + description: Pattern matching to apply + required: false + default: "*" + type: string +{% endconfiguration %} + +## Patterns + +Pattern matching using [fnmatch](https://docs.python.org/3.6/library/fnmatch.html) can be used to limit filesystem monitoring to only files which match the configured patterns. The following example shows the configuration required to only monitor filetypes `.yaml` and `.txt`. + +{% raw %} +```yaml +folder_watcher: + - folder: /config + patterns: + - '*.yaml' + - '*.txt' +``` +{% endraw %} + +## Automations + +Automations can be triggered on filesystem event data using a `data_template`. The following automation will send a notification with the name and folder of new files added to that folder: + +{% raw %} +```yaml +#Send notification for new image (including the image itself) +automation: + alias: New file alert + trigger: + platform: event + event_type: folder_watcher + event_data: + event_type: created + action: + service: notify.notify + data_template: + title: New image captured! + message: "Created {{ trigger.event.data.file }} in {{ trigger.event.data.folder }}" + data: + file: "{{ trigger.event.data.path }}" +``` +{% endraw %} diff --git a/source/_components/foursquare.markdown b/source/_components/foursquare.markdown index 10b5d6ebe61..5ec302887eb 100644 --- a/source/_components/foursquare.markdown +++ b/source/_components/foursquare.markdown @@ -1,7 +1,7 @@ --- layout: page title: Foursquare -description: "Instructions how to the Foursquare API into Home Assistant." +description: "Instructions on how to the Foursquare API into Home Assistant." date: 2016-08-08 17:20 sidebar: true comments: false @@ -31,7 +31,7 @@ Configuration variables: #### Getting the access token #### After you have registered your APP on your [My Apps Page](https://foursquare.com/developers/apps) you get a `CLIENT_ID` and you have specified a -`REDIRECT_URL` which can be any URL you like, but since it will get your access token via a HTTP GET request, it should be a URL which will ignore the `access_token` HTTP GET variable. A good idea is to choose the URL of your Home Assistant. +`REDIRECT_URL` which can be any URL you like, but since it will get your access token via an HTTP GET request, it should be a URL which will ignore the `access_token` HTTP GET variable. A good idea is to choose the URL of your Home Assistant. Visit the following URL in your browser: ``` @@ -40,7 +40,7 @@ https://foursquare.com/oauth2/authenticate?client_id=CLIENT_ID&response_type=tok and change the `CLIENT_ID` and `YOUR_REGISTERED_REDIRECT_URL` to your actual values. You will receive an OAuth request landing page, asking you if you want to connect your Foursquare account to your newly created app. Say "Yes". -After that, you will get redirected to your `REDIRECT_URL` with the `access_token` as a HTTP GET variable. Copy everything after the = and paste it in your configuration.yaml as the `access_token`. +After that, you will get redirected to your `REDIRECT_URL` with the `access_token` as an HTTP GET variable. Copy everything after the = and paste it in your configuration.yaml as the `access_token`. ### {% linkable_title Real-Time API %} diff --git a/source/_components/freedns.markdown b/source/_components/freedns.markdown new file mode 100644 index 00000000000..960d1411d99 --- /dev/null +++ b/source/_components/freedns.markdown @@ -0,0 +1,49 @@ +--- +layout: page +title: "freedns.afraid.org" +description: "Keep your DNS record up to date with FreeDNS." +date: 2018-03-27 21:30 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Utility +ha_release: 0.67 +--- + +With the `freedns` component you can keep your [FreeDNS](https://freedns.afraid.org) record up to date. + +## {% linkable_title Configuration %} + +You need to determine your update URL or your access token. + +1. Head over to the [FreeDNS](https://freedns.afraid.org) website and login to your account. +2. Select the menu "Dynamic DNS" +3. You should now see your update candiates in a table at the bottom of the page. +4. Copy the link target of the "Direct URL". +5. The access token is the part at the end of the link: `https://freedns.afraid.org/dynamic/update.php?YOUR_UPDATE_TOKEN` +6. Either put the token as `access_token` _or_ the whole URL into the `url` attribute. + +To use the component in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +freedns: + access_token: YOUR_TOKEN +``` + +{% configuration %} + access_token: + description: Your access token. This is exclusive to `url`. + required: false + type: string + url: + description: The full update URL. This is exclusive to `access_token`. + required: false + type: string + update_interval: + description: How often to call the update service. + required: false + type: time period + default: 10 minutes +{% endconfiguration %} diff --git a/source/_components/fritzbox.markdown b/source/_components/fritzbox.markdown new file mode 100644 index 00000000000..a5ca0a5f68b --- /dev/null +++ b/source/_components/fritzbox.markdown @@ -0,0 +1,55 @@ +--- +layout: page +title: "Fritzbox" +description: "Instructions on how to integrate the AVM Fritzbox Smart Home components." +date: 2018-02-18 17:10 +sidebar: true +comments: false +sharing: true +footer: true +logo: avm.png +ha_category: Hub +ha_release: 0.68 +ha_iot_class: "Local Polling" +--- + +The [AVM](https://en.avm.de) Fritzbox component for Home Assistant allows you to integrate the switch and climate devices. + +#### {% linkable_title Tested Devices %} + +- [FRITZ!Box 6490 Cable](https://en.avm.de/products/fritzbox/fritzbox-6490-cable/) +- [FRITZ!Box 7590](https://en.avm.de/products/fritzbox/fritzbox-7590/) +- [FRITZ!DECT 200](https://en.avm.de/products/fritzdect/fritzdect-200/) +- [Eurotronic Comet DECT](https://www.eurotronic.org/en/products/comet-dect.html) + + +## {% linkable_title Setup %} + +```yaml +# Example configuration.yaml entry +fritzbox: + devices: + - host: fritz.box + username: YOUR_USERNAME + password: YOUR_PASSWORD +``` + +{% configuration %} +devices: + description: A list of Fritzbox devices. + required: true + type: map + keys: + host: + description: The hostname or IP address of the Fritzbox. + required: true + type: optional + username: + description: The username for Smart Home access. + required: true + type: string + password: + description: The password of the user. + required: true + type: string +{% endconfiguration %} diff --git a/source/_components/frontend.markdown b/source/_components/frontend.markdown index 40274f80623..3cb9e3d5fc8 100644 --- a/source/_components/frontend.markdown +++ b/source/_components/frontend.markdown @@ -23,7 +23,7 @@ frontend: description: "Version of the JavaScript to serve to clients. Options: `es5` - transpiled so old browsers understand it. `latest` - not transpiled, so will work on recent browsers only. `auto` - select a version according to the browser user-agent. The value in the config can be overiden by putting `es5` or `latest` in the URL. For example `http://localhost:8123/states?es5` " required: false type: string - default: es5 + default: auto themes: description: Allow to define different themes. See below for further details. required: false @@ -39,7 +39,11 @@ frontend: required: true type: [list, string] extra_html_url: - description: "List of addtional [resources](/developers/frontend_creating_custom_ui/) to load." + description: "List of additional [resources](/developers/frontend_creating_custom_ui/) to load in `latest` javascript mode." + required: false + type: list + extra_html_url_es5: + description: "List of additional [resources](/developers/frontend_creating_custom_ui/) to load in `es5` javascript mode." required: false type: list development_repo: @@ -65,7 +69,7 @@ frontend: primary-color: blue ``` -The example above defined two themes named `happy` and `sad`. For each theme you can set values for CSS variables. For a partial list of variables used by the main frontend see [ha-style.html](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/resources/ha-style.html). +The example above defined two themes named `happy` and `sad`. For each theme you can set values for CSS variables. For a partial list of variables used by the main frontend see [ha-style.js](https://github.com/home-assistant/home-assistant-polymer/blob/master/src/resources/ha-style.js). There are 2 themes-related services: @@ -131,7 +135,7 @@ Those will be loaded via `` on a ### {% linkable_title Manual Language Selection %} -The browser language is automatically detected. To use a different language, go to **General** in the Configuration panel and select a one from "Choose a Language". It will be applied immediately. +The browser language is automatically detected. To use a different language, go to **General** in the Configuration panel and select one from "Choose a Language". It will be applied immediately.
diff --git a/source/_components/gc100.markdown b/source/_components/gc100.markdown
index 063dddcab09..43d74d72b7c 100644
--- a/source/_components/gc100.markdown
+++ b/source/_components/gc100.markdown
@@ -14,7 +14,7 @@ ha_release: 0.57
The Global Caché [GC-100](https://www.globalcache.com/products/gc-100/) can be integrated into Home Assistant. GC-100 is a TCP-controllable
hardware device which has an array of relays, RS232 serial ports, and flexible ports which can be programmed to be either digital inputs or IR blaster outputs. There are a variety of submodels of the GC-100 which have different amounts of each I/O type.
-Currently, only relays and ports configured to be digital inputs are supported in Home Assistant. For IR support, please use the iTach remote platform (https://home-assistant.io/components/remote.itach/), but note that it will likely not function concurrently on the same GC100 due to limitations in the TCP socket server implementation used by Global Caché.
+Currently, only relays and ports configured to be digital inputs are supported in Home Assistant. For IR support, please use the iTach remote platform (/components/remote.itach/), but note that it will likely not function concurrently on the same GC100 due to limitations in the TCP socket server implementation used by Global Caché.
To enable this device, add the following lines to your `configuration.yaml`:
diff --git a/source/_components/goalfeed.markdown b/source/_components/goalfeed.markdown
new file mode 100644
index 00000000000..474e8a0351f
--- /dev/null
+++ b/source/_components/goalfeed.markdown
@@ -0,0 +1,54 @@
+---
+layout: page
+title: "Goalfeed"
+description: "Instructions on how to setup Goalfeed events within Home Assistant."
+date: 2017-12-13 17:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: goalfeed.png
+ha_category: Other
+ha_release: 0.63
+---
+
+The `goalfeed` component lets you use your Goalfeed account to trigger events in Home Assistant whenever a NHL or MLB team scores.
+
+To use this component, enter your email address and password from your goalfeed.ca account in your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+goalfeed:
+ username: YOUR_E_MAIL_ADDRESS
+ password: YOUR_PASSWORD
+```
+
+{% configuration %}
+username:
+ required: true
+ description: The email address on your goalfeed.ca account.
+ type: string
+password:
+ required: true
+ description: The password on your goalfeed.ca account.
+ type: string
+{% endconfiguration %}
+
+Now you can use the goal event type in your automations:
+
+```yaml
+- alias: 'Jets Goal'
+ trigger:
+ platform: event
+ event_type: goal
+ event_data:
+ team_name: "Winnipeg Jets"
+```
+
+Goal events have the following event data:
+
+- **team**: Three letter code representing the team. This is unique within the leagues, but not unique across the leagues (i.e. 'WPG' or 'TOR').
+- **team_name**: The team that scored (i.e. 'Winnipeg Jets' or 'Toronto Blue Jays').
+- **team_hash**: A unique hash for the team (you can find these values on https://goalfeed.ca/get-teams).
+- **league_id**: A unique number for the league.
+- **league_name**: A the short name of the league (i.e. 'NHL' or 'MLB').
diff --git a/source/_components/google_assistant.markdown b/source/_components/google_assistant.markdown
index cb2efbb6361..c9fbcd65227 100644
--- a/source/_components/google_assistant.markdown
+++ b/source/_components/google_assistant.markdown
@@ -13,14 +13,21 @@ featured: true
ha_release: 0.56
---
-# Google Assistant Docs
+
+ Use [Home Assistant Cloud](/cloud/) to integrate with Google Assistant without any effort. +
+ +The `google_assistant` component allows you to control things via Google Assistant (on your mobile or tablet) or a Google Home device. + The Google Assistant component requires a bit more setup than most due to the way Google requires Assistant Apps to be set up.-To use Google Assistant your Home Assistant configuration has to be externally accessible, with a hostname and SSL certificate. If you haven't already configured that you should do so before continuing. +To use Google Assistant, your Home Assistant configuration has to be externally accessible with a hostname and SSL certificate. If you haven't already configured that, you should do so before continuing.
-### {% linkable_title Configuration %} +## {% linkable_title Configuration %} + +To enable this, add the following lines to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -29,108 +36,148 @@ google_assistant: client_id: [long URL safe random string] access_token: [a different long URL safe random string] agent_user_id: [a string to identify user] - api_key: [an API Key generated for the Google Actions project] + api_key: [a Homegraph API Key generated for the Google Actions project] exposed_domains: - switch - light - group -``` - -*Note:* It's very important that you use very long strings for `client_id` and `access_token`. Those are essentially the credentials to your Home Assistant instance. You can generate them with the following command: - -`cat /dev/urandom|fold -w 120|head -n 1|base64 -w 0|tr -dc '0-9A-Za-z'|cut -c -80` - -*Configuration Variables:* -* *expose_by_default* (Optional): Expose devices in all supported domains by default. -* *project_id* (Required): Project ID from the Google Developer console (looks like `words-2ab12`) -* *client_id* (Required): A long random URL safe string (no spaces or special characters) that will be used for Implicit OAuth. -* *access_token* (Required): Another different long random URL safe string. -* *agent_user_id* (Optional): A string to identify the user, e.g., email address. If not provided, the component will generate one. -* *api_key* (Optional): An API Key generated for the project from Google Console which allows you to update devices without unlinking and relinking an account (see setup below). If not provided then the request_sync service is not exposed. -* *exposed_domains* (Optional): An array of Home Assistant domains to expose to Google Assistant. Options include: - - `switch` - - `light` - - `cover` - - `media_player` - - `group` - - `fan` - - `scene` - - `script` - -You can also customize your devices similar to other components by adding keys to entities: - -```yaml -homeassistant: - customize: - master_bedroom_light: - google_assistant: true - google_assistant_name: bedroom light - bedroom_blinds: + entity_config: + switch.kitchen: + name: Custom Name for Google Assistant aliases: - - bedroom shades - - bedroom covers - hallway_ceiling_switch: - google_assistant: true - google_assistant_type: light + - bright lights + - entry lights + light.living_room: + expose: false + room: living room ``` -*Entity Customization Keys:* -* *google_assistant*: True exposes entity, false will hide it -* *google_assistant_name*: Can be used to override the primary name of an entity. By default the `friendly_name` of an entity is used. -* *google_assistant_type*: Can be used to override the domain/type of an entity. For example a switch can be treated as a light -* *aliases*: Provides "nicknames" to Google Assistant. These function as alternate names for an entity that Assistant will understand when spoken. +Configuration variables: + +{% configuration %} + +project_id: + description: Project ID from the Google Developer console (looks like `words-2ab12`) + required: true + type: string +client_id: + description: A long random URL safe string (no spaces or special characters) that will be used for Implicit OAuth (example `aBcDeFgHiJkLmNoP`) + required: true + type: string +access_token: + description: Another different long random URL safe string (example `aBcDeFgHiJkLmNoP`) + required: true + type: string +agent_user_id: + description: A string to identify the user, e.g., email address. If not provided, the component will generate one. + required: false + type: string +api_key: + description: An API Key generated for the project from [Google Console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview) which allows you to update devices without unlinking and relinking an account (see step 9 below). If not provided then the `google_assistant.request_sync` service is not exposed. It is recommended to set up this configuration key as it also allows the usage of the following command, "Ok Google, sync my devices". Once you have setup this component you will need to call this service (or command) each time you add a new device that you wish to control via the Google Assistant integration. + required: false + type: string +expose_by_default: + description: Expose devices in all supported domains by default. If set to false, you need to either expose domains or add the expose configuration option to each entity in entity_config and set it to true. + required: false + default: True + type: boolean +exposed_domains: + description: List of entity domains to expose to Google Assistant. + required: false + type: list +entity_config: + description: Entity specific configuration for Google Assistant + required: false + type: map + keys: + '`If after symlinking and adding `hdmi_cec:` to your configuration you are getting the following error in your logs,
`* failed to open vchiq instance` you will also need to add the user account Home Assistant runs under, to the `video` group. To add the Home Assistant user account to the `video` group, run the following command. `$ usermod -a -G video
+ It might be necessary to install an additional package: + `$ sudo apt-get install libavahi-compat-libdnssd-dev` +
+ ++ If you are upgrading Home Assistant from `0.65.x` and have used the HomeKit component, some accessories may not respond or may behave unusually. To fix these problems, you will need to remove the Home Assistant Bridge from your Home, stop Home Assistant and delete the `.homekit.state` file in your configuration folder and follow the Homekit [setup](#setup) steps again. +
+ +```yaml +# Example configuration.yaml entry configuring HomeKit +homekit: + filter: + include_domains: + - alarm_control_panel + - light + - media_player + entity_config: + alarm_control_panel.home: + code: 1234 + light.kitchen_table: + name: Kitchen Table Light + lock.front_door: + code: 1234 + media_player.living_room: + feature_list: + - feature: on_off + - feature: play_pause + - feature: play_stop + - feature: toggle_mute + switch.bedroom_outlet: + type: outlet +``` + +{% configuration %} + homekit: + description: HomeKit configuration. + required: true + type: map + keys: + auto_start: + description: Flag if the HomeKit Server should start automatically after the Home Assistant Core Setup is done. ([Disable Auto Start](#disable-auto-start)) + required: false + type: boolean + default: true + port: + description: Port for the HomeKit extension. + required: false + type: int + default: 51827 + name: + description: Need to be individual for each instance of Home Assistant using the component on the same local network. Between `3` and `25` characters. Alphanumeric and spaces allowed. + required: false + type: string + default: '`Home Assistant Bridge`' + ip_address: + description: The local network IP address. Only necessary if the default from Home Assistant does not work. + required: false + type: string + filter: + description: Filters for entities to be included / excluded from HomeKit. ([Configure Filter](#configure-filter)) + required: false + type: map + keys: + include_domains: + description: Domains to be included. + required: false + type: list + include_entities: + description: Entities to be included. + required: false + type: list + exclude_domains: + description: Domains to be excluded. + required: false + type: list + exclude_entities: + description: Entities to be excluded. + required: false + type: list + entity_config: + description: Configuration for specific entities. All subordinate keys are the corresponding entity ids to the domains, e.g. `alarm_control_panel.alarm`. + required: false + type: map + keys: + '`+ If you use Z-Wave, or `discovery:` you'll need to disable auto-start, see the [section below](#disable-auto-start) for details on how to do this. You'll then need to start the HomeKit component once Z-Wave is ready, or an appropriate delay to allow your entities to be discovered. +
+ +## {% linkable_title Setup %} + +To enable the `HomeKit` component in Home Assistant, add the following to your configuration file: + +```yaml +# Example for HomeKit setup +homekit: +``` + +After Home Assistant has started, the entities specified by the filter are exposed to `HomeKit` if they are [supported](#supported-components). To add them: +1. Open the Home Assistant frontend. A new card will display the `pin code`. +1. Open the `Home` app. +2. Choose `Add Accessory`, than select `Don't Have a Code or Can't Scan?` and enter the `pin code`. +4. Confirm the you are adding an `Uncertified Accessory` by clicking on `Add Anyway`. +5. Follow the setup be clicking on `Next` and lastly `Done` in the top right hand corner. +6. The `Home Assistant` Bridge and the Accessories should now be listed in the `Home` app. + +After the setup is completed you should be able to control your Home Assistant components through `Home` and `Siri`. + + +## {% linkable_title Considerations %} + + +### {% linkable_title Accessory ID %} + +Currently this component uses the `entity_id` to generate a unique `accessory id (aid)` for `HomeKit`. The `aid` is used to identify a device and save all configurations made for it. This however means that if you decide to change an `entity_id` all configurations for this accessory made in the `Home` app will be lost. + +### {% linkable_title Device Limit %} + +The HomeKit guidelines only allow a maximum of 100 unique accessories (`aid`) per bridge. Be mindful of this when configuring the filter(s). + +### {% linkable_title Persistence Storage %} + +Unfortunately `HomeKit` doesn't support any kind of persistent storage - only the configuration for accessories that are added to the `Home Assistant Bridge` are kept. To avoid problems it is recommended to use an automation to always start `HomeKit` with at least the same entities setup. If for some reason some entities are not setup, their config will be deleted. (State unknown or similar will not cause any issues.) + +A common situation might be if you decide to disable parts of the configuration for testing. Please make sure to disable `auto start` and `turn off` the `Start HomeKit` automation (if you have one). + + +## {% linkable_title Disable Auto Start %} + +Depending on your individual setup, it might be necessary to disable `Auto Start` for all accessories to be available for `HomeKit`. Only those entities that are fully setup when the `HomeKit` component is started, can be added. To start `HomeKit` when `auto_start: False`, you can call the service `homekit.start`. + +If you have Z-Wave entities you want exposed to HomeKit then you'll need to disable auto start and then start it after the Z-Wave mesh is ready. This is because the Z-Wave entities won't be fully set up until then. This can be automated using an automation: + +{% raw %} +```yaml +# Example for Z-Wave +homekit: + auto_start: False + +automation: + - alias: 'Start HomeKit' + trigger: + - platform: event + event_type: zwave.network_ready + - platform: event + event_type: zwave.network_complete + action: + - service: homekit.start +``` +{% endraw %} + +For a general delay where your component doesn't generate an event, you can also do: + +{% raw %} +```yaml +# Example using a delay after start of Home Assistant +homekit: + auto_start: False + +automation: + - alias: 'Start HomeKit' + trigger: + - platform: homeassistant + event: start + action: + - delay: 00:05 # Waits 5 minutes + - service: homekit.start +``` +{% endraw %} + + +## {% linkable_title Configure Filter %} + +By default no entity will be excluded. To limit which entities are being exposed to `HomeKit`, you can use the `filter` parameter. Keep in mind only [supported components](#supported-components) can be added. + +{% raw %} +```yaml +# Example filter to include specified domains and exclude specified entities +homekit: + filter: + include_domains: + - alarm_control_panel + - light + exclude_entities: + - light.kitchen_light +``` +{% endraw %} + +Filters are applied as follows: + +1. No includes or excludes - pass all entities +2. Includes, no excludes - only include specified entities +3. Excludes, no includes - only exclude specified entities +4. Both includes and excludes: + * 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 + - 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 + - if entity is included, pass (as #2 above) + - if entity include and exclude, the entity exclude is ignored + + +## {% linkable_title Supported Components %} + +The following components are currently supported: + +| Component | Type Name | Description | +| --------- | --------- | ----------- | +| alarm_control_panel | SecuritySystem | All security systems. | +| automation / input_boolean / remote / script | Switch | All represented as switches. | +| binary_sensor | Sensor | Support for `co2`, `door`, `garage_door`, `gas`, `moisture`, `motion`, `occupancy`, `opening`, `smoke` and `window` device classes. Defaults to the `occupancy` device class for everything else. | +| climate | Thermostat | All climate devices. | +| cover | GarageDoorOpener | All covers that support `open` and `close` and have `garage` as their `device_class`. | +| cover | WindowCovering | All covers that support `set_cover_position`. | +| cover | WindowCovering | All covers that support `open_cover` and `close_cover` through value mapping. (`open` -> `>=50`; `close` -> `<50`) | +| cover | WindowCovering | All covers that support `open_cover`, `stop_cover` and `close_cover` through value mapping. (`open` -> `>70`; `close` -> `<30`; `stop` -> every value in between) | +| device_tracker | Sensor | Support for `occupancy` device class. | +| fan | Fan | Support for `on / off`, `direction` and `oscillating`. | +| light | Light | Support for `on / off`, `brightness` and `rgb_color`. | +| lock | DoorLock | Support for `lock / unlock`. | +| media_player | MediaPlayer | Represented as a series of switches which control `on / off`, `play / pause`, `play / stop`, or `mute` depending on `supported_features` of entity and the `mode` list specified in `entity_config`. | +| sensor | TemperatureSensor | All sensors that have `Celsius` or `Fahrenheit` as their `unit_of_measurement` or `temperature` as their `device_class`. | +| sensor | HumiditySensor | All sensors that have `%` as their `unit_of_measurement` and `humidity` as their `device_class`. | +| sensor | AirQualitySensor | All sensors that have `pm25` as part of their `entity_id` or `pm25` as their `device_class` | +| sensor | CarbonDioxideSensor | All sensors that have `co2` as part of their `entity_id` or `co2` as their `device_class` | +| sensor | LightSensor | All sensors that have `lm` or `lx` as their `unit_of_measurement` or `illuminance` as their `device_class` | +| switch | Switch | Represented as a switch by default but can be changed by using `type` within `entity_config`. | + + +## {% linkable_title Error reporting %} + +If you encounter any issues or bug and want to report them on `GitHub`, please follow these steps to make it easier for others to help and get your issue solved. + +1. Enable debugging mode: +```yaml +logger: + default: warning + logs: + homeassistant.components.homekit: debug + pyhap: debug +``` +2. Reproduce the bug / problem you have encountered. +3. Stop Home Assistant and copy the log from the log file. That is necessary since some errors only get logged, when Home Assistant is being shutdown. +4. Follow this link: [home-assistant/issues/new](https://github.com/home-assistant/home-assistant/issues/new?labels=component: homekit) and open a new issue. +5. Fill out all fields and especially include the following information: + - The configuration entries for `homekit` and the `component` that is causing the issue. + - The log / traceback you have generated before. + - Screenshots of the failing entity in the `states` panel. + +## {% linkable_title Troubleshooting PIN not appearing %} + +In some instances, the PIN will not appear as a persistent status or in the log files despite deleting `.homekit.state`, enabling logging, and reboot. The log files will include the error ```Duplicate AID found when attempting to add accessory```. + +In such cases, modifying your configuration.yaml to add a filter limiting the included entities similar to the following: + +```yaml +filter: + include_domains: + - light +``` + +Restart Home-Assistant and re-attempt pairing - a persistent status should now correctly appear. diff --git a/source/_components/homekit_controller.markdown b/source/_components/homekit_controller.markdown new file mode 100644 index 00000000000..daa9e79b71e --- /dev/null +++ b/source/_components/homekit_controller.markdown @@ -0,0 +1,37 @@ +--- +layout: page +title: "HomeKit controller support" +description: "Instructions how to integrate your HomeKit devices within Home Assistant." +date: 2018-03-19 21:04 +sidebar: true +comments: false +sharing: true +footer: true +logo: apple-homekit.png +ha_category: Hub +ha_release: 0.68 +ha_iot_class: "Local Polling" +--- + +[HomeKit](https://developer.apple.com/homekit/) controller integration for Home Assistant allows you to connect HomeKit accessories to Home Assistant. This component should not be confused with the [HomeKit](/components/homekit/) component, which allows you to control Home Assistant devices via HomeKit. + ++ You may need additional packages to support the HomeKit Python module: + `$ sudo apt-get install libgmp-dev libmpfr-dev libmpc-dev` +
+ +There is currently support for the following device types within Home Assistant: + +- [Climate](/components/climate.homekit_controller/) +- [Light](/components/light.homekit_controller/) +- [Switch](/components/switch.homekit_controller/) + +The component will be automatically configured if the [`discovery:`](/components/discovery/) component is enabled and an enable entry added for HomeKit: + +```yaml +discovery: + enable: + - homekit +``` + +For each detected HomeKit accessory, a configuration prompt will appear in the web front end. Use this to provide the HomeKit PIN. Note that HomeKit accessories can only be paired to one device at once. If your device is currently paired with Siri, you will need to reset it in order to pair it with Home Assistant. Once Home Assistant is configured to work with the device, you can export it back to Siri with the [`HomeKit`](/components/homekit/) component. diff --git a/source/_components/homematic.markdown b/source/_components/homematic.markdown index 93cf903eb44..5f860b4d6d0 100644 --- a/source/_components/homematic.markdown +++ b/source/_components/homematic.markdown @@ -2,7 +2,7 @@ layout: page title: "Homematic" description: "Instructions for integrating Homematic into Home Assistant." -date: 2016-11-27 21:38 +date: 2018-02-13 19:10 sidebar: true comments: false sharing: true @@ -13,73 +13,82 @@ ha_iot_class: "Local Push" featured: false --- - -The [Homematic](http://www.homematic.com/) component provides bi-directional communication with your CCU/Homegear. It uses a XML-RPC connection to set values on devices and subscribes to receive events the devices and the CCU emit. +The [Homematic](http://www.homematic.com/) component provides bi-directional communication with your CCU/Homegear. It uses a XML-RPC connection to set values on devices and subscribes to receive events the devices and the CCU emit. If you are using Homegear with paired [Intertechno](http://intertechno.at/) devices, uni-directional communication is possible as well. Device support is available for most of the wired and wireless devices, as well as a few IP devices. If you have a setup with mixed protocols, you have to configure additional hosts with the appropriate ports. The default is using port 2001, which are wireless devices. Wired devices usually are available through port 2000 and IP devices through port 2010. The virtual thermostatgroups the CCU provides use port 9292 **and** require you to set the `path` setting to `/groups`. -If you want to see if a specific device you have is supported, head over to the [pyhomematic](https://github.com/danielperna84/pyhomematic/tree/master/pyhomematic/devicetypes) repository and browse through the source code. A dictionary with the device identifiers (e.g. HM-Sec-SC-2) can be found within the relevant modules near the bottom. If your device is not supported, feel free to contribute. +If you want to see if a specific device you have is supported, head over to the [pyhomematic](https://github.com/danielperna84/pyhomematic/tree/master/pyhomematic/devicetypes) repository and browse through the source code. A dictionary with the device identifiers (e.g., HM-Sec-SC-2) can be found within the relevant modules near the bottom. If your device is not supported, feel free to contribute. We automatically detect all devices we currently support and try to generate useful names. If you enable name-resolving, we try to fetch names from Metadata (Homegear), via JSON-RPC or the XML-API you may have installed on your CCU. Since this may fail this is disabled by default. -You can manually rename the created entities by using Home Assistants [Customizing](https://home-assistant.io/getting-started/customizing-devices/) feature. With it you are also able to hide entities you don't want to see in the UI. +You can manually rename the created entities by using Home Assistant's [Customizing](/docs/configuration/customizing-devices/) feature. With it you are also able to hide entities you don't want to see in the UI. To set up the component, add the following information to your `configuration.yaml` file: ```yaml homematic: - hosts: + interfaces: wireless: - ip: 127.0.0.1 + host: 127.0.0.1 ``` Configuration variables (global): -- **hosts** (*Required*): Configuration for each host to integrate into Home Assistant. +- **interfaces** (*Required*): Configuration for each XML-RPC interface to integrate into Home Assistant. +- **hosts** (*Optional*): Configuration for each Hub (CCU/Homegear) to integrate into Home Assistant. - **local_ip** (*Optional*): IP of device running Home Assistant. Override auto-detected value for exotic network setups. - **local_port** (*Optional*): Port for connection with Home Assistant. By default it is randomly assigned. -Configuration variables (host): +Configuration variables (interface): -- **ip** (*Required*): IP address of CCU/Homegear device. +- **host** (*Required*): IP address or Hostname of CCU/Homegear device or Hass.io add-on. - **port** (*Optional*): Port of CCU/Homegear XML-RPC Server. Wireless: 2001, wired: 2000, IP: 2010, thermostatgroups: 9292. - **callback_ip** (*Optional*): Set this, if Home Assistant is reachable under a different IP from the CCU (NAT, Docker etc.). - **callback_port** (*Optional*): Set this, if Home Assistant is reachable under a different port from the CCU (NAT, Docker etc.). - **resolvenames** (*Optional*): [`metadata`, `json`, `xml`] Try to fetch device names. Defaults to `false` if not specified. +- **jsonport** (*Optional*): Port of CCU JSON-RPC Server. The default is 80, but it may be different when running CCU virtually via Docker. - **username** (*Optional*): When fetching names via JSON-RPC, you need to specify a user with guest-access to the CCU. - **password** (*Optional*): When fetching names via JSON-RPC, you need to specify the password of the user you have configured above. -- **primary** (*Optional*): Set to `true` when using multiple hosts and this host should provide the services and variables. -- **variables** (*Optional*): Set to `true` if you want to use CCU2/Homegear variables. Should only be enabled for the primary host. When using a CCU credentials are required. - **path** (*Optional*): Set to `/groups` when using port 9292. +Configuration variables (host): + +- **host** (*Required*): IP address of CCU/Homegear device. +- **username** (*Optional*): When fetching names via JSON-RPC, you need to specify a user with guest-access to the CCU. +- **password** (*Optional*): When fetching names via JSON-RPC, you need to specify the password of the user you have configured above. + #### Example configuration with multiple protocols and some other options set: ```yaml homematic: - hosts: + interfaces: rf: - ip: 127.0.0.1 + host: 127.0.0.1 resolvenames: json username: Admin password: secret - primary: true - variables: true wired: - ip: 127.0.0.1 + host: 127.0.0.1 port: 2000 resolvenames: json username: Admin password: secret ip: - ip: 127.0.0.1 + host: 127.0.0.1 port: 2010 groups: - ip: 127.0.0.1 + host: 127.0.0.1 port: 9292 resolvenames: json username: Admin password: secret path: /groups + hosts: + ccu2: + host: 127.0.0.1 + username: Admin + password: secret + ``` ### {% linkable_title The `resolvenames` option %} @@ -100,7 +109,7 @@ This does *not* affect the entities in Home Assistant. They all use their own co ### {% linkable_title Reading attributes of entities %} -Most devices have, besides their state, additional attributes like their battery state or valve position. These can be accessed using templates in automations, or even as their own entities using the [template sensor](https://home-assistant.io/components/sensor.template/) component. Here's an example of a template sensor that exposes the valve state of a thermostat. +Most devices have, besides their state, additional attributes like their battery state or valve position. These can be accessed using templates in automations, or even as their own entities using the [template sensor](/components/sensor.template/) component. Here's an example of a template sensor that exposes the valve state of a thermostat. ```yaml sensor: @@ -115,19 +124,19 @@ sensor: ### {% linkable_title Variables %} It is possible to read and set values of system variables you have setup on the CCU/Homegear. The supported types for setting values are float- and bool-variables. -The states of the variables are available through the attributes of your hub entity (e.g. `homematic.rf`). Use templates (as mentioned above) to make your variables available to automations or as entities. +The states of the variables are available through the attributes of your hub entity (e.g., `homematic.ccu2`). Use templates (as mentioned above) to make your variables available to automations or as entities. The values of variables are polled from the CCU/Homegear in an interval of 30 seconds. Setting the value of a variable happens instantly and is directly pushed. ### {% linkable_title Events %} When HomeMatic devices change their state or some other internal value, the CCU/Homegear sends event messages to Home Assistant. These events are automatically parsed and the entities in Home Assistant are updated. However, you can also manually use these events to trigger automations. Two event-types are available: -* **homematic.keypress**: For devices with buttons, see information below -* **homematic.impulse**: For impulse sensors +- **homematic.keypress**: For devices with buttons, see information below +- **homematic.impulse**: For impulse sensors #### {% linkable_title Devices with buttons %} -Devices with buttons (e.g. HM-Sen-MDIR-WM55, remote controls) may not be fully visible in the UI. This is intended, as buttons don't serve any value here and all they do is trigger events. +Devices with buttons (e.g., HM-Sen-MDIR-WM55, remote controls) may not be fully visible in the UI. This is intended, as buttons don't serve any value here and all they do is trigger events. As an example: The HM-Sen-MDIR-WM55 motion detector will be displayed as 2 entities. A motion sensor and a brightness sensor. On top of that we have 2 sets (one set per button) of 4 events: PRESS_SHORT, PRESS_LONG, PRESS_CONT, PRESS_LONG_RELEASE. Be aware, that there are devices which don't provide all of these events. But in general: if you can press it, it usually at least has PRESS_SHORT. @@ -148,17 +157,41 @@ automation: ``` The channel parameter is equal to the channel of the button you are configuring the automation for. You can view the available channels in the UI you use to pair your devices. -The name depends on if you chose to resolve names or not. If not, it will be the device ID (e.g. LEQ1234657). If you chose to resolve names (and that is successful), it will be the name you have set in your CCU or in the metadata (e.g. "Kitchen Switch"). +The name depends on if you chose to resolve names or not. If not, it will be the device ID (e.g., LEQ1234657). If you chose to resolve names (and that is successful), it will be the name you have set in your CCU or in the metadata (e.g., "Kitchen Switch"). + +You can test whether your button works within Home Assistant if you look at the terminal output. When pressing a button, lines similar to those should appear: + +```bash +2018-01-27 11:51:32 INFO (Thread-12) [pyhomematic.devicetypes.generic] HMGeneric.event: address=MEQ1234567:6, interface_id=homeassistant-CCU2, key=PRESS_SHORT, value=True +2018-01-27 11:51:32 INFO (MainThread) [homeassistant.core] Bus:Handling+Don't use option `server_host` on a hass.io installation! +
+ ```yaml # Example configuration.yaml entry http: @@ -26,18 +30,20 @@ http: Configuration variables: - **api_password** (*Optional*): Protect Home Assistant with a password. -- **server_host** (*Optional*): Only listen to incoming requests on specific IP/host (default: accept all) +- **server_host** (*Optional*): Only listen to incoming requests on specific IP/host (default: bind to `0.0.0.0` which means accept all IPv4 connections). Use `server_host: "::0"` if you want to listen to (and only) IPv6. - **server_port** (*Optional*): Let you set a port to use. Defaults to 8123. - **base_url** (*Optional*): The URL that Home Assistant is available on the internet. For example: `hass-example.duckdns.org:8123`. Defaults to the local IP address. The iOS app finds local installations, if you have an outside URL use this so that you can auto-fill when discovered in the app. - **ssl_certificate** (*Optional*): Path to your TLS/SSL certificate to serve Home Assistant over a secure connection. +- **ssl_peer_certificate** (*Optional*): Path to the client/peer TLS/SSL certificate to accept secure connections from. - **ssl_key** (*Optional*): Path to your TLS/SSL key to serve Home Assistant over a secure connection. -- **cors_allowed_origins** (*Optional*): A list of origin domain names to allow [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) requests from. Enabling this will set the `Access-Control-Allow-Origin` header to the Origin header if it is found in the list, and the `Access-Control-Allow-Headers` header to `Origin, Accept, X-Requested-With, Content-type, X-HA-access`. You must provide the exact Origin, i.e. `https://home-assistant.io` will allow requests from `https://home-assistant.io` but __not__ `http://home-assistant.io`. -- **use_x_forwarded_for** (*Optional*): Enable parsing of the `X-Forwarded-For` header, passing on the client's correct IP address in proxied setups. You should only enable this in a trustworthy network environment, as clients passing that header could easily spoof their source IP address. Defaults to False. -- **trusted_networks** (*Optional*): List of trusted networks, consisting of IP addresses or networks, that are allowed to bypass password protection when accessing Home Assistant. It should be noted that if you use a reverse proxy, all requests to Home Assistant, regardless of source, will arrive from the reverse proxy IP address. Therefore in a reverse proxy scenario, this option should be used with extreme care. +- **cors_allowed_origins** (*Optional*): A list of origin domain names to allow [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) requests from. Enabling this will set the `Access-Control-Allow-Origin` header to the Origin header if it is found in the list, and the `Access-Control-Allow-Headers` header to `Origin, Accept, X-Requested-With, Content-type, X-HA-access`. You must provide the exact Origin, i.e. `https://www.home-assistant.io` will allow requests from `https://www.home-assistant.io` but __not__ `http://www.home-assistant.io`. +- **use_x_forwarded_for** (*Optional*): Enable parsing of the `X-Forwarded-For` header, passing on the client's correct IP address in proxied setups. You must also whitelist trusted proxies using the `trusted_proxies` setting below for this to work. Non-whitelisted requests with this header will be considered IP spoofing attacks, and the header will, therefore, be ignored. Defaults to False. +- **trusted_proxies** (*Optional*): List of trusted proxies, consisting of IP addresses or networks, that are allowed to set the `X-Forwarded-For` header. This is required when using `use_x_forwarded_for` because all requests to Home Assistant, regardless of source, will arrive from the reverse proxy IP address. Therefore in a reverse proxy scenario, this option should be set with extreme care. +- **trusted_networks** (*Optional*): List of trusted networks, consisting of IP addresses or networks, that are allowed to bypass password protection when accessing Home Assistant. If using a reverse proxy with the `use_x_forwarded_for` option enabled, requests proxied to Home Assistant with a trusted `X-Forwarded-For` header will appear to come from the IP given in that header instead of the proxy IP. - **ip_ban_enabled** (*Optional*): Flag indicating whether additional IP filtering is enabled. Defaults to False. - **login_attempts_threshold** (*Optional*): Number of failed login attempt from single IP after which it will be automatically banned if `ip_ban_enabled` is True. Defaults to -1, meaning that no new automatic bans will be added. -The sample below shows a configuration entry with possible values: +The sample below shows a configuration entry with possible values: ```yaml # Example configuration.yaml entry @@ -48,40 +54,55 @@ http: ssl_key: /etc/letsencrypt/live/hass.example.com/privkey.pem cors_allowed_origins: - https://google.com - - https://home-assistant.io + - https://www.home-assistant.io use_x_forwarded_for: True + trusted_proxies: + - 127.0.0.1 + - ::1 trusted_networks: - 127.0.0.1 - ::1 - 192.168.0.0/24 - - 2001:DB8:ABCD::/48 + - fd00::/8 ip_ban_enabled: True login_attempts_threshold: 5 ``` The [Set up encryption using Let's Encrypt](/blog/2015/12/13/setup-encryption-using-lets-encrypt/) blog post gives you details about the encryption of your traffic using free certificates from [Let's Encrypt](https://letsencrypt.org/). -Or use a self signed certificate following the instructions here [Self-signed certificate for SSL/TLS](/docs/ecosystem/certificates/tls_self_signed_certificate/) +Or use a self signed certificate following the instructions here [Self-signed certificate for SSL/TLS](/docs/ecosystem/certificates/tls_self_signed_certificate/). -On top of the `http` component is a [REST API](/developers/rest_api/) and a [Python API](/developers/python_api/) available. There is also support for [Server-sent events](/developers/server_sent_events/). +## {% linkable_title APIs %} -The `http` platforms are not real platforms within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) sends and receives messages over HTTP. +On top of the `http` component is a [REST API](/developers/rest_api/), [Python API](/developers/python_api/) and [WebSocket API](/developers/websocket_api/) available. There is also support for [Server-sent events](/developers/server_sent_events/). + +The `http` platforms are not real platforms within the meaning of the terminology used around Home Assistant. Home Assistant's [REST API](/developers/rest_api/) sends and receives messages over HTTP. + +## {% linkable_title HTTP sensors %} To use those kind of [sensors](/components/sensor.http/) or [binary sensors](components/binary_sensor.http/) in your installation no configuration in Home Assistant is needed. All configuration is done on the devices themselves. This means that you must be able to edit the target URL or endpoint and the payload. The entity will be created after the first message has arrived. All [requests](/developers/rest_api/#post-apistatesltentity_id) need to be sent to the endpoint of the device and must be **POST**. -If you want to use Home Assistant to host or serve static files then create a directory called `www` under the `.homeassistant` configuration path. The static files in `.homeassistant/www/` can be accessed by the following URL `http://your.domain:8123/local/`. +## {% linkable_title IP filtering and banning %} -If you want to apply additional IP filtering, and automatically ban brute force attempts, set `ip_ban_enabled` to `True` and the maximum number of attempts. After the first ban, an `ip_bans.yaml` file will be created in the root configuration folder. It will have the banned IP address and time in UTC when it was added: +If you want to apply additional IP filtering, and automatically ban brute force attempts, set `ip_ban_enabled` to `True` and the maximum number of attempts. After the first ban, an `ip_bans.yaml` file will be created in the root configuration folder. It will have the banned IP address and time in UTC when it was added: ```yaml 127.0.0.1: banned_at: '2016-11-16T19:20:03' ``` -After a ban is added a Persistent Notification is populated to the Home Assistant frontend. +After a ban is added a Persistent Notification is populated to the Home Assistant frontend.-Please note, that sources from `trusted_networks` won't be banned automatically. +Please note, that sources from `trusted_networks` won't be banned automatically. +
+ +## {% linkable_title Hosting files %} + +If you want to use Home Assistant to host or serve static files then create a directory called `www` under the configuration path (`/config` on Hass.io, `.homeassistant` elsewhere). The static files in `www/` can be accessed by the following URL `http://your.domain:8123/local/`, for example `audio.mp3` would be accessed as `http://your.domain:8123/local/audio.mp3`. + ++ If you've had to create the `www/` folder for the first time, you'll need to restart Home Assistant.
diff --git a/source/_components/hue.markdown b/source/_components/hue.markdown new file mode 100644 index 00000000000..ce0244b72ef --- /dev/null +++ b/source/_components/hue.markdown @@ -0,0 +1,154 @@ +--- +layout: page +title: "Philips Hue" +description: "Instructions on setting up Philips Hue within Home Assistant." +date: 2017-11-29 23:51 +sidebar: true +comments: false +sharing: true +footer: true +logo: philips_hue.png +ha_category: Hub +ha_iot_class: "Local Polling" +featured: true +ha_release: "0.60" +--- + +Philips Hue support is integrated into Home Assistant as a Hub that can drive the light platform. The preferred way to setup the Philips Hue platform is by enabling the [discovery component](/components/discovery/). + +Once discovered, if you have a custom default view, locate `configurator.philips_hue` in the entities list ( < > ) and add it to a group in `configuration.yaml`. Restart Home Assistant so that the configurator is visible in the Home Assistant dashboard. Once Home Assistant is restarted, locate and click on `configurator.philips_hue` to bring up the initiation dialog. This will prompt you to press the Hue button to register the Hue hub in Home Assistant. Once complete, the configurator entity isn't needed anymore and can be removed from any visible group in `configuration.yaml`. + +When you configure the Hue bridge from Home Assistant, it writes a token to a file in your Home Assistant [configuration directory](/docs/configuration/). That token authenticates the communication with the Hue bridge. This token uses the Address of the Hue Bridge. If the IP address for the Hue Bridge changes, you will need to register the Hue Bridge with Home Assistant again. To avoid this you may set up DHCP registration for your Hue Bridge, so that it always has the same IP address. + +Once registration is complete you should see the Hue lights listed as `light` entities. If you don't you may have to restart Home Assistant once more. Add these light entities to `configuration.yaml` file and restart Home Assistant once more to complete the installation. + +If you want to enable the component without relying on the [discovery component](/components/discovery/), add the following lines to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +hue: + bridges: + - host: DEVICE_IP_ADDRESS +``` + +Configuration variables: + +- **host** (*Required*): The IP address of the device, eg. 192.168.1.10. Required if not using the `discovery` component to discover Hue bridges. +- **allow_unreachable** (*Optional*): (true/false) This will allow unreachable bulbs to report their state correctly. +- **filename** (*Optional*): Make this unique if specifying multiple Hue hubs. +- **allow_hue_groups** (*Optional*): (true/false) Enable this to stop Home Assistant from importing the groups defined on the Hue bridge. + +## {% linkable_title Examples %} + +```yaml +# Example configuration.yaml entry specifying optional parameters +hue: + bridges: + - host: DEVICE_IP_ADDRESS + allow_unreachable: true + allow_hue_groups: true +``` + +### {% linkable_title Migrating from older configuration %} + +In previous versions of the `hue` component the configuration looked different: + +```yaml +# Example configuration.yaml entry +light: + - platform: hue + host: DEVICE_IP_ADDRESS +``` + +You will need to convert each bridge into an entry in the new configuration style. See above for an example. + +### {% linkable_title Multiple Hue bridges %} + +Multiple Hue bridges work transparently with discovery, you don't have to do anything. If you prefer to configure them manually and use multiple Hue bridges then it's needed that you provide a configuration file for every bridge. The bridges can't share a single configuration file. + +Add `filename` to your Hue configuration entry in your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +hue: + bridges: + - host: BRIDGE1_IP_ADDRESS + filename: phue.conf + - host: BRIDGE2_IP_ADDRESS + filename: phue2.conf +``` + +### {% linkable_title Using Hue Groups in Home Assistant %} + +The Hue API allows you to group lights. Home Assistant also supports grouping of entities natively, but sometimes it can be useful to use Hue Groups to group light bulbs. By doing so, Home Assistant only needs to send one API call to change the state of all the bulbs in those groups instead of one call for every light in the group. This causes all the bulbs to change state simultaneously. + +These Hue Groups can be a `Luminaire`, `Lightsource`, `LightGroup` or `Room`. The `Luminaire` and `Lightsource` can't be created manually since the Hue bridge manages these automatically based on the discovered bulbs. The `Room` and `LightGroup` can be created manually through the API, or the mobile app. A bulb can only exist in one `Room`, but can exist in multiple `LightGroup`. The `LightGroup` can be useful to link certain bulbs together since. + +The 2nd generation Hue app only allows to create a `Room`. You need to use the first generation app or the API to create a `LightGroup`. + +Example: + +To create a `LightGroup` named `Ceiling lights` that contains the lights 1, 2 and 3, execute the following command: + +```bash +$ curl -XPOST -d '{"name": "Ceiling lights", "lights": ["1", "2", "3"]}' http://+ To support Hue Light Groups, your bridge needs to have at least firmware 1.13 (released on June 3, 2016). +
+ +More information can be found on the [Philips Hue API documentation](https://www.developers.meethue.com/documentation/groups-api#22_create_group) website. + + +### {% linkable_title Using Hue Scenes in Home Assistant %} + +The Hue platform has its own concept of scenes for setting the colors of a group of lights at once. Hue Scenes are very cheap, get created by all kinds of apps (as it is the only way to have 2 or more lights change at the same time), and are rarely deleted. A typical Hue hub might have hundreds of scenes stored in them, many that you've never used, almost all very poorly named. + +To avoid user interface overload we don't expose scenes directly. Instead there is a hue.hue_activate_scene service which can be used by `automation` or `script` components. +This will have all the bulbs transitioned at once, instead of one at a time using standard scenes in Home Assistant. + +For instance: + +```yaml +script: + porch_on: + sequence: + - service: hue.hue_activate_scene + data: + group_name: "Porch" + scene_name: "Porch Orange" +``` + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `group_name` | no | The group/room name of the lights. Find this in the Hue official app. +| `scene_name` | no | The name of the scene. Find this in the Hue official app. + +*Note*: `group_name` is not linked to Home Assistant group name. + +### {% linkable_title Finding Group and Scene Names %} + +How do you find these names? + +The easiest way to do this is only use the scenes from the 2nd generation Hue app. That is organized by room (group) and scene Name. Use the values of room name and scene name that you see in the app. You can test these work on the `dev-service` console of your Home Assistant instance. + +Alternatively, you can dump all rooms and scene names using this [gist](https://gist.github.com/sdague/5479b632e0fce931951c0636c39a9578). This does **not** tell you which groups and scenes work together but it's sufficient to get values that you can test in the `dev-service` console. + +### {% linkable_title Caveats %} + +The Hue API doesn't activate scenes directly, only on a Hue Group (typically rooms, especially if using the 2nd gen app). But Hue Scenes don't actually reference their group. So heuristic matching is used. + +Neither group names or scene names are guaranteed unique in Hue. If you are getting non deterministic behavior, adjust your Hue scenes via the App to be more identifying. + +The Hue hub has limited spaces for scenes, and will delete scenes if new ones get created that would overflow that space. The API docs say this is based on "Least Recently Used". diff --git a/source/_components/hydrawise.markdown b/source/_components/hydrawise.markdown new file mode 100644 index 00000000000..3c29b449166 --- /dev/null +++ b/source/_components/hydrawise.markdown @@ -0,0 +1,40 @@ +--- +layout: page +title: "Hunter Hydrawise" +description: "Instructions on how to integrate your Hunter Hydrawise Wi-Fi irrigation control system within Home Assistant." +date: 2018-04-11 08:02 +sidebar: true +comments: false +sharing: true +footer: true +logo: hydrawise_logo.png +ha_category: Hub +ha_release: 0.71 +ha_iot_class: Cloud Polling +--- + +The `hydrawise` component allows you to integrate your [Hunter Hydrawise](https://hydrawise.com) Wi-Fi irrigation controller system in Home Assistant. + +To enable it, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +hydrawise: + access_token: YOUR_API_KEY +``` + +{% configuration %} +access_token: + description: The API KEY assigned to your Hydrawise account. + required: true + type: string +scan_interval: + description: The time interval, in seconds, to poll the Hydrawise cloud. + required: false + type: int + default: 30 +{% endconfiguration %} + +To get your API access token log into your [Hydrawise account](https://app.hydrawise.com/config/account) and in the 'My Account Details' section under Account Settings click 'Generate API Key'. Enter that key in your configuration file as the `API_KEY`. + +Finish the configuration by visiting the [Hydrawise binary sensor](/components/binary_sensor.hydrawise/), [Hydrawise sensor](/components/sensor.hydrawise/) and [Hydrawise switch](/components/switch.hydrawise/) documentation. diff --git a/source/_components/ifttt.manything.markdown b/source/_components/ifttt.manything.markdown index 7288afb90b9..84d0228bc15 100644 --- a/source/_components/ifttt.manything.markdown +++ b/source/_components/ifttt.manything.markdown @@ -1,7 +1,7 @@ --- layout: page title: "ManyThing" -description: "Instructions how to setup ManyThing support with IFTTT." +description: "Instructions on how to setup ManyThing support with IFTTT." date: 2015-09-07 18:00 sidebar: true comments: false diff --git a/source/_components/ifttt.markdown b/source/_components/ifttt.markdown index fc330b5f799..9f48303946c 100644 --- a/source/_components/ifttt.markdown +++ b/source/_components/ifttt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "IFTTT" -description: "Instructions how to setup IFTTT within Home Assistant." +description: "Instructions on how to setup IFTTT within Home Assistant." date: 2015-09-07 18:00 sidebar: true comments: false @@ -21,7 +21,7 @@ ifttt: key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ``` -`key` is your API key which can be obtained by viewing the **Settings** of the [Webhooks applet](https://ifttt.com/services/maker_webhooks/settings). It's the last part of the URL (e.g. https://maker.ifttt.com/use/MYAPIKEY) you will find under **My Applets** > **Webhooks** > **Settings**. +`key` is your API key which can be obtained by viewing the **Settings** of the [Webhooks applet](https://ifttt.com/services/maker_webhooks/settings). It's the last part of the URL (e.g., https://maker.ifttt.com/use/MYAPIKEY) you will find under **My Applets** > **Webhooks** > **Settings**.@@ -64,6 +64,7 @@ Choose "Webhooks" as service. You need to setup a unique trigger for each event you sent to IFTTT.
+{% raw %} ```yaml # Example configuration.yaml Automation entry automation: @@ -75,9 +76,11 @@ automation: service: ifttt.trigger data: {"event":"TestHA_Trigger", "value1":"Hello World!"} ``` +{% endraw %} IFTTT can also be used in scripts and with `data_template`. Here is the above automation broken into an automation and script using variables and data_templates. +{% raw %} ```yaml # Example configuration.yaml Automation entry automation: @@ -89,10 +92,12 @@ automation: service: script.ifttt_notify data_template: value1: 'HA Status:' - value2: {% raw %}"{{ trigger.event.data.entity_id.split('_')[1] }} is "{% endraw %} - value3: {% raw %}"{{ trigger.event.data.to_state.state }}"{% endraw %} + value2: "{{ trigger.event.data.entity_id.split('_')[1] }} is " + value3: "{{ trigger.event.data.to_state.state }}" ``` +{% endraw %} +{% raw %} ```yaml #Example Script to send TestHA_Trigger to IFTTT but with some other data (homeassistant UP). ifttt_notify: @@ -100,6 +105,7 @@ ifttt_notify: - service: ifttt.trigger data_template: {"event":"TestHA_Trigger", "value1":"{{ value1 }}", "value2":"{{ value2 }}", "value3":"{{ value3 }}"} ``` +{% endraw %} ### {% linkable_title Sending events from IFTTT to Home Assistant %} diff --git a/source/_components/ihc.markdown b/source/_components/ihc.markdown new file mode 100644 index 00000000000..0030d30361f --- /dev/null +++ b/source/_components/ihc.markdown @@ -0,0 +1,90 @@ +--- +layout: page +title: "IHC" +description: "Instructions on how to integrate the IHC components with Home Assistant" +date: 2017-11-11 22:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: ihc.png +ha_category: Hub +ha_release: "0.62" +ha_iot_class: "Local Push" +--- + +IHC Controller integration for Home Assistant allows you to connect the LK IHC controller to Home Assistant. +(The controller is sold under other names in different countries - "ELKO Living system" in Sweden and Norway) + +An `ihc` section must be present in the `configuration.yaml` file and contain the following options: + +```yaml +# Example configuration.yaml entry +ihc: + url: http://192.168.1.3 + username: admin + password: mysecret + auto_setup: True + info: True +``` + +{% configuration %} +auto_setup: + description: True to have IHC products auto setup. + required: false + type: bool +info: + description: If True additional IHC info will be shown on each component. + required: false + type: bool +password: + description: The password for the IHC Controller. + required: true + type: string +url: + description: The URL of the IHC Controller. + required: true + type: string +username: + description: The username for the IHC Controller. + required: true + type: string +{% endconfiguration %} + +The info option will show the IHC "name", "note" and "position" attributes. +This will make it easier to identify the IHC products within Home Assistant + +There is currently support for the following device types within Home Assistant: + +- [Binary Sensor](/components/binary_sensor.ihc/) +- [Sensor](/components/sensor.ihc/) +- [Light](/components/light.ihc/) +- [Switch](/components/switch.ihc/) + +### Auto setup of IHC products + +If the auto setup is enabled, the `ihc` component will automatically find IHC products and insert these as devices in Home Assistant. +To disable this set auto_setup to False. (Auto setup is on by default) +See the individual device types for a list of IHC products to be recognized automatically. + +Components will get a default name that is a combination of the IHC group and IHC resource id. +If you want to change the display names use the [Customizing entities](/docs/configuration/customizing-devices/) + +### {% linkable_title Manual setup %} + +Each device is associated with an IHC resource id. +To manually setup components you specify resource ids from the IHC project. +(The IHC project is the file you edit/upload to the IHC Controller using LK IHC Visual - or similar program if your controller is not the LK brand). +The project file is an XML file and you can view it with any text/XML editor. +You can rename it to have the XML extension and use a browser like Chrome or Internet Explorer. +The resources are the \+If the platform fails to load because it could not install its requirement, install cmake: `sudo apt-get install cmake`. +
diff --git a/source/_components/image_processing.facebox.markdown b/source/_components/image_processing.facebox.markdown new file mode 100644 index 00000000000..ebb9892aad8 --- /dev/null +++ b/source/_components/image_processing.facebox.markdown @@ -0,0 +1,133 @@ +--- +layout: page +title: "Facebox" +description: "Detect and recognize faces with Facebox." +date: 2018-05-03 00:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: machine-box.png +ha_category: Image Processing +featured: false +ha_release: 0.70 +--- + +The `facebox` image processing platform allows you to detect and recognize faces in a camera image using [Facebox](https://machinebox.io/docs/facebox). The state of the entity is the number of faces detected, and recognized faces are listed in the `matched_faces` attribute. An `image_processing.detect_face` event is fired for each recognized face, and the event `data` provides the `confidence` of recognition, the `name` of the person, the `image_id` of the image associated with the match, the `bounding_box` that contains the face in the image, and the `entity_id` that processing was performed on. + +## {% linkable_title Setup %} + +Facebox runs in a Docker container and it is recommended that you run this container on a machine with a minimum of 2 GB RAM. On your machine with Docker, run the Facebox container with: + +```bash +MB_KEY="INSERT-YOUR-KEY-HERE" + +sudo docker run --name=facebox --restart=always -p 8080:8080 -e "MB_KEY=$MB_KEY" machinebox/facebox +``` + +If you only require face detection (number of faces) you can disable face recognition by adding `-e "MB_FACEBOX_DISABLE_RECOGNITION=true"` to the `docker run` command. + +## {% linkable_title Configuration %} + +To enable this platform in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +image_processing: + - platform: facebox + ip_address: 192.168.0.1 + port: 8080 + source: + - entity_id: camera.local_file + name: my_custom_name +``` + +{% configuration %} +ip_address: + description: The IP address of your machine hosting Facebox. + required: true + type: string +port: + description: The port which Facebox is exposed on. + required: true + type: string +source: + description: The list of image sources. + required: true + type: map + keys: + entity_id: + description: A camera entity id to get picture from. + required: true + type: string + name: + description: This parameter allows you to override the name of your `image_processing` entity. + required: false + type: string +{% endconfiguration %} + +## {% linkable_title Automations %} + +Use the `image_processing.detect_face` events to trigger automations, and breakout the `trigger.event.data` using a [data_template](https://www.home-assistant.io/docs/automation/templating/). The following example automation sends a notification when Ringo Star is recognized: + +{% raw %} +```yaml +- id: '12345' + alias: Ringo Starr recognised + trigger: + platform: event + event_type: image_processing.detect_face + event_data: + name: 'Ringo_Starr' + action: + service: notify.platform + data_template: + message: Ringo_Starr recognised with probability {{ trigger.event.data.confidence }} + title: Door-cam notification +``` +{% endraw %} + +## {% linkable_title Service `facebox_teach_face` %} + +The service `facebox_teach_face` can be used to teach Facebox faces. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | no | Entity ID of Facebox entity. +| `name` | no | The name to associate with a face. +| `file_path` | no | The path to the image file. + +A valid service data example: + +{% raw %} +```yaml +{ + "entity_id": "image_processing.facebox_local_file", + "name": "superman", + "file_path": "/images/superman_1.jpeg" +} +``` +{% endraw %} + +An `image_processing.teach_classifier` event is fired for each service call, providing feedback on whether teaching has been successful or unsuccessful. In the unsuccessful case, the `message` field of the `event_data` will contain information on the cause of failure, and a warning is also published in the logs. An automation can be used to receive alerts on teaching, for example, the following automation will send a notification with the teaching image and a message describing the status of the teaching: + +```yaml +- id: '11200961111' + alias: Send facebox teaching result + trigger: + platform: event + event_type: image_processing.teach_classifier + event_data: + classifier: facebox + action: + service: notify.platform + data_template: + title: Facebox teaching + message: Name {{ trigger.event.data.name }} teaching was successful? {{ trigger.event.data.success }} + data: + file: ' {{trigger.event.data.file_path}} ' +``` + +## {% linkable_title Optimising resources %} + +[Image processing components](https://www.home-assistant.io/components/image_processing/) process the image from a camera at a fixed period given by the `scan_interval`. This leads to excessive processing if the image on the camera hasn't changed, as the default `scan_interval` is 10 seconds. You can override this by adding to your config `scan_interval: 10000` (setting the interval to 10,000 seconds), and then call the `image_processing.scan` service when you actually want to perform processing. diff --git a/source/_components/image_processing.markdown b/source/_components/image_processing.markdown index e74ef6ec5c8..1f1507bf280 100644 --- a/source/_components/image_processing.markdown +++ b/source/_components/image_processing.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Image Processing" -description: "Instructions how to setup image processing with Home Assistant." +description: "Instructions on how to setup image processing with Home Assistant." date: 2017-01-09 00:00 sidebar: true comments: false @@ -22,7 +22,7 @@ If you are running Home Assistant over SSL or from within a container, you will Alpr entities attribute have a vehicle counter `vehicles` and all found plates as `plates`. -This event is trigger after OpenALPR found a new licence plate. +This event is trigger after OpenALPR found a new license plate. ```yaml # Example configuration.yaml automation entry diff --git a/source/_components/image_processing.microsoft_face_detect.markdown b/source/_components/image_processing.microsoft_face_detect.markdown index c15e5baab07..06cca72d260 100644 --- a/source/_components/image_processing.microsoft_face_detect.markdown +++ b/source/_components/image_processing.microsoft_face_detect.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Microsoft Face Detect" -description: "Instructions how to integrate Microsoft Face Detect into Home Assistant." +description: "Instructions on how to integrate Microsoft Face Detect into Home Assistant." date: 2017-01-25 00:00 sidebar: true comments: false @@ -13,7 +13,7 @@ featured: false ha_release: 0.38 --- -The `microsoft_face_detect` image processing platform allows you to use the [Microsoft Face Identify](https://www.microsoft.com/cognitive-services/en-us/) API through Home Assistant. This platform enables you do detect face on camera and fire a event with attributes. +The `microsoft_face_detect` image processing platform allows you to use the [Microsoft Face Identify](https://www.microsoft.com/cognitive-services/en-us/) API through Home Assistant. This platform enables you do detect face on camera and fire an event with attributes. Please refer to the [component](/components/microsoft_face/) configuration on how to setup the API key. diff --git a/source/_components/image_processing.microsoft_face_identify.markdown b/source/_components/image_processing.microsoft_face_identify.markdown index e600ae36a61..7f0de67938f 100644 --- a/source/_components/image_processing.microsoft_face_identify.markdown +++ b/source/_components/image_processing.microsoft_face_identify.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Microsoft Face Identify" -description: "Instructions how to integrate Microsoft Face Identify into Home Assistant." +description: "Instructions on how to integrate Microsoft Face Identify into Home Assistant." date: 2017-01-25 00:00 sidebar: true comments: false @@ -13,7 +13,7 @@ featured: false ha_release: 0.37 --- -The `microsoft_face_identify` image processing platform lets you use [Microsoft Face identify](https://www.microsoft.com/cognitive-services/en-us/) API through Home Assistant. This platform allow you do identify persons on camera and fire a event with identify persons. +The `microsoft_face_identify` image processing platform lets you use [Microsoft Face identify](https://www.microsoft.com/cognitive-services/en-us/) API through Home Assistant. This platform allow you do identify persons on camera and fire an event with attributes. Please refer to the [component](/components/microsoft_face/) configuration on how to setup the API key. @@ -24,10 +24,10 @@ For using the result inside an automation rule, take a look at the [component](/ ```yaml # Example configuration.yaml entry image_processing: - - platform: microsoft_face_identify - group: family - source: - - entity_id: camera.door + - platform: microsoft_face_identify + group: family + source: + - entity_id: camera.door ``` Configuration variables: diff --git a/source/_components/image_processing.openalpr_cloud.markdown b/source/_components/image_processing.openalpr_cloud.markdown index 3a13097c872..96e180a7055 100644 --- a/source/_components/image_processing.openalpr_cloud.markdown +++ b/source/_components/image_processing.openalpr_cloud.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenALPR Cloud" -description: "Instructions how to integrate licences plates with OpenALPR cloud into Home Assistant." +description: "Instructions on how to integrate licences plates with OpenALPR cloud into Home Assistant." date: 2017-01-09 00:00 sidebar: true comments: false @@ -13,7 +13,7 @@ featured: false ha_release: 0.36 --- -[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you to process licences plates from a camera. You can use them to open a garage door or trigger any other [automation](https://home-assistant.io/components/automation/). +[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you to process licences plates from a camera. You can use them to open a garage door or trigger any other [automation](/components/automation/). For using the result inside an automation rule, take a look at the [component](/components/image_processing/) page. diff --git a/source/_components/image_processing.openalpr_local.markdown b/source/_components/image_processing.openalpr_local.markdown index 593a9212614..d5da4bab3ee 100644 --- a/source/_components/image_processing.openalpr_local.markdown +++ b/source/_components/image_processing.openalpr_local.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenALPR Local" -description: "Instructions how to integrate licences plates with OpenALPR local into Home Assistant." +description: "Instructions on how to integrate licences plates with OpenALPR local into Home Assistant." date: 2017-01-09 00:00 sidebar: true comments: false @@ -14,7 +14,7 @@ ha_release: 0.36 redirect_from: /components/openalpr/ --- -[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you to process licences plates from a camera. You can use them to open a garage door or trigger any other [automation](https://home-assistant.io/components/automation/). +[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you to process licences plates from a camera. You can use them to open a garage door or trigger any other [automation](/components/automation/). For using inside automation look on [component](/components/image_processing) page. diff --git a/source/_components/image_processing.opencv.markdown b/source/_components/image_processing.opencv.markdown index db6bfd2d5cb..9e485ec6c30 100644 --- a/source/_components/image_processing.opencv.markdown +++ b/source/_components/image_processing.opencv.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenCV" -description: "Instructions how to integrate OpenCV image processing into Home Assistant." +description: "Instructions on how to integrate OpenCV image processing into Home Assistant." date: 2017-01-25 00:00 sidebar: true comments: false diff --git a/source/_components/image_processing.seven_segments.markdown b/source/_components/image_processing.seven_segments.markdown index db0ebf4f1b7..a5944d821b5 100644 --- a/source/_components/image_processing.seven_segments.markdown +++ b/source/_components/image_processing.seven_segments.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Seven segments display" -description: "Instructions how to use OCR for seven segments displays into Home Assistant." +description: "Instructions on how to use OCR for seven segments displays into Home Assistant." date: 2017-05-18 08:00 sidebar: true comments: false @@ -93,6 +93,7 @@ image_processing: With the help of a [template sensor](/components/sensor.template/), the value can be shown as badge. +{% raw %} ```yaml sensor: - platform: template @@ -102,4 +103,4 @@ sensor: friendly_name: 'Ampere' unit_of_measurement: 'A' ``` - +{% endraw %} diff --git a/source/_components/influxdb.markdown b/source/_components/influxdb.markdown index f2291bda29d..9df07711f80 100644 --- a/source/_components/influxdb.markdown +++ b/source/_components/influxdb.markdown @@ -23,11 +23,11 @@ The default InfluxDB configuration doesn't enforce authentication. If you have i influxdb: ``` -You will still need to create a database named `home_assistant` via InfluxDB's web interface or command line. For instructions how to create a database check the [InfluxDB documentation](https://docs.influxdata.com/influxdb/latest/introduction/getting_started/#creating-a-database) relevant to the version you have installed. +You will still need to create a database named `home_assistant` via InfluxDB's command line interface. For instructions on how to create a database check the [InfluxDB documentation](https://docs.influxdata.com/influxdb/latest/introduction/getting_started/#creating-a-database) relevant to the version you have installed. Configuration variables: -- **host** (*Optional*): IP address of your database host, e.g. 192.168.1.10. Defaults to `localhost`. +- **host** (*Optional*): IP address of your database host, e.g., 192.168.1.10. Defaults to `localhost`. - **port** (*Optional*): Port to use. Defaults to 8086. - **username** (*Optional*): The username of the database user. The user needs read/write privileges on the database. - **password** (*Optional*): The password for the database user account. @@ -35,10 +35,9 @@ Configuration variables: - **ssl** (*Optional*): Use https instead of http to connect. Defaults to false. - **verify_ssl** (*Optional*): Verify SSL certificate for https request. Defaults to false. - **max_retries** (*Optional*): Allow the component to retry if there was a network error when transmitting data -- **retry_queue_limit** (*Optional*): If retry enabled, specify how much calls are allowed to be queued for retry. - **default_measurement** (*Optional*): Measurement name to use when an entity doesn't have a unit. Defaults to entity id. - **override_measurement** (*Optional*): Measurement name to use instead of unit or default measurement. This will store all data points in a single measurement. -- **component_config**, **component_config_domain**, **component_config_glob** (*Optional*): These attributes contains component-specific override values. See [Customizing devices and services](https://home-assistant.io/getting-started/customizing-devices/) for format. +- **component_config**, **component_config_domain**, **component_config_glob** (*Optional*): These attributes contains component-specific override values. See [Customizing devices and services](/getting-started/customizing-devices/) for format. - **override_measurement** (*Optional*): Measurement name to use for this component, takes precedence over the global 'override_measurement' and component-specific 'unit_of_measurement' attribute. - **exclude** (*Optional*): Configure which components should be excluded from recording to InfluxDB. - **entities** (*Optional*): The list of entity ids to be excluded from recording to InfluxDB. @@ -49,123 +48,13 @@ Configuration variables: - **tags** (*Optional*): Tags to mark the data. - **tags_attributes** (*Optional*): The list of attribute names which should be reported as tags and not fields to InfluxDB. For example, if set to `friendly_name`, it will be possible to group by entities' friendly names as well, in addition to their ids. -## {% linkable_title Data migration %} +## {% linkable_title Helper scripts %} -Starting with 0.36 the InfluxDB component has a new schema to store values in the InfluxDB databases. - -- There will no longer be any tags/fields named `time`. -- All numeric fields (int/float/bool) will be stored as float inside InfluxDB database. -- All string fields corresponding to state attributes will be renamed as `FIELDNAME_str`, where `FIELDNAME` is the state attribute, to avoid type conflicts. -- All string fields corresponding to a state will be renamed as `state` (former value). -- Fields named `value` will always be stored as float. -- Fields named `state` will always be stored as string. - -### {% linkable_title Migration script %} - -If you need to migrate your database, you may require to run the `influxdb_migrator` script. Run the script after upgrade to 0.36 but before the first regular start of `hass` version 0.36. - -These are the steps the script will perform: -1. Create a new database (called `DBNAME__old`) to store old data. -2. Copy data from `DBNAME` database to `DBNAME__old` database. -3. Empty `DBNAME` database (using `drop` then `create`). `DBNAME` database is now considered as the new database. -4. For each measurement of `DBNAME__old` database: - 1. Read all points from the current measurement (in groups of 1000 points by default) and convert them. - 2. Send group of points to `DBNAME` database. -5. Delete the `DBNAME__old` database if needed. - -Example to run the script: - -```bash -$ hass --script influxdb_migrator \ - -H IP_INFLUXDB_HOST -u INFLUXDB_USERNAME -p INFLUXDB_PASSWORD \ - -d INFLUXDB_DB_NAME -``` -Script arguments: - -``` -required arguments: - -d dbname, --dbname dbname InfluxDB database name - -optional arguments: - -h, --help show this help message and exit - -H host, --host host InfluxDB host address - -P port, --port port InfluxDB host port - -u username, --username username - InfluxDB username - -p password, --password password - InfluxDB password - -s step, --step step How many points to migrate at the same time - -o override_measurement, --override-measurement override_measurement - Store all your points in the same measurement - -D, --delete Delete old database -``` - -- If you run the script with only the `-h` option, you will get a help printout with a short explanation of the different options. -- The host option defaults to `'127.0.0.1'`. -- The port option defaults to `8086`. -- You should be able to omit username and password if InfluxDB authentication is disabled, which it is by default. -- The step option defaults to `1000`. - - -## {% linkable_title Data import script %} - -If you want to import all the recorded data from your recorder database you can use the data import script. -It will read all your state_change events from the database and add them as data-points to the InfluxDB. -You can specify the source database either by pointing the `--config` option to the config directory which includes the default SQLite database or by giving a sqlalchemy connection URI with `--uri`. -The writing to InfluxDB is done in batches that can be changed with `--step`. - -You can control, which data is imported by using the command line options `--exclude_entities` and `--exclude_domains`. -Both get a comma separated list of either entity-ids or domain names that are excluded from the import. - -To test what gets imported you can use the `--simulate` option, which disables the actual write to the InfluxDB instance. -This only writes the statistics how much points would be imported from which entity. - -Example to run the script: - -```bash -$ hass --script influxdb_import --config CONFIG_DIR \ - -H IP_INFLUXDB_HOST -u INFLUXDB_USERNAME -p INFLUXDB_PASSWORD \ - --dbname INFLUXDB_DB_NAME --exclude_domains automation,configurator -``` -Script arguments: - -``` -required arguments: - -d dbname, --dbname dbname - InfluxDB database name - -optional arguments: - -h, --help show this help message and exit - -c path_to_config_dir, --config path_to_config_dir - Directory that contains the Home Assistant - configuration - --uri URI Connect to URI and import (if other than default - sqlite) eg: mysql://localhost/homeassistant - - -H host, --host host InfluxDB host address - -P port, --port port InfluxDB host port - -u username, --username username - InfluxDB username - -p password, --password password - InfluxDB password - -s step, --step step How many points to import at the same time - -t tags, --tags tags Comma separated list of tags (key:value) for all - points - -D default_measurement, --default-measurement default_measurement - Store all your points in the same measurement - -o override_measurement, --override-measurement override_measurement - Store all your points in the same measurement - -e exclude_entities, --exclude_entities exclude_entities - Comma separated list of excluded entities - -E exclude_domains, --exclude_domains exclude_domains - Comma separated list of excluded domains - -S, --simulate Do not write points but simulate preprocessing - and print statistics -``` +- [Helper script `influxdb_import`](/docs/tools/influxdb_import/) +- [Helper script `db_migrator`](/docs/tools/db_migrator/) (only used for [Home Assistant 0.36](/blog/2017/01/14/iss-usps-images-packages/#influxdb-export)) ## {% linkable_title Examples %} - ### {% linkable_title Full configuration %} ```yaml diff --git a/source/_components/input_boolean.markdown b/source/_components/input_boolean.markdown index 61e82ff846c..68f75566ba4 100644 --- a/source/_components/input_boolean.markdown +++ b/source/_components/input_boolean.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Boolean" -description: "Instructions how to integrate the Input Boolean component into Home Assistant." +description: "Instructions on how to integrate the Input Boolean component into Home Assistant." date: 2016-01-17 16:58 sidebar: true comments: false @@ -24,16 +24,34 @@ input_boolean: icon: mdi:car ``` -Configuration variables: +{% configuration %} + input_boolean: + description: Alias for the input. Multiple entries are allowed. + required: true + type: map + keys: + name: + description: Friendly name of the input. + required: false + type: String + initial: + description: Initial value when Home Assistant starts. + required: false + type: boolean + default: false + icon: + description: Icon to display for the component. Refer to the [Customizing devices](/docs/configuration/customizing-devices/#possible-values) page for possible values. + required: false + type: icon +{% endconfiguration %} -- **[alias]** (*Required*): Alias for the input. - - **name** (*Optional*): Friendly name of the input. - - **initial** (*Optional*): Initial value when Home Assistant starts. Defaults to `False`. - - **icon** (*Optional*): Icon for entry. +### {% linkable_title Restore State %} -Pick an icon that you can find on [materialdesignicons.com](https://materialdesignicons.com/) to use for your input and prefix the name with `mdi:`. For example `mdi:car`, `mdi:ambulance`, or `mdi:motorbike`. +This component will automatically restore the state it had prior to Home Assistant stopping as long as you have the `recorder` component enabled and your entity does **not** have a set value for `initial`. To disable this feature, set a valid value for `initial`. Additional information can be found in the [Restore state](/components/recorder/#restore-state) section of the [`recorder`](/components/recorder/) component documentation. -Here's an example of an automation using the above input_boolean. This action will only occur if the switch is on. +## {% linkable_title Automation Examples %} + +Here's an example of an automation using the above `input_boolean`. This action will only occur if the switch is on. ```yaml automation: diff --git a/source/_components/input_datetime.markdown b/source/_components/input_datetime.markdown index 588154ca277..e8a793ae6a3 100644 --- a/source/_components/input_datetime.markdown +++ b/source/_components/input_datetime.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Datetime" -description: "Instructions how to integrate the Input Datetime component into Home Assistant." +description: "Instructions on how to integrate the Input Datetime component into Home Assistant." date: 2017-09-14 16:01 sidebar: true comments: false @@ -33,18 +33,89 @@ input_datetime: has_time: true ``` -Configuration variables: +{% configuration %} + input_datetime: + description: Alias for the datetime input. Multiple entries are allowed. + required: true + type: map + keys: + name: + description: Friendly name of the datetime input. + required: false + type: String + has_time: + description: Set to `true` if the input should have a time. At least one `has_time` or `has_date` must be defined. + required: false + type: Boolean + default: false + has_date: + description: Set to `true` if the input should have a date. At least one `has_time` or `has_date` must be defined. + required: false + type: Boolean + default: false + initial: + description: Set the initial value of this input, depending on `has_time` and `has_date`. + required: false + type: datetime | time | date + default: 1970-01-01 00:00 | 1970-01-01 | 00:00 +{% endconfiguration %} -- **[alias]** (*Required*): Alias for the datetime input. Multiple entries are allowed. - - **name** (*Optional*): Friendly name of the datetime input. - - **has_time** (*Optional*): Set to `true` if this input should have time. Defaults to `false`. - - **has_date** (*Optional*): Set to `true` if this input should have a date. Defaults to `false`. - - **initial** (*Optional*): Set the initial value of this input. Defaults to '1970-01-01 00:00'. If has_time is `false` this must be just a date (e.g.: '1970-01-01'). If has_date is `false` this must be just a time (e.g.: '15:16'). +### {% linkable_title Attributes %} -A datetime input entity's state exports several attributes that can be useful in automations and templates: +A datetime input entity's state exports several attributes that can be useful in automations and templates. -- **has_time**: `true` if this entity has time. -- **has_date**: `true` if this entity has a date. -- **year**, **month**, **day** (Only available if *has_date* is true): The year, month and day of the date. -- **hour**, **minute**, **second** (Only available if *has_time* is true): The hour, minute and second of the time. -- **timestamp**: A timestamp representing the time held in the input. If *has_date* is true, this is the UNIX timestamp of the date / time held by the input. Otherwise (i.e., if only *has_time* is true) the number of seconds since midnight representing the time held by the input. +| Attribute | Description | +| ----- | ----- | +| `has_time` | `true` if this entity has a time. +| `has_date` | `true` if this entity has a date. +| `year``month`
`day` | The year, month and day of the date.
(only available if `has_date: true`) +| `hour`
`minute`
`second` | The hour, minute and second of the time.
(only available if `has_time: true`) +| `timestamp` | A timestamp representing the time held in the input.
If `has_date: true`, this is the UNIX timestamp of the date / time held by the input. Otherwise if only `has_time: true`, this is the number of seconds since midnight representing the time held by the input. + +### {% linkable_title Restore State %} + +This component will automatically restore the state it had prior to Home Assistant stopping as long as you have the `recorder` component enabled and your entity does **not** have a set value for `initial`. To disable this feature, set a valid value for `initial`. Additional information can be found in the [Restore state](/components/recorder/#restore-state) section of the [`recorder`](/components/recorder/) component documentation. + +### {% linkable_title Services %} + +This component provides a service to modify the state of the `input_datetime`. + +| Service | Data | Description | +| ----- | ----- | ----- | +| `set_datetime` | `time` | This can be used to dynamically set the time. +| `set_datetime` | `date` | This can be used to dynamically set the date. + +## {% linkable_title Automation Examples %} + +The following example shows the usage of the `input_datetime` as a trigger in an automation (note that you will need a [time sensor](/components/sensor.time_date/) elsewhere in your configuration): + +{% raw %} +```yaml +# Example configuration.yaml entry +# Turns on bedroom light at the time specified. +automation: + trigger: + platform: template + value_template: "{{ states('sensor.time') == (states.input_datetime.bedroom_alarm_clock_time.attributes.timestamp | int | timestamp_custom('%H:%M', False)) }}" + action: + service: light.turn_on + entity_id: light.bedroom +``` +{% endraw %} + +To dynamically set the `input_datetime` you can call `input_datetime.set_datetime`. The following example can be used in an automation rule: + +```yaml +# Example configuration.yaml entry +# Sets input_datetime to '05:30' when an input_boolean is turned on. +automation: + trigger: + platform: state + entity_id: input_boolean.example + to: 'on' + action: + service: input_datetime.set_datetime + entity_id: input_datetime.bedroom_alarm_clock_time + data: + time: '05:30:00' +``` diff --git a/source/_components/input_number.markdown b/source/_components/input_number.markdown index 9c041e1b7f3..9f7f65ed956 100644 --- a/source/_components/input_number.markdown +++ b/source/_components/input_number.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Number" -description: "Instructions how to integrate the Input Number component into Home Assistant." +description: "Instructions on how to integrate the Input Number component into Home Assistant." date: 2017-09-19 03:30 sidebar: true comments: false @@ -14,7 +14,7 @@ redirect_from: /components/input_slider/ ---
-Before version 0.55 this component was known as `input_slider` and did not have the `mode` configuration option. +Before version 0.55 this component was known as `input_slider` and did not have the `mode` configuration option. Also, service `select_value` is now `set_value`.
The `input_number` component allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. The frontend can display a slider, or a numeric input box. Changes to the slider or numeric input box generate state events. These state events can be utilized as `automation` triggers as well. @@ -39,27 +39,60 @@ input_number: mode: box ``` -Configuration variables: +{% configuration %} + input_number: + description: Alias for the input. Multiple entries are allowed. + required: true + type: map + keys: + min: + description: Minimum value. + required: true + type: float + max: + description: Maximum value. + required: true + type: float + name: + description: Friendly name of the input. + required: false + type: string + initial: + description: Initial value when Home Assistant starts. + required: false + type: float + default: 0 + step: + description: Step value for the slider. Smallest value `0.001`. + required: false + type: float + default: 1 + mode: + description: Can specify `box` or `slider`. + required: false + type: box | slider + default: slider + unit_of_measurement: + description: Unit of measurement in which the value of the slider is expressed in. + required: false + type: string + icon: + description: Icon to display in front of the box/slider in the frontend. Refer to the [Customizing devices](/docs/configuration/customizing-devices/#possible-values) page for possible values. + required: false + type: icon +{% endconfiguration %} -- **[alias]** (*Required*): Alias for the input. Multiple entries are allowed. - - **min** (*Required*): Minimum value. - - **max** (*Required*): Maximum value. - - **name** (*Optional*): Friendly name of the input. - - **initial** (*Optional*): Initial value when Home Assistant starts. Defaults to 0. - - **step** (*Optional*): Step value for the slider. Defaults to 1. - - **mode** (*Optional*): Can specify `box`, or `slider`. Defaults to `slider`. - - **unit_of_measurement** (*Optional*): Unit of measurement in which the value of the slider is expressed in. - - **icon** (*Optional*): Icon to display in front of the box/slider in the frontend. Refer to the [Customizing devices](https://home-assistant.io/docs/configuration/customizing-devices/#possible-values) page for possible values. +### {% linkable_title Restore State %} + +This component will automatically restore the state it had prior to Home Assistant stopping as long as you have the `recorder` component enabled and your entity does **not** have a set value for `initial`. To disable this feature, set a valid value for `initial`. Additional information can be found in the [Restore state](/components/recorder/#restore-state) section of the [`recorder`](/components/recorder/) component documentation. ## {% linkable_title Automation Examples %} Here's an example of `input_number` being used as a trigger in an automation. -```yaml {% raw %} +```yaml # Example configuration.yaml entry using 'input_number' as a trigger in an automation - -# Define input_number input_number: bedroom_brightness: name: Brightness @@ -67,8 +100,6 @@ input_number: min: 0 max: 254 step: 1 - -# Automation. automation: - alias: Bedroom Light - Adjust Brightness trigger: @@ -76,20 +107,18 @@ automation: entity_id: input_number.bedroom_brightness action: - service: light.turn_on -# Note the use of 'data_template:' below rather than the normal 'data:' if you weren't using an input variable + # Note the use of 'data_template:' below rather than the normal 'data:' if you weren't using an input variable data_template: entity_id: light.bedroom - brightness: '{{ trigger.to_state.state | int }}' -{% endraw %} + brightness: "{{ trigger.to_state.state | int }}" ``` +{% endraw %} Another code example using `input_number`, this time being used in an action in an automation. -```yaml {% raw %} +```yaml # Example configuration.yaml entry using 'input_number' in an action in an automation - -# Define 'input_select' input_select: scene_bedroom: name: Scene @@ -101,8 +130,6 @@ input_select: - Relax - 'OFF' initial: 'Select' - -# Define input_number input_number: bedroom_brightness: name: Brightness @@ -110,8 +137,6 @@ input_number: min: 0 max: 254 step: 1 - -# Automation. automation: - alias: Bedroom Light - Custom trigger: @@ -120,21 +145,18 @@ automation: to: CUSTOM action: - service: light.turn_on -# Again, note the use of 'data_template:' rather than the normal 'data:' if you weren't using an input variable. + # Again, note the use of 'data_template:' rather than the normal 'data:' if you weren't using an input variable. data_template: entity_id: light.bedroom - brightness: '{{ states.input_number.bedroom_brightness.state | int }}' -{% endraw %} + brightness: "{{ states('input_number.bedroom_brightness') | int }}" ``` - +{% endraw %} Example of `input_number` being used in a bidirectional manner, both being set by and controlled by an MQTT action in an automation. -```yaml {% raw %} +```yaml # Example configuration.yaml entry using 'input_number' in an action in an automation - -# Define input_number input_number: target_temp: name: Target Heater Temperature Slider @@ -144,30 +166,66 @@ input_number: unit_of_measurement: step icon: mdi:target -# Automation. # This automation script runs when a value is received via MQTT on retained topic: setTemperature # It sets the value slider on the GUI. This slides also had its own automation when the value is changed. -- alias: Set temp slider - trigger: - platform: mqtt - topic: "setTemperature" - action: - service: input_number.set_value - data_template: - entity_id: input_number.target_temp - value: '{{ trigger.payload}}' +automation: + - alias: Set temp slider + trigger: + platform: mqtt + topic: 'setTemperature' + action: + service: input_number.set_value + data_template: + entity_id: input_number.target_temp + value: "{{ trigger.payload }}" - # This automation script runs when the target temperature slider is moved. - # It publishes its value to the same MQTT topic it is also subscribed to. -- alias: Temp slider moved - trigger: - platform: state - entity_id: input_number.target_temp - action: - service: mqtt.publish - data_template: - topic: "setTemperature" - retain: true - payload: '{{ states.input_number.target_temp.state | int }}' -{% endraw %} +# This automation script runs when the target temperature slider is moved. +# It publishes its value to the same MQTT topic it is also subscribed to. +automation: + - alias: Temp slider moved + trigger: + platform: state + entity_id: input_number.target_temp + action: + service: mqtt.publish + data_template: + topic: 'setTemperature' + retain: true + payload: "{{ states('input_number.target_temp') | int }}" ``` +{% endraw %} + +Here's an example of `input_number` being used as a delay in an automation. + +{% raw %} +```yaml +# Example configuration.yaml entry using 'input_number' as a delay in an automation +input_number: + minutes: + name: minutes + icon: mdi:clock-start + initial: 3 + min: 0 + max: 6 + step: 1 + + seconds: + name: seconds + icon: mdi:clock-start + initial: 30 + min: 0 + max: 60 + step: 10 + +automation: + - alias: turn something off after x time after turning it on + trigger: + platform: state + entity_id: switch.something + to: 'on' + action: + - delay: '00:{{ states.input_number.minutes.state | int }}:{{ states.input_number.seconds.state | int }}' + - service: switch.turn_off + entity_id: switch.something +``` +{% endraw %} diff --git a/source/_components/input_select.markdown b/source/_components/input_select.markdown index e8cf94f94d1..dec70767fd1 100644 --- a/source/_components/input_select.markdown +++ b/source/_components/input_select.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Select" -description: "Instructions how to integrate the Input Select component into Home Assistant." +description: "Instructions on how to integrate the Input Select component into Home Assistant." date: 2016-02-02 17:00 sidebar: true comments: false @@ -33,27 +33,64 @@ input_select: - Home Alone ``` -Configuration variables: - -- **[alias]** array (*Required*): Alias for the input. Multiple entries are allowed.. - - **name** (*Optional*): Friendly name of the input. - - **options** array (*Required*): List of options to choose from. - - **initial** (*Optional*): Initial value when Home Assistant starts. - - **icon** (*Optional*): Icon for entry. - -Pick an icon that you can find on [materialdesignicons.com](https://materialdesignicons.com/) to use for your input and prefix the name with `mdi:`. For example `mdi:car`, `mdi:ambulance`, or `mdi:motorbike`. +{% configuration %} + input_select: + description: Alias for the input. Multiple entries are allowed. + required: true + type: map + keys: + name: + description: Friendly name of the input. + required: false + type: String + options: + description: List of options to choose from. + required: true + type: Array + initial: + description: Initial value when Home Assistant starts. + required: false + type: Element of options + default: First element of options + icon: + description: Icon to display for the component. Refer to the [Customizing devices](/docs/configuration/customizing-devices/#possible-values) page for possible values. + required: false + type: icon +{% endconfiguration %}Because YAML defines [booleans](http://yaml.org/type/bool.html) as equivalent, any variations of 'On', 'Yes', 'Y', 'Off', 'No', or 'N' (regardless of case) used as option names will be replaced by True and False unless they are defined in quotation marks.
+### {% linkable_title Restore State %} + +This component will automatically restore the state it had prior to Home Assistant stopping as long as you have the `recorder` component enabled and your entity does **not** have a set value for `initial`. To disable this feature, set a valid value for `initial`. Additional information can be found in the [Restore state](/components/recorder/#restore-state) section of the [`recorder`](/components/recorder/) component documentation. + ### {% linkable_title Services %} -This components provide three services to modify the state of the `input_select`: +This components provide three services to modify the state of the `input_select`. -- `input_select.select_option`: This can be used to select a specific option. The option is passed as `option` attribute in the service data. -- `input_select.select_previous`: Select the previous option. -- `input_select.select_next`: Select the next option. +| Service | Data | Description | +| ------- | ---- | ----------- | +| `select_option` | `option` | This can be used to select a specific option. +| `set_options` | `options``entity_id(s)` | Set the options for specific `input_select` entities. +| `select_previous` | | Select the previous option. +| `select_next` | | Select the next option. + +### {% linkable_title Scenes %} + +To specify a target option in a [Scene](/components/scene/) you have to specify the target as `option` attribute: + +```yaml +# Example configuration.yaml entry +scene: + - name: Example1 + entities: + input_select.who_cooks: + option: Paulus +``` + +## {% linkable_title Automation Examples %} The following example shows the usage of the `input_select.select_option` service in an automation: @@ -87,23 +124,10 @@ automation: options: ["Item A", "Item B", "Item C"] ``` -### {% linkable_title Scenes %} - -To specify a target option in a [Scene](/components/scene/) you have to specify the target as `option` attribute: - -```yaml -# Example configuration.yaml entry -scene: - - name: Example1 - entities: - input_select.who_cooks: - option: Paulus -``` - Example of `input_select` being used in a bidirectional manner, both being set by and controlled by an MQTT action in an automation. -```yaml {% raw %} +```yaml # Example configuration.yaml entry using 'input_select' in an action in an automation # Define input_select @@ -129,7 +153,7 @@ input_select: service: input_select.select_option data_template: entity_id: input_select.thermostat_mode - option: '{{ trigger.payload }}' + option: "{{ trigger.payload }}" # This automation script runs when the thermostat mode selector is changed. # It publishes its value to the same MQTT topic it is also subscribed to. @@ -142,6 +166,6 @@ input_select: data_template: topic: "thermostatMode" retain: true - payload: '{{ states.input_select.thermostat_mode.state }}' -{% endraw %} + payload: "{{ states('input_select.thermostat_mode') }}" ``` +{% endraw %} diff --git a/source/_components/input_text.markdown b/source/_components/input_text.markdown index 26ad4846a74..187f08a0e46 100644 --- a/source/_components/input_text.markdown +++ b/source/_components/input_text.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Text" -description: "Instructions how to integrate the Input Text component into Home Assistant." +description: "Instructions on how to integrate the Input Text component into Home Assistant." date: 2016-03-15 06:00 sidebar: true comments: false @@ -12,7 +12,7 @@ ha_category: Automation ha_release: 0.53 --- -The `input_text` component allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. Changes to the value stored in the text box generate state events. These state events can be utilized as `automation` triggers as well. +The `input_text` component allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. Changes to the value stored in the text box generate state events. These state events can be utilized as `automation` triggers as well. It can also be configured in password mode (obscured text). ```yaml # Example configuration.yaml entries @@ -27,13 +27,48 @@ input_text: text3: name: Text 3 pattern: '[a-fA-F0-9]*' + text4: + name: Text 4 + mode: password ``` -Configuration variables: +{% configuration %} + input_text: + description: Alias for the input. Multiple entries are allowed. + required: true + type: map + keys: + name: + description: Friendly name of the text input. + required: false + type: String + min: + description: Minimum length for the text value. + required: false + type: int + default: 0 + max: + description: Maximum length for the text value. + required: false + type: int + default: 100 + initial: + description: Initial value when Home Assistant starts. + required: false + type: String + default: empty + pattern: + description: Regex pattern for client side validation. + required: false + type: String + default: empty + mode: + description: Can specify `text` or `password`. Elements of type "password" provide a way for the user to securely enter a value. + required: false + type: String + default: text +{% endconfiguration %} -- **[alias]** (*Required*): Alias for the text input. -- **min** (*Optional*): Minimum length for the text value. Default is `0`. -- **max** (*Optional*): Maximum length for the text value. Default is `100`. -- **name** (*Optional*): Friendly name of the text input. -- **initial** (*Optional*): Initial value when Home Assistant starts. Default is empty string. -- **pattern** (*Optional*): Regex pattern for client side validation. Default is empty string, which is treated same as `.*`. +### {% linkable_title Restore State %} + +This component will automatically restore the state it had prior to Home Assistant stopping as long as you have the `recorder` component enabled and your entity does **not** have a set value for `initial`. To disable this feature, set a valid value for `initial`. Additional information can be found in the [Restore state](/components/recorder/#restore-state) section of the [`recorder`](/components/recorder/) component documentation. diff --git a/source/_components/insteon_hub.markdown b/source/_components/insteon_hub.markdown deleted file mode 100644 index 03bf4b8a6ec..00000000000 --- a/source/_components/insteon_hub.markdown +++ /dev/null @@ -1,37 +0,0 @@ ---- -layout: page -title: "Insteon Hub" -description: "Instructions how to setup the Insteon Hub within Home Assistant." -date: 2016-01-27 08:00 -sidebar: true -comments: false -sharing: true -footer: true -logo: insteon.png -ha_category: Hub -ha_iot_class: "Cloud Polling" ---- - -
-This component has been disabled due to a complaint by Insteon. It will be enabled again once this issue has been resolved. -
- -The `insteon` component lets you use your [Insteon Hub](http://www.insteon.com/insteon-hub/) with Home Assistant. - -You will need to obtain an Insteon REST API key from the [Insteon Developer program](http://www.insteon.com/become-an-insteon-developer) to use this component. - -To integrate your Insteon Hub with Home Assistant, add the following section to your `configuration.yaml` file: - -```yaml -# Example configuration.yaml entry -insteon_hub: - username: YOUR_USERNAME - password: YOUR_PASSWORD - api_key: YOUR_API_KEY -``` - -Configuration variables: - -- **username** (*Required*): The username used to access the Insteon interface (e.g. the [connect.insteon.com](http://connect.insteon.com/) site). -- **password** (*Required*): The password used to access the Insteon interface. -- **api_key** (*Required*): The Insteon REST API key emailed to you once you are approved in the Insteon Developer program. diff --git a/source/_components/insteon_local.markdown b/source/_components/insteon_local.markdown index 96a339f0f03..b4b534aabd9 100644 --- a/source/_components/insteon_local.markdown +++ b/source/_components/insteon_local.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Insteon (local)" -description: "Instructions how to setup the Insteon Hub locally within Home Assistant." +description: "Instructions on how to setup the Insteon Hub locally within Home Assistant." date: 2016-12-18 08:00 sidebar: true comments: false @@ -10,48 +10,53 @@ footer: true logo: insteon.png ha_category: Hub ha_iot_class: "Local Polling" -ha_version: 0.36 +ha_release: 0.36 +redirect_from: /components/insteon_hub/ --- The `insteon_local` component let you use your [Insteon Hub](http://www.insteon.com/insteon-hub/) with Home Assistant. -To integrate your Insteon local setup with Home Assistant, add the following section to your `configuration.yaml` file: +## {% linkable_title Configuration %} + +To integrate your Insteon Hub (local setup) with Home Assistant, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml platform entry insteon_local: - host: YOUR HUB IP - username: YOUR HUB USERNAME - password: YOUR HUB PASSWORD + host: YOUR_HUB_IP + username: YOUR_HUB_USERNAME + password: YOUR_HUB_PASSWORD ``` -Configuration variables: +{% configuration %} +host: + description: The IP address of your hub. + required: true + type: string +username: + description: The username used to access the Insteon interface (find in your Insteon app). + required: true + type: string +password: + description: The password used to access the Insteon interface. + required: true + type: string +timeout: + description: Timeout to wait for connections. + required: false + type: time + default: 10 seconds +port: + description: The port your hub is configured to listen to. + required: false + type: string + default: 25105 +{% endconfiguration %} + *Note: The username and password here are for the hub and are different than the ones used to access the app. You can usually find these on the bottom of your hub (unless you've changed them through the settings in the app)* -- **host** (*Required*): The IP address of your hub. -- **username** (*Required*): The username used to access the Insteon interface (find in your Insteon app). -- **password** (*Required*): The password used to access the Insteon interface. -- **timeout** (*Optional*): Timeout to wait for connections. Defaults to 10 seconds. -- **port** (*Optional*): The port your hub is configured to listen to. Defaults to `25105`. -### {% linkable_title Full configuration %} - -The `insteon_local` component currently supports both lights (dimmers) and switches. A full configuration may look like so: - -```yaml -insteon_local: - host: YOUR HUB IP - username: YOUR HUB USERNAME - password: YOUR HUB PASSWORD - timeout: 10 - port: 25105 - -light: - - platform: insteon_local - -switch: - - platform: insteon_local - -fan: - - platform: insteon_local -``` +The `insteon_local` component currently supports lights (dimmers), switches and fans. ++This component replaces the old `insteon_hub` component, which has been removed due to a complaint by Insteon. +
diff --git a/source/_components/insteon_plm.markdown b/source/_components/insteon_plm.markdown index f28db9b74cd..52f7b93530c 100644 --- a/source/_components/insteon_plm.markdown +++ b/source/_components/insteon_plm.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Insteon PLM" -description: "Instructions how to setup an Insteon USB PLM locally within Home Assistant." +description: "Instructions on how to setup an Insteon USB PLM locally within Home Assistant." date: 2017-02-19 16:00 sidebar: true comments: false @@ -10,62 +10,127 @@ footer: true logo: insteon.png ha_category: Hub ha_iot_class: "Local Push" -ha_version: 0.39 +ha_release: 0.39 --- -This component adds "local push" support for INSTEON PowerLinc Modems allowing -linked INSTEON devices to be used within Home Assistant as lights, switches, -and binary sensors. Device support is provided by the underlying [insteonplm] -package. It is known to work with both the [2413U] USB and [2412S] -RS242 flavors of PLM. This component does not work with the IP-based hub -products. For that, you'll want the "Insteon (Local)" component instead. +This component adds "local push" support for INSTEON PowerLinc Modems allowing linked INSTEON devices to be used within Home Assistant as lights, switches, and binary sensors. Device support is provided by the underlying [insteonplm] package. It is known to work with the [2413U] USB and [2412S] RS242 flavors of PLM and the [2448A7] USB stick. This component does not work with the IP-based hub products. For that, you'll want the [Insteon local component](/components/insteon_local/) instead. [insteonplm]: https://github.com/nugget/python-insteonplm [2413U]: https://www.insteon.com/powerlinc-modem-usb [2412S]: https://www.insteon.com/powerlinc-modem-serial +[2448A7]: https://www.smarthome.com/insteon-2448a7-portable-usb-adapter.html +## {% linkable_title Configuration %} ```yaml # insteon_plm supported configuration variables insteon_plm: port: SERIAL_PORT device_override: - - address: INSTEON_ADDRESS - platform: DEVICE_PLATFORM + - address: ADDRESS + cat: CATEGORY + subcat: SUBCATEGORY + firmware: FIRMWARE + product_key: PRODUCT_KEY + x10_devices: + - housecode: HOUSECODE + unitcode: UNITCODE + platform: PLATFORM + steps: STEPS + x10_all_units_off: HOUSECODE + x10_all_lights_on: HOUSECODE + x10_all_lights_off: HOUSECODE ``` -Configuration variables: -- **port** (*Required*): The port for your device, e.g. `/dev/ttyUSB0` -- **device_override** (*Optional*): Override the default device platform - +{% configuration %} +port: + description: The port for your device, e.g., `/dev/ttyUSB0` + required: true + type: string +device_override: + description: Override the default device definition + required: false + type: list + keys: + ADDRESS: + description: is found on the device itself in the form 1A.2B.3C or 1a2b3c + CATEGORY: + description: is found in the back of the device's User Guide in the form of 0x00 - 0xff + SUBCATEGORY: + description: is found in the back of the device's User Guide in the form of 0x00 - 0xff + FIRMWARE: + description: is a more advanced option and will typically not be used. + PRODUCT_KEY: + description: is a more advanced option and will typically not be used. +x10_devices: + description: Define X10 devices to control or respond to + required: false + type: list + keys: + HOUSECODE: + description: is the X10 housecode values a - p + UNITCODE: + description: is the X10 unit code values 1 - 16 + PLATFORM: + description: is the Home Assistant Platform to associate the device with. Choose one of the following supported platforms. + type: string + keys: + binary_sensor: + description: Used for on/off devices or keypad buttons that are read only. + light: + description: Used for dimmable X10 devices + switch: + description: Used for On/Off X10 devices + STEPS: + description: is the number of dim/bright steps the device supports. Used for dimmable X10 devices only. + default: 22 +x10_all_units_off: + description: Creates an binary_sensor that responds to the X10 standard command for All Units Off. + required: false +x10_all_lights_on: + description: Creates an binary_sensor that responds to the X10 standard command for All Lights On + required: false +x10_all_lights_off: + description: Creates an binary_sensor that responds to the X10 standard command for All Lights Off + required: false +{% endconfiguration %} + +### {% linkable_title Autodiscovery %} + +The first time autodiscovery runs, the duration may require up to 20 seconds per device. Subsequent startups will occur much quicker using cached device information. If a device is not recognized during autodiscovery, you can add the device to the **device_override** configuration. + +In order for a device to be discovered it must be linked to the PLM as either a responder or a controller. + +### {% linkable_title Linking Devices to the PLM %} + +In order for any two Insteon devices to talk with one another, they must be linked. For an overview of device linking, please read the Insteon page on [understanding linking]. The Insteon PLM module supports All-Linking through [Development Tools] service calls. The following services are available: + +- **insteon_plm.add_all_link**: Tells the Insteon Modem (IM) start All-Linking mode. Once the IM is in All-Linking mode, press the link button on the device to complete All-Linking. +- **insteon_plm.delete_all_link**: Tells the Insteon Modem (IM) to remove an All-Link record from the All-Link Database of the IM and a device. Once the IM is set to delete the link, press the link button on the corresponding device to complete the process. +- **insteon_plm.load_all_link_database**: Load the All-Link Database for a device. WARNING - Loading a device All-Link database is very time consuming and inconsistent. This may take a LONG time and may need to be repeated to obtain all records. +- **insteon_plm.print_all_link_database**: Print the All-Link Database for a device. Requires that the All-Link Database is loaded into memory. +- **insteon_plm.print_im_all_link_database**: Print the All-Link Database for the INSTEON Modem (IM). + +If you are looking for more advanced options, you can use the [insteonplm_interactive] command line tool that is distributed with the +[insteonplm] Python module. Please see the documentation on the [insteonplm] GitHub site. Alternatively, you can download [HouseLinc] which runs on any Windows PC, or you can use [Insteon Terminal] which is open source and runs on most platforms. SmartHome no longer supports HouseLinc, but it still works. Insteon Terminal is a very useful tool but please read the disclaimers carefully, they are important. + +[understanding linking]: http://www.insteon.com/support-knowledgebase/2015/1/28/understanding-linking +[Development Tools]: https://www.home-assistant.io/docs/tools/dev-tools/ +[HouseLinc]: https://www.smarthome.com/houselinc.html +[Insteon Terminal]: https://github.com/pfrommerd/insteon-terminal +[insteonplm_interactive]: https://github.com/nugget/python-insteonplm#command-line-interface ### {% linkable_title Customization %} -The only configuration item that is absolutely necessary is the port so that -Home Assistant can connect to the PLM. This will expose all the supported INSTEON -devices which exist in the modem's ALL-Link database. However, devices will -only be shown by their INSTEON hex address (e.g. "1A.2B.3C") which can be a bit -unwieldy. As you link and unlink devices using the 'Set' buttons, they'll be -added and removed from Home Assistant automatically. +The only configuration item that is absolutely necessary is the port so that Home Assistant can connect to the PLM. This will expose all the supported INSTEON devices which exist in the modem’s ALL-Link database. However, devices will only be shown by their INSTEON hex address (e.g., “1A.2B.3C”) which can be a bit unwieldy. As you link and unlink devices using the ‘Set’ buttons, they’ll be added and removed from Home Assistant automatically. -You can use the normal Home Assistant [device customization] section of your -configuration to assign friendly names and special icons to your devices. This -is especially useful for setting device_class on your binary_sensor INSTEON -devices. - -[device customization]: /getting-started/customizing-devices/ +You can use the normal Home Assistant [device customization](/getting-started/customizing-devices/) section of your configuration to assign friendly names and special icons to your devices. This is especially useful for setting device_class on your binary_sensor INSTEON devices. ### {% linkable_title Device Overrides %} -INSTEON devices are added to Home Assistant using the platform(s) that make the -most sense given the model and features of the hardware. In most cases this is -unambiguous, but sometimes the component will not be able to guess the actual -usage of the device. For example, there might be a table lamp plugged into an -INSTEON appliance relay module. By default, this will show as a 'switch' -device in Home Assistant, but it really should be a 'light' device. For -exceptions like this, the component supports a device platform override. You -can set any device (by address) to explicitly use a specific platform if the -default is not correct. +INSTEON devices are added to Home Assistant using the platform(s) that make the most sense given the model and features of the hardware. The features of the INSTEON device are built into the Home Assistant platform. Changing the platform is not recommended. There are two primary uses for the **device_override** feature. +- Devices that do not respond during autodiscovery. This is common for battery operated devices. +- Devices that have not been fully developed. This allows an unknown device to be mapped to a device that operates similarly to another device. ### {% linkable_title Example Configuration with Options%} @@ -83,7 +148,71 @@ homeassistant: insteon_plm: port: /dev/ttyUSB0 device_override: - - address: a1b2c3 # Icon Appliance Module for bedside lamp - platform: light # make it a light instead of a switch + - address: a1b2c3 # Hidden Door Sensor [2845-222] + cat: 0x10 + subcat: 0x11 ``` +### {% linkable_title What NOT to do %} + +Insteon PLM is a top level component and device discovery will identify the Home Assistant platform the device belongs in. As such, do not declare Insteon devices in other platforms. For example, this configuration will NOT work: + +```yaml +light: + - platform: insteon_plm + address: 1a2b3c +``` + +### {% linkable_title Events and Mini-Remotes %} + +Mini-Remote devices do not appear as Home Assistant entities. They generate +events. The following events are available: + +- **insteon_plm.button_on** + - **address**: (required) The Insteon device address in lower case without + dots (e.g. 1a2b3c) + - **button**: (Optional) The button id in lower case. For an 4 button remote + the values are a to d. For an 8 button remote the values are a to g. For + a one button remote this field is not used. +- **insteon_plm.button_of** + - **address**: (required) The Insteon device address in lower case without + dots (e.g. 1a2b3c) + - **button**: (Optional) The button id in lower case. For an 4 button remote + the values are a to d. For an 8 button remote the values are a to g. For + a one button remote this field is not used. + +This allows the mini-remotes to be configured as + +Here is an example of how to use these events for automations: + +``` +automation: + # 4 or 8 button remote with button c pressed + trigger: + platform: event + event_type: insteon_plm.button_on + event_data: + address: 1a2b3c + button: c + condition: + - condition: state + entity_id: light.some_light + state: 'off' + action: + service: light.turn_on + entity_id: light.some_light + + # single button remote + trigger: + platform: event + event_type: insteon_plm.button_on + event_data: + address: 1a2b3c + condition: + - condition: state + entity_id: light.some_light + state: 'off' + action: + service: light.turn_on + entity_id: light.some_light +``` diff --git a/source/_components/intent_script.markdown b/source/_components/intent_script.markdown index 68336fd79d5..eab43f4b930 100644 --- a/source/_components/intent_script.markdown +++ b/source/_components/intent_script.markdown @@ -12,7 +12,7 @@ ha_category: Intent ha_release: "0.50" --- -The intent_script component allows users to configure actions and responses to intents. Intents can be fired by any component that supports it. Examples are Alexa (Amazon Echo), API.ai (Google Assistant) and Snips. +The intent_script component allows users to configure actions and responses to intents. Intents can be fired by any component that supports it. Examples are [Alexa](/components/alexa/) (Amazon Echo), [API.ai](/components/dialogflow/) (Google Assistant) and [Snips](/components/snips/). ```yaml # Example configuration.yaml entry diff --git a/source/_components/ios.markdown b/source/_components/ios.markdown new file mode 100644 index 00000000000..44ac2fa88e3 --- /dev/null +++ b/source/_components/ios.markdown @@ -0,0 +1,17 @@ +--- +layout: page +title: "iOS" +description: "Instructions on how to use the iOS companion app with Home Assistant." +date: 2018-04-06 08:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: apple.png +ha_category: Hub +featured: false +ha_release: 0.31 +ha_iot_class: depends +--- + +The `ios` component is the Home Assistant part for using the iOS companion app. For further details please check the [iOS section](/docs/ecosystem/ios/) in the documentation for further details. diff --git a/source/_components/iota.markdown b/source/_components/iota.markdown new file mode 100644 index 00000000000..d50ad4f5452 --- /dev/null +++ b/source/_components/iota.markdown @@ -0,0 +1,62 @@ +--- +layout: page +title: "IOTA" +description: "Instructions on how to integrate IOTA wallets with Home Assistant." +date: 2017-12-31 13:29 +sidebar: true +comments: false +sharing: true +footer: true +logo: iota.png +ha_category: Finance +ha_release: 0.62 +ha_iot_class: "Cloud Polling" +--- + +[IOTA](http://iota.org/) is a new blockless distributed ledger which is scalable, lightweight and makes it possible to transfer value without any fees. + +The `iota` component displays various details (e.g., the balance, node attributes) of IOTA wallets. + +```yaml +# configuration.yaml example +iota: + iri: https://testnet140.tangle.works:4434 + wallets: + - name: Default Wallet + seed: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +``` + +{% configuration %} +iri: + description: URL of the IRI node. + required: true + type: string +testnet: + description: Flag for indicating "testnet". + required: false + default: false + type: bool +wallets: + description: List of IOTA wallets. + required: true + type: list + keys: + name: + description: Name of the wallet. + seed: + description: Seed of the wallet. +{% endconfiguration %} + +A full configuration example could look the one below: + +```yaml +# Full example +iota: + iri: https://testnet140.tangle.works:4434 + testnet: true + wallets: + - name: Default Wallet + seed: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + - name: Exchange Wallet + seed: XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX +``` diff --git a/source/_components/isy994.markdown b/source/_components/isy994.markdown index 8cf050f2383..1c833178215 100644 --- a/source/_components/isy994.markdown +++ b/source/_components/isy994.markdown @@ -1,7 +1,7 @@ --- layout: page title: "ISY994 Controller" -description: "Instructions how to setup the ISY994 controller within Home Assistant." +description: "Instructions on how to setup the ISY994 controller within Home Assistant." date: 2015-01-20 22:36 sidebar: true comments: false @@ -29,22 +29,66 @@ isy994: username: ISY_USERNAME password: ISY_PASSWORD ``` + Configuration variables: - **host** (*Required*): The host entry should be in full URL format, eg. http://192.168.10.100:80 - **username** (*Required*): The username that used to access the ISY interface. - **password** (*Required*): The password that used to access the ISY interface. -- **sensor_string** (*Optional*): This is the string that is used to identify which devices are to be assumed to be sensors instead of lights of switches. By default, this string is 'sensor'. If this string is found in the device name or folder, Home Assistant will assume it is as a sensor or binary sensor (if the device has on/off or true/false states). -- **hidden_string** (*Optional*): The HIDDEN_STRING is a string that is used to identify which devices are to be hidden on Home Assistant's front page. This string will be stripped from the device's name before being used. By default, this value is '{HIDE ME}'. +- **sensor_string** (*Optional*): This is the string that is used to identify which devices are to be assumed to be sensors instead of lights of switches. By default, this string is 'sensor'. If this string is found in the device name or folder, Home Assistant will assume it is as a sensor or binary sensor (if the device has on/off or true/false states). This is only necessary for nodes that are not automatically detected as sensors by Home Assistant. Insteon door, window, motion and leak sensors should all be detected automatically. +- **ignore_string** (*Optional*): Any devices that contain this string in their name (or folder path) will be ignored by Home Assistant. They will not become entities at all. The default value is `{IGNORE ME}`. +- **enable_climate** (*Optional*): When enabled, climate measurements from the optional climate module in the ISY994 will show up in Home Assistant as sensors. The default value is `True`. - **tls** (*Optional*): This entry should reflect the version of TLS that the ISY controller is using for HTTPS encryption. This value can be either 1.1 or 1.2. If this value is not set, it is assumed to be version 1.1. This is the default for most users. ISY994 Pro users may likely be using 1.2. When using HTTPS in the host entry, it is best practice to set this value. Once the ISY controller is configured, it will automatically import any binary sensors, covers, fans, lights, locks, sensors and switches it can locate. +### {% linkable_title Sensors %} + +An Insteon door/window sensor will show up as a single Binary Sensor rather than two discrete devices like it does in the ISY994 admin panel. Note that when in "Two Nodes" mode, the sensor will have an UNKNOWN state until the sensor changes for the first time since the last Home Assistant reboot. If you do not use Insteon scenes that are controlled directly from the door sensor, you may prefer to set the sensor to "One Node" mode using the ISY Admin Panel. + +Each Insteon leak sensor will also show up as a single Binary Sensor as opposed to the two nodes seen in the ISY994. The name of the device will be based on what the parent node is named in the ISY994, which is typically the one with "-Dry" at the end of the name. This may be confusing, because "On" means wet in Home Assistant. You can rename this node either in the ISY994 Admin Panel (which will change the entity_id in Home Assistant) or assign a `friendly_name` in the [Customization section](/docs/configuration/customizing-devices/) of your configuration. + +If your leak or door/window sensor supports heartbeats, a new binary_sensor device will be added to Home Assistant to represent the battery state. The sensor will stay "Off" so long as the daily heartbeats occur. If a heartbeat is missed, the sensor will flip to "On". The name of this device will be based on the heartbeat node in the ISY. + +### {% linkable_title Handling Insteon Control Events %} + +A Home Assistant `isy994_control` event is emitted for every "control" event in the Insteon network. This allows you to write automations that trigger based on Insteon button presses. You can also trigger off of the unique Insteon events, such as double-presses, long-holds etc. + +```yaml +automation: + - alias: turn off living room on double tap lightswitch + trigger: + platform: event + event_type: isy994_control + event_data: + entity_id: light.lr_track_lights_front + control: 'DFOF' + action: + service: light.turn_off + entity_id: light.lr_track_lights_rear +``` + +All `isy994_control` events will have an `entity_id` and `control` parameter in its `event_data`. You'll need to refer to ISY994 documentation for the list of every possible control type, but the common ones are: + +- `DON`: On button. +- `DOF`: Off button. +- `DFON`: "Fast On", usually from double-tapping an On button. +- `DFOF`: "Fast Off", usually from double-tapping an Off button. +- `FDUP`: "Fade Up", usually while holding down an On button. +- `FDDOWN`: "Fade Down", usually while holding down an Off button. +- `FDSTOP`: "Fade Stop", when releasing a long-held button. +- `BRT`: "Brighten", from controllers that issue a single command to slightly brighten a light. +- `DIM`: "Dim", from controllers that issue a single command to slightly dim a light. + +### {% linkable_title Insteon Scenes %} + +All Insteon scenes configured in the ISY994 will show up as switches in Home Assistant. + ### {% linkable_title Creating Custom Devices %} Using the Programs tab in the controller's Administrative Console, custom devices can be created that will appear natively inside of Home Assistant. Home Assistant will scan the following folders and build the device to the associated domains: -``` +```text My Programs ├── HA.binary_sensor | ├── Movement In House @@ -82,11 +126,12 @@ My Programs ``` A device is created by creating a directory, with the name for the device, under any of the following root directories: - * *HA.binary_sensor* will create a binary sensor (see [Customizing Devices](https://home-assistant.io/getting-started/customizing-devices/) to set the sensor class) - * *HA.cover* will create a cover - * *HA.fan* will create a fan - * *HA.lock* will create a lock - * *HA.switch* will create a switch + +- *HA.binary_sensor* will create a binary sensor (see [Customizing Devices](/getting-started/customizing-devices/) to set the sensor class). +- *HA.cover* will create a cover. +- *HA.fan* will create a fan. +- *HA.lock* will create a lock. +- *HA.switch* will create a switch. A program, named *status*, is required under the program device directory. A program, named *actions*, is required for all program devices except for binary_sensor. Any other programs in these device directories will be ignored. The *status* program requires that you create a variable with the name of your choice. This variable will store the actual status of the new device and will be updated by the *action* program. @@ -95,21 +140,23 @@ A program, named *status*, is required under the program device directory. A pro The *status* program in this directory is what indicates the state of the device: - * *binary_sensor* on if the clause returns true, otherwise off - * *cover* closed if the clause returns true, otherwise open - * *fan* on if the clause returns true, otherwise off - * *lock* locked if the clause returns true, otherwise unlocked - * *switch* on if the clause returns true, otherwise off + +- *binary_sensor* on if the clause returns true, otherwise off. +- *cover* closed if the clause returns true, otherwise open. +- *fan* on if the clause returns true, otherwise off. +- *lock* locked if the clause returns true, otherwise unlocked. +- *switch* on if the clause returns true, otherwise off.
diff --git a/source/_components/joaoapps_join.markdown b/source/_components/joaoapps_join.markdown
index e27aa82e1a1..822a14604ba 100644
--- a/source/_components/joaoapps_join.markdown
+++ b/source/_components/joaoapps_join.markdown
@@ -12,23 +12,21 @@ ha_category: Hub
ha_release: "0.24"
---
-
-The Join platform exposes services from [Join](http://joaoapps.com/join). In Home Assistant, the Join features are divided up in two locations, the Join component, and the Join notify platform. The notify platform allows us to send messages to Join devices, the component allows us to access the other special features that Join offers.
+The `joaoapps_join` component exposes services from [Join](http://joaoapps.com/join). In Home Assistant, the Join features are divided up in two locations, the Join component, and the Join notify platform. The notify platform allows us to send messages to Join devices, the component allows us to access the other special features that Join offers.
In the `configuration.yaml` file you need to provide the api key and device id or name of the target device. You can find your device id and api key [here](https://joinjoaomgcd.appspot.com/).
To set it up, add the following information to your `configuration.yaml` file:
```yaml
+# Example configuration.yaml entry
notify:
- platform: joaoapps_join
api_key: asd97823jb628a34fwsdfwefd5384345tf2d
- device_id: d5asdfasdf54645h45h368761dfe5gt8a *optional
- device_ids: d5asdfasdf54645h45h368761dfe5gt8a, a4asdfasdf54645h45h368761dfe5gt3b *optional
- device_names: Pixel, iPhone *optional
- name: Phones *optional
-
-
+ device_id: d5asdfasdf54645h45h368761dfe5gt8a
+ device_ids: d5asdfasdf54645h45h368761dfe5gt8a, a4asdfasdf54645h45h368761dfe5gt3b
+ device_names: Pixel, iPhone
+ name: Phones
joaoapps_join:
- name: android
device_id: group.android
@@ -42,20 +40,19 @@ Configuration variables:
- **device_ids** (*Optional*): Comma separated list of device ids.
- **device_names** (*Optional*): Comma separated list of device names.
-The notify service has two optional parameters: `icon` and `vibration`. You can use them like so:
+The notify service has two optional parameters: `icon` and `vibration`. You can use them like so:
```json
{"message":"Hello from Home Assistant!","title":"Home Assistant","data":{"icon":"https://goo.gl/xeetdy", "vibration":"0,65,706,86,657,95,668,100"}}
```
-The services exposed in the joaoapps_join component can be used with the service data described below:
+The services exposed in the `joaoapps_join` component can be used with the service data described below:
| Service | Data |
|------------------------------ |------------------------------------------------------------------ |
| joaoapps_join/ring | |
-| joaoapps_join/send_sms | {"number":"5553334444", "message":"Hello!"} |
-| joaoapps_join/send_tasker | {"command":"test"} |
-| joaoapps_join/send_url | {"url":"http://google.com"} |
-| joaoapps_join/send_wallpaper | {"url":"http://www.planwallpaper.com/static/images/ZhGEqAP.jpg"} |
-| joaoapps_join/send_file | {"url":"http://download.thinkbroadband.com/5MB.zip"} |
-
+| joaoapps_join/send_sms | `{"number":"5553334444", "message":"Hello!"}` |
+| joaoapps_join/send_tasker | `{"command":"test"}` |
+| joaoapps_join/send_url | `{"url":"http://google.com"}` |
+| joaoapps_join/send_wallpaper | `{"url":"http://www.planwallpaper.com/static/images/ZhGEqAP.jpg"}` |
+| joaoapps_join/send_file | `{"url":"http://download.thinkbroadband.com/5MB.zip"}` |
diff --git a/source/_components/juicenet.markdown b/source/_components/juicenet.markdown
index 5015022c550..0ff22b9908e 100644
--- a/source/_components/juicenet.markdown
+++ b/source/_components/juicenet.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Juicenet"
-description: "Instructions how to setup WiFi-equipped Juicenet charging stations with Home Assistant."
+description: "Instructions on how to setup WiFi-equipped Juicenet charging stations with Home Assistant."
date: 2017-05-20 22:00
sidebar: true
comments: false
@@ -12,13 +12,14 @@ ha_category: Hub
ha_release: 0.47
---
-
The `juicenet` sensor platform pulls data from a [JuiceNet](https://emotorwerks.com/products/juicenet/) charging station equipped with a wifi connection. It will access and make available all of the devices attached to your account.
+## {% linkable_title Configuration %}
+
To enable the platform in your installation, add the following to your `configuration.yaml` file:
```yaml
-# Example configuration.yml entry
+# Example configuration.yaml entry
juicenet:
access_token: ACCESS_TOKEN
```
diff --git a/source/_components/keyboard.markdown b/source/_components/keyboard.markdown
index 07b3e2db260..d1324ae76ae 100644
--- a/source/_components/keyboard.markdown
+++ b/source/_components/keyboard.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Keyboard"
-description: "Instructions how to simulate key presses with Home Assistant."
+description: "Instructions on how to simulate key presses with Home Assistant."
date: 2015-01-24 14:39
sidebar: true
comments: false
@@ -12,15 +12,14 @@ ha_category: Automation
ha_release: pre 0.7
---
-
The `keyboard` component simulates key presses on the host machine. It currently offers the following Buttons as a Service (BaaS):
- * `keyboard/volume_up`
- * `keyboard/volume_down`
- * `keyboard/volume_mute`
- * `keyboard/media_play_pause`
- * `keyboard/media_next_track`
- * `keyboard/media_prev_track`
+- `keyboard/volume_up`
+- `keyboard/volume_down`
+- `keyboard/volume_mute`
+- `keyboard/media_play_pause`
+- `keyboard/media_next_track`
+- `keyboard/media_prev_track`
To load this component, add the following lines to your `configuration.yaml`:
@@ -33,7 +32,7 @@ keyboard:
You may need to install platform-specific [dependencies for PyUserInput](https://github.com/PyUserInput/PyUserInput#dependencies) in order to use the keyboard component. In most cases this can be done by running:
```bash
-$ pip3 install [package name]
+pip3 install [package name]
```
#### {% linkable_title Windows %}
diff --git a/source/_components/keyboard_remote.markdown b/source/_components/keyboard_remote.markdown
index f1d80bfa973..f94507ac0e2 100644
--- a/source/_components/keyboard_remote.markdown
+++ b/source/_components/keyboard_remote.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Keyboard Remote"
-description: "Instructions how to use a keyboard to remote control Home Assistant."
+description: "Instructions on how to use a keyboard to remote control Home Assistant."
date: 2016-09-28 14:39
sidebar: true
comments: false
@@ -15,11 +15,10 @@ ha_iot_class: "Local Push"
Receive signals from a keyboard and use it as a remote control.
-This component allows you to use a keyboard as remote control. It will fire `keyboard_remote_command_received` events which can then be used in automation rules.
+This component allows you to use one or more keyboards as remote controls. It will fire `keyboard_remote_command_received` events which can then be used in automation rules.
The `evdev` package is used to interface with the keyboard and thus this is Linux only. It also means you can't use your normal keyboard for this because `evdev` will block it.
-
```yaml
# Example configuration.yaml entry
keyboard_remote:
@@ -37,15 +36,17 @@ In case of presence of multiple devices of the same model, `device_descriptor` m
A list of possible device descriptors and names is reported in the debug log at startup when the device indicated in the configuration entry could not be found.
-A full configuration for Keyboard Remote could look like the one below:
+A full configuration for two Keyboard Remotes could look like the one below:
```yaml
keyboard_remote:
- device_descriptor: '/dev/input/by-id/bluetooth-keyboard'
+- device_descriptor: '/dev/input/by-id/bluetooth-keyboard'
+ type: 'key_up'
+- device_descriptor: '/dev/input/event0'
type: 'key_up'
```
-or like the following:
+Or like the following for one keyboard:
```yaml
keyboard_remote:
@@ -62,19 +63,24 @@ automation:
platform: event
event_type: keyboard_remote_command_received
event_data:
+ device_descriptor: "/dev/input/event0"
key_code: 107 # inspect log to obtain desired keycode
action:
service: light.turn_on
entity_id: light.all
```
+`device_descriptor` or `device_name` may be specificed in the trigger so the automation will be fired only for that keyboard. This is especially useful if you wish to use several bluetooth remotes to control different devices. Omit them to ensure the same key triggers the automation for all keyboards/remotes.
+
## {% linkable_title Disconnections %}
+
This component manages disconnections and re-connections of the keyboard, for example in the case of a Bluetooth device that turns off automatically to preserve battery.
If the keyboard disconnects, the component will fire an event `keyboard_remote_disconnected`.
When the keyboard reconnects, an event `keyboard_remote_connected` will be fired.
Here's an automation example that plays a sound through a media player whenever the keyboard connects/disconnects:
+
```yaml
automation:
- alias: Keyboard Connected
@@ -100,13 +106,14 @@ automation:
```
## {% linkable_title Permissions %}
+
There might be permissions problems with the event input device file. If this is the case, the user that Home Assistant runs as must be allowed read and write permissions with:
```bash
-$ sudo setfacl -m u:HASS_USER:rw /dev/input/event*
+sudo setfacl -m u:HASS_USER:rw /dev/input/event*
```
-where `HASS_USER` is the user who runs Home Assistant.
+Where `HASS_USER` is the user who runs Home Assistant.
If you want to make this permanent, you can use a udev rule that sets it for all event input devices. Add a file `/etc/udev/rules.d/99-userdev-input.rules` containing:
@@ -114,8 +121,8 @@ If you want to make this permanent, you can use a udev rule that sets it for all
KERNEL=="event*", SUBSYSTEM=="input", RUN+="/usr/bin/setfacl -m u:HASS_USER:rw $env{DEVNAME}"
```
-You can check ACLs permissions with
+You can check ACLs permissions with:
```bash
-$ getfacl /dev/input/event*
+getfacl /dev/input/event*
```
diff --git a/source/_components/kira.markdown b/source/_components/kira.markdown
index d2c2594834a..0e74ad07b69 100644
--- a/source/_components/kira.markdown
+++ b/source/_components/kira.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Kira"
-description: "Instructions how to integrate Keene Electronics IR over IP modules (Kira) into Home Assistant."
+description: "Instructions on how to integrate Keene Electronics IR over IP modules (Kira) into Home Assistant."
date: 2017-05-07 00:00
sidebar: true
comments: false
@@ -39,6 +39,7 @@ kira:
```
Configuration variables:
+
- **sensors** (*Optional*): Kira sensors to register
- **name** (*Optional*): Name of this sensor.
- **host** (*Optional*): Bind address for this sensor. 0.0.0.0 is default.
@@ -70,17 +71,19 @@ The first time the Kira component is loaded, `kira_codes.yaml` will be created i
```
Configuration variables:
+
- **name** (*Required*): The name of this code.
- **code** (*Required*): The data for this code (see below).
- **device** (*Optional*): The device this code is associated with. Default is "unknown".
- **type** (*Optional*): The type of this code. If this field is omitted, the type will be autodetected if possible.
- **repeat** (*Optional*): The number of times to repeat this code (on transmit). Default is 1.
-Some manufacturers (e.g. Samsung) require an IR code to be sent a number of times in a row in rapid succession (usually 3). This doesn't apply to the vast majority of devices, but it can be helpful if needed.
+Some manufacturers (e.g., Samsung) require an IR code to be sent a number of times in a row in rapid succession (usually 3). This doesn't apply to the vast majority of devices, but it can be helpful if needed.
### {% linkable_title Code Types %}
When creating an entry in `kira_codes.yaml`, a few different kinds of codes can be used.
+
- **kira**: This is the native wire protocol used by Kira modules. These can be captured using netcat.
- **pronto**: Pronto codes are supported.
- **nec**: If the device uses NEC IR codes and the manufacturer has published them, they can be used here.
diff --git a/source/_components/knx.markdown b/source/_components/knx.markdown
index ff8c0786fcc..7acfae76761 100644
--- a/source/_components/knx.markdown
+++ b/source/_components/knx.markdown
@@ -31,6 +31,7 @@ There is currently support for the following device types within Home Assistant:
- [Light](/components/light.knx)
- [Thermostat](/components/climate.knx)
- [Notify](/components/notify.knx)
+- [Scene](/components/scene.knx)
### {% linkable_title Configuration %}
@@ -82,8 +83,7 @@ knx:
- **fire_event** (*Optional*): If set to True, platform will write all received KNX messages to event bus
- **fire_event_filter** (*Optional*): If `fire_event` is set `fire_event_filter` has to be specified. `fire_event_filter` defines a list of patterns for filtering KNX addresses. Only telegrams which match this pattern are sent to the HOme Assistant event bus.
-- **state_updater** (*Optional*): The component will collect the current state of each configured device from the KNX bus to display it correctly within Home-Assistant. Set this option to False to prevent this behaviour.
-- **time_address** (*Optional*): Broadcast current local time to KNX bus with configured group address.
+- **state_updater** (*Optional*): The component will collect the current state of each configured device from the KNX bus to display it correctly within Home-Assistant. Set this option to False to prevent this behavior.
### {% linkable_title Services %}
@@ -98,6 +98,27 @@ Service Data: {"address": "1/0/15", "payload": 0}
* **address**: KNX group address
* **payload**: Payload, either an integer or an array of integers
+### {% linkable_title Exposing sensor values or time to knx bus %}
+
+KNX component is able to expose time or sensor values to KNX bus. The component will broadcast any change of the exposed value to the KNX bus and answer read requests to the specified group address:
+
+```yaml
+# Example configuration.yaml entry
+knx:
+ expose::
+ - type: 'temperature'
+ entity_id: 'sensor.owm_temperature'
+ address: '0/0/2'
+ - type: 'time'
+ address: '0/0/1'
+ - type: 'datetime'
+ address: '0/0/23'
+```
+
+* **type**: Type of the exposed value. Either time or datetime or any supported type of [KNX Sensor](/components/sensor.knx/) (e.g., "temperature" or "humidity").
+* **entity_id**: Entity id of the HASS component to be exposed. Not necessary for types time and datetime.
+* **address**: KNX group address.
+
### {% linkable_title Known issues %}
diff --git a/source/_components/konnected.markdown b/source/_components/konnected.markdown
new file mode 100644
index 00000000000..4710844aa45
--- /dev/null
+++ b/source/_components/konnected.markdown
@@ -0,0 +1,156 @@
+---
+layout: page
+title: "Konnected"
+description: "Connect wired alarm sensors and siren using the NodeMCU based Konnected Alarm Panel"
+date: 2018-04-03 12:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: konnected.png
+ha_category: Alarm
+ha_release: "0.70"
+---
+
+The `konnected` component lets you connect wired sensors and switches to a NodeMCU ESP8226 based device running the [open source Konnected software](https://github.com/konnected-io/konnected-security). Reuse the wired sensors and siren from an old or pre-wired alarm system installation and integrate them directly into Home Assistant.
+
+Visit the [Konnected.io website](https://konnected.io) for more information about the Konnected Alarm Panel board and compatible hardware.
+
+The component currently supports the following device types in Home Assistant:
+
+- [Binary Sensor](/components/binary_sensor.konnected/): Wired door and window sensors, motion detectors, glass-break detectors, leak sensors, smoke & CO detectors or any open/close switch.
+- [Switch](/components/switch.konnected/): Actuate a siren, strobe, buzzer or relay module.
+
+This component requires the [`discovery`](https://www.home-assistant.io/components/discovery) component to be enabled.
+
+## {% linkable_title Configuration %}
+
+A `konnected` section must be present in the `configuration.yml` file that specifies the Konnected devices on the network and the sensors or actuators attached to them:
+
+```yaml
+# Example configuration.yaml entry
+konnected:
+ access_token: REPLACE_ME_WITH_A_RANDOM_STRING
+ devices:
+ - id: 8bcd53
+ binary_sensors:
+ - zone: 1
+ type: door
+ switches:
+ - zone: out
+ - id: 438a38
+ binary_sensors:
+ - pin: 2
+ type: door
+ switches:
+ - pin: 5
+```
+
+{% configuration %}
+access_token:
+ description: Any random string. This is used to ensure that only those devices which you have configured can authenticate to Home Assistant to change a device state.
+ required: true
+ type: string
+api_host:
+ description: Override the IP address/host (and port number) of Home Assistant that the Konnected device(s) will use to communicate sensor state updates. If omitted, this is defaulted to the value of `base_url` in the `http` component. If you've set `base_url` to an external hostname, then you'll want to set this value back to your _local_ IP address and port (e.g. `http://192.168.1.101:8123`).
+ required: false
+ type: url
+ default: value of `base_url`
+devices:
+ description: A list of Konnected devices that you have on your network.
+ required: true
+ type: list
+ keys:
+ id:
+ description: The MAC address of the WiFi module with colons/punctuation removed. You can either use the full 12-character MAC address or only the last 6 characters. This is visible in the device's WiFi SSID and hostname.
+ required: true
+ type: string
+ binary_sensors:
+ description: A list of binary sensors connected to the device. See [Konnected Binary Sensor](/components/binary_sensor.konnected/) for configuration variables.
+ required: false
+ type: list
+ keys:
+ pin:
+ description: The number corresponding to the _IO index_ of the labeled pin on the NodeMCU dev board. See the [NodeMCU GPIO documentation](https://nodemcu.readthedocs.io/en/master/en/modules/gpio/) for more details. Valid values are 1, 2, 5, 6, 7 and 9.
+ required: exclusive
+ zone:
+ description: The number corresponding to the labeled zone on the [Konnected Alarm Panel](https://konnected.io) board. Valid values are 1, 2, 3, 4, 5 and 6.
+ required: exclusive
+ type:
+ description: Any [binary sensor](/components/binary_sensor/) class, typically `door`, `window`, `motion` or `smoke`.
+ required: true
+ name:
+ description: The name of the device used in the front end.
+ required: false
+ default: automatically generated
+ switches:
+ description: A list of actuators (on/off switches) connected to the device. See [Konnected Switch](/components/switch.konnected/) for configuration variables.
+ required: false
+ type: list
+ keys:
+ pin:
+ description: The number corresponding to the _IO index_ of the labeled pin on the NodeMCU dev board. See the [NodeMCU GPIO documentation](https://nodemcu.readthedocs.io/en/master/en/modules/gpio/) for more details. Valid values are 1, 2, 5, 6, 7 and 8.
+ required: exclusive
+ zone:
+ description: The number corresponding to the labeled zone on the [Konnected Alarm Panel](https://konnected.io) board or the word `out` to specify the dedicated ALARM/OUT terminal on the Konnected board. Valid values are 1, 2, 3, 4, 5 and out.
+ required: exclusive
+ name:
+ description: The name of the device used in the front end.
+ required: false
+ default: automatically generated
+ activation:
+ description: Either "low" or "high" to specify the state when the switch is turned on.
+ default: high
+ required: false
+{% endconfiguration%}
+
+#### {% linkable_title 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).
+
+## {% linkable_title Full configuration %}
+
+```yaml
+# Example configuration.yaml entry
+konnected:
+ access_token: REPLACE_ME_WITH_A_RANDOM_STRING
+ devices:
+ - id: 8bcd53
+ binary_sensors:
+ - zone: 1
+ type: door
+ name: 'Front Door'
+ - zone: 3
+ type: motion
+ name: 'Test Motion'
+ switches:
+ - zone: out
+ name: siren
+ - id: 438a38
+ binary_sensors:
+ - pin: 1
+ type: motion
+ name: 'Office Motion'
+ - pin: 2
+ type: door
+ name: 'Office Door'
+ switches:
+ - pin: 5
+ name: 'Garage Door'
+ activation: low
+```
+
+### {% linkable_title 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 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 |
diff --git a/source/_components/light.abode.markdown b/source/_components/light.abode.markdown
index bb6d597deef..f362107791d 100644
--- a/source/_components/light.abode.markdown
+++ b/source/_components/light.abode.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Abode Light"
-description: "Instructions how to integrate Abode lights into Home Assistant."
+description: "Instructions on how to integrate Abode lights into Home Assistant."
date: 2017-08-26 13:28
sidebar: true
comments: false
diff --git a/source/_components/light.ads.markdown b/source/_components/light.ads.markdown
new file mode 100644
index 00000000000..aaedc1c12f4
--- /dev/null
+++ b/source/_components/light.ads.markdown
@@ -0,0 +1,42 @@
+---
+layout: page
+title: "ADS Light"
+description: Instructions on how to set up ADS lights within Home Assistant
+date: 2017-10-25 10:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: beckhoff.png
+ha_category: Light
+ha_release: "0.60"
+ha_iot_class: "Local Push"
+---
+
+The `ads` light platform allows you to control your connecte ADS lights.
+
+To use your ADS device, you first have to set up your [ADS hub](/components/ads/) and then add the following to your `configuration.yaml`
+file:
+
+```yaml
+# Example configuration.yaml entry
+light:
+ - platform: ads
+ adsvar: GVL.enable_light
+ adsvar_brightness: GVL.brightness
+```
+
+{% configuration %}
+ adsvar:
+ required: true
+ description: The name of the boolean variable that switches the light on
+ type: string
+ adsvar_brightness:
+ required: false
+ description: The name of the variable that controls the brightness, use an unsigned integer on the PLC side
+ type: integer
+ name:
+ required: false
+ description: An identifier for the Light in the frontend
+ type: string
+{% endconfiguration %}
diff --git a/source/_components/light.avion.markdown b/source/_components/light.avion.markdown
index 74260e93957..68c40b1aac4 100644
--- a/source/_components/light.avion.markdown
+++ b/source/_components/light.avion.markdown
@@ -21,8 +21,6 @@ To enable these lights, add the following lines to your `configuration.yaml` fil
# Example configuration.yaml entry
light:
- platform: avion
- username: testuser@fakedomain.com
- password: foobar
```
Configuration variables:
diff --git a/source/_components/light.blinksticklight.markdown b/source/_components/light.blinksticklight.markdown
index 9deab2be84a..c11da280aca 100644
--- a/source/_components/light.blinksticklight.markdown
+++ b/source/_components/light.blinksticklight.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Blinkstick"
-description: "Instructions how to setup Blinkstick lights within Home Assistant."
+description: "Instructions on how to setup Blinkstick lights within Home Assistant."
date: 2015-10-08 10:00
sidebar: true
comments: false
diff --git a/source/_components/light.blinkt.markdown b/source/_components/light.blinkt.markdown
index 617e81cac21..ad2d6200f87 100644
--- a/source/_components/light.blinkt.markdown
+++ b/source/_components/light.blinkt.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Blinkt!"
-description: "Instructions how to setup Blinkt! RGB LED lights within Home Assistant."
+description: "Instructions on how to setup Blinkt! RGB LED lights within Home Assistant."
date: 2017-04-30 9:00
sidebar: true
comments: false
diff --git a/source/_components/light.deconz.markdown b/source/_components/light.deconz.markdown
new file mode 100644
index 00000000000..918f0733665
--- /dev/null
+++ b/source/_components/light.deconz.markdown
@@ -0,0 +1,29 @@
+---
+layout: page
+title: "deCONZ Lights"
+description: "Instructions on how to integrate Zigbee lights from deCONZ into Home Assistant."
+date: 2017-11-12 16:30
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: deconz.jpeg
+ha_category: Light
+ha_release: "0.61"
+ha_iot_class: "Local Push"
+---
+
+See the [deCONZ main component](/components/deconz/) for configuration instructions.
+
+The `Entity Id` names will be `light.device_name`, where `device_name` is defined in deCONZ. Light groups created in deCONZ will be created in Home Assistant as lights named `light.group_name_in_deconz`, allowing the user to control groups of lights with only a single API call to deCONZ.
+
+#### {% linkable_title Verified supported lights %}
+
+- IKEA Trådfri bulb E14 WS opal 400lm
+- IKEA Trådfri Bulb E27 WS Opal 980lm
+- IKEA Trådfri Bulb E27 WS Opal 1000lm
+- IKEA Trådfri Bulb GU10 W 400lm
+- OSRAM Flex RGBW
+- OSRAM Gardenpole RGBW
+- Philips Hue White A19
+- Philips Hue White Ambiance A19
diff --git a/source/_components/light.decora_wifi.markdown b/source/_components/light.decora_wifi.markdown
index 85dbcd0e575..7fc68d0dcf8 100644
--- a/source/_components/light.decora_wifi.markdown
+++ b/source/_components/light.decora_wifi.markdown
@@ -8,16 +8,17 @@ comments: false
sharing: true
footer: true
ha_category: Light
-ha_iot_class: "Local Polling"
+ha_iot_class: "Cloud Polling"
logo: leviton.png
ha_release: 0.51
---
-Support for [Leviton Decora Wi-Fi](http://www.leviton.com/en/products/lighting-controls/decora-smart-with-wifi) dimmers/switches.
+Support for [Leviton Decora Wi-Fi](http://www.leviton.com/en/products/lighting-controls/decora-smart-with-wifi) dimmers/switches via the MyLeviton API.
Supported devices (tested):
-- [DW6HD1-BZ](https://www.leviton.com/en/products/dw6hd) (Decora Smart Wi-Fi 600W Dimmer)
+- [DW6HD1-BZ](https://www.leviton.com/en/products/dw6hd-1bz) (Decora Smart Wi-Fi 600W Dimmer)
+- [DW15S-1BZ](https://www.leviton.com/en/products/dw15s-1bz) (Decora Smart Wi-Fi 15A Switch)
To enable these lights, add the following lines to your `configuration.yaml` file:
@@ -25,13 +26,18 @@ To enable these lights, add the following lines to your `configuration.yaml` fil
# Example configuration.yaml entry
light:
- platform: decora_wifi
- username: my_leviton_user_email@email.com
- password: my_leviton_password
+ username: YOUR_USERNAME
+ password: YOUR_PASSWORD
```
-Configuration variables:
-
-- **username** (*Required*): Your "My Leviton" app email address/user name.
-- **password** (*Required*): Your "My Leviton" app password.
-
+{% configuration %}
+username:
+ description: Your "My Leviton" app email address/user name.
+ required: true
+ type: string
+password:
+ description: Your "My Leviton" app password.
+ required: true
+ type: string
+{% endconfiguration %}
diff --git a/source/_components/light.eufy.markdown b/source/_components/light.eufy.markdown
new file mode 100644
index 00000000000..d8596c00487
--- /dev/null
+++ b/source/_components/light.eufy.markdown
@@ -0,0 +1,19 @@
+---
+layout: page
+title: "Eufy Lights"
+description: "Instructions on how to integrate Eufy LED lights into Home Assistant."
+date: 2018-04-09 19:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: eufy.png
+ha_category: Light
+ha_iot_class: "Local Polling"
+ha_release: 0.68
+---
+
+The `eufy` platform allows you to control your [Eufy](http://www.eufylife.com) lights from within Home Assistant.
+
+They will be automatically discovered if the [Eufy](/components/eufy/) component is enabled.
+
diff --git a/source/_components/light.flux_led.markdown b/source/_components/light.flux_led.markdown
index e74e6942d96..d53ebb88a69 100644
--- a/source/_components/light.flux_led.markdown
+++ b/source/_components/light.flux_led.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Flux Led/MagicLight"
-description: "Instructions how to setup Flux led/MagicLight within Home Assistant."
+description: "Instructions on how to setup Flux led/MagicLight within Home Assistant."
date: 2015-07-17 20:09
sidebar: true
comments: false
@@ -109,6 +109,14 @@ Will add a light with rgb+white mode (default). White and RGB channels can be ad
mode: "rgbw"
```
+Will add a light with white mode only. This is useful when only W channel is connected to an RGBW controller and allows the white level to be controlled via brightness value.
+
+```yaml
+ 192.168.1.10:
+ name: NAME
+ mode: "w"
+```
+
Some devices such as the Ledenet RGBW controller use a slightly different protocol for communicating the brightness to each color channel. If your device is only turning on or off but not changing color or brightness try adding the LEDENET protocol.
```yaml
diff --git a/source/_components/light.futurenow.markdown b/source/_components/light.futurenow.markdown
new file mode 100644
index 00000000000..fac13214fca
--- /dev/null
+++ b/source/_components/light.futurenow.markdown
@@ -0,0 +1,97 @@
+---
+layout: page
+title: "P5 FutureNow Lights"
+description: "Instructions on how to set up P5 FutureNow relay/dimmer units as lights within Home Assistant."
+date: 2018-07-24 15:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: p5.png
+ha_category: Light
+ha_release: 0.75
+---
+
+The `futurenow` light platform allows you to use [P5](http://www.p5.hu) FutureNow relay/dimmer units as lights. Currently supported units:
+* [FutureNow FNIP-6x2AD](http://www.p5.hu/index.php/products/ethernet-modules/265-fnip-6x2ad) dimmer unit (outputs only)
+* [FutureNow FNIP-8x10A](http://www.p5.hu/index.php/products/ethernet-modules/263-fnip-8x10a) relay unit (outputs only)
+
+### {% linkable_title Configuration Sample %}
+
+To use your FutureNow units, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+light:
+ - platform: futurenow
+ driver: FNIP6x10ad
+ host: 192.168.1.101
+ port: 7078
+ devices:
+ 5:
+ name: Dimmer Channel 5
+ dimmable: true
+```
+
+{% configuration %}
+driver:
+ description: "Type of the device. Currently `FNIP6x10ad` or `FNIP8x10a`."
+ required: true
+ type: string
+host:
+ description: "The IP address or hostname of your unit, e.g., `192.168.1.101`."
+ required: true
+ type: string
+port:
+ description: "The TCP port, as set in the unit's settings. Default is `7078`."
+ required: true
+ type: string
+devices:
+ description: "List of output channels to set up as lights."
+ required: true
+ type: map
+ keys:
+ channel_number:
+ description: "Output's (light) properties."
+ required: true
+ type: map
+ keys:
+ name:
+ description: "The name of the light."
+ required: true
+ type: string
+ dimmable:
+ description: "Set to `true` to enable dimming (FNIP6x10ad only)."
+ required: false
+ type: boolean
+ default: false
+{% endconfiguration %}
+
+### {% linkable_title Extended Configuration Sample %}
+
+The following example `configuration.yaml` has two different FutureNow units with multiple channels:
+
+```yaml
+# Example configuration.yaml entry
+light:
+ - platform: futurenow
+ driver: FNIP6x10ad
+ host: 192.168.1.101
+ port: 7078
+ devices:
+ 5:
+ name: Dimmer Channel 5
+ 6:
+ name: Dimmer Channel 6
+ dimmable: true
+
+ - platform: futurenow
+ driver: FNIP8x10a
+ host: 192.168.1.102
+ port: 7078
+ devices:
+ 1:
+ name: Relay Channel 1
+ 2:
+ name: Relay Channel 2
+```
diff --git a/source/_components/light.greenwave.markdown b/source/_components/light.greenwave.markdown
new file mode 100644
index 00000000000..16f8e160993
--- /dev/null
+++ b/source/_components/light.greenwave.markdown
@@ -0,0 +1,41 @@
+---
+layout: page
+title: Greenwave Reality (TCP Connected) Lights
+description: "Instructions on how to set up Greenwave Reality lights within Home Assistant."
+date: 2017-11-17 18:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: greenwavereality.png
+ha_category: Light
+ha_release: 0.61
+ha_iot_class: "Local Polling"
+---
+
+This component communicates with the Greenwave Reality (TCP Connected) Gateway to allow control of all lights and fixtures registered to the gateway. Bulbs and Fixtures can be created and modified inside the TCP Lighting App for Android and iOS.
+
+This component has been tested on firmware revisions:
+
+- 2.0.105
+
+To configure the connection to the gateway, add the following to your `configuration.yaml` file:
+
+```yaml
+light:
+ - platform: greenwave
+ host: XXX.XXX.XXX.XXX
+ version: 3
+```
+The version option is the major revision of your firmware, which should be 2 or 3. If you are running Version 2, there are no extra steps. If you are running Version 3, you must press the Sync button on the gateway prior to the first launch of Home Assistant, so a token can be grabbed. Once Home Assistant has started, you can either press the Sync button again or wait for it to time out manually.
+
+{% configuration %}
+host:
+ description: The IP Address of your Gateway
+ required: true
+ type: string
+version:
+ description: Major version of the gateway firmware
+ required: true
+ type: integer
+{% endconfiguration %}
diff --git a/source/_components/light.group.markdown b/source/_components/light.group.markdown
new file mode 100644
index 00000000000..4ec8262463d
--- /dev/null
+++ b/source/_components/light.group.markdown
@@ -0,0 +1,63 @@
+---
+layout: page
+title: "Light Group"
+description: "Instructions for how to setup light groups within Home Assistant."
+date: 2018-02-23 11:41
+sidebar: true
+comments: false
+sharing: true
+footer: true
+ha_category: Light
+ha_release: 0.65
+ha_iot_class: "Local Push"
+logo: home-assistant.png
+---
+
+The group light platform lets you combine multiple lights into one entity. All child lights of a light group can still be used as usual, but controlling the state of the grouped light will forward the command to each child light.
+
+To enable this platform in your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+light:
+ - platform: group
+ name: Kitchen Lights
+ entities:
+ - light.kitchen_ceiling_lights
+ - light.kitchen_under_cabinet_lights
+ - light.kitchen_spot_lights
+ - light.pendant_lights
+```
+
+{% configuration %}
+ name:
+ description: The name of the light group. Defaults to "Light Group".
+ required: false
+ type: string
+ entities:
+ description: A list of entities to be included in the light group.
+ required: true
+ type: string list
+{% endconfiguration %}
+
+
+
+Example of the light group "Kitchen Lights".
+
diff --git a/source/_components/light.homekit_controller.markdown b/source/_components/light.homekit_controller.markdown
new file mode 100644
index 00000000000..f3f7243a10f
--- /dev/null
+++ b/source/_components/light.homekit_controller.markdown
@@ -0,0 +1,16 @@
+---
+layout: page
+title: "HomeKit Light"
+description: "Instructions how to setup HomeKit lights within Home Assistant."
+date: 2017-03-19 21:08
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: apple-homekit.png
+ha_category: Light
+ha_iot_class: "Local Polling"
+ha_release: 0.68
+---
+
+To get your HomeKit lights working with Home Assistant, follow the instructions for the general [HomeKit controller component](/components/homekit_controller/).
diff --git a/source/_components/light.homematic.markdown b/source/_components/light.homematic.markdown
index b2223ae9e4c..86249ce98e0 100644
--- a/source/_components/light.homematic.markdown
+++ b/source/_components/light.homematic.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Homematic Light"
-description: "Instructions how to integrate Homematic lights within Home Assistant."
+description: "Instructions on how to integrate Homematic lights within Home Assistant."
date: 2016-06-28 08:30
sidebar: true
comments: false
diff --git a/source/_components/light.homematicip_cloud.markdown b/source/_components/light.homematicip_cloud.markdown
new file mode 100644
index 00000000000..6ea102daa8d
--- /dev/null
+++ b/source/_components/light.homematicip_cloud.markdown
@@ -0,0 +1,21 @@
+---
+layout: page
+title: "HomematicIP Cloud Light"
+description: "Instructions on how to integrate HomematicIP light switches within Home Assistant."
+date: 2018-04-02 13:40
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: homematicip_cloud.png
+ha_category: Switch
+ha_release: 0.70
+ha_iot_class: "Cloud Push"
+---
+
+The `homematicip_cloud` light platform allows you to control
+[HomematicIP](http://www.homematic-ip.com) light switches through Home Assistant.
+
+Devices will be configured automatically. Please refer to the
+[component](/components/homematicip_cloud/) configuration on how to setup
+HomematicIP Cloud.
diff --git a/source/_components/light.hue.markdown b/source/_components/light.hue.markdown
index 871972d4f0c..59e8b8e970e 100644
--- a/source/_components/light.hue.markdown
+++ b/source/_components/light.hue.markdown
@@ -1,7 +1,7 @@
---
layout: page
-title: "Philips Hue"
-description: "Instructions how to setup Philips Hue within Home Assistant."
+title: "Philips Hue Light"
+description: "Instructions on how to integrate Philips Hue lights into Home Assistant."
date: 2015-03-23 20:09
sidebar: true
comments: false
@@ -10,123 +10,11 @@ footer: true
logo: philips_hue.png
ha_category: Light
ha_iot_class: "Local Polling"
-featured: true
ha_release: pre 0.7
---
-Philips Hue support is integrated into Home Assistant as a light platform. The preferred way to setup the Philips Hue platform is by enabling the [discovery component](/components/discovery/).
+The Philips Hue light platform allows you to control your Philips Hue lights.
-Once discovered, if you have a custom default view, locate `configurator.philips_hue` in the entities list ( < > ) and add it to a group in `configuration.yaml`. Restart Home Assistant so that the configurator is visible in the Home Assistant dashboard. Once Home Assistant is restarted, locate and click on `configurator.philips_hue` to bring up the initiation dialog. This will prompt you to press the Hue button to register the Hue hub in Home Assistant. Once complete, the configurator entity isn't needed anymore and can be removed from any visible group in `configuration.yaml`.
+This component will automatically add `Lights` configured on your Hue bridges.
-When you configure the Hue bridge from Home Assistant, it writes a token to a file in your Home Assistant [configuration directory](/docs/configuration/). That token authenticates the communication with the Hue bridge. This token uses the IP Address of the Hue Bridge. If the IP address for the Hue Bridge changes, you will need to register the Hue Bridge with Home Assistant again. To avoid this you may set up DHCP registration for your Hue Bridge, so that it always has the same IP address.
-
-Restarting Home Assistant once more should result in the Hue lights listed as "light" entities. Add these light entities to configuration.yaml and restart Home Assistant once more to complete the installation.
-
-If you want to enable the component without relying on the [discovery component](/components/discovery/), add the following lines to your `configuration.yaml` file:
-
-```yaml
-# Example configuration.yaml entry
-light:
- - platform: hue
- host: DEVICE_IP_ADDRESS
-```
-
-Configuration variables:
-
-- **host** (*Optional*): IP address of the device, eg. 192.168.1.10. Required if not using the `discovery` component to discover Hue bridges.
-- **allow_unreachable** (*Optional*): (true/false) This will allow unreachable bulbs to report their state correctly.
-- **filename** (*Optional*): Make this unique if specifying multiple Hue hubs.
-- **allow_in_emulated_hue** (*Optional*): )true/false) Enable this to block all Hue entities from being added to the `emulated_hue` component.
-- **allow_hue_groups** (*Optional*): (true/false) Enable this to stop Home Assistant from importing the groups defined on the Hue bridge.
-
-### {% linkable_title Multiple Hue bridges %}
-
-If you use multiple Hue bridges then it's needed that you provide a configuration file for every bridge. The bridges can't share a single configuration file.
-
-Add `filename` to your Hue configuration entry in your `configuration.yaml` file:
-
-```yaml
-# Example configuration.yaml entry
-light:
- - platform: hue
- host: BRIDGE1_IP_ADDRESS
- filename: phue.conf
- - platform: hue
- host: BRIDGE2_IP_ADDRESS
- filename: phue2.conf
-```
-
-### {% linkable_title Using Hue Groups in Home Assistant %}
-
-The Hue API allows you to group lights. Home Assistant also supports grouping of entities natively, but sometimes it can be useful to use Hue Groups to group light bulbs. By doing so, Home Assistant only needs to send one API call to change the state of all the bulbs in those groups instead of one call for every light in the group. This causes all the bulbs to change state simultaneously.
-
-These Hue Groups can be a `Luminaire`, `Lightsource`, `LightGroup` or `Room`. The `Luminaire` and `Lightsource` can't be created manually since the Hue bridge manages these automatically based on the discovered bulbs. The `Room` and `LightGroup` can be created manually through the API, or the mobile app. A bulb can only exist in one `Room`, but can exist in multiple `LightGroup`. The `LightGroup` can be useful to link certain bulbs together since.
-
-The 2nd generation Hue app only allows to create a `Room`. You need to use the first generation app or the API to create a `LightGroup`.
-
-Example:
-
-To create a `LightGroup` named `Ceiling lights` that contains the lights 1, 2 and 3, execute the following command:
-
-```bash
-$ curl -XPOST -d '{"name": "Ceiling lights", "lights": ["1", "2", "3"]}' http://
- To support Hue Light Groups, your bridge needs to have at least firmware 1.13 (released on June 3, 2016).
-
+
+configuration.yaml by appending a sequential number to the section: light 2:, light 3: etc.
-In order to apply attributes to an entity you will need to add `data:` to the configuration. See example below +In order to apply attributes to an entity, you will need to add `data:` to the configuration. See example below
```yaml diff --git a/source/_components/light.mochad.markdown b/source/_components/light.mochad.markdown index 0bf8b817fe6..9721e9d6c98 100644 --- a/source/_components/light.mochad.markdown +++ b/source/_components/light.mochad.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Mochad Light" -description: "Instructions how to integrate X10 Mochad switches into Home Assistant." +description: "Instructions on how to integrate X10 Mochad lights into Home Assistant." date: 2017-07-14 11:29 sidebar: true comments: false @@ -11,13 +11,14 @@ ha_category: Light ha_release: 0.51 --- -The `mochad` switch platform lets you control an X10 enabled dimmer/light -device. +The `mochad` light platform lets you control an X10 enabled dimmer/light device. + + To enable this sensor, you first have to set up the [mochad component](/components/mochad/) and then add the following to your `configuration.yaml` file: ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry light: - platform: mochad devices: @@ -28,5 +29,7 @@ light: Configuration variables: - **address** (*Required*): The X10 address of the light. -- **name** (*Optional*): The name of the switch. Default is: x10_light_dev_*address*. +- **name** (*Optional*): The name of the light. Default is: x10_light_dev_*address*. - **comm_type** (*Optional*): pl (powerline) or rf (radio frequency). Default is pl. +- **brightness_levels** (*Optional*): The number of brightness levels the X10 light device supports. This can either be 32, 64, or 256 (note that the max +value sent to the device will be n-1 because it starts at 0) diff --git a/source/_components/light.mqtt.markdown b/source/_components/light.mqtt.markdown index ba3041dde38..e92f859fb7c 100644 --- a/source/_components/light.mqtt.markdown +++ b/source/_components/light.mqtt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MQTT Light" -description: "Instructions how to setup MQTT lights within Home Assistant." +description: "Instructions on how to setup MQTT lights within Home Assistant." date: 2015-11-13 08:30 sidebar: true comments: false @@ -14,6 +14,8 @@ ha_iot_class: depends The `mqtt` light platform lets you control your MQTT enabled lights. It supports setting brightness, color temperature, effects, flashing, on/off, RGB colors, transitions, XY colors and white values. +## {% linkable_title Configuration %} + In an ideal scenario, the MQTT device will have a state topic to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT light will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the switch will be `false` / `off`. When a state topic is not available, the light will work in optimistic mode. In this mode, the light will immediately change state after every command. Otherwise, the light will wait for state confirmation from the device (message from `state_topic`). @@ -21,45 +23,159 @@ When a state topic is not available, the light will work in optimistic mode. In Optimistic mode can be forced, even if the `state_topic` is available. Try to enable it, if experiencing incorrect light operation. ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry light: - platform: mqtt command_topic: "office/rgb1/light/switch" ``` -Configuration variables: - -- **command_topic** (*Required*): The MQTT topic to publish commands to change the switch state. -- **brightness_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's brightness. -- **brightness_scale** (*Optional*): Defines the maximum brightness value (i.e. 100%) of the MQTT device (defaults to 255). -- **brightness_state_topic** (*Optional*): The MQTT topic subscribed to receive brightness state updates. -- **brightness_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the brightness value. -- **color_temp_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's color temperature state. The color temperature command slider has a range of 157 to 500 mireds (micro reciprocal degrees). -- **color_temp_state_topic** (*Optional*): The MQTT topic subscribed to receive color temperature state updates. -- **color_temp_value_template** (*Optional*): Defines a [template](/topics/templating/) to extract the color temperature value. -- **effect_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's effect state. -- **effect_state_topic** (*Optional*): The MQTT topic subscribed to receive effect state updates. -- **effect_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the effect value. -- **effect_list** (*Optional*): The list of effects the light supports. -- **name** (*Optional*): The name of the switch. Default is 'MQTT Switch'. -- **on_command_type** (*Optional*): Defines when on the payload_on is sent. Using `last` (the default) will send any style (brightness, color, etc) topics first and then a `payload_on` to the `command_topic`. Using `first` will send the `payload_on` and then any style topics. Using `brightness` will only send brightness commands instead of the `payload_on` to turn the light on. -- **optimistic** (*Optional*): Flag that defines if switch works in optimistic mode. Default is true if no state topic defined, else false. -- **payload_off** (*Optional*): The payload that represents disabled state. Default is "OFF". -- **payload_on** (*Optional*): The payload that represents enabled state. Default is "ON". -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. -- **retain** (*Optional*): If the published message should have the retain flag on or not. -- **rgb_command_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to compose message which will be sent to `rgb_command_topic`. Available variables: `red`, `green` and `blue`. -- **rgb_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's RGB state. -- **rgb_state_topic** (*Optional*): The MQTT topic subscribed to receive RGB state updates. -- **rgb_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the RGB value. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **state_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the state value. The template should match the payload "on" and "off" values, so if your light uses "power on" to turn on, your `state_value_template` string should return "power on" when the switch is on. For example if the message is just "on", your `state_value_template` should be `power {{ value }}`. -- **white_value_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's white value. -- **white_value_state_topic** (*Optional*): The MQTT topic subscribed to receive white value updates. -- **white_value_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the white value. -- **xy_command_topic** (*Optional*): The MQTT topic to publish commands to change the light's XY state. -- **xy_state_topic** (*Optional*): The MQTT topic subscribed to receive XY state updates. -- **xy_value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the XY value. +{% configuration %} +name: + description: The name of the light. + required: false + type: string + default: MQTT Light +command_topic: + description: The MQTT topic to publish commands to change the switch state. + required: true + type: string +brightness_command_topic: + description: The MQTT topic to publish commands to change the light’s brightness. + required: false + type: string +brightness_scale: + description: "Defines the maximum brightness value (i.e. 100%) of the MQTT device." + required: false + type: integer + default: 255 +brightness_state_topic: + description: The MQTT topic subscribed to receive brightness state updates. + required: false + type: string +brightness_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the brightness value." + required: false + type: string +color_temp_command_topic: + description: The MQTT topic to publish commands to change the light’s color temperature state. The color temperature command slider has a range of 153 to 500 mireds (micro reciprocal degrees). + required: false + type: string +color_temp_state_topic: + description: The MQTT topic subscribed to receive color temperature state updates. + required: false + type: string +color_temp_value_template: + description: "Defines a [template](/topics/templating/) to extract the color temperature value." + required: false + type: string +effect_command_topic: + description: "The MQTT topic to publish commands to change the light's effect state." + required: false + type: string +effect_state_topic: + description: The MQTT topic subscribed to receive effect state updates. + required: false + type: string +effect_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the effect value." + required: false + type: string +effect_list: + description: The list of effects the light supports. + required: false + type: string list +on_command_type: + description: "Defines when on the payload_on is sent. Using `last` (the default) will send any style (brightness, color, etc) topics first and then a `payload_on` to the `command_topic`. Using `first` will send the `payload_on` and then any style topics. Using `brightness` will only send brightness commands instead of the `payload_on` to turn the light on." + required: false + type: string +optimistic: + description: Flag that defines if switch works in optimistic mode. + required: false + type: boolean + default: "`true` if no state topic defined, else `false`." +payload_on: + description: The payload that represents enabled state. + required: false + type: string + default: "ON" +payload_off: + description: The payload that represents disabled state. + required: false + type: string + default: "OFF" +qos: + description: The maximum QoS level of the state topic. + required: false + type: integer + default: 0 +retain: + description: If the published message should have the retain flag on or not. + required: false + type: boolean + default: false +rgb_command_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to compose message which will be sent to `rgb_command_topic`. Available variables: `red`, `green` and `blue`." + required: false + type: string +rgb_command_topic: + description: "The MQTT topic to publish commands to change the light's RGB state." + required: false + type: string +rgb_state_topic: + description: The MQTT topic subscribed to receive RGB state updates. The expected payload is the RGB values separated by commas, for example `255,0,127`. + required: false + type: string +rgb_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the RGB value." + required: false + type: string +state_topic: + description: The MQTT topic subscribed to receive state updates. + required: false + type: string +state_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the state value. The template should match the payload `on` and `off` values, so if your light uses `power on` to turn on, your `state_value_template` string should return `power on` when the switch is on. For example if the message is just `on`, your `state_value_template` should be `power {{ value }}`." + required: false + type: string +white_value_command_topic: + description: "The MQTT topic to publish commands to change the light's white value." + required: false + type: string +white_value_state_topic: + description: The MQTT topic subscribed to receive white value updates. + required: false + type: string +white_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the white value." + required: false + type: string +xy_command_topic: + description: "The MQTT topic to publish commands to change the light's XY state." + required: false + type: string +xy_state_topic: + description: The MQTT topic subscribed to receive XY state updates. + required: false + type: string +xy_value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the XY value." + required: false + type: string +availability_topic: + description: The MQTT topic subscribed to receive availability (online/offline) updates. + required: false + type: string +payload_available: + description: The payload that represents the available state. + required: false + type: string + default: online +payload_not_available: + description: The payload that represents the unavailable state. + required: false + type: string + default: offline +{% endconfiguration %}Make sure that your topics match exactly. `some-topic/` and `some-topic` are different topics. @@ -71,7 +187,7 @@ Configuration variables: ## {% linkable_title Comparison of light MQTT platforms %} -| Function | [`mqtt`](https://home-assistant.io/components/light.mqtt/) | [`mqtt_json`](https://home-assistant.io/components/light.mqtt_json/) | [`mqtt_template`](https://home-assistant.io/components/light.mqtt_template/) | +| Function | [`mqtt`](/components/light.mqtt/) | [`mqtt_json`](/components/light.mqtt_json/) | [`mqtt_template`](/components/light.mqtt_template/) | |-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------| | Brightness | ✔ | ✔ | ✔ | | Color temperature | ✔ | ✔ | ✔ | @@ -80,6 +196,7 @@ Configuration variables: | RGB Color | ✔ | ✔ | ✔ | | Transitions | ✘ | ✔ | ✔ | | XY Color | ✔ | ✔ | ✘ | +| HS Color | ✘ | ✔ | ✘ | | White Value | ✔ | ✔ | ✔ | ## {% linkable_title Examples %} @@ -90,8 +207,9 @@ In this section you will find some real life examples of how to use this sensor. To enable a light with brightness and RGB support in your installation, add the following to your `configuration.yaml` file: +{% raw %} ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry light: - platform: mqtt name: "Office Light RGB" @@ -101,28 +219,29 @@ light: brightness_command_topic: "office/rgb1/brightness/set" rgb_state_topic: "office/rgb1/rgb/status" rgb_command_topic: "office/rgb1/rgb/set" - state_value_template: "{% raw %}{{ value_json.state }}{% endraw %}" - brightness_value_template: "{% raw %}{{ value_json.brightness }}{% endraw %}" - rgb_value_template: "{% raw %}{{ value_json.rgb | join(',') }}{% endraw %}" + state_value_template: "{{ value_json.state }}" + brightness_value_template: "{{ value_json.brightness }}" + rgb_value_template: "{{ value_json.rgb | join(',') }}" qos: 0 payload_on: "ON" payload_off: "OFF" optimistic: false ``` +{% endraw %} ### {% linkable_title Brightness and no RGB support %} To enable a light with brightness (no RGB version) in your installation, add the following to your `configuration.yaml` file: ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry light: - platform: mqtt name: "Office light" - state_topic: "office/rgb1/light/status" - command_topic: "office/rgb1/light/switch" - brightness_state_topic: 'office/rgb1/light/brightness' - brightness_command_topic: 'office/rgb1/light/brightness/set' + state_topic: "office/light/status" + command_topic: "office/light/switch" + brightness_state_topic: 'office/light/brightness' + brightness_command_topic: 'office/light/brightness/set' qos: 0 payload_on: "ON" payload_off: "OFF" @@ -134,19 +253,18 @@ light: To enable a light that sends only brightness topics to turn it on, add the following to your `configuration.yaml` file. The `command_topic` is only used to send an off command in this case: ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry light: - platform: mqtt name: "Brightness light" state_topic: "office/light/status" command_topic: "office/light/switch" payload_off: "OFF" - brightness_state_topic: 'office/rgb1/light/brightness' - brightness_command_topic: 'office/rgb1/light/brightness/set' + brightness_state_topic: 'office/light/brightness' + brightness_command_topic: 'office/light/brightness/set' on_command_type: 'brightness' ``` - ### {% linkable_title Implementations %} - A [basic example](https://github.com/mertenats/open-home-automation/tree/master/ha_mqtt_light) using a nodeMCU board (ESP8266) to control its built-in LED (on/off). diff --git a/source/_components/light.mqtt_json.markdown b/source/_components/light.mqtt_json.markdown index 54732fe5bff..6e70c8be891 100644 --- a/source/_components/light.mqtt_json.markdown +++ b/source/_components/light.mqtt_json.markdown @@ -23,10 +23,12 @@ This platform supports on/off, brightness, RGB colors, XY colors, color temperat "color_temp": 155, "color": { "r": 255, - "g": 255, - "b": 255, - "x": 0.123, - "y": 0.123 + "g": 180, + "b": 200, + "x": 0.406, + "y": 0.301, + "h": 344.0, + "s": 29.412 }, "effect": "colorloop", "state": "ON", @@ -48,35 +50,116 @@ light: command_topic: "home/rgb1/set" ``` -Configuration variables: - -- **command_topic** (*Required*): The MQTT topic to publish commands to change the light's state. -- **brightness** (*Optional*): Flag that defines if the light supports brightness. Default is false. -- **color_temp** (*Optional*): Flag that defines if the light supports color temperature. Default is false. -- **effect** (*Optional*): Flag that defines if the light supports effects. Default is false. -- **effect_list** (*Optional*): The list of effects the light supports. -- **flash_time_long** (*Optional*): The duration, in seconds, of a "long" flash. Default is 10. -- **flash_time_short** (*Optional*): The duration, in seconds, of a "short" flash. Default is 2. -- **name** (*Optional*): The name of the light. Default is "MQTT JSON Light." -- **optimistic** (*Optional*): Flag that defines if the light works in optimistic mode. Default is true if no state topic defined, else false. -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. -- **retain** (*Optional*): If the published message should have the retain flag on or not. -- **rgb** (*Optional*): Flag that defines if the light supports RGB colors. Default is false. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **white_value** (*Optional*): Flag that defines if the light supports white values. Default is false. -- **xy** (*Optional*): Flag that defines if the light supports XY colors. Default is false. +{% configuration %} +name: + description: The name of the light. + required: false + type: string + default: MQTT JSON Light +command_topic: + description: The MQTT topic to publish commands to change the light’s state. + required: true + type: string +brightness: + description: Flag that defines if the light supports brightness. + required: false + type: boolean + default: false +brightness_scale: + description: "Defines the maximum brightness value (i.e. 100%) of the MQTT device." + required: false + type: integer + default: 255 +color_temp: + description: Flag that defines if the light supports color temperature. + required: false + type: boolean + default: false +effect: + description: Flag that defines if the light supports effects. + required: false + type: boolean + default: false +effect_list: + description: The list of effects the light supports. + required: false + type: string list +flash_time_long: + description: The duration, in seconds, of a “long” flash. + required: false + type: integer + default: 10 +flash_time_short: + description: The duration, in seconds, of a “short” flash. + required: false + type: integer + default: 2 +optimistic: + description: Flag that defines if the light works in optimistic mode. + required: false + type: boolean + default: "`true` if no state topic defined, else `false`." +qos: + description: The maximum QoS level of the state topic. + required: false + type: integer + default: 0 +retain: + description: If the published message should have the retain flag on or not. + required: false + type: boolean + default: false +rgb: + description: Flag that defines if the light supports RGB colors. + required: false + type: boolean + default: false +state_topic: + description: The MQTT topic subscribed to receive state updates. + required: false + type: string +white_value: + description: Flag that defines if the light supports white values. + required: false + type: boolean + default: false +xy: + description: Flag that defines if the light supports XY colors. + required: false + type: boolean + default: false +hs: + description: Flag that defines if the light supports HS colors. + required: false + type: boolean + default: false +availability_topic: + description: The MQTT topic subscribed to receive availability (online/offline) updates. + required: false + type: string +payload_available: + description: The payload that represents the available state. + required: false + type: string + default: online +payload_not_available: + description: The payload that represents the unavailable state. + required: false + type: string + default: offline +{% endconfiguration %}
Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics.
- XY and RGB can not be used at the same time. If both are provided, XY overrides RGB. + RGB, XY and HSV can not be used at the same time in `state_topic` messages. Make sure that only one of the color models is in the "color" section of the state MQTT payload.
## {% linkable_title Comparison of light MQTT platforms %} -| Function | [`mqtt`](https://home-assistant.io/components/light.mqtt/) | [`mqtt_json`](https://home-assistant.io/components/light.mqtt_json/) | [`mqtt_template`](https://home-assistant.io/components/light.mqtt_template/) | +| Function | [`mqtt`](/components/light.mqtt/) | [`mqtt_json`](/components/light.mqtt_json/) | [`mqtt_template`](/components/light.mqtt_template/) | |-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------| | Brightness | ✔ | ✔ | ✔ | | Color temperature | ✔ | ✔ | ✔ | @@ -85,6 +168,7 @@ Configuration variables: | RGB Color | ✔ | ✔ | ✔ | | Transitions | ✘ | ✔ | ✔ | | XY Color | ✔ | ✔ | ✘ | +| HS Color | ✘ | ✔ | ✘ | | White Value | ✔ | ✔ | ✔ | ## {% linkable_title Examples %} @@ -120,6 +204,54 @@ light: brightness: true ``` +### {% linkable_title Brightness Scaled %} + +To enable a light using a brightness scale other than 8bit the `brightness_scale` option may be added to denote the "fully on" value: +```yaml +# Example configuration.yaml entry +light: + - platform: mqtt_json + name: mqtt_json_light_1 + state_topic: "home/light" + command_topic: "home/light/set" + brightness: true + brightness_scale: 4095 +``` + +Home Assistant will then convert its 8bit value in the message to and from the device: + +```json +{ + "brightness": 4095, + "state": "ON" +} +``` + +### {% linkable_title HS Color %} + +To use a light with hue+saturation as the color model, set `hs` to `true` in the platform configuration: + +```yaml +light: + - platform: mqtt_json + name: mqtt_json_hs_light + state_topic: "home/light" + command_topic: "home/light/set" + hs: True +``` + +Home Assistant expects the hue values to be in the range 0 to 360 and the saturation values to be scaled from 0 to 100. For example, the following is a blue color shade: + +```json +{ + "state": "ON", + "color": { + "h": 24.0, + "s": 100.0 + } +} +``` + ### {% linkable_title Implementations %} - A full example of custom lighting using this platform and an ESP8266 microcontroller can be found [here](https://github.com/corbanmailloux/esp-mqtt-rgb-led). It supports on/off, brightness, transitions, RGB colors, and flashing. @@ -127,3 +259,7 @@ light: - There is also another implementation forked from the above repo, it supports all the same features but is made for addressable LED strips using FastLED on a NodeMCU V3 it can be found [here](https://github.com/JammyDodger231/nodemcu-mqtt-rgb-led). - [MQTT JSON Light](https://github.com/mertenats/Open-Home-Automation/tree/master/ha_mqtt_rgbw_light_with_discovery) is another implementation for ESP8266 including [MQTT discovery](/docs/mqtt/discovery/). + +- [esphomelib](https://github.com/OttoWinter/esphomelib) is a library for ESP8266 and ESP32 boards that has many of Home Assistant's MQTT features (like [discovery](/docs/mqtt/discovery/)) pre-implemented and provides high-level abstractions for components such as lights or sensors. + +- [AiLight](https://github.com/stelgenhof/AiLight) is a custom firmware for the Ai-Thinker (and equivalent) RGBW WiFi light bulbs that has an ESP8266 onboard and controlled by the MY9291 LED driver. It implements the [MQTT JSON light](/components/light.mqtt_json/) platform and supports ON/OFF, RGBW colours, brightness, colour temperature, flashing and transitions. Also it includes [MQTT Auto Discovery](/docs/mqtt/discovery/)) and the MQTT Last Will and Testament is enabled as well. \ No newline at end of file diff --git a/source/_components/light.mqtt_template.markdown b/source/_components/light.mqtt_template.markdown index 3eed0fa3445..11b43726724 100644 --- a/source/_components/light.mqtt_template.markdown +++ b/source/_components/light.mqtt_template.markdown @@ -33,24 +33,89 @@ light: command_off_template: "off" ``` -Configuration variables: - -- **name** (*Optional*): The name of the light. Default is "MQTT Template Light." -- **effect_list** (*Optional*): List of possible effects. -- **command_topic** (*Required*): The MQTT topic to publish commands to change the light's state. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **command_on_template** (*Required*): The [template](/docs/configuration/templating/#processing-incoming-data) for *on* state changes. Available variables: `state`, `brightness`, `red`, `green`, `blue`, `flash`, `transition` and `effect`. -- **command_off_template** (*Required*): The [template](/docs/configuration/templating/#processing-incoming-data) for *off* state changes. Available variables: `state` and `transition`. -- **state_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract state from the state payload value. -- **brightness_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract brightness from the state payload value. -- **red_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract red color from the state payload value. -- **green_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract green color from the state payload value. -- **blue_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract blue color from the state payload value. -- **color_temp_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract color temperature from the state payload value. -- **effect_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract effect from the state payload value. -- **white_value_template** (*Optional*): [Template](/docs/configuration/templating/#processing-incoming-data) to extract white value from the state payload value. -- **optimistic** (*Optional*): Flag that defines if the light works in optimistic mode. Default is true if no state topic or state template is defined, else false. -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. +{% configuration %} +name: + description: The name of the light. + required: false + type: string + default: MQTT Template Light +effect_list: + description: List of possible effects. + required: false + type: string list +command_topic: + description: The MQTT topic to publish commands to change the light’s state. + required: true + type: string +state_topic: + description: The MQTT topic subscribed to receive state updates. + required: false + type: string +command_on_template: + description: "The [template](/docs/configuration/templating/#processing-incoming-data) for *on* state changes. Available variables: `state`, `brightness`, `red`, `green`, `blue`, `flash`, `transition` and `effect`." + required: true + type: string +command_off_template: + description: "The [template](/docs/configuration/templating/#processing-incoming-data) for *off* state changes. Available variables: `state` and `transition`." + required: true + type: string +state_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract state from the state payload value." + required: false + type: string +brightness_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract brightness from the state payload value." + required: false + type: string +red_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract red color from the state payload value." + required: false + type: string +green_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract green color from the state payload value." + required: false + type: string +blue_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract blue color from the state payload value." + required: false + type: string +color_temp_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract color temperature from the state payload value." + required: false + type: string +effect_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract effect from the state payload value." + required: false + type: string +white_value_template: + description: "[Template](/docs/configuration/templating/#processing-incoming-data) to extract white value from the state payload value." + required: false + type: string +optimistic: + description: Flag that defines if the light works in optimistic mode. + required: false + type: string + default: "`true` if no state topic or state template is defined, else `false`." +qos: + description: The maximum QoS level of the state topic. + required: false + type: integer + default: 0 +availability_topic: + description: The MQTT topic subscribed to receive availability (online/offline) updates. + required: false + type: string +payload_available: + description: The payload that represents the available state. + required: false + type: string + default: online +payload_not_available: + description: The payload that represents the unavailable state. + required: false + type: string + default: offline +{% endconfiguration %}Make sure that your topics match exact. `some-topic/` and `some-topic` are different topics. @@ -58,7 +123,7 @@ Configuration variables: ## {% linkable_title Comparison of light MQTT platforms %} -| Function | [`mqtt`](https://home-assistant.io/components/light.mqtt/) | [`mqtt_json`](https://home-assistant.io/components/light.mqtt_json/) | [`mqtt_template`](https://home-assistant.io/components/light.mqtt_template/) | +| Function | [`mqtt`](/components/light.mqtt/) | [`mqtt_json`](/components/light.mqtt_json/) | [`mqtt_template`](/components/light.mqtt_template/) | |-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------| | Brightness | ✔ | ✔ | ✔ | | Color temperature | ✔ | ✔ | ✔ | @@ -67,6 +132,7 @@ Configuration variables: | RGB Color | ✔ | ✔ | ✔ | | Transitions | ✘ | ✔ | ✔ | | XY Color | ✔ | ✔ | ✘ | +| HS Color | ✘ | ✔ | ✘ | | White Value | ✔ | ✔ | ✔ | ## {% linkable_title Examples %} @@ -75,7 +141,7 @@ In this section you find some real life examples of how to use this light. ### {% linkable_title Simple string payload %} -For a simple string payload with the format `state,brightness,r-g-b` (e.g. `on,255,255-255-255`), add the following to your `configuration.yaml` file: +For a simple string payload with the format `state,brightness,r-g-b` (e.g., `on,255,255-255-255`), add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry diff --git a/source/_components/light.mysensors.markdown b/source/_components/light.mysensors.markdown index 4bf9a9d28a8..5f91aa43fe1 100644 --- a/source/_components/light.mysensors.markdown +++ b/source/_components/light.mysensors.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MySensors Light" -description: "Instructions how to integrate MySensors lights into Home Assistant." +description: "Instructions on how to integrate MySensors lights into Home Assistant." date: 2016-10-01 15:00 +0200 sidebar: true comments: false diff --git a/source/_components/light.mystrom.markdown b/source/_components/light.mystrom.markdown index f9ceacdb226..9cc2555fb16 100644 --- a/source/_components/light.mystrom.markdown +++ b/source/_components/light.mystrom.markdown @@ -1,7 +1,7 @@ --- layout: page title: "myStrom WiFi Bulb" -description: "Instructions how to integrate myStrom WiFi Bulbs into Home Assistant." +description: "Instructions on how to integrate myStrom WiFi Bulbs into Home Assistant." date: 2017-04-18 06:00 sidebar: true comments: false diff --git a/source/_components/light.nanoleaf_aurora.markdown b/source/_components/light.nanoleaf_aurora.markdown new file mode 100644 index 00000000000..9127387e298 --- /dev/null +++ b/source/_components/light.nanoleaf_aurora.markdown @@ -0,0 +1,56 @@ +--- +layout: page +title: "Nanoleaf Aurora Light Panel" +description: "Instructions how to integrate Nanoleaf Aurora Light Panels into Home Assistant." +date: 2018-01-04 20:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: nanoleaf_aurora_light.png +ha_category: Light +ha_iot_class: "Local Polling" +featured: false +ha_release: 0.67 +--- + +### {% linkable_title Configuration Sample %} + +The `nanoleaf_aurora` platform allows you to control [Nanoleaf Aurora Light Panels](https://nanoleaf.me) from Home Assistant. + +The preferred way to set up this platform is by enabling the [discovery component](https://www.home-assistant.io/components/discovery/). Make sure to press and hold the *ON* button for 5 seconds (the LED will start flashing) on your Nanoleaf Aurora Panel while Home Assistant is starting. + +To configure the Aurora lights manually, add the following lines to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +light: + - platform: nanoleaf_aurora + host: 192.168.1.10 + token: xxxxxxxxxxxxxxxxxxxxx +``` + +{% configuration %} +host: + description: IP address or host-name of the device, e.g., 192.168.1.10. + required: true + type: string +token: + description: The *auth* token that you get via *POST* to */api/v1/new* + required: true + type: string +name: + description: Name of the component, make this unique if you have multiple Light Panels + required: false + type: string + default: Aurora +{% endconfiguration %} + +### {% linkable_title Getting The Auth Token %} + +1. Make sure that your Nanoleaf Aurora Panel is fully patched (as of the time of writing the latest version was 2.2.0) +2. Hold down the *ON* button on the Panel for 5 seconds; the LED will start flashing +3. Issue a *POST* request to the API endpoint, e.g., via `$ curl -i -X POST http://192.168.1.155:16021/api/v1/new` +4. The output should include the auth token like *{"auth_token":"xxxxxxxxxxxxxxxxxxxxx"}*, copy the resulting token into your configuration + +If you get a 403 Forbidden message, you probably did not press the *ON* button long enough. The time-frame to get a valid token is only 30 seconds, so you have to be quick to issue the curl request. diff --git a/source/_components/light.osramlightify.markdown b/source/_components/light.osramlightify.markdown index 86fa342c9b3..d0479693e0c 100644 --- a/source/_components/light.osramlightify.markdown +++ b/source/_components/light.osramlightify.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Osram Lightify" -description: "Instructions how to integrate Osram Lightify into Home Assistant." +description: "Instructions on how to integrate Osram Lightify into Home Assistant." date: 2016-05-29 08:00 sidebar: true comments: false @@ -23,5 +23,5 @@ light: Configuration variables: - **host** (*Required*): IP address of the Osram Lightify bridge, eg. `192.168.1.50`. +- **allow_lightify_nodes** (*Optional*): (true/false) Edit this to stop homeassistant from importing the lightify lights. - **allow_lightify_groups** (*Optional*): (true/false) Edit this to stop homeassistant from importing the lightify groups. - diff --git a/source/_components/light.piglow.markdown b/source/_components/light.piglow.markdown index d261a816487..c2664af84cf 100644 --- a/source/_components/light.piglow.markdown +++ b/source/_components/light.piglow.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Piglow" -description: "Instructions how to setup Piglow LED's within Home Assistant." +description: "Instructions on how to setup Piglow LED's within Home Assistant." date: 2017-01-13 18:00 sidebar: true comments: false diff --git a/source/_components/light.qwikswitch.markdown b/source/_components/light.qwikswitch.markdown index e1f600c98f3..13f61413f64 100644 --- a/source/_components/light.qwikswitch.markdown +++ b/source/_components/light.qwikswitch.markdown @@ -1,7 +1,7 @@ --- layout: page title: "QwikSwitch Light" -description: "Instructions how to integrate Qwikswitch dimmers and relays as lights into Home Assistant." +description: "Instructions on how to integrate Qwikswitch dimmers and relays as lights into Home Assistant." date: 2016-05-04 00:00 sidebar: true comments: false diff --git a/source/_components/light.rflink.markdown b/source/_components/light.rflink.markdown index 0bd73b588ef..cc56e6de3ee 100644 --- a/source/_components/light.rflink.markdown +++ b/source/_components/light.rflink.markdown @@ -1,7 +1,7 @@ --- layout: page title: "RFLink Light" -description: "Instructions how to integrate RFLink lights into Home Assistant." +description: "Instructions on how to integrate RFLink lights into Home Assistant." date: 2016-01-04 sidebar: true comments: false @@ -50,7 +50,7 @@ Device configuration variables: - **name** (*Optional*): Name for the device, defaults to Rflink ID. - **type** (*Optional*): Override automatically detected type of the light device, can be: switchable, dimmable, hybrid or toggle. See 'Light Types' below. (default: Switchable) - **aliases** (*Optional*): Alternative Rflink ID's this device is known by. -- **fire_event** (*Optional*): Fire an `button_pressed` event if this device is turned on or off (default: False). +- **fire_event** (*Optional*): Fire a `button_pressed` event if this device is turned on or off (default: False). - **signal_repetitions** (*Optional*): Repeat every Rflink command this number of times (default: 1). - **fire_event_** (*Optional*): Set default `fire_event` for RFLink switch devices (see below). - **signal_repetitions** (*Optional*): Set default `signal_repetitions` for RFLink switch devices (see below). @@ -86,7 +86,7 @@ Any on/off command from any alias ID updates the current state of the light. How Light devices can come in different forms. Some only switch on and off, other support dimming. Dimmable devices might not always respond nicely to repeated `on` command as they turn into a pulsating state until `on` is pressed again (for example KlikAanKlikUit). The RFLink component support three types of lights to make things work in every situation: -- *Hybrid*: This type sends a `dim` followed by an a `on` command; and `off` commands. This will make dimmable devices turn on at the requested dim level and on/off devices on. One caveat is this type is not compatible with signal repetition as multiple `on` signals will cause dimmers to go into disco mode. +- *Hybrid*: This type sends a `dim` followed by an an `on` command; and `off` commands. This will make dimmable devices turn on at the requested dim level and on/off devices on. One caveat is this type is not compatible with signal repetition as multiple `on` signals will cause dimmers to go into disco mode. - *Switchable*: Device type that sends only `on` and `off` commands. It work for both on/off and dimmable type switches. However dimmables might have issues with signal repetition (see above). - *Dimmable*: Sends only `dim` and `off` commands. This does not work on on/off type devices as they don't understand the `dim` command. For dimmers this does not cause issues with signal repetitions. - *Toggle*: Device type that sends only `on` commands to turn on or off the device. Some switches like for example Livolo light switches use the same 'on' command to switch on and switch off the lights. If the light is on and 'on' gets sent, the light will turn off and if the light is off and 'on' gets sent, the light will turn on. If the device has an unknown state, it will assume it is off by default. diff --git a/source/_components/light.rfxtrx.markdown b/source/_components/light.rfxtrx.markdown index ee5c513fe81..c83d9f71fc7 100644 --- a/source/_components/light.rfxtrx.markdown +++ b/source/_components/light.rfxtrx.markdown @@ -1,7 +1,7 @@ --- layout: page title: "RFXtrx Light" -description: "Instructions how to integrate RFXtrx lights into Home Assistant." +description: "Instructions on how to integrate RFXtrx lights into Home Assistant." date: 2015-10-08 10:15 sidebar: true comments: false @@ -60,3 +60,8 @@ Configuration variables: - **automatic_add** (*Optional*): To enable the automatic addition of new lights. - **signal_repetitions** (*Optional*): Because the RFXtrx device sends its actions via radio and from most receivers it's impossible to know if the signal was received or not. Therefore you can configure the switch to try to send each signal repeatedly. - **fire_event** (*Optional*): Fires an event even if the state is the same as before. Can be used for automations. + +
+If a device ID consists of only numbers, please make sure to surround it with quotes. +This is a known limitation in YAML, because the device ID will be interpreted as a number otherwise. +
diff --git a/source/_components/light.scsgate.markdown b/source/_components/light.scsgate.markdown index 5625b43cfb3..07df0ca0f7e 100644 --- a/source/_components/light.scsgate.markdown +++ b/source/_components/light.scsgate.markdown @@ -1,7 +1,7 @@ --- layout: page title: "SCSGate Light" -description: "Instructions how to integrate SCSGate lights into Home Assistant." +description: "Instructions on how to integrate SCSGate lights into Home Assistant." date: 2016-01-31 19:30 sidebar: true comments: false diff --git a/source/_components/light.sensehat.markdown b/source/_components/light.sensehat.markdown index b2bb9dbce5a..7c7a4d0b378 100644 --- a/source/_components/light.sensehat.markdown +++ b/source/_components/light.sensehat.markdown @@ -1,16 +1,16 @@ --- layout: page title: "Sense HAT Light" -description: "Instructions how to setup Sense HAT LED lights within Home Assistant." +description: "Instructions on how to setup Sense HAT LED lights within Home Assistant." date: 2017-04-29 16:00 sidebar: true comments: false sharing: true footer: true logo: sense-hat.png -ha_version: 0.44 ha_category: Light ha_iot_class: "Assumed State" +ha_release: 0.44 --- The `sensehat` light platform lets you control the [Sense HAT](https://www.raspberrypi.org/products/sense-hat/) board's 8x8 RGB LED matrix on your Raspberry Pi from within Home Assistant. diff --git a/source/_components/light.sisyphus.markdown b/source/_components/light.sisyphus.markdown new file mode 100644 index 00000000000..4c9e0146a99 --- /dev/null +++ b/source/_components/light.sisyphus.markdown @@ -0,0 +1,20 @@ +--- +layout: page +title: "Sisyphus Light" +description: "Instructions on how to integrate the light in your Sisyphus Kinetic Art Table into Home Assistant." +date: 2018-05-06 22:26 +sidebar: true +comments: false +sharing: true +footer: true +logo: sisyphus.png +ha_category: Light +ha_iot_class: "Local Push" +ha_release: 0.75 +--- + +The [Sisyphus](https://sisyphus-industries.com/) integration for Home Assistant allows you to observe and control your Sisyphus Kinetic Art Table. + +Lights will be automatically added for each of your Sisyphus tables if the Sisyphus component is configured. + +For more configuration information see the [Sisyphus component](/components/sisyphus/) documentation. diff --git a/source/_components/light.tellstick.markdown b/source/_components/light.tellstick.markdown index a81d2384646..9c66e121ec6 100644 --- a/source/_components/light.tellstick.markdown +++ b/source/_components/light.tellstick.markdown @@ -1,7 +1,7 @@ --- layout: page title: "TellStick Light" -description: "Instructions how to integrate TellStick lights into Home Assistant." +description: "Instructions on how to integrate TellStick lights into Home Assistant." date: 2015-08-06 19:00 sidebar: true comments: false @@ -15,7 +15,7 @@ ha_iot_class: "Assumed State" This `tellstick` light platform allows you to control your [TellStick](http://www.telldus.se/products/tellstick) dimmers. -To use your TellStick device, you first have to set up your [Tellstick hub](https://home-assistant.io/components/tellstick/) and then add the following to your `configuration.yaml` file: +To use your TellStick device, you first have to set up your [Tellstick hub](/components/tellstick/) and then add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry diff --git a/source/_components/light.template.markdown b/source/_components/light.template.markdown index 69f0315c940..9d1315b3106 100755 --- a/source/_components/light.template.markdown +++ b/source/_components/light.template.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Template Light" -description: "Instructions how to integrate Template Lights into Home Assistant." +description: "Instructions on how to integrate Template Lights into Home Assistant." date: 2016-05-18 20:32 sidebar: true comments: false @@ -42,7 +42,7 @@ light: {% endraw %} {% configuration %} - switches: + lights: description: List of your lights. required: true type: map @@ -52,7 +52,7 @@ light: required: false type: string entity_id: - description: Add a list of entity IDs so the switch only reacts to state changes of these entities. This will reduce the number of times the light will try to update its state. + description: A list of entity IDs so the light only reacts to state changes of these entities. This can be used if the automatic analysis fails to find all relevant entities. required: false type: [string, list] value_template: diff --git a/source/_components/light.tplink.markdown b/source/_components/light.tplink.markdown index 68fff983950..158504bcae0 100644 --- a/source/_components/light.tplink.markdown +++ b/source/_components/light.tplink.markdown @@ -1,7 +1,7 @@ --- layout: page -title: "TPLink Bulb" -description: "Instructions how to integrate TPLink bulbs into Home Assistant." +title: "TP-Link Bulb" +description: "Instructions on how to integrate TP-Link bulbs into Home Assistant." date: 2017-07-25 08:00 sidebar: true comments: false @@ -14,7 +14,7 @@ ha_release: "0.50" --- -The `tplink` light platform allows you to control the state of your [TPLink smart bulb](http://www.tp-link.com/en/products/list-5609.html). +The `tplink` light platform allows you to control the state of your [TP-Link smart bulb](http://www.tp-link.com/en/products/list-5609.html). Supported units: @@ -23,7 +23,7 @@ Supported units: - LB120 - LB130 -To use your TPLink light in your installation, add the following to your `configuration.yaml` file: +To use your TP-Link light in your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -32,9 +32,15 @@ light: host: IP_ADDRESS ``` -Configuration variables: - -- **host** (*Required*): The IP address of your TP-Link bulb, eg. `192.168.1.32`. -- **name** (*Optional*): The name to use when displaying this bulb. - +{% configuration %} +name: + description: The name to use when displaying this bulb. + required: false + type: string + default: TP-Link Light +host: + description: "The IP address of your TP-Link bulb, eg. `192.168.1.32`." + required: true + type: string +{% endconfiguration %} diff --git a/source/_components/light.tuya.markdown b/source/_components/light.tuya.markdown new file mode 100644 index 00000000000..ec3d418e5e5 --- /dev/null +++ b/source/_components/light.tuya.markdown @@ -0,0 +1,23 @@ +--- +layout: page +title: "Tuya Light" +description: "Instructions on how to setup the Tuya lights within Home Assistant." +date: 2018-07-16 09:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: tuya.png +ha_category: Light +ha_iot_class: "Cloud Polling" +ha_release: 0.74 +--- + + +The `tuya` light platform allows you to control your [Tuya Smart](https://www.tuya.com) lights. + +The platform supports most kinds of Tuya light. + ++Full configuration details can be found on the main [Tuya component](/components/tuya/) page. +
\ No newline at end of file diff --git a/source/_components/light.velbus.markdown b/source/_components/light.velbus.markdown index 662b788ca41..ddafbaa7eb5 100644 --- a/source/_components/light.velbus.markdown +++ b/source/_components/light.velbus.markdown @@ -15,26 +15,41 @@ ha_release: "0.50" The `velbus` light allows you to control [Velbus](http://www.velbus.eu) lights. +## {% linkable_title Configuration %} + To use your Velbus lights in your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry - light: - platform: velbus devices: - - name: Light 1 - module: 0xda - channel: 4 - - name: Light 2 - module: 0xbc - channel: 1 + - name: Light 1 + module: 0xda + channel: 4 + - name: Light 2 + module: 0xbc + channel: 1 ``` -Configuration variables: -- **devices** array (*Required*): The array contains the lights to configure - - **name** (*Required*): Name of the light. - - **module** (*Required*): The hexadecimal module address - - **channel** (*Required*): The channel number in the module. +{% configuration %} +devices: + description: The list contains the lights to configure. + required: true + type: map + keys: + name: + description: Name to use in the frontend. + required: true + type: string + module: + description: The hexadecimal module address. + required: true + type: string + channel: + description: The channel number in the module. + required: true + type: string +{% endconfiguration %} For hub configuration, see [the Velbus component](/components/velbus/). diff --git a/source/_components/light.vera.markdown b/source/_components/light.vera.markdown index da0fc42fff5..dba42ffcaf0 100644 --- a/source/_components/light.vera.markdown +++ b/source/_components/light.vera.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Vera Light" -description: "Instructions how to integrate Vera lights into Home Assistant." +description: "Instructions on how to integrate Vera lights into Home Assistant." date: 2015-10-20 21:00 sidebar: true comments: false diff --git a/source/_components/light.wemo.markdown b/source/_components/light.wemo.markdown index a2ff553aada..1ae147ef864 100644 --- a/source/_components/light.wemo.markdown +++ b/source/_components/light.wemo.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Belkin WeMo Lights" -description: "Instructions how to integrate Belkin WeMo LED lights into Home Assistant." +description: "Instructions on how to integrate Belkin WeMo LED lights and WeMo Dimmer Switch into Home Assistant." date: 2016-02-20 00:45 sidebar: true comments: false @@ -14,7 +14,7 @@ ha_release: 0.14 --- -The `wemo` platform allows you to control your [Belkin WeMo](http://www.belkin.com/us/p/P-F5Z0489/) LED lights from within Home Assistant. +The `wemo` platform allows you to control your Belkin WeMo [LED lights](http://www.belkin.com/us/p/P-F5Z0489/) and [Smart Dimmer Switch](http://www.belkin.com/us/F7C059-Belkin/p/P-F7C059/) from within Home Assistant. They will be automatically discovered if the discovery component is enabled. diff --git a/source/_components/light.wink.markdown b/source/_components/light.wink.markdown index 5e7b74771ed..e537c116018 100644 --- a/source/_components/light.wink.markdown +++ b/source/_components/light.wink.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Wink Light" -description: "Instructions how to setup the Wink lights within Home Assistant." +description: "Instructions on how to setup the Wink lights within Home Assistant." date: 2015-01-20 22:36 sidebar: true comments: false diff --git a/source/_components/light.x10.markdown b/source/_components/light.x10.markdown index 7e0a52fd58a..45df065a499 100644 --- a/source/_components/light.x10.markdown +++ b/source/_components/light.x10.markdown @@ -1,7 +1,7 @@ --- layout: page title: "X10" -description: "Instructions how to setup X10 devices within Home Assistant." +description: "Instructions on how to setup X10 devices within Home Assistant." date: 2016-07-27 sidebar: true comments: false @@ -25,6 +25,7 @@ light: - platform: x10 devices: - id: a2 + name: Guest Room - id: a3 name: Bedroom Lamp ``` @@ -32,4 +33,4 @@ light: Configuration variables: - **id** (*Required*): Device identifier. Composed of house code and unit id. -- **name** (*Optional*): A friendly name for the device. By default *id* from the device is used. +- **name** (*Required*): A friendly name for the device. diff --git a/source/_components/light.xiaomi_aqara.markdown b/source/_components/light.xiaomi_aqara.markdown index 25e01ba22c7..48bf4fb1358 100644 --- a/source/_components/light.xiaomi_aqara.markdown +++ b/source/_components/light.xiaomi_aqara.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Xiaomi Light" -description: "Instructions how to setup the Xiaomi light within Home Assistant." +description: "Instructions on how to setup the Xiaomi light within Home Assistant." date: 2017-07-21 16:34 sidebar: true comments: false diff --git a/source/_components/light.xiaomi_miio.markdown b/source/_components/light.xiaomi_miio.markdown index 5f76deb341e..4597bc7f8fa 100644 --- a/source/_components/light.xiaomi_miio.markdown +++ b/source/_components/light.xiaomi_miio.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Xiaomi Philips Light" -description: "Instructions how to integrate your Xiaomi Philips Lights within Home Assistant." +description: "Instructions on how to integrate your Xiaomi Philips Lights within Home Assistant." date: 2017-08-26 08:45 sidebar: true comments: false @@ -9,13 +9,58 @@ sharing: true footer: true logo: philips.png ha_category: Light -ha_version: 0.53 ha_iot_class: "Local Polling" +ha_release: 0.53 --- -The `xiaomi_miio` platform allows you to control the state of your Xiaomi Philips LED Ball Lamp and Xiaomi Philips LED Ceiling Lamp. +The `xiaomi_miio` platform allows you to control the state of your Xiaomi Philips LED Ball Lamp, Xiaomi Philips Zhirui LED Bulb E14 Candle Lamp, Xiaomi Philips LED Ceiling Lamp and Xiaomi Philips Eyecare Lamp 2. -Currently, the supported features are `on`, `off`, `set_cct` (colortemp) , `set_bright` (brightness). +## Features + +### Philips LED Ball Lamp and Philips Zhirui LED Candle Lamp + +* Power (on, off) +* Brightness +* Color temperature (175...333 mireds) +* Scene (1, 2, 3, 4) +* Delayed turn off (Resolution in seconds) +* Attributes + - model + - scene + - delayed_turn_off + +### Philips LED Ceiling Lamp + +* Power (on, off) +* Brightness +* Color temperature (175...370 mireds) +* Scene (1, 2, 3, 4) +* Night light mode (on, off) +* Delayed turn off (Resolution in seconds) +* Attributes + - model + - scene + - delayed_turn_off + - night_light_mode + - automatic_color_temperature + +### Philips Eyecare Smart Lamp 2 + +* Eyecare light (on, off) +* Ambient light (on, off) +* Brightness (of each light) +* Scene (1, 2, 3, 4) +* Night light mode (on, off) +* Delayed turn off (Resolution in seconds) +* Eye fatigue reminder / notification (on, off) +* Eyecare mode (on, off) +* Attributes + - model + - scene + - delayed_turn_off + - night_light_mode + - reminder + - eyecare_mode Please follow the instructions on [Retrieving the Access Token](/components/vacuum.xiaomi_miio/#retrieving-the-access-token) to get the API token to use in the `configuration.yaml` file. @@ -28,9 +73,93 @@ light: name: Xiaomi Philips Smart LED Ball host: 192.168.130.67 token: YOUR_TOKEN + model: philips.light.bulb ``` -Configuration variables: -- **host** (*Required*): The IP of your light. -- **token** (*Required*): The API token of your light. -- **name** (*Optional*): The name of your light. +{% configuration %} +host: + description: The IP address of your miio light. + required: true + type: string +token: + description: The API token of your miio light. + required: true + type: string +name: + description: The name of your miio light. + required: false + type: string + default: Xiaomi Philips Light +model: + description: The model of your miio light. Valid values are `philips.light.bulb`, `philips.light.candle2`, `philips.light.sread1`, `philips.light.ceiling` and `philips.light.zyceiling`. This setting can be used to bypass the device model detection and is recommended if your device isn't always available. + required: false + type: string +{% endconfiguration %} + +## {% linkable_title Platform Services %} + +### {% linkable_title Service `light.xiaomi_miio_set_scene` %} + +Set one of the 4 available fixed scenes. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on a specific light. Else targets all. | +| `scene` | no | Scene, between 1 and 4. | + +### {% linkable_title Service `light.xiaomi_miio_set_delayed_turn_off` %} + +Delayed turn off. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on a specific light. Else targets all. | +| `time_period` | no | Time period for the delayed turn off. | + +### {% linkable_title Service `light.xiaomi_miio_reminder_on` %} (Eyecare Smart Lamp 2 only) + +Enable the eye fatigue reminder/notification. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on a specific light. Else targets all. | + +### {% linkable_title Service `light.xiaomi_miio_reminder_off` %} (Eyecare Smart Lamp 2 only) + +Disable the eye fatigue reminder/notification. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on a specific light. Else targets all. | + +### {% linkable_title Service `light.xiaomi_miio_night_light_mode_on` %} (Eyecare Smart Lamp 2 only) + +Turn the smart night light mode on. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on a specific light. Else targets all. | + +### {% linkable_title Service `light.xiaomi_miio_night_light_mode_off` %} (Eyecare Smart Lamp 2 only) + +Turn the smart night light mode off. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on a specific light. Else targets all. | + +### {% linkable_title Service `light.xiaomi_miio_eyecare_mode_on` %} (Eyecare Smart Lamp 2 only) + +Turn the eyecare mode on. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on a specific light. Else targets all. | + +### {% linkable_title Service `light.xiaomi_miio_eyecare_mode_off` %} (Eyecare Smart Lamp 2 only) + +Turn the eyecare mode off. + +| Service data attribute | Optional | Description | +|---------------------------|----------|-------------------------------------------------------| +| `entity_id` | yes | Only act on a specific light. Else targets all. | diff --git a/source/_components/light.yeelight.markdown b/source/_components/light.yeelight.markdown index c082a8b2d8c..c446d5950f7 100644 --- a/source/_components/light.yeelight.markdown +++ b/source/_components/light.yeelight.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Yeelight Wifi Bulb" -description: "Instructions how to setup Yeelight Wifi devices within Home Assistant." +description: "Instructions on how to setup Yeelight Wifi devices within Home Assistant." date: 2016-10-29 sidebar: true comments: false @@ -35,7 +35,7 @@ light: Configuration variables: -- **ip** (*Required*): IP(s) of your wifi bulbs +- **ip** (*Required*): IP(s) of your Wifi bulbs - **name** (*Optional*): A friendly name for the device. - **transition** (*Optional*, default 350): Smooth transitions over time (in ms). - **use_music_mode** (*Optional*, default False): Enable music mode. @@ -48,7 +48,8 @@ Per default the bulb limits the amount of requests per minute to 60, a limitatioBefore trying to control your light through Home Assistant, you have to setup your bulb using Yeelight app. ( [Android](https://play.google.com/store/apps/details?id=com.yeelight.cherry&hl=fr), [IOS](https://itunes.apple.com/us/app/yeelight/id977125608?mt=8) ). In the bulb property, you have to enable "LAN Mode" (previously called "Developer mode"). LAN mode may only be available with the latest firmware installed on your bulb. Firmware can be updated in the application after connecting the bulb. -Determine your bulb IP (using router, software, ping ...) +Determine your bulb IP (using router, software, ping ...). +Information on how to enable "LAN Mode" can be found [here](https://getyeti.co/posts/how-to-control-yeelight-and-your-smarthome-with-yeti).
@@ -58,9 +59,22 @@ This component is tested to work with the following models. If you have a differ - **YLDP01YL**: LED Bulb (White) - **YLDP02YL**: LED Bulb (Color) - **YLDP03YL**: LED Bulb (Color) - E26 +- **YLDP06YL**: LED Bulb (Color) II +- **YLDD01YL**: Lightstrip (Color) - **YLDD02YL**: Lightstrip (Color) +- **MJCTD01YL**: Xiaomi Mijia Bedside Lamp - WIFI Version! +- **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) +- **YLXD02YL**: Yeelight Ceiling Light 4 (Jiaoyue 650) +- **YLXD01YL**: Yeelight Smart LED Ceiling Light - Youth Version +## {% linkable_title Platform Services %} +### {% linkable_title Service `light.yeelight_set_mode` %} +Set an operation mode. +| Service data attribute | Optional | Description | +|---------------------------|----------|---------------------------------------------------------------------------------------------| +| `entity_id` | yes | Only act on a specific yeelight. Else targets all. | +| `mode` | no | Operation mode. Valid values are 'last', 'normal', 'rgb', 'hsv', 'color_flow', 'moonlight'. | diff --git a/source/_components/light.yeelightsunflower.markdown b/source/_components/light.yeelightsunflower.markdown index 1b0e441970d..0583084626c 100644 --- a/source/_components/light.yeelightsunflower.markdown +++ b/source/_components/light.yeelightsunflower.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Yeelight Sunflower Bulb" -description: "Instructions how to setup Yeelight Sunflower hub and bulbs within Home Assistant." +description: "Instructions on how to setup Yeelight Sunflower hub and bulbs within Home Assistant." date: 2017-02-11 sidebar: true comments: false diff --git a/source/_components/light.zengge.markdown b/source/_components/light.zengge.markdown index ed15a92752a..b2f46b065d4 100644 --- a/source/_components/light.zengge.markdown +++ b/source/_components/light.zengge.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Zengge" -description: "Instructions how to integrate Zengge Bluetooth bulbs into Home Assistant." +description: "Instructions on how to integrate Zengge Bluetooth bulbs into Home Assistant." date: 2017-01-14 08:00 sidebar: true comments: false diff --git a/source/_components/light.zha.markdown b/source/_components/light.zha.markdown index c3b0cc2d8b7..904c1e59de8 100644 --- a/source/_components/light.zha.markdown +++ b/source/_components/light.zha.markdown @@ -1,7 +1,7 @@ --- layout: page title: "ZigBee Home Automation Light" -description: "Instructions how to setup ZigBee Home Automation lights within Home Assistant." +description: "Instructions on how to setup ZigBee Home Automation lights within Home Assistant." date: 2017-02-22 00:00 sidebar: true comments: false diff --git a/source/_components/light.zigbee.markdown b/source/_components/light.zigbee.markdown index 5730043d1eb..a7d8529551e 100644 --- a/source/_components/light.zigbee.markdown +++ b/source/_components/light.zigbee.markdown @@ -13,7 +13,7 @@ ha_release: 0.12 ha_iot_class: "Local Polling" --- -A ZigBee light in this context is a light connected to one of the digital output pins on a ZigBee module. It can simply be switched on and off. By default, a light is considered `on` when the ZigBee device's digital output is held `high` and considered `off` when it is held `low`. This behaviour can be inverted by setting the `on_state` configuration variable to `low`. +A ZigBee light in this context is a light connected to one of the digital output pins on a ZigBee module. It can simply be switched on and off. By default, a light is considered `on` when the ZigBee device's digital output is held `high` and considered `off` when it is held `low`. This behavior can be inverted by setting the `on_state` configuration variable to `low`. To configure a digital output pin as light, add the following to your `configuration.yaml` file: diff --git a/source/_components/light.zwave.markdown b/source/_components/light.zwave.markdown index 4053e61f1d3..891f63e8867 100644 --- a/source/_components/light.zwave.markdown +++ b/source/_components/light.zwave.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Z-Wave Light" -description: "Instructions how to setup the Z-Wave lights within Home Assistant." +description: "Instructions on how to setup the Z-Wave lights within Home Assistant." date: 2015-11-11 13:00 sidebar: true comments: false diff --git a/source/_components/lirc.markdown b/source/_components/lirc.markdown index ffe675ea0c4..ad96e2316b2 100644 --- a/source/_components/lirc.markdown +++ b/source/_components/lirc.markdown @@ -1,7 +1,7 @@ --- layout: page title: "LIRC" -description: "Instructions how to integrate IR remotes with LIRC into Home Assistant." +description: "Instructions on how to integrate IR remotes with LIRC into Home Assistant." date: 2016-05-22 19:59 sidebar: true comments: false @@ -14,9 +14,9 @@ ha_release: 0.21 ha_iot_class: "Local Push" --- -[LIRC](http://www.lirc.org/) integration for Home Assistant allows you to receive signals from an infrared remote control and control actions based on the buttons you press. You can use them to set scenes or trigger any other [automation](https://home-assistant.io/components/automation/). +[LIRC](http://www.lirc.org/) integration for Home Assistant allows you to receive signals from an infrared remote control and control actions based on the buttons you press. You can use them to set scenes or trigger any other [automation](/components/automation/). -Sending IR commands is not supported in this component (yet), but can be accomplished using the [shell_command component](https://home-assistant.io/components/shell_command/) in conjunction with the `irsend` command. +Sending IR commands is not supported in this component (yet), but can be accomplished using the [shell_command component](/components/shell_command/) in conjunction with the `irsend` command. ### {% linkable_title Installation %} @@ -32,16 +32,16 @@ The configuration is slightly different : - The `hardware.conf` file is not supported, obsoleted by a new `lirc_options.conf` file and systemd unit definitions. - The former single `lirc` service is replaced with the three systemd services `lircd.service`, `lircmd.service` and `irexec.service`. There is no counterpart to the 0.9.0 `lirc` service which covered all of these. Using a separate transmitter device requires yet another service. - - 0.9.4 defaults to using systemd for controlling the services. This is not just start/stop functionality, systemd is used to implement new features and to address shortcomings in 0.9.0. However, traditional systemV scripts are also installed and could be used although this is less tested and not really documented. - -For more infomation have a look at `/usr/share/doc/lirc/README.Debian.gz` where the update process is explained when you have updated from jessie to stretch. + - 0.9.4 defaults to using systemd for controlling the services. This is not just start/stop functionality, systemd is used to implement new features and to address shortcomings in 0.9.0. However, traditional systemV scripts are also installed and could be used although this is less tested and not really documented. + +For more information have a look at `/usr/share/doc/lirc/README.Debian.gz` where the update process is explained when you have updated from jessie to stretch.
### {% linkable_title Configuring LIRC %} -Now teach LIRC about your particular remote control by preparing a lircd configuration file (`/etc/lirc/lircd.conf`). Search the [LIRC remote database](http://lirc.sourceforge.net/remotes/) for your model. If you can't find it, then you can always use the `irrecord` program to learn your remote. This will create a valid configuration file. Add as many remotes as you want by pasting them into the file. If `irrecord` doesn't work (e.g. for some air conditioner remotes), then the `mode2` program is capable of reading the codes in raw mode, followed by `irrecord -a` to extract hex codes. +Now teach LIRC about your particular remote control by preparing a lircd configuration file (`/etc/lirc/lircd.conf`). Search the [LIRC remote database](http://lirc.sourceforge.net/remotes/) for your model. If you can't find it, then you can always use the `irrecord` program to learn your remote. This will create a valid configuration file. Add as many remotes as you want by pasting them into the file. If `irrecord` doesn't work (e.g., for some air conditioner remotes), then the `mode2` program is capable of reading the codes in raw mode, followed by `irrecord -a` to extract hex codes. -Next, you have to make a `~/.lircrc` file that maps keypresses to system actions. [The configuration](http://www.lirc.org/html/configure.html) is a bit tedious but it must be done. Use the `prog = home-assistant` for all keys you want to be recognized by Home Assistant. The values you set for `button` must be the same as in the `lircd.conf` file and the values you put for `config` entry will be the sensor value in Home Assistant when you press the button. An example may look like this: +Next, you have to make a `~/.lircrc` file that maps keypresses to system actions. The file has to be in the home dir of the user running Home Assistant, e.g. in `/home/homeassistant/.lircrc` if you're running in a virtual env. [The configuration](http://www.lirc.org/html/configure.html) is a bit tedious but it must be done. Use the `prog = home-assistant` for all keys you want to be recognized by Home Assistant. The values you set for `button` must be the same as in the `lircd.conf` file and the values you put for `config` entry will be the sensor value in Home Assistant when you press the button. An example may look like this: ```bash begin @@ -98,4 +98,4 @@ automation: entity_id: group.a_lights ``` -The `button_name` data values (e.g. `KEY_0`) are set by you in the `.lircrc` file. +The `button_name` data values (e.g., `KEY_0`) are set by you in the `.lircrc` file. diff --git a/source/_components/litejet.markdown b/source/_components/litejet.markdown index 3770bb024be..fb334089530 100644 --- a/source/_components/litejet.markdown +++ b/source/_components/litejet.markdown @@ -1,7 +1,7 @@ --- layout: page title: "LiteJet" -description: "Instructions how to setup the LiteJet hub within Home Assistant." +description: "Instructions on how to setup the LiteJet hub within Home Assistant." date: 2015-10-26 09:37 sidebar: true comments: false diff --git a/source/_components/lock.abode.markdown b/source/_components/lock.abode.markdown index c1e28603708..9dcc3cff907 100644 --- a/source/_components/lock.abode.markdown +++ b/source/_components/lock.abode.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Abode Lock" -description: "Instructions how to integrate Abode locks into Home Assistant." +description: "Instructions on how to integrate Abode locks into Home Assistant." date: 2017-08-26 13:28 sidebar: true comments: false diff --git a/source/_components/lock.august.markdown b/source/_components/lock.august.markdown new file mode 100644 index 00000000000..eda4f37d06e --- /dev/null +++ b/source/_components/lock.august.markdown @@ -0,0 +1,18 @@ +--- +layout: page +title: "August Lock" +description: "Instructions on how to integrate your August devices into Home Assistant." +date: 2018-02-17 22:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: august.png +ha_category: Lock +ha_release: "0.64" +ha_iot_class: "Cloud Polling" +--- + +The `august` lock platform allows you to control your [August](http://august.com) lock from within Home Assistant. + +To add `august` lock to your installation, follow instructions in [August component](/components/august/). diff --git a/source/_components/lock.bmw_connected_drive.markdown b/source/_components/lock.bmw_connected_drive.markdown new file mode 100755 index 00000000000..4c6c7a2edcf --- /dev/null +++ b/source/_components/lock.bmw_connected_drive.markdown @@ -0,0 +1,20 @@ +--- +layout: page +title: "BMW Connected Drive Lock" +description: "Instructions on how to setup your BMW Connected Drive account with Home Assistant." +date: 2018-02-22 23:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: bmw.png +ha_category: Lock +ha_release: 0.66 +--- + + +The `bmw_connected_drive` platform allows you to import data on your BMW into Home Assistant. + +The lock will be automatically configured if `bmw_connected_drive` component is configured. + +For more configuration information see the [`bmw_connected_drive` component](/components/bmw_connected_drive/) documentation. diff --git a/source/_components/lock.homematic.markdown b/source/_components/lock.homematic.markdown new file mode 100644 index 00000000000..d536312e2ea --- /dev/null +++ b/source/_components/lock.homematic.markdown @@ -0,0 +1,18 @@ +--- +layout: page +title: "Homematic Lock (KeyMatic)" +description: "Instructions how to integrate Homematic locks (KeyMatic) within Home Assistant." +date: 2018-01-28 03:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: homematic.png +ha_category: Lock +ha_release: 0.66 +ha_iot_class: "Local Push" +--- + +The `homematic` lock platform lets you observe and control the state of the HomeMatic [Homematic](http://www.homematic.com/) KeyMatic lock through Home Assistant. + +Devices will be configured automatically. Please refer to the [component](/components/homematic/) configuration on how to setup Homematic. diff --git a/source/_components/lock.isy994.markdown b/source/_components/lock.isy994.markdown index 04109b9cd6e..b019662a68c 100644 --- a/source/_components/lock.isy994.markdown +++ b/source/_components/lock.isy994.markdown @@ -1,7 +1,7 @@ --- layout: page title: "ISY994 Lock" -description: "Instructions how to integrate ISY994 locks into Home Assistant." +description: "Instructions on how to integrate ISY994 locks into Home Assistant." date: 2016-09-03 23:00 sidebar: true comments: false diff --git a/source/_components/lock.kiwi.markdown b/source/_components/lock.kiwi.markdown new file mode 100644 index 00000000000..08c3e9746b5 --- /dev/null +++ b/source/_components/lock.kiwi.markdown @@ -0,0 +1,39 @@ +--- +layout: page +title: "KIWI Lock" +description: "Instructions on how to integrate KIWI Smart Lock and Smart Entry." +date: 2018-05-16 13:37 +sidebar: true +comments: false +sharing: true +footer: true +logo: kiwi.png +ha_category: Lock +featured: false +ha_release: 0.72 +ha_iot_class: "Cloud Polling" +--- + +The `KIWI` platform allows you to open your KIWI Smart Locks and Smart Entry Devices. +All you need to get started is a KIWI account. Register at [the KIWI website](https://kiwi.ki/login/). + +## {% linkable_title Configuration %} + +```yaml +# Example configuration.yaml entry +lock: + - platform: kiwi + username: mail@example.com + password: mySecretPassword +``` + +{% configuration %} +username: + required: true + description: The username of your KIWI account. + type: string +password: + required: true + description: The password of your KIWI account. + type: string +{% endconfiguration %} diff --git a/source/_components/lock.lockitron.markdown b/source/_components/lock.lockitron.markdown index 418881c1693..6b320e71086 100644 --- a/source/_components/lock.lockitron.markdown +++ b/source/_components/lock.lockitron.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Lockitron Lock" -description: "Instructions how to integrate Lockitron locks into Home Assistant." +description: "Instructions on how to integrate Lockitron locks into Home Assistant." date: 2017-03-24 00:00 sidebar: true comments: false diff --git a/source/_components/lock.markdown b/source/_components/lock.markdown index c2c3cc55301..97cc4622020 100644 --- a/source/_components/lock.markdown +++ b/source/_components/lock.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Locks" -description: "Instructions how to setup your locks with Home Assistant." +description: "Instructions on how to setup your locks with Home Assistant." date: 2015-11-21 08:10 sidebar: true comments: false @@ -12,11 +12,11 @@ footer: true Keeps track which locks are in your environment, their state and allows you to control them. * Maintains a state per lock and a combined state `all_locks`. - * Registers services `lock/lock` and `lock/unlock` to control locks. + * Registers services `lock.lock` and `lock.unlock` to control locks. ### {% linkable_title Use the services %} -Go to the **Developer Tools**, then to **Call Service** in the frontend, and choose `lock/lock` or `lock/unlock` from the list of available services (**Available services:** on the left). Enter something like the sample below into the **Service Data** field and hit **CALL SERVICE**. +Go to the **Developer Tools**, then to **Call Service** in the frontend, and choose `lock.lock` or `lock.unlock` from the list of available services (**Services:** on the left). Enter something like the sample below into the **Service Data** field and hit **CALL SERVICE**. ```json {"entity_id":"lock.front_door"} diff --git a/source/_components/lock.mqtt.markdown b/source/_components/lock.mqtt.markdown index 6f91de7d133..ff8eb051702 100644 --- a/source/_components/lock.mqtt.markdown +++ b/source/_components/lock.mqtt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MQTT Lock" -description: "Instructions how to integrate MQTT locks into Home Assistant." +description: "Instructions on how to integrate MQTT locks into Home Assistant." date: 2016-02-28 15:00 sidebar: true comments: false @@ -24,23 +24,70 @@ Optimistic mode can be forced, even if state topic is available. Try to enable i To enable MQTT locks in your installation, add the following to your `configuration.yaml` file: ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry lock: - platform: mqtt command_topic: "home/frontdoor/set" ``` -Configuration variables: - -- **command_topic** (*Required*): The MQTT topic to publish commands to change the lock state. -- **name** (*Optional*): The name of the lock. Default is 'MQTT Lock'. -- **state_topic** (*Optional*): The MQTT topic subscribed to receive state updates. -- **payload_lock** (*Optional*): The payload that represents enabled/locked state. Default is "LOCK". -- **payload_unlock** (*Optional*): The payload that represents disabled/unlocked state. Default is "UNLOCK". -- **optimistic** (*Optional*): Flag that defines if lock works in optimistic mode. Default is `true` if no `state_topic` defined, else `false`. -- **qos** (*Optional*): The maximum QoS level of the state topic. Default is 0 and will also be used to publishing messages. -- **retain** (*Optional*): If the published message should have the retain flag on or not. -- **value_template** (*Optional*): Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload. +{% configuration %} +name: + description: The name of the lock. + required: false + type: string + default: MQTT Lock +command_topic: + description: The MQTT topic to publish commands to change the lock state. + required: true + type: string +state_topic: + description: The MQTT topic subscribed to receive state updates. + required: false + type: string +payload_lock: + description: The payload that represents enabled/locked state. + required: false + type: string + default: LOCK +payload_unlock: + description: The payload that represents disabled/unlocked state. + required: false + type: string + default: UNLOCK +optimistic: + description: Flag that defines if lock works in optimistic mode. + required: false + type: string + default: "`true` if no `state_topic` defined, else `false`." +qos: + description: The maximum QoS level of the state topic. + required: false + type: integer + default: 0 +retain: + description: If the published message should have the retain flag on or not. + required: false + type: boolean + default: false +value_template: + description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract a value from the payload." + required: false + type: string +availability_topic: + description: The MQTT topic subscribed to receive availability (online/offline) updates. + required: false + type: string +payload_available: + description: The payload that represents the available state. + required: false + type: string + default: online +payload_not_available: + description: The payload that represents the unavailable state. + required: false + type: string + default: offline +{% endconfiguration %}Make sure that your topics match exactly. `some-topic/` and `some-topic` are different topics. @@ -58,7 +105,7 @@ The example below shows a full configuration for a MQTT lock. # Example configuration.yml entry lock: - platform: mqtt - name: Frontdoor + name: Frontdoor state_topic: "home-assistant/frontdoor/" command_topic: "home-assistant/frontdoor/set" payload_lock: "LOCK" @@ -69,7 +116,7 @@ lock: value_template: '{% raw %}{{ value.x }}{% endraw %}' ``` -Keep an eye on retaining messages to keep the state as you don't want to unlock your door by accident when you restart something. +Keep an eye on retaining messages to keep the state as you don't want to unlock your door by accident when you restart something. For a check you can use the command line tools `mosquitto_pub` shipped with `mosquitto` to send MQTT messages. This allows you to operate your lock manually: diff --git a/source/_components/lock.nello.markdown b/source/_components/lock.nello.markdown index 53f2e26e79b..558f9098b96 100644 --- a/source/_components/lock.nello.markdown +++ b/source/_components/lock.nello.markdown @@ -16,6 +16,7 @@ ha_iot_class: "Cloud Polling" --- The `nello` platform allows you to control [Nello](https://nello.io) intercoms. + To get started you need to create a secondary Nello account and authorize it to access your lock(s).
@@ -24,18 +25,26 @@ Be aware that if you use your main account for Home Assistant you may not be abl ## {% linkable_title Configuration %} +To add your Nello locks to your installation, add the following to your `configuration.yaml` file: + ```yaml # Example configuration.yaml entry lock: - platform: nello - username: mail@example.com - password: mySecretPassword + username: YOUR_USERNAME + password: YOUR_PASSWORD ``` -Configuration variables: - -- **username** (*Required*): The username of your Nello account. -- **password** (*Required*): The password of your Nello account. +{% configuration %} +username: + description: The username of your Nello account. + required: true + type: string +password: + description: The password of your Nello account. + required: true + type: string +{% endconfiguration %} ## {% linkable_title Events %} diff --git a/source/_components/lock.sesame.markdown b/source/_components/lock.sesame.markdown index 121d337cefb..affd029f63a 100644 --- a/source/_components/lock.sesame.markdown +++ b/source/_components/lock.sesame.markdown @@ -15,18 +15,28 @@ ha_release: "0.47" The `sesame` platform allows you to control your [Sesame](https://candyhouse.co/) smart locks made by CANDY HOUSE, Inc. +## {% linkable_title Configuration %} + Your Sesame needs to be paired with a mobile device running the app in *virtual station* mode, or a standalone [Wi-Fi Access Point](https://candyhouse.co/collections/frontpage/products/wi-fi-access-point). -Once you have remote access enabled, add the following to your `configuration.yaml` file: +Once you have remote access enabled using one of the above AND the Integration - cloud option enabled on the Sesame app for that lock settings, add the following to your `configuration.yaml` file: + ```yaml # Example configuration.yaml entry lock: - platform: sesame - email: abc@i-lovecandyhouse.co - password: super-strong-password + email: YOUR_E_MAIL_ADDRESS + password: YOUR_PASSWORD ``` -Configuration variables: +{% configuration %} +email: + description: The email address for your Sesame account. + required: true + type: string +password: + description: The password for your Sesame account. + required: true + type: string +{% endconfiguration %} -- **email** (*Required*): The email address for your Sesame account. -- **password** (*Required*): The password for your Sesame account. diff --git a/source/_components/lock.vera.markdown b/source/_components/lock.vera.markdown index 8baf864dfd3..a3050389878 100644 --- a/source/_components/lock.vera.markdown +++ b/source/_components/lock.vera.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Vera Lock" -description: "Instructions how to integrate Vera locks into Home Assistant." +description: "Instructions on how to integrate Vera locks into Home Assistant." date: 2016-06-29 15:00 sidebar: true comments: false diff --git a/source/_components/lock.verisure.markdown b/source/_components/lock.verisure.markdown index 2e726771795..e3c2d31e850 100644 --- a/source/_components/lock.verisure.markdown +++ b/source/_components/lock.verisure.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Verisure Lock" -description: "Instructions how to setup the Verisure locks within Home Assistant." +description: "Instructions on how to setup the Verisure locks within Home Assistant." date: 2016-02-12 06:00 sidebar: true comments: false diff --git a/source/_components/lock.wink.markdown b/source/_components/lock.wink.markdown index 1f51751b3f4..38b37fe9ea0 100644 --- a/source/_components/lock.wink.markdown +++ b/source/_components/lock.wink.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Wink Lock" -description: "Instructions how to setup the Wink locks within Home Assistant." +description: "Instructions on how to setup the Wink locks within Home Assistant." date: 2015-11-20 12:00 sidebar: true comments: false @@ -13,13 +13,11 @@ ha_release: 0.9 ha_iot_class: "Cloud Polling" --- - The Wink lock platform allows you to control your [Wink](http://www.wink.com/) locks. The requirement is that you have setup [Wink](/components/wink/). - -### Supported lock devices +### {% linkable_title Supported lock devices %} - Kwikset - Schlage @@ -56,7 +54,7 @@ You can use the service wink/wink_set_lock_alarm_sensitivity to set the alarm se | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `sensitivity` | no | String one of low, medium_low, medium, medium_high, high +| `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: @@ -140,7 +138,6 @@ You can use the service wink/wink_add_new_lock_key_code to add a new user code t | `name` | no | the name of the new key code | `code` | no | The new code. Must match length of existing codes. -
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.
diff --git a/source/_components/lock.xiaomi_aqara.markdown b/source/_components/lock.xiaomi_aqara.markdown new file mode 100644 index 00000000000..501e4899537 --- /dev/null +++ b/source/_components/lock.xiaomi_aqara.markdown @@ -0,0 +1,24 @@ +--- +layout: page +title: "Xiaomi Aqara Lock" +description: "Instructions on how to setup the Xiaomi Aqara Lock within Home Assistant." +date: 2018-05-17 20:24 +sidebar: true +comments: false +sharing: true +footer: true +logo: xiaomi.png +ha_category: Lock +ha_release: "0.71" +ha_iot_class: "Local Push" +--- + + +The `xiaomi aqara` lock platform allows you to get data (`changed_by` property, `verified_wrong_times` attribute) from your [Xiaomi](http://www.mi.com/en/) Aqara locks. +A Aqara lock cannot be controlled by Home Assistant. The property `changed_by` provides the user/key ID of the last successful unlock. + +If someone tries to unlock the device but fails more than 3 times the `verified_wrong_times` attribute will be incremented. The counter resets on a successful unlock. + +The requirement to use this platform is that you have set up the [Xiaomi Aqara](/components/xiaomi_aqara/) component. + + diff --git a/source/_components/lock.zwave.markdown b/source/_components/lock.zwave.markdown index e1d6fd7b33d..ba25eacd6c0 100644 --- a/source/_components/lock.zwave.markdown +++ b/source/_components/lock.zwave.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Z-Wave Lock" -description: "Instructions how to setup the Z-Wave Locks within Home Assistant." +description: "Instructions on how to setup the Z-Wave Locks within Home Assistant." date: 2016-05-07 08:00 sidebar: true comments: false diff --git a/source/_components/logbook.markdown b/source/_components/logbook.markdown index 74e493fc9bf..438e7474306 100644 --- a/source/_components/logbook.markdown +++ b/source/_components/logbook.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Logbook" -description: "Instructions how to enable the logbook component for Home Assistant." +description: "Instructions on how to enable the logbook component for Home Assistant." date: 2015-04-25 9:23 sidebar: true comments: false @@ -11,7 +11,7 @@ logo: logbook.png ha_category: "History" --- - The logbook component provides a different perspective on the history of your house by showing all the changes that happened to your house in reverse chronological order. [See the demo for a live example](/demo/). It depends on the `recorder` component for storing the data. This means that if the [`recorder`](/components/recorder/) component is set up to use e.g. MySQL or PostgreSQL as data store, the `logbook` component does not use the default SQLite database to store data.
+ The logbook component provides a different perspective on the history of your house by showing all the changes that happened to your house in reverse chronological order. [See the demo for a live example](/demo/). It depends on the `recorder` component for storing the data. This means that if the [`recorder`](/components/recorder/) component is set up to use e.g., MySQL or PostgreSQL as data store, the `logbook` component does not use the default SQLite database to store data.
To enable the logbook in your installation, add the following to your `configuration.yaml` file:
@@ -26,8 +26,8 @@ Configuration variables:
- **entities** (*Optional*): The list of entity ids to be excluded from creating logbook entries.
- **domains** (*Optional*): The list of domains to be excluded from creating logbook entries.
- **include** (*Optional*): Configure which components should create logbook entries.
- - **entities** (*Optional*): The list of entity ids to be included from creating logbook entries.
- - **domains** (*Optional*): The list of domains to be included from creating logbook entries.
+ - **entities** (*Optional*): The list of entity ids to be included in creating logbook entries.
+ - **domains** (*Optional*): The list of domains to be included in creating logbook entries.
If you want to exclude messages of some entities or domains from the logbook just add the `exclude` parameter like:
@@ -73,7 +73,7 @@ logbook:
### {% linkable_title Exclude Events %}
-Entities customized as hidden are excluded from the logbook by default, but sometimes you want to show the entity in the UI and not in the logbook. For instance you use the `sensor.date`to show the current date in the UI, but you do not want an logbook entry for that sensor every day.
+Entities customized as hidden are excluded from the logbook by default, but sometimes you want to show the entity in the UI and not in the logbook. For instance you use the `sensor.date`to show the current date in the UI, but you do not want a logbook entry for that sensor every day.
To exclude these entities just add them to the `exclude` > `entities` list in the configuration of the logbook.
To exclude all events from a whole domain add it to the `exclude` > `domain` list. For instance you use the `sun` domain only to trigger automations on the `azimuth attribute, then you possible are not interested in the logbook entries for sun rise and sun set.
diff --git a/source/_components/logentries.markdown b/source/_components/logentries.markdown
index e14b908b871..b365e57f63d 100644
--- a/source/_components/logentries.markdown
+++ b/source/_components/logentries.markdown
@@ -11,7 +11,9 @@ footer: true
ha_category: "History"
---
-The `logentries` component makes it possible to log all state changes to [your Logentries account](http://logentries.com/) using Logentries Webhook endpoint and a token based log
+The `logentries` component makes it possible to log all state changes to [Logentries](http://logentries.com/) using Logentries Webhook endpoint.
+
+Open the **Add a Log** page and choose **Manual**. Enter a name for your log in **Log Name**, add a group in **Select Log Set**, set **Token TCP - logs are identified by a token.** and press **Create Log Token**. The generated token is required for the Home Assistant configuration.
To use the `logentries` component in your installation, add the following to your `configuration.yaml` file:
@@ -21,6 +23,10 @@ logentries:
token: TOKEN
```
-Configuration variables:
+{% configuration %}
+token:
+ description: The token for the log to use.
+ required: true
+ type: string
+{% endconfiguration %}
-- **token** (*Required*): Your Logentries log token.
diff --git a/source/_components/logger.markdown b/source/_components/logger.markdown
index 70168cf440b..d3cef23a013 100644
--- a/source/_components/logger.markdown
+++ b/source/_components/logger.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Logger"
-description: "Instructions how to enable the logger component for Home Assistant."
+description: "Instructions on how to enable the logger component for Home Assistant."
date: 2015-11-12 17:00
sidebar: true
comments: false
@@ -11,15 +11,16 @@ logo: home-assistant.png
ha_category: "Utility"
---
-The logger component lets you define the level of logging activities in Home Assistant.
+The `logger` component lets you define the level of logging activities in Home Assistant.
-To enable the logger in your installation, add the following to your `configuration.yaml` file:
+To enable the `logger` component in your installation, add the following to your `configuration.yaml` file:
-To have a full log and log everything only this entry is needed (without any qualifier):
```yaml
+# Example configuration.yaml entry
logger:
```
-To log all messages and ignore events lower than critical for specified components.
+
+To log all messages and ignore events lower than critical for specified components:
```yaml
# Example configuration.yaml entry
@@ -30,7 +31,7 @@ logger:
homeassistant.components.camera: critical
```
-To ignore all messages lower than critical and log event for specified components.
+To ignore all messages lower than critical and log event for specified components:
```yaml
# Example configuration.yaml entry
@@ -43,7 +44,25 @@ logger:
homeassistant.components.camera: critical
```
-Possible log severities are:
+{% configuration %}
+ default:
+ description: Default log level.
+ required: false
+ type: '[log_level](#log-levels)'
+ default: debug
+ logs:
+ description: List of components and their log level.
+ required: false
+ type: map
+ keys:
+ '<component_namespace>':
+ description: Logger namespace of the component.
+ type: '[log_level](#log-levels)'
+{% endconfiguration %}
+
+### {% linkable_title Log Levels %}
+
+Possible log severity levels are:
- critical
- fatal
@@ -53,11 +72,26 @@ Possible log severities are:
- info
- debug
- notset
-
+
+## {% linkable_title Services %}
+
+### {% linkable_title Service `set_default_level` %}
+
+You can alter the default log level (for components without a specified log
+level) using the service `logger.set_default_level`.
+
+An example call might look like this:
+
+```yaml
+service: logger.set_default_level
+data:
+ level: info
+```
+
### {% linkable_title Service `set_level` %}
You can alter log level for one or several components using the service
-``logger.set_level``. It accepts the same format as ``logs`` in the configuration.
+`logger.set_level`. It accepts the same format as `logs` in the configuration.
An example call might look like this:
@@ -68,7 +102,9 @@ data:
homeassistant.components.media_player.yamaha: debug
```
-The log information are stored in the [configuration directory](/docs/configuration/) as `home-assistant.log` and you can read it with the command-line tool `cat` or follow it dynamically with `tail -f`.
+The log information are stored in the [configuration directory](/docs/configuration/)
+as `home-assistant.log` and you can read it with the command-line tool `cat` or
+follow it dynamically with `tail -f`.
If you are a Hassbian user you can use the example below:
@@ -76,7 +112,8 @@ If you are a Hassbian user you can use the example below:
$ tail -f /home/homeassistant/.homeassistant/home-assistant.log
```
-If you are a Hass.io user you can use the example below, whenlogged in through the ssh addon:
+If you are a Hass.io user, you can use the example below, when logged in through
+the [SSH add-on](/addons/ssh/):
```bash
$ tail -f /config/home-assistant.log
diff --git a/source/_components/lutron.markdown b/source/_components/lutron.markdown
index c946160db1e..6799e1feb55 100644
--- a/source/_components/lutron.markdown
+++ b/source/_components/lutron.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Lutron"
-description: "Instructions how to use Lutron devices with Home Assistant."
+description: "Instructions on how to use Lutron devices with Home Assistant."
date: 2017-01-28 13:00
sidebar: true
comments: false
@@ -18,6 +18,8 @@ ha_iot_class: "Local Polling"
Presently, there's only support for communicating with the [RadioRA 2](http://www.lutron.com/en-US/Products/Pages/WholeHomeSystems/RadioRA2/Overview.aspx) Main Repeater and only handle light switches and dimmers.
+## {% linkable_title Configuration %}
+
When configured, the `lutron` component will automatically discover the rooms and their associated switches/dimmers as configured by the RadioRA 2 software from Lutron. Each room will be treated as a separate group.
To use Lutron RadioRA 2 devices in your installation, add the following to your `configuration.yaml` file using the IP address of your RadioRA 2 main repeater:
diff --git a/source/_components/lutron_caseta.markdown b/source/_components/lutron_caseta.markdown
index 912bd82dc41..9783766c89d 100644
--- a/source/_components/lutron_caseta.markdown
+++ b/source/_components/lutron_caseta.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Lutron Caseta"
-description: "Instructions how to use Lutron Caseta devices with Home Assistant."
+description: "Instructions on how to use Lutron Caseta devices with Home Assistant."
date: 2017-01-28 13:00
sidebar: true
comments: false
@@ -25,7 +25,7 @@ The currently supported Caseta devices are:
- Scenes as Home Assistant [scenes](/components/scene.lutron_caseta/)
- Lutron shades as Home Assistant [covers](/components/cover.lutron_caseta/)
-When configured, the `lutron_caseta` component will automatically discover the currently supported devices as setup in the Lutron Smart Bridge. The name assigned in the Lutron mobile app will be used to form the `entity_id` used in Home Assistant. e.g. a dimmer called 'Bedroom Lamp' becomes `light.bedroom_lamp` in Home Assistant.
+When configured, the `lutron_caseta` component will automatically discover the currently supported devices as setup in the Lutron Smart Bridge. The name assigned in the Lutron mobile app will be used to form the `entity_id` used in Home Assistant. e.g., a dimmer called 'Bedroom Lamp' becomes `light.bedroom_lamp` in Home Assistant.
To use Lutron Caseta devices in your installation, you must first log in to your Lutron account and generate a certificate that allows Home Assistant to connect to your bridge. This can be accomplished by downloading and executing [this script](/assets/get_lutron_cert.zip), which will generate three files: caseta.key, caseta.crt, caseta-bridge.crt when you run it. See the instructions at the top of the script for more information.
diff --git a/source/_components/mailbox.asterisk_mbox.markdown b/source/_components/mailbox.asterisk_mbox.markdown
index 25a0859aa92..07e50d287c1 100644
--- a/source/_components/mailbox.asterisk_mbox.markdown
+++ b/source/_components/mailbox.asterisk_mbox.markdown
@@ -1,15 +1,15 @@
---
layout: page
title: "Asterisk Voicemail Mailbox"
-description: "Instructions how to integrate an Asterisk Voicemail within Home Assistant."
+description: "Instructions on how to integrate an Asterisk Voicemail within Home Assistant."
date: 2017-06-30 18:30
sidebar: true
comments: false
sharing: true
footer: true
+logo: asterisk.png
ha_category: Mailbox
-ha_version: 0.51
+ha_release: 0.51
---
-The Asterisk Voicemail Mailbox provides visual and audio access to voicemail on the Asterisk PBX server. This mailbox is enabled automatically through the [Asterisk Voicemail component](/components/asterisk_mbox) configuration.
-
+The Asterisk Voicemail Mailbox provides visual and audio access to voicemail on the Asterisk PBX server. This mailbox is enabled automatically through the [Asterisk Voicemail component](/components/asterisk_mbox/) configuration.
diff --git a/source/_components/mailbox.markdown b/source/_components/mailbox.markdown
index 88ff203523f..c6d270fdad9 100644
--- a/source/_components/mailbox.markdown
+++ b/source/_components/mailbox.markdown
@@ -1,18 +1,17 @@
---
layout: page
title: "Mailbox"
-description: "Instructions how to setup your mailboxes with Home Assistant."
+description: "Instructions on how to setup your mailboxes with Home Assistant."
date: 2017-06-30 18:30
sidebar: true
comments: false
sharing: true
-ha_version: 0.51
footer: true
+ha_release: 0.51
---
-Mailboxes provide an list of messages with short information about each. Mailbox messages appear on a separate panel in the frontend.
+Mailboxes provide a list of messages with short information about each. Mailbox messages appear on a separate panel in the frontend.
Home Assistant currently supports only the [Asterisk Voicemail](/component/mailbox.asterisk_mbox) mailbox.
Each mailbox also provides an entity to indicate the number of messages available on the main page.
-
diff --git a/source/_components/mailgun.markdown b/source/_components/mailgun.markdown
index 835464dfd06..2f13d2c0625 100644
--- a/source/_components/mailgun.markdown
+++ b/source/_components/mailgun.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Mailgun"
-description: "Instructions how to add Mailgun mail notifications to Home Assistant."
+description: "Instructions on how to add Mailgun mail notifications to Home Assistant."
date: 2017-02-06 16:52
sidebar: true
comments: false
@@ -12,7 +12,7 @@ ha_category: Notifications
ha_release: 0.38
---
-The component supports push messages and generates events based on inbound data. To use, add a Route set to Store and Notify with a URL of the following form: `https://
diff --git a/source/_components/media_player.philips_js.markdown b/source/_components/media_player.philips_js.markdown
index d7e663e8e55..78f87af83a6 100644
--- a/source/_components/media_player.philips_js.markdown
+++ b/source/_components/media_player.philips_js.markdown
@@ -29,3 +29,21 @@ Configuration variables:
- **host** (*Required*): IP address of TV.
- **name** (*Optional*): The name you would like to give to the Philips TV.
+- **turn_on_action** (*Optional*): A script that will be executed to turn on the TV (can be used with wol).
+- **api_version** (*Optional*): The JointSpace API version of your Philips TV, defaults to `1`. This is an experimental option and not all the functionalities are guaranteed to work with API versions different from `1` and `5`.
+
+
+When using api_version: 5 changing sources switches tv channels. Additionally this allows setting the volume level. +
+ + +```yaml +# Example configuration.yaml with turn_on_action +media_player: + - platform: philips_js + host: 192.168.1.99 + turn_on_action: + service: wake_on_lan.send_magic_packet + data: + mac: aa:bb:cc:dd:ee:ff +``` diff --git a/source/_components/media_player.pioneer.markdown b/source/_components/media_player.pioneer.markdown index 66086c5ded3..6bc6d1a5b00 100644 --- a/source/_components/media_player.pioneer.markdown +++ b/source/_components/media_player.pioneer.markdown @@ -29,7 +29,7 @@ Configuration variables: - **host** (*Required*): The IP of the Pioneer device, eg. `192.168.0.10` - **name** (*Optional*): The name you would like to give to the receiver. -- **port** (*Optional*): The port on which the Pioneer device listens, e.g. `23` (default) or `8102` +- **port** (*Optional*): The port on which the Pioneer device listens, e.g., `23` (default) or `8102` - **timeout** (*Optional*): Number of seconds (float) to wait for blocking operations like connect, write, and read. Notes: diff --git a/source/_components/media_player.plex.markdown b/source/_components/media_player.plex.markdown index ddaf3a611bf..e17068d2211 100644 --- a/source/_components/media_player.plex.markdown +++ b/source/_components/media_player.plex.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Plex" -description: "Instructions how to integrate Plex into Home Assistant." +description: "Instructions on how to integrate Plex into Home Assistant." date: 2015-10-05 21:21 sidebar: true comments: false @@ -69,6 +69,8 @@ media_player: show_all_controls: false use_custom_entity_ids: true use_episode_art: true + remove_unavailable_clients: true + client_remove_interval: 600 ``` - **entity_namespace** (*Optional*): Prefix for entity ID's. Defaults to `null`. Useful when using overlapping components (ex. Apple TV and Plex components when you have Apple TV's you use as Plex clients). Go from _media_player.playroom2_ to _media_player.plex_playroom_ - **include_non_clients** (*Optional*): Display non-recontrollable clients (ex. remote clients, PlexConnect Apple TV's). Defaults to `false`. @@ -76,6 +78,8 @@ media_player: - **show_all_controls** (*Optional*): Forces all controls to display. Defaults to `false`. Ignores dynamic controls (ex. show volume controls for client A but not for client B) based on detected client capabilities. This option allows you to override this detection if you suspect it to be incorrect. - **use_custom_entity_ids** (*Optional*): Name Entity ID's by client ID's instead of friendly names. Defaults to `false`. HA assigns entity ID's on a first come first serve basis. When you have identically named devices connecting (ex. media_player.plex_web_safari, media_player.plex_web_safari2), you can't reliably distinguish and or predict which device is which. This option avoids this issue by using unique client ID's (ex. media_player.dy4hdna2drhn). - **use_episode_art** (*Optional*): Display TV episode art instead of TV show art. Defaults to `false`. +- **remove_unavailable_clients** (*Optional*): Remove stale plex clients from UI after interval. Defaults to `true`. +- **client_remove_interval** (*Optional*): How long a client is to be unavailable for before it is cleaned up. Defaults to `600 seconds (10min)`. ### {% linkable_title Service `play_media` %} diff --git a/source/_components/media_player.roku.markdown b/source/_components/media_player.roku.markdown index 5c889727de3..c7771e0f406 100644 --- a/source/_components/media_player.roku.markdown +++ b/source/_components/media_player.roku.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Roku" -description: "Instructions how to integrate Roku into Home Assistant." +description: "Instructions on how to integrate Roku into Home Assistant." date: 2016-05-16 20:0+0000 sidebar: true comments: false diff --git a/source/_components/media_player.samsungtv.markdown b/source/_components/media_player.samsungtv.markdown index 2caaf7b0778..69174a09969 100644 --- a/source/_components/media_player.samsungtv.markdown +++ b/source/_components/media_player.samsungtv.markdown @@ -38,6 +38,7 @@ Configuration variables: Currently known supported models: - C7700 +- D5500 - D6500 - D7000 - D8000 @@ -49,29 +50,53 @@ Currently known supported models: - EH5600 - F6400AF - F6400 +- F8000BF - D6505 - D6300SF - U6000 (port must be set to 8001) - U6300 (port must be set to 8001, and `pip3 install websocket-client` must be executed) +- K5579 (port must be set to 8001, On/Off, Forward/Backward, Volume control, but no Play button) - K6500AF (port must be set to 8001) +- KS7005 (port must be set to 8001, and `pip3 install websocket-client` must be executed, MAC address must be provided, On/Off, Volume are OK, no channel change) +- KS8000 (port must be set to 8001, and `pip3 install websocket-client` must be executed) - KS8005 (port must be set to 8001, and `pip3 install websocket-client` must be executed) +- KU6020 (port must be set to 8001, and `pip3 install websocket-client` must be executed) +- KU6290 (port must be set to 8001) +- KU7000 (port must be set to 8001) +- MU6170UXZG (port must be set to 8001, and `pip3 install websocket-client` must be executed) - KS7502 (port must be set to 8001, and `pip3 install websocket-client` must be executed, turn on doesn't work, turn off works fine) - K5600AK (partially supported, turn on works but state is not updated) +- M5620 (port must be set to 8001, and `pip3 install websocket-client` must be executed) - UE65KS8005 (port must be set to 8001, On/Off, Forward/Backward, Volume are OK, but no Play button) +- UE6199UXZG (port must be set to 8001, On/Off, Forward/Backward, Volume control, but no Play button) +- Q7F (port must be set to 8001, MAC must be specified for Power On) +- UE40KU6400U (port must be set to 8001, and `pip3 install websocket-client` must be executed) Currently tested but not working models: - J5200 - Unable to see state and unable to control +- J5500 - State is always "on" and unable to control (but port 8001 *is* open) - JU7000 - Unable to see state and unable to control (but port 8001 *is* open) - JU7500 - Unable to see state and unable to control +- JS8005 - State tracking working but unable to control (but port 8001 *is* open) - JS9000 - State is always "on" and unable to control (but port 8001 *is* open) - JS9500 - State is always "on" and unable to control (but port 8001 *is* open) -- MU6170UXZG (port set to 8001, `pip3 install websocket-client` must be executed, turning on works, status not working reliably, turning off is not permanent (it comes back on).) +- MU6300 - Port set to 8001, `pip3 install websocket-client` must be executed, turning on works, status not working reliably, turning off is not permanent (it comes back on) +None of the 2014 (H) and 2015 (J) model series (e.g., J5200) will work, since Samsung have used a different (encrypted) type of interface for these. + If your model is not on the list then give it a test, if everything works correctly then add it to the list on [GitHub](https://github.com/home-assistant/home-assistant.github.io/tree/current/source/_components/media_player.samsungtv.markdown). -The first letter (U, P, L, H & K) represent the screen type, e.g. LED or Plasma. The second letter represents the region, E is Europe, N is North America and A is Asia & Australia. The two numbers following that represent the screen size. +The first letter (U, P, L, H & K) represent the screen type, e.g., LED or Plasma. The second letter represents the region, E is Europe, N is North America and A is Asia & Australia. The two numbers following that represent the screen size. If you add your model remember to remove these before adding them to the list. -Currently the ability to select a source is not implemented. +Changing channels can be done by calling the `media_player.play_media` service with the following payload: -There's currently a [known issue](https://github.com/home-assistant/home-assistant/issues/2098) with some TVs receiving a *Key press UP* that can interrupt certain applications. This should be fixed as of March 2017. +```javascript +{ + "entity_id": "media_player.office_tv", + "media_content_id": "590", + "media_content_type": "channel" +} +``` + +Currently the ability to select a source is not implemented. diff --git a/source/_components/media_player.sisyphus.markdown b/source/_components/media_player.sisyphus.markdown new file mode 100644 index 00000000000..ef0637ea32a --- /dev/null +++ b/source/_components/media_player.sisyphus.markdown @@ -0,0 +1,20 @@ +--- +layout: page +title: "Sisyphus Media Player" +description: "Instructions on how to integrate media playing on your Sisyphus Kinetic Art Table into Home Assistant." +date: 2018-05-06 22:26 +sidebar: true +comments: false +sharing: true +footer: true +logo: sisyphus.png +ha_category: Media Player +ha_iot_class: "Local Push" +ha_release: 0.75 +--- + +The [Sisyphus](https://sisyphus-industries.com/) integration for Home Assistant allows you to observe and control your Sisyphus Kinetic Art Table. + +Media players will be automatically added for each of your Sisyphus tables if the Sisyphus component is configured. + +For more configuration information see the [Sisyphus component](/components/sisyphus/) documentation. diff --git a/source/_components/media_player.songpal.markdown b/source/_components/media_player.songpal.markdown new file mode 100644 index 00000000000..0fd9a73f72c --- /dev/null +++ b/source/_components/media_player.songpal.markdown @@ -0,0 +1,68 @@ +--- +layout: page +title: "Sony SongPal compatible devices" +description: "Instructions on how to integrate Sony Songpal devices into Home Assistant." +date: 2018-02-03 09:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: sony.png +ha_category: Media Player +ha_iot_class: "Local Polling" +ha_release: 0.65 +--- + +The `songpal` platform allows you to control Sony's Songpal ("[Audio Control API](https://developer.sony.com/develop/audio-control-api/)") compatible devices such as soundbars, AV receivers and wireless speakers from Home Assistant. + +Even when the API officially supports only a few devices (HT-ST5000, HT-MT500, HT-CT800, SRS-ZR5 and STR-DN1080), it has also been confirmed to work on others. [The list of supported devices](http://vssupport.sony.net/en_ww/device.html) from Sony's Songpal website lists devices which are likely to be compatible with this platform. + +If the platform works with your non-listed device, or you encounter bugs, please feel free to [report them upstream](https://github.com/rytilahti/python-songpal). + +A few notes: + +- The quick start-up mode has to be enabled in order to turn the device on. +- Supports currently only one output terminal, i.e. the volume control works only on the first volume controller as reported by the backend library. +- Some devices, e.g., HT-XT3, do not support decreasing the volume step-by-step correctly. +- Feel free to improve the available services! + +## {% linkable_title Configuration %} + +The platform will be loaded automatically by discovery component. If you want to manually configure it, add the following to your `configuration.yaml` file: + +```yaml +media_player: + - platform: songpal + name: my soundbar + endpoint: http://IP_ADDRESS:10000/sony +``` + +{% configuration %} +name: + description: The name to display for this device. + required: false + type: string +endpoint: + description: API endpoint of the device. + required: true + type: string +{% endconfiguration %} + +See [python-songpal's documentation](https://github.com/rytilahti/python-songpal#locating-the-endpoint) how to get your API endpoint. + +## {% linkable_title Services %} + +In addition to the general [media player services](/components/media_player/#services), the following services are provided: + +### {% linkable_title Service `media_player/songpal_set_sound_setting` %} + +For a list of available settings and their values use [`songpal sound`](https://github.com/rytilahti/python-songpal#sound-settings) command. + +| Service data attribute | Optional | Description | +|------------------------|----------|--------------------------------------------------| +| `entity_id` | yes | Target entity, leave unset for all devices | +| `name` | no | Configuration variable, e.g., `nightmode` | +| `value` | no | New configuration value, e.g., `on` | + + + diff --git a/source/_components/media_player.soundtouch.markdown b/source/_components/media_player.soundtouch.markdown index fa2a550b024..463914f2366 100644 --- a/source/_components/media_player.soundtouch.markdown +++ b/source/_components/media_player.soundtouch.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Soundtouch" -description: "Instructions how to integrate Bose Soundtouch devices into Home Assistant." +description: "Instructions on how to integrate Bose Soundtouch devices into Home Assistant." date: 2016-11-06 13:00 sidebar: true comments: false diff --git a/source/_components/media_player.spotify.markdown b/source/_components/media_player.spotify.markdown index ec347498342..8de7240135f 100644 --- a/source/_components/media_player.spotify.markdown +++ b/source/_components/media_player.spotify.markdown @@ -29,7 +29,7 @@ To create the required Spotify Application: - Login to [Spotify Developer](https://developer.spotify.com) - Visit the [My Applications](https://developer.spotify.com/my-applications/#!/applications) page -- Select **Create An App**. Enter any name and description. Once your application is created, view it and copy your **Client ID** and **Client Secret**, which are used in the Home Assistant configuration file. +- Select **Create An App**. Enter any name and description. Once your application is created, view it and copy your **Client ID** and **Client Secret**, which are used in the Home Assistant configuration file. - Add a **Redirect URI** in the following forms: No SSL: `http://This platform now uses the web interface of the Logitech Media Server to send commands. The default port of the web interface is 9000. It is the same port that you use to access the LMS through your web browser. Originally, this platform used the telnet interface, which defaults to 9090. If you previously specified the port in your configuration file, you will likely need to update it.
+ +### {% linkable_title Service `squeezebox_call_method` %} + +Call a custom Squeezebox JSONRPC API. + +See documentation for this interface on http://HOST:PORT/html/docs/cli-api.html?player= where HOST and PORT are the host name and port for your Logitech Media Server. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | no | Name(s) of the Squeezebox entities where to run the API method. +| `command` | no | Command to pass to Logitech Media Server (p0 in the CLI documentation). +| `parameters` | yes | Array of additional parameters to pass to Logitech Media Server (p1, ..., pN in the CLI documentation). + +This service can be used to integrate any Squeezebox action to an automation. + +It can also be used to target a Squeezebox from IFTT (or DialogFlow, Alexa...). + +For example, to play an album from your collection, create an IFTT applet like this: +- Trigger: Google assistant, with sentence: `I want to listen to album $` +- Action: JSON post query with such JSON body: +`{ "entity_id": "media_player.squeezebox_radio", "command": "playlist", "parameters": ["loadtracks", "album.titlesearch={{TextField}}"] }` +This can work with title search and basically any thing. The same wouldn't have worked by calling directly Squeezebox server as IFTT cannot escape the text field. diff --git a/source/_components/media_player.ue_smart_radio.markdown b/source/_components/media_player.ue_smart_radio.markdown new file mode 100644 index 00000000000..0a250b6b860 --- /dev/null +++ b/source/_components/media_player.ue_smart_radio.markdown @@ -0,0 +1,38 @@ +--- +layout: page +title: "Logitech UE Smart Radio" +description: "Instructions on how to integrate a Logitech UE Smart Radio player into Home Assistant." +date: 2017-12-09 20:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: ueradio.png +ha_category: Media Player +ha_release: "0.60" +ha_iot_class: "Cloud Polling" +--- + + +The `ue_radio` platform allows you to control a [Logitech UE Smart Radio](https://www.uesmartradio.com) from Home Assistant. This lets you control both Logitech UE Smart Radios and Logitech Squeezebox Radios that have been updated with the UE Smart Radio update. + +To add your UE Smart Radio player to your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +media_player: + - platform: ue_smart_radio + username: YOUR_USERNAME + password: YOUR_PASSWORD +``` + +{% configuration %} +username: + description: The email you use to log in to `uesmartradio.com`. + required: true + type: string +password: + description: The password you use to log in to `uesmartradio.com`. + required: true + type: string +{% endconfiguration %} diff --git a/source/_components/media_player.universal.markdown b/source/_components/media_player.universal.markdown index 106f114f780..76cbc4a4ba6 100644 --- a/source/_components/media_player.universal.markdown +++ b/source/_components/media_player.universal.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Universal" -description: "Instructions how to create a universal media player in Home Assistant." +description: "Instructions on how to create a universal media player in Home Assistant." date: 2016-01-12 22:00 sidebar: true comments: false diff --git a/source/_components/media_player.vizio.markdown b/source/_components/media_player.vizio.markdown index 7c8cfa363ba..12916a2ed3c 100644 --- a/source/_components/media_player.vizio.markdown +++ b/source/_components/media_player.vizio.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Vizio SmartCast TV" -description: "Instructions how to integrate Vizio SmartCast TV into Home Assistant." +description: "Instructions on how to integrate Vizio SmartCast TV into Home Assistant." date: 2017-07-10 19:00 sidebar: true comments: false @@ -14,7 +14,7 @@ ha_release: 0.49 ha_iot_class: "Local Polling" --- -The `vizio` component will allow you to control [SmartCast](https://www.vizio.com/smartcast-app) compatible TVs (2016+ models). +The `vizio` component will allow you to control [SmartCast](https://www.vizio.com/smartcast-app) compatible TVs (2016+ models). ## Pairing @@ -36,7 +36,7 @@ Make sure that your TV is on before continuing. If you don't know IP address of your TV run following command: -```bash +```bash $ pyvizio --ip=0 --auth=0 discover ``` @@ -56,14 +56,14 @@ Initiation will show you two different values: Finally, at this point a PIN code should be displayed at the top of your TV. With all these values, you can now finish pairing: ```bash -$ pyvizio --ip={ip} pair_finish --token={challenge_token} --pin={tv_pin} +$ pyvizio --ip={ip} pair_finish --token={challenge_token} --pin={tv_pin} ``` -You will need the authentication token returned by this command to configure Home Assistant. +You will need the authentication token returned by this command to configure Home Assistant. ## Configuration -To add your Vizio TV to your installation, add the following to your `configuration.yaml` file: +To add your Vizio TV to your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -77,6 +77,7 @@ Configuration variables: - **host** (*Required*): IP address of your TV. - **access_token** (*Required*): Authentication token you received in the last step of the pairing process. +- **suppress_warning** (*Optional*): Set to `true` to disable self-signed certificate warnings. ## Notes and limitations @@ -84,20 +85,10 @@ Configuration variables: If the `Power Mode` of your TV is set to `Eco Mode`, turning the device ON won't work. -### Changing tracks +### Changing tracks -Changing tracks works like channels switching. If you have source other than regular TV it might end do nothing. +Changing tracks works like channels switching. If you have source other than regular TV it might end do nothing. ### Sources Source list shows all external devices connected to the TV through HDMI plus list of internal devices (TV mode, Chrome Cast, etc.). - --Vizio SmartCast service is accessible through HTTPS with self-signed certificate. If you have low LOGLEVEL in your Home Assistant configuration, you'll see a lot of warnings like this: -`InsecureRequestWarning: Unverified HTTPS request is being made. Adding certificate verification is strongly advised.` - -You can adjust the log level for `media_player` components with the [logger](https://home-assistant.io/components/logger/) component, or if you need to keep a low log level for `media_player` you could proxy calls to your TV through an NGINX reverse proxy. - -If you want to only ignore only this specific [python urllib3 SSL warning](https://urllib3.readthedocs.io/en/latest/advanced-usage.html#ssl-warnings), you will need to run Home Assistant with the python flag `-W` or the environment variable `PYTHONWARNINGS` set to: -`ignore:Unverified HTTPS request is being made` -
diff --git a/source/_components/media_player.vlc.markdown b/source/_components/media_player.vlc.markdown index 21ed9cdf248..09254957645 100644 --- a/source/_components/media_player.vlc.markdown +++ b/source/_components/media_player.vlc.markdown @@ -60,3 +60,7 @@ You need to add the `homeassistant` user to the `audio` group: ```bash sudo usermod -a -G audio homeassistant ``` + +##### {% linkable_title VLC currently not supported with Hass.io %} + +According to the forum topic ["How to add VLC into my Hassio"](http://community.home-assistant.io/t/how-to-add-vlc-into-my-hassio/23000/5), it is not possible to install packages like VLC on Hass.io. diff --git a/source/_components/media_player.volumio.markdown b/source/_components/media_player.volumio.markdown index f8945adc889..26053822e8a 100644 --- a/source/_components/media_player.volumio.markdown +++ b/source/_components/media_player.volumio.markdown @@ -12,12 +12,11 @@ ha_category: Media Player ha_release: 0.41 --- -The `Volumio` platform allows you to control a [Volumio](http://volumio.org) media player -from Home Assistant. +The `Volumio` platform allows you to control a [Volumio](http://volumio.org) media player from Home Assistant. +The preferred way to set up the Volumio platform is by enabling the [discovery component](/components/discovery/). -To add a Volumio player to your installation, add the following to -your `configuration.yaml` file. +In case the discovery does not work, or you need specific configuration variables, you can add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry diff --git a/source/_components/media_player.webostv.markdown b/source/_components/media_player.webostv.markdown index 102852ead3e..a4afa661dad 100644 --- a/source/_components/media_player.webostv.markdown +++ b/source/_components/media_player.webostv.markdown @@ -1,7 +1,7 @@ --- layout: page title: "LG webOS Smart TV" -description: "Instructions how to integrate a LG webOS Smart TV within Home Assistant." +description: "Instructions on how to integrate a LG webOS Smart TV within Home Assistant." date: 2016-04-18 23:24 sidebar: true comments: false @@ -19,7 +19,7 @@ The `webostv` platform allows you to control a [LG](http://www.lg.com/) webOS Sm To begin with enable *LG Connect Apps* feature in *Network* settings of the TV [instructions](http://www.lg.com/uk/support/product-help/CT00008334-1437131798537-others). -Once basic configuration is added to your `configuration.yaml` *Configuration* card should prompt on your HA's States. Follow the instructions and accept pairing request on your TV. +Once basic configuration is added to your `configuration.yaml` *Configuration* card should prompt on your Home Assistants's states. Follow the instructions and accept pairing request on your TV. Pairing information will be saved to the `filename:` provided in configuration; this process is IP sensitive, in case the IP address of your TV would change in future. @@ -36,16 +36,18 @@ media_player: Configuration variables: -- **host** (*Optional*): The IP of the LG webOS Smart TV, e.g. `192.168.0.10`. +- **host** (*Optional*): The IP of the LG webOS Smart TV, e.g., `192.168.0.10`. - **turn_on_action** (*Optional*): Defines an [action](/docs/automation/action/) to turn the TV on. - **name** (*Optional*): The name you would like to give to the LG webOS Smart TV. - **timeout** (*Optional*): The timeout for connections to the TV in seconds. -- **filename** (*Optional*): The filename where the pairing key with the TV should be stored. This path is relative to Home Assistant's config directory. It defaults to `webostv.conf`. +- **filename** (*Optional*): The filename where the pairing key with the TV should be stored. This path is relative to Home Assistant's config directory. It defaults to `webostv.conf`. **NOTE**: When using multiple TVs each TV will need its own unique file. - **customize** array (*Optional*): List of options to customize. - - ***sources** array (*Optional*): List of hardware and webOS App inputs. + - **sources** array (*Optional*): List of hardware and webOS App inputs. If you do not specify `host:`, all LG webOS Smart TVs within your network will be auto-discovered. +### {% linkable_title Example %} + A full configuration example will look like the sample below: ```yaml @@ -53,7 +55,7 @@ A full configuration example will look like the sample below: media_player: - platform: webostv host: 192.168.0.10 - name: Living Room TV + name: Living Room TV timeout: 5 filename: webostv.conf turn_on_action: @@ -67,10 +69,10 @@ media_player: - makotv - netflix ``` -** avoid using `[ ]` in the `name:` of your device. +Avoid using `[ ]` in the `name:` of your device. -*Turn On Action* +### {% linkable_title Turn on action %} Home Assistant is able to turn on a LG webOS Smart TV if you specify an action, like HDMI-CEC or WakeOnLan. @@ -88,11 +90,42 @@ media_player: turn_on_action: service: wake_on_lan.send_magic_packet data: - mac: B4:E6:2A:1E:11:0F + mac: "B4-E6-2A-1E-11-0F" ``` -Any other [actions](/docs/automation/action/) to power on the device can be configured. +Any other [actions](/docs/automation/action/) to power on the device can be configured. -*Sources* +### {% linkable_title Sources %} To obtain complete list of available sources currently configured on the TV, once the webOS TV is configured and linked, while its powered on head to the **Developer Tools** > **States**, find your `media_player.+When starting or restarting Home Assistant make sure your TV is off. This is a flaw in the TV itself. +
+ +Configuration variables: + +- **host** (*Optional*): The IP of the Xiaomi TV, eg. 192.168.0.10 +- **name** (*Optional*): The name to use on the frontend. Default is 'Xiaomi TV'. + +If you do not set a host in the configuration file, local TVs will automatically be discovered. + +To manually add a TV you can use the following configuration: + +```yaml +# Example configuration.yaml entry +media_player: + - platform: xiaomi_tv + host: YOUR_TV_IP + name: YOUR_TV_NAME +``` + ++The platform will never turn your TV off. Instead, it will be put to sleep and woken up. This can be useful, because the selected source of the TV will remain the same. It will essentially turn your TV into a dumb TV. +
diff --git a/source/_components/media_player.yamaha.markdown b/source/_components/media_player.yamaha.markdown index 8ab1d511144..b996e642a47 100644 --- a/source/_components/media_player.yamaha.markdown +++ b/source/_components/media_player.yamaha.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Yamaha Network Receivers" -description: "Instructions how to integrate Yamaha Network Receivers into Home Assistant." +description: "Instructions on how to integrate Yamaha Network Receivers into Home Assistant." date: 2016-03-26 0:58 -0700 sidebar: true comments: false @@ -36,7 +36,9 @@ Configuration variables: default name (often model number) that is returned by the device. - **host** (*Optional*): IP address or hostname of the device - **source_ignore** (*Optional*): List of sources to hide in the front-end -- **source_names** (*Optional*): Mapping of internal AVR source names to custom ones, allowing to rename e.g. `HDMI1` to `ChromeCast` +- **source_names** (*Optional*): Mapping of internal AVR source names to custom ones, allowing one to rename e.g., `HDMI1` to `ChromeCast` +- **zone_ignore** (*Optional*): List of zones to hide in the front-end +- **zone_names** (*Optional*): Mapping of zone names to custom ones, allowing one to rename e.g., `Main_Zone` to `Family Room` ### {% linkable_title Discovery notes %} @@ -50,7 +52,7 @@ Configuration variables: have your receiver switched off. - In some cases, auto-discovery fails due to a known bug in the receiver's firmware. It is possible to manually specify the - receiver's IP address or via it's hostname (if it is discoverable by + receiver's IP address or via its hostname (if it is discoverable by your DNS) then. ### {% linkable_title Supported operations %} @@ -59,7 +61,7 @@ Configuration variables: volume control and source selection. Playback controls, for instance play and stop are available for sources that supports it. - The `play_media` service is implemented for `NET RADIO` source - only. The `media_id` is a `>` separted string of the menu path on + only. The `media_id` is a `>` separated string of the menu path on the vtuner service. For instance `Bookmarks>Internet>WAMC 90.3 FM`. ### {% linkable_title Example configuration %} @@ -76,6 +78,10 @@ media_player: source_names: HDMI1: "ChromeCast" AV4: "Vinyl" + zone_ignore: + - "Zone_2" + zone_names: + Main_Zone: "Family Room" ``` ### {% linkable_title Example `play_media` script %} @@ -107,3 +113,13 @@ script: media_content_id: "Bookmarks>Internet>Radio Paradise" ``` + +### {% linkable_title Service `yamaha_enable_output` %} + +Enable or disable an output port (HDMI) on the receiver. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | yes | String or list of strings that point at `entity_id`s of Yamaha receivers. +| `port` | no | Port to enable or disable, e.g., `hdmi1`. +| `enabled` | no | To enable set true, otherwise set to false. diff --git a/source/_components/media_player.yamaha_musiccast.markdown b/source/_components/media_player.yamaha_musiccast.markdown index 121687b9827..7d98e77102f 100644 --- a/source/_components/media_player.yamaha_musiccast.markdown +++ b/source/_components/media_player.yamaha_musiccast.markdown @@ -16,7 +16,7 @@ The `yamaha_musiccast` platform allows you to control [Yamaha MusicCast Receiver Supported devices are listed on their [German site](https://de.yamaha.com/de/products/contents/audio_visual/musiccast/products.html). -To add a Yamaha Network Receiver to your installation, add the following to your `configuration.yaml` file: +To add a Yamaha MusicCast Receiver to your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry @@ -27,7 +27,7 @@ media_player: Configuration variables: - **host** (*Required*): IP address or hostname of the device -- **port** (*Optional*): UDP Port +- **port** (*Optional*): UDP source port. If multiple devices are present, specify a different port per device - **interval_seconds** (*Optional*): Polling interval (default: 480 seconds = 8 minutes) A few notes: diff --git a/source/_components/media_player.ziggo_mediabox_xl.markdown b/source/_components/media_player.ziggo_mediabox_xl.markdown new file mode 100644 index 00000000000..0581b320a26 --- /dev/null +++ b/source/_components/media_player.ziggo_mediabox_xl.markdown @@ -0,0 +1,43 @@ +--- +layout: page +title: "Ziggo Mediabox XL" +description: "Instructions on how to integrate the Ziggo Mediabox XL into Home Assistant." +date: 2017-11-10 20:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: ziggo.png +ha_category: Media Player +ha_iot_class: "Local Polling" +ha_release: "0.60" +--- + +The `ziggo_mediabox_xl` component allows you to control a [Ziggo](https://www.ziggo.nl/) Mediabox XL from Home Assistant. + +To add a Ziggo Mediabox XL to your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +media_player: + - platform: ziggo_mediabox_xl + host: 192.168.0.123 + name: Ziggo Mediabox +``` + +{% configuration %} + host: + description: The hostname or address of the device. + required: true + type: string + name: + description: The name of the device used in the frontend. + required: false + type: string +{% endconfiguration %} + +The channel information (numbers and names) are downloaded from ziggo.nl on startup. + +#### {% linkable_title Preparation of the Mediabox %} + +Makes sure to enable the Home Network ("mijn thuisnetwerk") service in the settings menu of the media box. Once you have set up the Media Library ("mediabiblotheek"), we can determine whether the device is turned on or off. Without this, the component will fail to start. diff --git a/source/_components/melissa.markdown b/source/_components/melissa.markdown new file mode 100644 index 00000000000..46be358b61d --- /dev/null +++ b/source/_components/melissa.markdown @@ -0,0 +1,39 @@ +--- +layout: page +title: "Melissa Climate" +description: "Instructions on how to integrate Melissa Climate into Home Assistant." +date: 2017-01-05 17:30 +sidebar: true +comments: false +sharing: true +footer: true +logo: mclimate.png +ha_category: Hub +featured: false +ha_release: 0.63 +ha_iot_class: "Cloud Polling" +--- + +The `Melissa` component is the main component to connect to a [Melissa Climate](http://seemelissa.com/) A/C control. + +## {% linkable_title Configuration %} + +To set the Melissa component up, add the following information to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +melissa: + username: YOUR_MELISSA_USERNAME + password: YOUR_PASSWORD +``` + +{% configuration %} + username: + description: The username for accessing your Melissa account. + required: true + type: string + password: + description: The password for accessing your Melissa account. + required: true + type: string +{% endconfiguration %} diff --git a/source/_components/mercedesme.markdown b/source/_components/mercedesme.markdown new file mode 100644 index 00000000000..db5774c5183 --- /dev/null +++ b/source/_components/mercedesme.markdown @@ -0,0 +1,27 @@ +--- +layout: page +title: "Mercedes me" +description: "Instructions on how to integrate Mercedes car with Mercedes me into Home Assistant." +date: 2018-01-27 17:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: mercedesme.png +ha_category: Hub +ha_release: 0.63 +ha_iot_class: "Cloud Polling" +--- + + +The `mercedesme` component offers integration with the [Mercedes me](https://www.mercedes-benz.com/de/mercedes-me/) cloud service and provides presence detection as well as sensors such as doors, tires, windows, and service interval. + +This component provides the following platforms: + + - Binary Sensors: Windows, tires, doors and lock. + - Sensors:Fuel status, service interval, remaining km, etc. + - Device tracker: To track location of your car. + ++ The component was removed. The vendor disabled the API endpoint and a new API is not available currently. +
diff --git a/source/_components/mochad.markdown b/source/_components/mochad.markdown index f27367f0da1..bf0617cefb7 100644 --- a/source/_components/mochad.markdown +++ b/source/_components/mochad.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Mochad" -description: "Instructions how to integrate Mochad into Home Assistant." +description: "Instructions on how to integrate Mochad into Home Assistant." date: 2016-10-20 17:09 sidebar: true comments: false @@ -13,6 +13,8 @@ ha_release: 0.32 The `mochad` component is the main component to integrate all X10 platforms being controlled by [mochad](https://sourceforge.net/projects/mochad/). Besides this component you will have to setup your X10 devices separately. +## {% linkable_title Configuration %} + To integrate your Mochad units with Home Assistant, add the following section to your `configuration.yaml` file: ```yaml @@ -20,10 +22,20 @@ To integrate your Mochad units with Home Assistant, add the following section to mochad: ``` -Configuration variables: +{% configuration %} +host: + description: The host that mochad is running on. + required: false + type: string + default: localhost +port: + description: The port that mochad is running on. + required: false + type: int + default: 1099 +{% endconfiguration %} -- **host** (*Optional*): The host that mochad is running on. Defaults to `localhost`. -- **port** (*Optional*): The port that mochad is running on. Defaults to `1099`. +## {% linkable_title Example %} A full configuration sample could look like the one below: diff --git a/source/_components/modbus.markdown b/source/_components/modbus.markdown index f673298d82e..dcccf0ede67 100644 --- a/source/_components/modbus.markdown +++ b/source/_components/modbus.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Modbus" -description: "Instructions how to integrate Modbus within Home Assistant." +description: "Instructions on how to integrate Modbus within Home Assistant." date: 2015-04-25 9:16 sidebar: true comments: false @@ -16,6 +16,8 @@ ha_iot_class: "Local Push" [Modbus](http://www.modbus.org/) is a serial communication protocol to control PLCs (Programmable logic controller). It currently supports sensors and switches which can be controlled over serial, TCP, and UDP connections. +## {% linkable_title Configuration %} + To add modbus to your installation, add the following to your `configuration.yaml` file: For a network connection: @@ -30,7 +32,10 @@ modbus: Configuration variables: -- **type** (*Required*): Type of the connection to Modbus. +- **type** (*Required*): Type of the connection to Modbus. Possible values are: + - *tcp*: Modbus TCP protocol according to "MODBUS Messaging Implementation Guide version 1.0b" provided by Schneider Automation, + - *udp*: Modbus TCP form, but using UDP for transport (removes the overheads required for TCP), + - *rtuovertcp*: Modbus RTU message transmitted with a TCP/IP wrapper and sent over a network instead of serial lines. - **host** (*Required*): The IP address of your Modbus device, eg. 192.168.1.1. - **port** (*Required*): The port for the communication. - **timeout** (*Optional*): Timeout for slave response in seconds. (default: 3) @@ -51,7 +56,7 @@ modbus: Configuration variables: -- **type** (*Required*): Type of the connection to Modebus. +- **type** (*Required*): Type of the connection to Modbus. - **method** (*Required*): Method of the connection to Modbus. - **port** (*Required*): The port where your Modbus device is connected to your Home Assistant host. - **baudrate** (*Required*): The speed for the serial connection. diff --git a/source/_components/mqtt.markdown b/source/_components/mqtt.markdown index 5514b98c362..275cac866ed 100644 --- a/source/_components/mqtt.markdown +++ b/source/_components/mqtt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MQTT" -description: "Instructions how to setup MQTT within Home Assistant." +description: "Instructions on how to setup MQTT within Home Assistant." date: 2015-08-07 18:00 sidebar: true comments: false @@ -33,6 +33,10 @@ mqtt: broker: IP_ADDRESS_BROKER ``` ++The minimal setup uses the embedded MQTT broker, however a separate broker is advised for more stability. +
+ ## {% linkable_title Additional features %} - [Certificate](/docs/mqtt/certificate/) diff --git a/source/_components/mqtt_eventstream.markdown b/source/_components/mqtt_eventstream.markdown index 7dd471e5cbf..4946433e630 100644 --- a/source/_components/mqtt_eventstream.markdown +++ b/source/_components/mqtt_eventstream.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MQTT Eventstream" -description: "Instructions how to setup MQTT eventstream within Home Assistant." +description: "Instructions on how to setup MQTT eventstream within Home Assistant." date: 2016-01-13 08:00 sidebar: true comments: false @@ -15,6 +15,8 @@ ha_iot_class: depends The `mqtt_eventstream` component connects two Home Assistant instances via MQTT. +## {% linkable_title Configuration %} + To integrate MQTT Eventstream into Home Assistant, add the following section to your `configuration.yaml` file: ```yaml @@ -33,6 +35,10 @@ subscribe_topic: description: Topic to receive events from the remote server. required: false type: string +ignore_event: + description: Ignore sending these [events](/docs/configuration/events/) over mqtt. + required: false + type: list {% endconfiguration %} ## {% linkable_title Multiple Instances %} @@ -44,6 +50,9 @@ Events from multiple instances can be aggregated to a single master instance by mqtt_eventstream: publish_topic: master/topic subscribe_topic: slaves/# + ignore_event: + - call_service + - state_changed ``` For a multiple instance setup, each slave would publish to their own topic. diff --git a/source/_components/mqtt_statestream.markdown b/source/_components/mqtt_statestream.markdown index 5b7b832fe91..8b1afaa89d5 100644 --- a/source/_components/mqtt_statestream.markdown +++ b/source/_components/mqtt_statestream.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MQTT Statestream" -description: "Instructions how to setup MQTT Statestream within Home Assistant." +description: "Instructions on how to setup MQTT Statestream within Home Assistant." date: 2017-10-01 20:00 sidebar: true comments: false @@ -15,6 +15,8 @@ ha_iot_class: depends The `mqtt_statestream` component publishes state changes in Home Assistant to individual MQTT topics. +## {% linkable_title Configuration %} + To enable MQTT Statestream in Home Assistant, add the following section to your `configuration.yaml` file: ```yaml diff --git a/source/_components/mychevy.markdown b/source/_components/mychevy.markdown new file mode 100644 index 00000000000..15a6b88ff19 --- /dev/null +++ b/source/_components/mychevy.markdown @@ -0,0 +1,59 @@ +--- +layout: page +title: "MyChevy" +description: "Instructions on how to integrate Chevy Bolt car into Home Assistant." +date: 2017-08-28 17:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: chevy.png +ha_category: Hub +ha_release: 0.62 +ha_iot_class: "Cloud Polling" +--- + +The `MyChevy` component communicates with the [my.chevrolet](https://my.chevrolet.com) website using selenium to log in as your user, and screen scrape the data provided. GM does not make it easy to sign up for any official development program, so this provides a workaround to get access to your data. + +This component provides the following platforms: + + - Binary sensors: if the car is plugged in + - Sensors: Battery Level, Charge Mode, EST Range, Total Distance Traveled + +## {% linkable_title Configuration %} + +To use MyChevy in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +mychevy: + username: YOUR_E_MAIL_ADDRESS + password: YOUR_PASSWORD +``` + +{% configuration %} +username: + description: The email address associated with your my.chevrolet account. + required: true + type: string +password: + description: The password for your given my.chevrolet account. + required: true + type: string +{% endconfiguration %} + + +#### {% linkable_title Installation %} + +Because this uses selenium behind the scenes, installation is more complicated than merely pip install. See the [installation instructions](https://github.com/sdague/mychevy). + +#### {% linkable_title Limitations %} + +The architecture of the GM automotive networking imposes some limitations on the functionality of the component. + +The OnStar network link is very slow, and takes 1 - 3 minutes to get information back from the car. As such the mychevy component only polls every 30 minutes to not overwhelms that connection. + +The OnStar network (or more specifically the gateway used by the my.chevrolet website) appears to suffer more than most networks when the car is a) in a garage, and b) it's cold outside (like < 15 degrees F). One of the provided sensors is a status sensor which indicates if we got connectivity with the car on the last polling cycle or not. + +The "API" for this is written by web scraping. As such, it only currently is known to work if you have a Chevy Bolt EV, and only 1 Chevy car connected to OnStar. Patches for extended support should go to the https://github.com/sdague/mychevy project first, then Home Assistant can be extended. + diff --git a/source/_components/mycroft.markdown b/source/_components/mycroft.markdown index 50241b7a2f1..9754096be00 100644 --- a/source/_components/mycroft.markdown +++ b/source/_components/mycroft.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Mycroft" -description: "Instructions how to setup Mycroft AI within Home Assistant." +description: "Instructions on how to setup Mycroft AI within Home Assistant." date: 2017-08-26 17:00 sidebar: true comments: false @@ -12,7 +12,7 @@ ha_category: Voice ha_release: 0.53 --- -[Mycroft](https://mycroft.ai) is a open source voice assistant that allows you to send notifications and more to Mycroft from Home Assistant. +[Mycroft](https://mycroft.ai) is an open source voice assistant that allows you to send notifications and more to Mycroft from Home Assistant. ```yaml # Example configuration.yaml entry diff --git a/source/_components/mysensors.markdown b/source/_components/mysensors.markdown index c91f5a123e6..3cd360e2d26 100644 --- a/source/_components/mysensors.markdown +++ b/source/_components/mysensors.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MySensors" -description: "Instructions how to integrate MySensors sensors into Home Assistant." +description: "Instructions on how to integrate MySensors sensors into Home Assistant." date: 2016-10-01 15:00 +0200 sidebar: true comments: false @@ -24,27 +24,6 @@ Integrate your Serial, Ethernet or MQTT Client MySensors Gateway by adding the f mysensors: gateways: - device: '/dev/ttyUSB0' - persistence_file: 'path/mysensors.json' - baud_rate: 38400 - nodes: - 1: - name: 'kitchen' - 3: - name: 'living_room' - - device: '/dev/ttyACM0' - persistence_file: 'path/mysensors2.json' - baud_rate: 115200 - - device: '192.168.1.18' - persistence_file: 'path/mysensors3.json' - tcp_port: 5003 - - device: mqtt - persistence_file: 'path/mysensors4.json' - topic_in_prefix: 'mygateway1-out' - topic_out_prefix: 'mygateway1-in' - optimistic: false - persistence: true - retain: true - version: '2.0' ``` {% configuration %} @@ -62,6 +41,11 @@ mysensors: required: false type: int default: 115200 + persistence_file: + description: The path to a file to save sensor information. The file extension determines the file type. Currently supported file types are 'pickle' and 'json'. + required: false + type: string + default: path/to/config/directory/mysensors.pickle tcp_port: description: Specifies the port of the connected TCP Ethernet gateway. required: false @@ -83,23 +67,14 @@ mysensors: type: map keys: name: - description: The name the node will be renamed to. This nodename becomes part of the entity_id. Default entity_id is [sketch_name]\_[node_id]\_[child_id] and when this name is set, the entity_id becomes [name]\_[child_id]. + description: The name the node will be renamed to. This node name becomes part of the entity_id. Default entity_id is [sketch_name]\_[node_id]\_[child_id] and when this name is set, the entity_id becomes [name]\_[child_id]. required: true type: string - debug: - description: This option has been deprecated. Please remove this from your config if you have it included. Use the [logger component](/components/logger/) to filter log messages on log level. - required: false - type: int persistence: description: Enable or disable local persistence of sensor information. If this is disabled, then each sensor will need to send presentation messages after Home Assistant starts. required: false type: int default: true - persistence_file: - description: The path to a file to save sensor information. The file extension determines the file type. Currently supported file types are 'pickle' and 'json'. - required: false - type: string - default: path/to/config/directory/mysensors.pickle version: description: Specifies the MySensors protocol version to use. Supports 1.4, 1.5 and 2.0. required: false @@ -138,17 +113,47 @@ mqtt: The MQTT gateway requires MySensors version 2.0 and only the MQTT client gateway is supported. +### {% linkable_title Extended configuration example %} + +```yaml +# Example configuration.yaml entry +mysensors: + gateways: + - device: '/dev/ttyUSB0' + persistence_file: 'path/mysensors.json' + baud_rate: 38400 + nodes: + 1: + name: 'kitchen' + 3: + name: 'living_room' + - device: '/dev/ttyACM0' + persistence_file: 'path/mysensors2.json' + baud_rate: 115200 + - device: '192.168.1.18' + persistence_file: 'path/mysensors3.json' + tcp_port: 5003 + - device: mqtt + persistence_file: 'path/mysensors4.json' + topic_in_prefix: 'mygateway1-out' + topic_out_prefix: 'mygateway1-in' + optimistic: false + persistence: true + retain: true + version: '2.0' +``` + ### {% linkable_title Presentation %} Present a MySensors sensor or actuator, by following these steps: 1. Connect the serial gateway to your computer or the Ethernet or MQTT gateway to your network. 2. Configure the MySensors component in `configuration.yaml`. -3. Start hass. +3. Start Home Assistant. 4. Write and upload your MySensors sketch to the sensor. Make sure you: - Send sketch name. - Present the sensor's S_TYPE. - - Send at least one initial value per V_TYPE. In version 2.0 of MySensors this has to be done in the loop function. See below for an example in 2.0 of how to make sure the initial value has been received by the controller. + - Send at least one initial value per V_TYPE. In version 2.0 of MySensors, this has to be done in the loop function. See below for an example in 2.0 of how to make sure the initial value has been received by the controller. 5. Start the sensor. ```cpp @@ -231,9 +236,11 @@ void receive(const MyMessage &message) { } ``` -### {% linkable_title Heartbeats %} +### {% linkable_title SmartSleep %} -Sending a heartbeat from the MySensors device to Home Assistant activates the SmartSleep functionality in Home Assistant. This means that messages are buffered and only sent to the device upon receiving a heartbeat from the device. State changes are stored so that only the last requested state change is sent to the device. Other types of messages are queued in a FIFO queue. SmartSleep is useful for battery powered actuators that are waiting for commands. See the MySensors library API for information on how to send heartbeats and sleep device. +Sending a heartbeat, `I_HEARTBEAT_RESPONSE`, from the MySensors device to Home Assistant, using MySensors version 2.0 - 2.1, activates the SmartSleep functionality in Home Assistant. This means that messages are buffered and only sent to the device upon receiving a heartbeat from the device. State changes are stored so that only the last requested state change is sent to the device. Other types of messages are queued in a FIFO queue. SmartSleep is useful for battery powered actuators that are waiting for commands. See the MySensors library API for information on how to send heartbeats and sleep the device. + +In MySensors version 2.2 the serial API changed from using `I_HEARTBEAT_RESPONSE` to signal SmartSleep, to using `I_PRE_SLEEP_NOTIFICATION` and `I_POST_SLEEP_NOTIFICATION`. Home Assistant has been upgraded to support the new message types and will activate SmartSleep when receiving a message of type `I_PRE_SLEEP_NOTIFICATION`, if using MySensors version 2.2.x or higher. If Home Assistant is configured to use MySensors version 2.0 - 2.1 the old SmartSleep behavior is retained. ### {% linkable_title Message validation %} @@ -247,7 +254,7 @@ logger: homeassistant.components.mysensors: debug mysensors: debug ``` -The log should inform you of messages that failed validation or if a child value is missing that is required for a certain child type. Note that the log will log all possible combinations of platforms for a child type that failed validation. It is normal to see some platforms fail validation if the child type supports multiple platforms and your sketch doesn't send all corresponding value types. Eg. the S_BARO child type supports both V_PRESSURE and V_FORECAST value types. If you only send a V_PRESSURE value, an S_BARO entity with V_PRESSURE value will be set up for the sensor platform. But the log will inform of a sensor platform that failed validation due to missing V_FORECAST value type for the S_BARO child. Home Assistant will log failed validations of child values at warning level if one required value type for a platform has been received, but other required value types are missing. Most failed validations are logged at debug level. +The log should inform you of messages that failed validation or if a child value is missing that is required for a certain child type. Note that the log will log all possible combinations of platforms for a child type that failed validation. It is normal to see some platforms fail validation if the child type supports multiple platforms and your sketch doesn't send all corresponding value types. Eg. the S_BARO child type supports both V_PRESSURE and V_FORECAST value types. If you only send a V_PRESSURE value, an S_BARO entity with V_PRESSURE value will be set up for the sensor platform. However, the log will inform of a sensor platform that failed validation due to missing V_FORECAST value type for the S_BARO child. Home Assistant will log failed validations of child values at warning level if one required value type for a platform has been received, but other required value types are missing. Most failed validations are logged at debug level. Message validation was introduced in version 0.52 of Home Assistant. diff --git a/source/_components/namecheapdns.markdown b/source/_components/namecheapdns.markdown index 3331080fa93..4f68adb4606 100644 --- a/source/_components/namecheapdns.markdown +++ b/source/_components/namecheapdns.markdown @@ -16,7 +16,7 @@ ha_release: 0.56 With the `namecheapdns` component you can automatically update your dynamic DNS entry at [namecheapdns](https://www.namecheap.com/store/domains/freedns/).-Namecheap only supports IPv4 adresses to update. +Namecheap only supports IPv4 addresses to update.
To use the component in your installation, add the following to your `configuration.yaml` file: diff --git a/source/_components/neato.markdown b/source/_components/neato.markdown index 6e0849e6f01..43aca42701f 100644 --- a/source/_components/neato.markdown +++ b/source/_components/neato.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Neato Robotics" -description: "Instructions how to integrate your Neato within Home Assistant." +description: "Instructions on how to integrate your Neato within Home Assistant." date: 2016-10-09 20:15 sidebar: true comments: false @@ -12,22 +12,28 @@ ha_category: Hub ha_release: 0.33 --- -The `neato` component allows you to control your [Neato Botvac Connected](https://www.neatorobotics.com/robot-vacuum/botvac-connected-series/botvac-connected/). +The `neato` component allows you to control your [Neato Botvac Connected Robots](https://www.neatorobotics.com/robot-vacuum/botvac-connected-series/). To enable `neato` in your installation, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry neato: - username: USERNAME - password: PASSWORD + username: YOUR_USERNAME + password: YOUR_PASSWORD ``` -Configuration variables: - -- **username** (*Required*): Username for the Neato account. -- **password** (*Required*): Password for the Neato account. +{% configuration %} +username: + description: Username for the Neato account. + required: true + type: string +password: + description: Password for the Neato account. + required: true + type: string +{% endconfiguration %}-The Home Assistant Neato platform has only be tested with a Botvac Connected. There is no support for the Botvac D3 Connected and Botvac D5 Connected robots at this time. +After the update to firmware 4.0 (which adds cleaning maps) there is also support for displaying the maps of the Botvac D3 Connected and Botvac D5 Connected robots. More information on how to update can be found [here](https://support.neatorobotics.com/hc/en-us/articles/115004320694-Software-Update-4-0-for-Neato-Botvac-Connected-D3-D5-).
diff --git a/source/_components/nest.markdown b/source/_components/nest.markdown index b3d376c50fc..a6e021b94fa 100644 --- a/source/_components/nest.markdown +++ b/source/_components/nest.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Nest" -description: "Instructions how to integrate Nest into Home Assistant." +description: "Instructions on how to integrate Nest into Home Assistant." date: 2016-01-29 21:57 sidebar: true comments: false @@ -10,7 +10,7 @@ footer: true logo: nest.png ha_category: Hub featured: true -ha_iot_class: "Cloud Polling" +ha_iot_class: "Cloud Push" --- The Nest component is the main component to integrate all [Nest](https://nest.com/) related platforms. To connect Nest, you will have to [sign up for a developer account](https://developers.nest.com/products) and get a `client_id` and `client_secret`. @@ -27,14 +27,14 @@ The Nest component is the main component to integrate all [Nest](https://nest.co - Product name must be unique. We recommend [email] - Home Assistant. - The description, users, URLs can all be anything you want. - Leave the "Redirect URI" Field blank -7. For permissions check every box and if it's an option select the read/write option. +7. For permissions check every box and if it's an option select the read/write option. Note: there are important permissions under the "Other Permissions" category. If you are only adding a thermostat, do not just select the permissions under "Thermostat". You still need to check the boxes under "Other Permissions" in order to give you access to features like away mode, ETA, structure read/write, and postal code. - The description requires a specific format to be accepted. - Use "[Home Assistant] [Edit] [For Home Automation]" as the description as it is not super important. 8. Click "Create Product" 9. Once the new product page opens the "Product ID" and "Product Secret" are located on the right side. These will be used as `client_id` and `client_secret` below. 10. Once Home Assistant is started, a configurator will pop up asking you to log into your Nest account and copy a PIN code into Home Assistant. -Connecting to the Nest Developer API requires outbound port 8553 on your firewall. The configuration will fail if this is not accessible. +Connecting to the Nest Developer API requires outbound port 9553 on your firewall. The configuration will fail if this is not accessible. ### {% linkable_title Configuration %} @@ -65,7 +65,15 @@ Configuration variables: Currently there is a single `nest.set_mode` service available to switch between "away" and "home" modes. This service requires a `home_mode` param and has an -optional `structure` param. +optional `structure` param. While setting "away" mode, an estimated arrival time +can also be set with `eta`, `eta_window`, and `trip_id` parameters. + +- **home_mode** (*Required*): `home` or `away` +- **structure** (*Optional*): Structure(s). Default apply to all structures connected with Home Assistant. +- **eta** (*Optional*): Estimated Time of Arrival from now. +- **eta_window** (*Optional*): ETA window (default is 1 minute). +- **trip_id** (*Optional*): Unique ID for the trip. Using an existing trip ID will update that trip's ETA. + ```yaml # Example script to set away, no structure specified so will execute for all @@ -86,3 +94,16 @@ set_nest_home: structure: - Building ``` + +```yaml +# Example script to set eta, structure specified +set_nest_eta: + sequence: + - service: nest.set_mode + data: + home_mode: away + structure: + - Building + eta: 00:10:30 + eta_window: 00:05 +``` diff --git a/source/_components/netatmo.markdown b/source/_components/netatmo.markdown index a7b6a30a0c0..0efe4ac968c 100644 --- a/source/_components/netatmo.markdown +++ b/source/_components/netatmo.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Netatmo" -description: "Instructions how to integrate Netatmo component into Home Assistant." +description: "Instructions on how to integrate Netatmo component into Home Assistant." date: 2016-06-02 08:10 sidebar: true comments: false @@ -55,6 +55,3 @@ That's it. You can copy and paste your new `client id` and `client secret` in yo
--The Home Assistant Netatmo platform has only be tested with the classic indoor, outdoor module and rain meter. There is no support for the wind meter module at this time because developers does not own these modules. -
diff --git a/source/_components/netgear_lte.markdown b/source/_components/netgear_lte.markdown new file mode 100644 index 00000000000..36ce55a6fdc --- /dev/null +++ b/source/_components/netgear_lte.markdown @@ -0,0 +1,39 @@ +--- +layout: page +title: "Netgear LTE" +description: "Instructions on how to integrate your Netgear LTE modem within Home Assistant." +date: 2018-06-06 23:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: netgear.png +ha_release: 0.72 +ha_category: Other +ha_iot_class: "Local Polling" +--- + +The Netgear LTE integration for Home Assistant allows you to observe and control [Netgear LTE modems](https://www.netgear.com/home/products/mobile-broadband/lte-modems/default.aspx), currently only tested with LB2120. + +The integration provides: +* a notify service that will send an SMS +* a sensor with the number of unread SMS messages in the inbox +* a sensor with data usage + +```yaml +# Example configuration.yaml entry +netgear_lte: + - host: IP_ADDRESS + password: SECRET +``` + +{% configuration %} +host: + description: The IP address of the modem web interface. + required: true + type: string +password: + description: The password used for the modem web interface. + required: true + type: string +{% endconfiguration %} diff --git a/source/_components/notify.apns.markdown b/source/_components/notify.apns.markdown index 30737d617ec..dcad472dbb1 100644 --- a/source/_components/notify.apns.markdown +++ b/source/_components/notify.apns.markdown @@ -1,7 +1,7 @@ --- layout: page title: "APNS" -description: "Instructions how to add APNS notifications to Home Assistant." +description: "Instructions on how to add APNS notifications to Home Assistant." date: 2016-09-05 23:00 sidebar: true comments: false diff --git a/source/_components/notify.aws_lambda.markdown b/source/_components/notify.aws_lambda.markdown index 21ef850da95..be5a5494caa 100644 --- a/source/_components/notify.aws_lambda.markdown +++ b/source/_components/notify.aws_lambda.markdown @@ -1,7 +1,7 @@ --- layout: page title: "AWS Lambda" -description: "Instructions how to invoke AWS Lambda functions from Home Assistant." +description: "Instructions on how to invoke AWS Lambda functions from Home Assistant." date: 2016-05-14 16:35 sidebar: true comments: false diff --git a/source/_components/notify.aws_sns.markdown b/source/_components/notify.aws_sns.markdown index 21a6b48cc55..cfa69e00843 100644 --- a/source/_components/notify.aws_sns.markdown +++ b/source/_components/notify.aws_sns.markdown @@ -1,7 +1,7 @@ --- layout: page title: "AWS SNS" -description: "Instructions how to publish messages to AWS SNS from Home Assistant." +description: "Instructions on how to publish messages to AWS SNS from Home Assistant." date: 2016-05-14 16:35 sidebar: true comments: false diff --git a/source/_components/notify.aws_sqs.markdown b/source/_components/notify.aws_sqs.markdown index e40e81050b1..a1e8a33f8bd 100644 --- a/source/_components/notify.aws_sqs.markdown +++ b/source/_components/notify.aws_sqs.markdown @@ -1,7 +1,7 @@ --- layout: page title: "AWS SQS" -description: "Instructions how to publish messages to AWS SQS from Home Assistant." +description: "Instructions on how to publish messages to AWS SQS from Home Assistant." date: 2016-05-14 16:35 sidebar: true comments: false diff --git a/source/_components/notify.ciscospark.markdown b/source/_components/notify.ciscospark.markdown index 96bc67c4968..fb55b90a6f9 100644 --- a/source/_components/notify.ciscospark.markdown +++ b/source/_components/notify.ciscospark.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Cisco Spark" -description: "Instructions how to add CiscoSpark notifications to Home Assistant." +description: "Instructions on how to add CiscoSpark notifications to Home Assistant." date: 2017-02-20 15:00 sidebar: true comments: false @@ -18,6 +18,9 @@ To use this notification platform you need to get a developer token. To obtain a At this time you also need to specify the `Cisco Spark` `roomid`. The `roomid` can also be found at [Spark for Developers](https://developer.ciscospark.com/index.html). Just look in the Documentation under Rooms. +In order to get notified for all new messages in the room you will need to create a bot. This will post the messages from the bot and mark them as new for you which will alert you. If you use your own personal token the messages are added to the room but no notification is triggered. +Once you have created the bot through the new App menu you will need to add the bot to the room that you are a member of as well. Now use the bot access token in your configuration below. + To enable the Cisco Spark notification in your installation, add the following to your `configuration.yaml` file: ```yaml diff --git a/source/_components/notify.clickatell.markdown b/source/_components/notify.clickatell.markdown index 0c274c9a1b7..8ac5d9a614c 100644 --- a/source/_components/notify.clickatell.markdown +++ b/source/_components/notify.clickatell.markdown @@ -16,7 +16,7 @@ ha_release: 0.56 The `clickatell` platform uses [Clickatell](https://clickatell.com) to deliver SMS notifications from Home Assistant. ### Get your Clickatell API Credentials -Go to your [Clickatell SMS Platform Portal](https://portal.clickatell.com/#/) section and create a new SMS integration. There are three screens of information required to creater an integration. Please ensure the following: +Go to your [Clickatell SMS Platform Portal](https://portal.clickatell.com/#/) section and create a new SMS integration. There are three screens of information required to create an integration. Please ensure the following: 1. Give the new Integration an identification name. 2. Ensure it is set for 'production' use. @@ -40,7 +40,7 @@ Configuration variables: * **name** (Optional): Setting the optional parameter name allows multiple notifiers to be created. The default value is `clickatell`. The notifier will bind to the service notify.NOTIFIER_NAME. * **api_key** (Required): Your API key. -* **recipient** (Required): Your phone number. This is where you want to send your notification SMS messages. e.g. `61444333444`. +* **recipient** (Required): Your phone number. This is where you want to send your notification SMS messages. e.g., `61444333444`. -To use notifications, please see the [getting started with automation page](https://home-assistant.io/getting-started/automation/). +To use notifications, please see the [getting started with automation page](/getting-started/automation/). diff --git a/source/_components/notify.clicksend.markdown b/source/_components/notify.clicksend.markdown index 96a43adfe12..8d619617b42 100644 --- a/source/_components/notify.clicksend.markdown +++ b/source/_components/notify.clicksend.markdown @@ -15,27 +15,54 @@ ha_release: 0.48 The `clicksend` platform uses [ClickSend](https://clicksend.com) to deliver notifications from Home Assistant. -### Get your ClickSend API Credentials +## {% linkable_title Prerequisites %} + Go to your [ClickSend Dashboard](https://dashboard.clicksend.com) section and create your new project. After creating your project, you should now be able to obtain your `username` and `api_key`. -### Configuration +## {% linkable_title Configuration %} + To add ClickSend to your installation, add the following to your Home Assistant `configuration.yaml` file: ```yaml +# Example configuration.yaml entry notify: - platform: clicksend name: ClickSend username: CLICKSEND_USERNAME api_key: CLICKSEND_API_KEY recipient: PHONE_NO + +# Multiple recipients +notify: + - platform: clicksend + name: ClickSend + username: CLICKSEND_USERNAME + api_key: CLICKSEND_API_KEY + recipient: [PHONE_NO1, PHONE_NO2] ``` -Configuration variables: +{% configuration %} +name: + description: "Setting the optional parameter name allows multiple notifiers to be created. The default value is `ClickSend`. The notifier will bind to the service `notify.NOTIFIER_NAME`." + required: false + type: string +username: + description: Your Clicksend username. + required: true + type: string +api_key: + description: Your Clicksend API Key. + required: true + type: string +recipient: + description: "A single or multiple phone numbers. This is where you want to send your SMS notification messages, e.g., `09171234567` or `[09171234567, 09177654321]`." + required: true + type: string or list +sender: + description: The name or number of the sender. + required: false + type: string + default: recipient +{% endconfiguration %} -* **name** (Optional): Setting the optional parameter name allows multiple notifiers to be created. The default value is `ClickSend`. The notifier will bind to the service notify.NOTIFIER_NAME. -* **username** (Required): Your `Username`. -* **api_key** (Required): Your `API Key`. -* **recipient** (Required): Your phone no. This is where you want to send your notification SMS messages. eg: `09171234567` - - -To use notifications, please see the [getting started with automation page](https://home-assistant.io/getting-started/automation/). +To use notifications, please see the [getting started with automation page](/getting-started/automation/). diff --git a/source/_components/notify.clicksend_tts.markdown b/source/_components/notify.clicksend_tts.markdown index 28e860834f8..6009c9e9871 100644 --- a/source/_components/notify.clicksend_tts.markdown +++ b/source/_components/notify.clicksend_tts.markdown @@ -38,5 +38,5 @@ Configuration variables: * **language** (Optional): The language you want to use to convert the message to audio. Accepted values are found in the [ClickSend Documentation](http://docs.clicksend.apiary.io/#reference/voice/voice-languages). Default value is `en-us`. * **voice** (Optional): The voice that needs to be used to play the message to the recipient. Allowed values are `female` or `male`. Default value is `female`. -To use notifications, please see the [getting started with automation page](https://home-assistant.io/getting-started/automation/). +To use notifications, please see the [getting started with automation page](/getting-started/automation/). diff --git a/source/_components/notify.command_line.markdown b/source/_components/notify.command_line.markdown index a5d3b6a5942..4f82febe402 100644 --- a/source/_components/notify.command_line.markdown +++ b/source/_components/notify.command_line.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Command line Notify" -description: "Instructions how to add command line notifications to Home Assistant." +description: "Instructions on how to add command line notifications to Home Assistant." date: 2016-02-22 20:00 sidebar: true comments: false diff --git a/source/_components/notify.discord.markdown b/source/_components/notify.discord.markdown index 657b94e84e5..01029fb4b1c 100644 --- a/source/_components/notify.discord.markdown +++ b/source/_components/notify.discord.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Discord" -description: "Instructions how to add Discord notifications to Home Assistant." +description: "Instructions on how to add Discord notifications to Home Assistant." date: 2016-01-14 15:15 sidebar: true comments: false @@ -16,7 +16,7 @@ The [Discord service](https://discordapp.com/) is a platform for the notify comp In order to get a token you need to go to the [Discord My Apps page](https://discordapp.com/developers/applications/me) and create a new application. Once the application is ready, create a [bot](https://discordapp.com/developers/docs/topics/oauth2#bots) user (**Create a Bot User**) and activate **Require OAuth2 Code Grant**. Retrieve the **Client ID** and the (hidden) **Token** of your bot for later. -When setting up the application you can use this [icon](https://home-assistant.io/demo/favicon-192x192.png). +When setting up the application you can use this [icon](/demo/favicon-192x192.png). To use Discord notifications, add the following to your `configuration.yaml` file: @@ -35,11 +35,11 @@ Configuration variables: ### {% linkable_title Setting up the bot %} -Bots can only send messages to servers. To add the bot to a server you are an admin on, get the details of the bot from the [Discord My Apps page](https://discordapp.com/developers/applications/me). +Bots can only send messages to servers. To add the bot to a server you are an admin on, get the details of the bot from the [Discord My Apps page](https://discordapp.com/developers/applications/me).
-
+
+
+You will need the last part of the URL which is the `access_token` for your room.
+
+
+ 
+
+HTML5 push notifications **do not** work on iOS. +
+ To enable this platform, add the following lines to your `configuration.yaml` file: ```yaml @@ -21,41 +25,44 @@ To enable this platform, add the following lines to your `configuration.yaml` fi notify: - name: NOTIFIER_NAME platform: html5 - gcm_api_key: 'gcm-sender-key' + gcm_api_key: 'gcm-server-key' gcm_sender_id: 'gcm-sender-id' ``` Configuration variables: - **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`. -- **gcm_api_key** (*Required if pushing to Chrome*): The API key provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome. +- **gcm_api_key** (*Required if pushing to Chrome*): The API Server key provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome. - **gcm_sender_id** (*Required if pushing to Chrome*): The sender ID provided to you by Google for Google Cloud Messaging (GCM). Required to push to Chrome. ### {% linkable_title Getting ready for Chrome %} -1. Create new project at [https://console.cloud.google.com/home/dashboard](https://console.cloud.google.com/home/dashboard). -2. Go to [https://console.cloud.google.com/apis/credentials/domainverification](https://console.cloud.google.com/apis/credentials/domainverification) and verify your domain. -3. After that, go to [https://console.firebase.google.com](https://console.firebase.google.com) and select import Google project, select the project you created. -4. Then, click the cogwheel on top left and select "Project settings". -5. Select 'Cloud Messaging' tab, listed beneath Project Credentials will be your 152 character 'Server Key' and 12 digit ID 'Sender ID'. +1. Make sure you can access your Home Assistant installation from outside your network over https ([see docs](/docs/configuration/remote/)). +2. Create a new project at [https://console.cloud.google.com/home/dashboard](https://console.cloud.google.com/home/dashboard). +3. Go to [https://console.cloud.google.com/apis/credentials/domainverification](https://console.cloud.google.com/apis/credentials/domainverification) and verify your domain via Google Webmaster Central / Search Console - [instructions](#verify-your-domain). +4. With the domain verified, go to [https://console.firebase.google.com](https://console.firebase.google.com), select import Google project, and select the project you created. +5. Then, click the cogwheel on top left and select "Project settings". +6. Select 'Cloud Messaging' tab, listed beneath Project Credentials will be your 152 character 'Server Key' and 12 digit ID 'Sender ID' you need for configuring this component. -#### {% linkable_title Verify your domain with Hass.io %} +#### {% linkable_title Verify your domain %} -1. For verifying your domain you need to download a file in step 2. -2. Create a dictionary named "www" in you Hass.io configuration dictionary. -3. Place the file (something like this: google*.html) in the "www" directory. -4. You can open it by going to **https://yourdomain/local/exact_file_name.html** -5. Proceed with step 3. +Follow these steps to verify domain ownership with Google Webmaster Central / Search Console: +1. Enter your domain and add **'/local'** at the end, ie. https://example.com:8123/local +2. Select HTML file verification and download the google*.html file. +2. Create a directory named "www" in your Home Assistant configuration directory (/config share from Samba add-on). +3. Place the downloaded google*.html file in the "www" directory. +4. RESTART Home Assistant - this is important! +5. Verify the file can be accessed in the browser, ie. **https://example.com:8123/local/google123456789.html** (change filename) - you should a plain text message saying "google-site-verification: ..." - if you see "404: Not Found" or something else, retry the above steps. +6. Go back to Google Webmaster Central / Search Console and proceed with the verification. ### {% linkable_title Requirements %} The `html5` platform can only function if all of the following requirements are met: -(On Hass.io these requirements are already met.) * You are using Chrome and/or Firefox on any desktop platform, ChromeOS or Android. * Your Home Assistant instance is exposed to the world. * If using a proxy, HTTP basic authentication must be off for registering or unregistering for push notifications. It can be re-enabled afterwards. -* `pywebpush` must be installed. `libffi-dev`, `libpython-dev`, and `libssl-dev` must be installed prior to `pywebpush` (i.e. `pywebpush` probably won't automatically install). +* If you don't run Hass.io: `pywebpush` must be installed. `libffi-dev`, `libpython-dev`, and `libssl-dev` must be installed prior to `pywebpush` (i.e. `pywebpush` probably won't automatically install). * You have configured SSL for your Home Assistant. It doesn't need to be configured in Home Assistant though, i.e. you can be running [NGINX](/ecosystem/nginx/) in front of Home Assistant and this will still work. The certificate must be trustworthy (i.e. not self signed). * You are willing to accept the notification permission in your browser. @@ -65,7 +72,7 @@ The `html5` platform can only function if all of the following requirements are Assuming you have already added the platform to your configuration: 1. Open Home Assistant in Chrome or Firefox. -2. Assuming you have met all the [requirements](#requirements) above, you should see a new slider in the sidebar labeled Push Notifications. +2. Assuming you have met all the [requirements](#requirements) above, you should see a new slider for Push Notifications through the sidebar Configuration > General. 3. Slide it to the on position. 4. Within a few seconds you should be prompted to allow notifications from Home Assistant. 5. Assuming you accept, that's all there is to it! @@ -249,7 +256,7 @@ You will receive an event named `html5_notification.closed` when the notificatio ### {% linkable_title Making notifications work with NGINX proxy %} -If you use [NGINX](/ecosystem/nginx/) as an proxy with authentication in front of your Home Assistant instance, you may have trouble with receiving events back to Home Assistant. It's because of authentication token that cannot be passed through the proxy. +If you use [NGINX](/ecosystem/nginx/) as a proxy with authentication in front of your Home Assistant instance, you may have trouble with receiving events back to Home Assistant. It's because of authentication token that cannot be passed through the proxy. To solve the issue put additional location into your nginx site's configuration: diff --git a/source/_components/notify.instapush.markdown b/source/_components/notify.instapush.markdown index 427991e60dc..020f535c106 100644 --- a/source/_components/notify.instapush.markdown +++ b/source/_components/notify.instapush.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Instapush" -description: "Instructions how to add Instapush notifications to Home Assistant." +description: "Instructions on how to add Instapush notifications to Home Assistant." date: 2015-05-01 18:00 sidebar: true comments: false diff --git a/source/_components/notify.joaoapps_join.markdown b/source/_components/notify.joaoapps_join.markdown index 3f64711ff72..2143480d0e3 100644 --- a/source/_components/notify.joaoapps_join.markdown +++ b/source/_components/notify.joaoapps_join.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Join Notify" -description: "Instructions how to setup the Join notification platform within Home Assistant." +description: "Instructions on how to setup the Join notification platform within Home Assistant." date: 2016-07-12 09:00 sidebar: true comments: false diff --git a/source/_components/notify.kodi.markdown b/source/_components/notify.kodi.markdown index 6949a927227..7d350005a85 100644 --- a/source/_components/notify.kodi.markdown +++ b/source/_components/notify.kodi.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Kodi" -description: "Instructions how to add Kodi notifications to Home Assistant." +description: "Instructions on how to add Kodi notifications to Home Assistant." date: 2016-09-12 16:00 sidebar: true comments: false diff --git a/source/_components/notify.lametric.markdown b/source/_components/notify.lametric.markdown index cf50cffaa2e..b9ee3343439 100644 --- a/source/_components/notify.lametric.markdown +++ b/source/_components/notify.lametric.markdown @@ -43,6 +43,11 @@ cycles: required: false type: int default: 1 +priority: + description: Defines the priority of the notification. + required: False + type: string + default: warning {% endconfiguration %} Check out the list of all icons at [https://developer.lametric.com/icons](https://developer.lametric.com/icons). Note that icons always begin with "i" while animations begin with "a". This is part of the name, you can't just use the number! @@ -59,11 +64,12 @@ notify: lifetime: 20 icon: a7956 cycles: 3 + priority: info ``` ### {% linkable_title Changing sounds and icons %} -To add a notification sound or an icon override, it has to be done via service data. +To add a notification sound, icon, cycles, or priority override, it has to be done via service data. ```yaml - alias: "Send notification on arrival at school" @@ -79,4 +85,23 @@ To add a notification sound or an icon override, it has to be done via service d data: sound: 'notification' icon: 'i51' + cycles: 0 + priority: 'critical' +``` + +### {% linkable_title Only notify specific device %} + +If you have more than one La Metric device, you can specify which will receive the message by adding `target:` to the service data: + +```yaml + action: + service: notify.lametric + data: + message: "Son has arrived at school!" + target: "Office LaMetric" + data: + sound: 'notification' + icon: 'i51' ``` + + If target is not specified, all LaMetric devices will be notified. diff --git a/source/_components/notify.lannouncer.markdown b/source/_components/notify.lannouncer.markdown index 2f411679c95..5aba4e41f9e 100644 --- a/source/_components/notify.lannouncer.markdown +++ b/source/_components/notify.lannouncer.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Lannouncer" -description: "Instructions how to add Lannouncer notifications to Home Assistant." +description: "Instructions on how to add Lannouncer notifications to Home Assistant." date: 2017-01-06 10:00 sidebar: true comments: false diff --git a/source/_components/notify.llamalab_automate.markdown b/source/_components/notify.llamalab_automate.markdown index 3b5d5d2dd5a..40becc0eb52 100644 --- a/source/_components/notify.llamalab_automate.markdown +++ b/source/_components/notify.llamalab_automate.markdown @@ -1,7 +1,7 @@ --- layout: page title: "LlamaLab Automate" -description: "Instructions how to add user notifications to Home Assistant." +description: "Instructions on how to add user notifications to Home Assistant." date: 2016-08-21 13:00 sidebar: true comments: false diff --git a/source/_components/notify.mailgun.markdown b/source/_components/notify.mailgun.markdown index be571eb2c14..9e98d180524 100644 --- a/source/_components/notify.mailgun.markdown +++ b/source/_components/notify.mailgun.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Mailgun Notify" -description: "Instructions how to add Mailgun mail notifications to Home Assistant." +description: "Instructions on how to add Mailgun mail notifications to Home Assistant." date: 2017-02-06 16:52 sidebar: true comments: false diff --git a/source/_components/notify.markdown b/source/_components/notify.markdown index 6ef8c7c50db..7f3225bd73c 100644 --- a/source/_components/notify.markdown +++ b/source/_components/notify.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Notifications" -description: "Instructions how to add user notifications to Home Assistant." +description: "Instructions on how to add user notifications to Home Assistant." date: 2015-01-20 22:36 sidebar: true comments: false @@ -21,7 +21,7 @@ notify: api_key: ABCDEFG ``` -The **name** parameter is optional but needed if you want to use multiple platforms. The platform will be exposed as service `notify/ **Developer Tools** allows you to send MQTT messages. Choose *mqtt.publish* from the list of **Available services:** and enter something like the sample below into the **Service Data** field and hit **CALL SERVICE**.
```json
{"payload": "Test message from HA", "topic": "home/notification", "qos": 0, "retain": 0}
@@ -24,7 +24,18 @@ The MQTT notification support is different than the other [notification](/compon
-Using the [REST API](/developers/rest_api/#post-apiservicesltdomainltservice) to send a message to a given topic.
+The same will work for automations.
+
+
+ 
+
- If you are creating a client-side library, application, or open source project that will be redistributed and installed by end-users, you may want to require each of your users to register their own application rather than including your own API token with the software. -- -When setting up the application you can use this [icon](https://home-assistant.io/images/favicon-192x192.png). +Component specific values in the nested `data` section are optional. To use notifications, please see the [getting started with automation page](/getting-started/automation/). -When sending a notification, optional parameters can also be set as per the pushover [API documentation](https://pushover.net/api). +When sending a notification, optional parameters can also be set as per the pushover [API documentation](https://pushover.net/api). Example notification triggered from the Alexa component for an intents is shown below which also uses [Automation Templating](/getting-started/automation-templating/) for the message: +{% raw %} ```yaml # Example configuration.yaml entries alexa: @@ -66,10 +66,12 @@ alexa: action: service: notify.notify data_template: - message: "The location of {% raw %}{{ User }}{% endraw %} has been queried via Alexa." + message: "The location of {{ User }} has been queried via Alexa." + data: + title: "Home Assistant" data: - title: "Home Assistant" sound: falling device: pixel - url: "https://home-assistant.io/" + url: "https://www.home-assistant.io/" ``` +{% endraw %} diff --git a/source/_components/notify.pushsafer.markdown b/source/_components/notify.pushsafer.markdown index 4b003d97d82..5b1ce8ed54c 100644 --- a/source/_components/notify.pushsafer.markdown +++ b/source/_components/notify.pushsafer.markdown @@ -1,8 +1,8 @@ --- layout: page title: "Pushsafer" -description: "Instructions how to add Pushsafer notifications to Home Assistant." -date: 2017-02-17 20:46 +description: "Instructions on how to add Pushsafer notifications to Home Assistant." +date: 2018-01-05 11:15 sidebar: true comments: false sharing: true @@ -15,7 +15,7 @@ ha_release: 0.39 The [Pushsafer service](https://www.pushsafer.com/) is a platform for the notify component. This allows you to send messages to the user using Pushsafer. -In order to get an private or alias key you need to go to the [Pushsafer website](https://www.pushsafer.com) and register. +In order to get a private or alias key you need to go to the [Pushsafer website](https://www.pushsafer.com) and register. To use Pushsafer notifications, add the following to your `configuration.yaml` file: @@ -27,11 +27,78 @@ notify: private_key: ABCDEFGHJKLMNOPQRSTUVXYZ ``` -Configuration variables: +**Configuration variables:** - **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`. - **private_key** (*Required*): Your private or alias key. Private key = send the notification to all devices with standard params, alias key send the notification to the devices stored in the alias with predefined params. -When setting up the application you can use this [icon](https://home-assistant.io/images/favicon-192x192.png). +### {% linkable_title Examples %} + +Message to two devices with formatted text. + +```json +{ + "title": "Test to 2 devices", + "message": "Attention [b]bold[/b] text[br][url=https://www.pushsafer.com]Link to Pushsafer[/url]", + "target": ["1111", "2222"], + "data": { + "icon": "2", + "iconcolor": "#FF0000", + "sound": "2", + "vibration": "1", + "url": "https://www.home-assistant.io/", + "urltitle": "Open Home Assistant", + "time2live": "0" + } +} +``` + +Message to one device with formatted text and image from an external URL. + +```json +{ + "title": "Test to 1 device with image from an url", + "message": "Attention [i]italic[/i] Text[br][url=https://www.home-assistant.io/]Testlink[/url]", + "target": ["1111"], + "data": { + "icon": "14", + "iconcolor": "#FFFF00", + "sound": "22", + "vibration": "3", + "url": "https://www.home-assistant.io/", + "urltitle": "Open Home Assistant", + "time2live": "60", + "picture1": { + "url":"https://www.home-assistant.io/images/components/alexa/alexa-512x512.png" + } + } +} +``` + +Message to two devices and one device group with formatted text and local image. + +```json +{ + "title": "Test to 3 devices with local image", + "message": "Attention [i]italic[/i] Text[br][url=https://www.home-assistant.io/]Testlink[/url]", + "target": ["1111","2222","gs3333"], + "data": { + "icon": "20", + "iconcolor": "#FF00FF", + "sound": "33", + "vibration": "0", + "url": "https://www.home-assistant.io/", + "urltitle": "Open Home Assistant", + "time2live": "10", + "picture1": { + "path":"C:\\Users\\Kevin\\AppData\\Roaming\\.homeassistant\\image-760-testimage.jpg" + } + } +} +``` + +To customize your push-notification you can take a look at the [Pushsafer API description](https://www.pushsafer.com/en/pushapi). + +When setting up the application you can use this [icon](/images/favicon-192x192.png). To use notifications, please see the [getting started with automation page](/getting-started/automation/). diff --git a/source/_components/notify.rest.markdown b/source/_components/notify.rest.markdown index 370f26be8c3..4d1d83c5813 100644 --- a/source/_components/notify.rest.markdown +++ b/source/_components/notify.rest.markdown @@ -1,7 +1,7 @@ --- layout: page title: "REST" -description: "Instructions how to add RESTful notifications to Home Assistant." +description: "Instructions on how to add RESTful notifications to Home Assistant." date: 2016-02-12 07:00 sidebar: true comments: false @@ -30,6 +30,7 @@ Configuration variables: - **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`. - **resource** (*Required*): The resource or endpoint that will receive the value. - **method** (*Optional*): The method of the request. Default is GET. +- **headers** (*Optional*): The headers for the request. - **message_param_name** (*Optional*): Parameter name for the message. Defaults to `message`. - **title_param_name** (*Optional*): Parameter name for the title. Defaults to none. - **target_param_name** (*Optional*): Parameter name for the target. Defaults to none. diff --git a/source/_components/notify.rocketchat.markdown b/source/_components/notify.rocketchat.markdown index 2c014c30546..19d9c876d90 100644 --- a/source/_components/notify.rocketchat.markdown +++ b/source/_components/notify.rocketchat.markdown @@ -13,7 +13,9 @@ ha_release: 0.56 --- -The `rocketchat` platform allows you to send messages to your [Rocket.Chat](https://rocket.chat/) instance from Home Assistant. +The `rocketchat` notify platform allows you to send messages to your [Rocket.Chat](https://rocket.chat/) instance from Home Assistant. + +## {% linkable_title Configuration %} To add Rocket.Chat to your installation, add the following to your `configuration.yaml` file: @@ -23,9 +25,9 @@ notify: - platform: rocketchat name: NOTIFIER_NAME url: https://rocketchat.example.com - username: USERNAME - password: PASSWORD - room: my-awesome-room + username: YOUR_USERNAME + password: YOUR_PASSWORD + room: YOUR_ROOM_NAME ``` - **name** (*Optional*): Name displayed in the frontend. The notifier will bind to the service `notify.NOTIFIER_NAME`. @@ -49,8 +51,7 @@ rocketchat_notification: #### {% linkable_title Message variables %} - **message** (*Required*): Message to be displayed. -- **data** (*Optional*): Dictionary containing any of the variables defined in the - [Rocket.Chat docs](https://rocket.chat/docs/developer-guides/rest-api/chat/postmessage#message-object-example) +- **data** (*Optional*): Dictionary containing any of the variables defined in the [Rocket.Chat docs](https://rocket.chat/docs/developer-guides/rest-api/chat/postmessage#message-object-example) To use notifications, please see the [getting started with automation page](/getting-started/automation/). diff --git a/source/_components/notify.sendgrid.markdown b/source/_components/notify.sendgrid.markdown index 16bf7e992a1..2491bac32e4 100644 --- a/source/_components/notify.sendgrid.markdown +++ b/source/_components/notify.sendgrid.markdown @@ -1,7 +1,7 @@ --- layout: page title: "SendGrid" -description: "Instructions how to add email notifications via SendGrid to Home Assistant." +description: "Instructions on how to add email notifications via SendGrid to Home Assistant." date: 2016-02-27 18:00 sidebar: true comments: false diff --git a/source/_components/notify.simplepush.markdown b/source/_components/notify.simplepush.markdown index 4747d9a5f48..2556c820373 100644 --- a/source/_components/notify.simplepush.markdown +++ b/source/_components/notify.simplepush.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Simplepush" -description: "Instructions how to add Simplepush notifications to Home Assistant." +description: "Instructions on how to add Simplepush notifications to Home Assistant." date: 2016-09-11 18:00 sidebar: true comments: false diff --git a/source/_components/notify.slack.markdown b/source/_components/notify.slack.markdown index 0445d1df821..3e384990109 100644 --- a/source/_components/notify.slack.markdown +++ b/source/_components/notify.slack.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Slack" -description: "Instructions how to add Slack notifications to Home Assistant." +description: "Instructions on how to add Slack notifications to Home Assistant." date: 2015-08-06 18:00 sidebar: true comments: false @@ -36,13 +36,13 @@ Configuration variables: - **name** (*Optional*): Setting the optional parameter `name` allows multiple notifiers to be created. The default value is `notify`. The notifier will bind to the service `notify.NOTIFIER_NAME`. - **api_key** (*Required*): The Slack API token to use for sending Slack messages. -- **default_channel** (*Required*): The default channel to post to if no channel is explicitly specified when sending the notification message. +- **default_channel** (*Required*): The default channel to post to if no channel is explicitly specified when sending the notification message. A channel can be specified adding a target attribute to the json at the same level as "message" - **username** (*Optional*): Setting username will allow Home Assistant to post to Slack using the username specified. By default not setting this will post to Slack using the user account or botname that you generated the api_key as. - **icon** (*Optional*): Use one of the Slack emojis as an Icon for the supplied username. Slack uses the standard emoji sets used [here](http://www.webpagefx.com/tools/emoji-cheat-sheet/). ### {% linkable_title Slack service data %} -The following attributes can be placed `data` for extended functionality. +The following attributes can be placed inside `data` for extended functionality. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | @@ -60,6 +60,7 @@ Example for posting file from URL: { "message":"Message that will be added as a comment to the file.", "title":"Title of the file.", + "target": ["#channelname"], "data":{ "file":{ "url":"http://[url to file, photo, security camera etc]", diff --git a/source/_components/notify.smtp.markdown b/source/_components/notify.smtp.markdown index 533129e36cb..130f3dcf0dc 100644 --- a/source/_components/notify.smtp.markdown +++ b/source/_components/notify.smtp.markdown @@ -1,7 +1,7 @@ --- layout: page title: "SMTP" -description: "Instructions how to add e-mail notifications to Home Assistant." +description: "Instructions on how to add e-mail notifications to Home Assistant." date: 2015-06-03 18:00 sidebar: true comments: false @@ -148,7 +148,7 @@ The optional `html` field makes a custom text/HTML multi-part message, allowing