-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! +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 884a5432fa..1f0df69183 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 586a035f8f..d894320ab0 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 ed65a626c7..123e975e97 100644 --- a/source/_addons/duckdns.markdown +++ b/source/_addons/duckdns.markdown @@ -10,12 +10,14 @@ 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"] @@ -24,10 +26,10 @@ featured: true Configuration variables: +- **lets_encrypt.accept_terms** (*Optional*): If you accept the [Let's Encrypt Subscriber Agreement][le], 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. +- **seconds** (*Required*): Seconds between updates to Duck DNS. [le]: https://letsencrypt.org/repository/ @@ -47,3 +49,7 @@ If you use a port other than `8123` or an SSL proxy, change the port number acco ## {% 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. + +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 126fab9c1a..bf8324628c 100644 --- a/source/_addons/git_pull.markdown +++ b/source/_addons/git_pull.markdown @@ -13,7 +13,7 @@ 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, "repeat": { "active": false, @@ -32,10 +32,12 @@ Load and update configuration files for Home Assistant from a GIT repository. } ``` -- **repository** (*Required*): GIT url to your repository. +- **repository** (*Required*): GIT url to your repository. You have to add .git to your GITHub-Repository-URL (see example Config) - **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. - **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 21c4c8b8af..f48415638e 100644 --- a/source/_addons/google_assistant.markdown +++ b/source/_addons/google_assistant.markdown @@ -11,7 +11,7 @@ featured: true ---- If you are wanting to integrate your Google Home, or mobile phone running Google Assistant, with Home Assistant then you want the [Google Assistant component](https://home-assistant.io/components/google_assistant/). + 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. @@ -19,8 +19,8 @@ featured: true 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`. @@ -52,9 +52,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 { @@ -66,14 +66,13 @@ 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 [DialogFlow component][comp] to integrate the add-on into Home Assistant. - [GoogleAssistant]: https://assistant.google.com/ [GoogleActions]: https://actions.google.com/ [Samba]: /addons/samba/ diff --git a/source/_addons/homematic.markdown b/source/_addons/homematic.markdown index aa1137abd0..6a92bbff81 100644 --- a/source/_addons/homematic.markdown +++ b/source/_addons/homematic.markdown @@ -9,9 +9,9 @@ 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. +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 exists configuration, you need new learn it into Home-Assistant. +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) @@ -42,13 +42,13 @@ Configuration variables: - **wired_enable** (*Require*): Boolean. Enable or disable BidCoS-Wired. For RF devices -- **type** (*Require*): Device type for RFD service. Look into handbook of your device. -- **device** (*Require*): Device on host. +- **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 device. +- **serial** (*Require*): Serial number of the device. - **key** (*Require*): Encrypted key. -- **ip** (*Require*): IP address of lan gateway. +- **ip** (*Require*): IP address of LAN gateway. ## {% linkable_title Home Assistant configuration %} @@ -57,14 +57,14 @@ Use the following configuration in Home Assistant to use it: ```yaml homematic: interfaces: - BidCoS-RF: + rf: host: core-homematic port: 2001 ``` ## {% linkable_title Raspberry Pi3 %} -With HM-MOD-PRI-PCB you need add follow into your `config.txt` on boot partition: +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 8917e007bf..0ac8d01994 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 b7882dd2c6..66df1440c6 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 5512542ed2..f143d9ac34 100644 --- a/source/_addons/mosquitto.markdown +++ b/source/_addons/mosquitto.markdown @@ -35,15 +35,15 @@ Make sure you use logins and disable anonymous access if you want to secure the 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 @@ -59,3 +59,20 @@ mqtt: 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 recommened that you only open your firewall to the SSL/TLS port (8883) and only use the insecure port (1883) for local devices. +
diff --git a/source/_addons/nginx_proxy.markdown b/source/_addons/nginx_proxy.markdown index 318b9768d9..e1d8a5f01c 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. +Setup 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 10aba2dcf5..a4d2d6689a 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 f6aff2fd92..9d0f18923f 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,10 @@ 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. diff --git a/source/_addons/snips.markdown b/source/_addons/snips.markdown index 954d04d613..851afd8e7d 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 an ssh key (enclosed in quotation marks, on a single line without line breaks) or set a password in the options section. ```json { @@ -39,7 +39,7 @@ After logging in, you will find yourself in this add-ons container. The Home Ass Configuration variables: -- **authorized_keys** (*Optional*): Your public keys for authorized keyfile. Every element will be a line inside that file. +- **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. diff --git a/source/_addons/tellstick.markdown b/source/_addons/tellstick.markdown index d75100774c..49764d93da 100644 --- a/source/_addons/tellstick.markdown +++ b/source/_addons/tellstick.markdown @@ -15,17 +15,17 @@ Setting up the [Tellstick](http://telldus.com) service and tools contained in th 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 has been made to the configuration you need to restart the add-on for the changes to take effect. +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*): This is 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 parameter model 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 selflearning etc. +- **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 house. -- **fade** (*Optional*): Fade is either `true` or `false` and tells a dimmer if is should fade smooth or instant between values (only for IKEA protocol as it seems). +- **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. @@ -37,16 +37,15 @@ You will need to add internal communication details to `configuration.yaml` to e tellstick: host: core-tellstick port: [50800, 50801] - + ``` -To add [lights](https://home-assistant.io/components/light.tellstick/), [sensors](https://home-assistant.io/components/sensor.tellstick/) and [switches](https://home-assistant.io/components/switch.tellstick/) you follow the guidelines for each type individually that is [described for Home Assistant](https://home-assistant.io/components/tellstick/) +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 tdtool via a Home Assistant services call, see example below for selflearning device. +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 @@ -74,11 +73,11 @@ Example for adding more devices in the add-on configuration (note the comma sepa ## Service calls -If you wish to teach a selflearning device in your TellStick configuration: +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: +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. @@ -90,14 +89,14 @@ You can also use this to list devices or sensors and read the output in the add- #### 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":"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":"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 normaly devices of ’selflearning’ type. ’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 3314bcc903..87b689230b 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 index cea2088d32..9e8463add0 100644 --- a/source/_components/ads.markdown +++ b/source/_components/ads.markdown @@ -53,7 +53,6 @@ The ADS component will register the service `write_by_name` allowing you to writ 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`. +- **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 99889db76d..588eb46f40 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 fec4f0cb3f..98810aaa2a 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 ebffcc5c0d..82e1a7774e 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 19294db81b..e47a6322d6 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,7 +13,6 @@ ha_release: 0.56 ha_iot_class: "Cloud Polling" --- - 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). @@ -28,11 +27,11 @@ alarm_control_panel: {% 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." + 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." + 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" @@ -75,4 +74,3 @@ Setting Arlo to a custom mode (mapped to `home_mode_name` in `configuration.yaml 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.concord232.markdown b/source/_components/alarm_control_panel.concord232.markdown index 8a9c00b7b3..36f897e21e 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,9 +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 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 https://github.com/JasonCarter80/concord232. +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 adviced 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 a 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 86509ebe62..feeda4b768 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 diff --git a/source/_components/alarm_control_panel.manual_mqtt.markdown b/source/_components/alarm_control_panel.manual_mqtt.markdown index 95fd3e09ff..5ceaa64e3a 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. @@ -58,7 +58,7 @@ The following configuration variables from the base manual alarm platform are av - **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](/component/alarm_control_panel.manual/) for a description. +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: diff --git a/source/_components/alarm_control_panel.markdown b/source/_components/alarm_control_panel.markdown index ba5f469915..bdc1adf398 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 7e6feaa7a2..cb93a1b595 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 0a14c880db..a98ad9050a 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 77752ae7d0..a5f8915d08 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 af38f6ad37..ac5c14183a 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 78e7066f00..5cc4025f00 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 668b749205..821d38075e 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 diff --git a/source/_components/alarm_control_panel.verisure.markdown b/source/_components/alarm_control_panel.verisure.markdown index 0c06294c3e..669de86761 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 032bbd3cb3..e6fee5cdb5 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 82beb4b5e6..8cfc24d215 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,4 @@ 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. diff --git a/source/_components/alert.markdown b/source/_components/alert.markdown index acdf983305..4c59259cde 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 diff --git a/source/_components/alexa.markdown b/source/_components/alexa.markdown index 6b1347a386..23c8bc9c86 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 @@ -21,6 +21,7 @@ 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. @@ -45,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: @@ -166,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 bba7b7ac78..93d192a00c 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.
@@ -92,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:
@@ -143,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 5105f19c4c..ca16dd32b7 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 479a771329..e82ade68d1 100644 --- a/source/_components/arlo.markdown +++ b/source/_components/arlo.markdown @@ -15,19 +15,27 @@ 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 +{% endconfiguration %} It is recommended to create a dedicated user on Arlo website to be used within Home Assistant and then share your Arlo cameras. diff --git a/source/_components/asterisk_mbox.markdown b/source/_components/asterisk_mbox.markdown index d0d7ba72fe..2361dfe0c9 100644 --- a/source/_components/asterisk_mbox.markdown +++ b/source/_components/asterisk_mbox.markdown @@ -1,31 +1,32 @@ --- 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" --- -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. diff --git a/source/_components/august.markdown b/source/_components/august.markdown new file mode 100644 index 0000000000..818002e14c --- /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/automation.markdown b/source/_components/automation.markdown index 181d28ba12..658c0ebc63 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/bbb_gpio.markdown b/source/_components/bbb_gpio.markdown
index ab6a13d94e..785aec4f2d 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 14e8e14533..def5cabb19 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.alarmdecoder.markdown b/source/_components/binary_sensor.alarmdecoder.markdown
index 1bfbd1be9f..92cfa7fa4e 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 80775c3b2e..0c5c2abbe8 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 a03c972e7b..d18a2d321a 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 0000000000..be793af19b
--- /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 77ece6d147..939cc8f76d 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
diff --git a/source/_components/binary_sensor.bayesian.markdown b/source/_components/binary_sensor.bayesian.markdown
index 0d2858e982..ad52a8e85f 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 fbe724abf1..be2a9bd9fb 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 0000000000..74330ec563
--- /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 f966144470..b37d6e40bb 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
diff --git a/source/_components/binary_sensor.concord232.markdown b/source/_components/binary_sensor.concord232.markdown
index 4378b5fb14..39320bb672 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 0000000000..f049948283
--- /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 b16dc68c5e..0000000000
--- 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 189c943bf9..25f58c42cb 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 0000000000..d418559f8e --- /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 fa949ae66e..cf9f2c52bf 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.envisalink.markdown b/source/_components/binary_sensor.envisalink.markdown index 6e56da0b94..52735a8dbf 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 453c76d7e0..6635bae9e6 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 16b1876143..d68ec7d163 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 558c30b3a0..3767ed7476 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 3be8c01304..80d828723b 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 ae37f2e979..7e93130271 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,37 @@ 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 -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 +86,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 62022aa898..49486d62d7 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 37140c8433..5155aedeea 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.http.markdown b/source/_components/binary_sensor.http.markdown index aaddf8a725..c2442aa881 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.ihc.markdown b/source/_components/binary_sensor.ihc.markdown new file mode 100644 index 0000000000..da5aac7615 --- /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 bd685df7c2..d06c324a44 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 diff --git a/source/_components/binary_sensor.isy994.markdown b/source/_components/binary_sensor.isy994.markdown index 1318ef67d1..2cb7345d0e 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 73c747601a..d51c9effbb 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.markdown b/source/_components/binary_sensor.markdown index 6b6d1d8c5d..fe8f4a5107 100644 --- a/source/_components/binary_sensor.markdown +++ b/source/_components/binary_sensor.markdown @@ -11,27 +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 -- **problem**: `On` means a problem was detected, `Off` means the status is OK +- **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.
+
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 0000000000..e3fd446a3b --- /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.random.markdown b/source/_components/binary_sensor.random.markdown index ea8de4b90c..b1208681a8 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 4815aa2de7..50d031c457 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 4739781d2f..d882e5b406 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 diff --git a/source/_components/binary_sensor.rfxtrx.markdown b/source/_components/binary_sensor.rfxtrx.markdown index c676c46cec..296af16317 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 diff --git a/source/_components/binary_sensor.rpi_gpio.markdown b/source/_components/binary_sensor.rpi_gpio.markdown index 99a7eda5eb..a59333d82c 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 84404f4d78..d02cfaf2da 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 84744aaa9e..5d879e4966 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 507f568dd9..624bebfff2 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.tapsaff.markdown b/source/_components/binary_sensor.tapsaff.markdown index b8e8636af6..233596e6bd 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 2a73bea7f4..fc0b988bbf 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 290e3af9bc..7cc7af6285 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 @@ -48,6 +48,10 @@ binary_sensor: description: Name to use in the frontend. required: false type: string + entity_id: + 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: description: The type/class of the sensor to set the icon in the frontend. required: false @@ -57,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 diff --git a/source/_components/binary_sensor.threshold.markdown b/source/_components/binary_sensor.threshold.markdown index c2e9e875b3..21cc02b9fd 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 41ac39437e..ae8e37c55a 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 @@ -23,7 +23,7 @@ binary_sensor: - platform: trend sensors: solar_angle: - entity_id: sun.sun + entity_id: sensor.cpu_speed ``` Configuration variables: @@ -59,7 +59,7 @@ binary_sensor: - platform: trend sensors: sun_rising: - entity_id: sun.sun + entity_id: sensor.cpu_speed ``` 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: diff --git a/source/_components/binary_sensor.upcloud.markdown b/source/_components/binary_sensor.upcloud.markdown new file mode 100644 index 0000000000..6cae22e876 --- /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.vera.markdown b/source/_components/binary_sensor.vera.markdown index f28c1978fa..d5e5d9fb14 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 026ad16ab4..1f9b9f0f4e 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 862a6b258e..1d23f5bf7c 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.workday.markdown b/source/_components/binary_sensor.workday.markdown index 3864850d14..1ba1f8bd8c 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,14 +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 ] + workdays: [mon, wed, fri] ``` Configuration variables: - **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.8.1) notation. -- **province** (*Optional*): Province code according to [holidays](https://pypi.python.org/pypi/holidays/0.8.1) notation. Defaults to None. +- **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`. @@ -37,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 a317550cbf..6f33659f78 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 @@ -30,7 +30,7 @@ The requirement is that you have setup the [`xiaomi aqara` component](/component | 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 (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` | diff --git a/source/_components/binary_sensor.zha.markdown b/source/_components/binary_sensor.zha.markdown index 755e4396ed..df5853d670 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 213721cb65..233ebb2a91 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 233411d4f2..85c4cc30bb 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 25ab683a22..90ebd17355 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 diff --git a/source/_components/bmw_connected_drive.markdown b/source/_components/bmw_connected_drive.markdown new file mode 100644 index 0000000000..94f493ff24 --- /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 c5fa4b424e..6325fef367 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 index 6ae9f8c36a..8ea6b6ad08 100644 --- a/source/_components/calendar.caldav.markdown +++ b/source/_components/calendar.caldav.markdown @@ -13,11 +13,11 @@ 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 10 minutes. +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 eventually credentials for it. This component was tested against [Baikal](http://sabre.io/baikal/) but any component complying with the RFC4791 should work. +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: @@ -29,13 +29,51 @@ $ sudo apt-get install libxml2-dev libxslt1-dev zlib1g-dev 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 @@ -51,7 +89,7 @@ password: type: string calendars: required: false - description: List of the calendars to filter. Empty or absent means no filtering. + 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 @@ -68,7 +106,7 @@ custom_calendars: type: string search: required: true - pending_charges: Regular expression for filtering the events + description: Regular expression for filtering the events based on the content of their summary, description or location. type: string {% endconfiguration %} @@ -83,17 +121,49 @@ custom_calendars: - **start_time**: Start time of event. - **end_time**: End time of event. -### {% linkable_title Sensor attributes %} +### {% linkable_title Examples %} +All events of the calendars "private" and "holidays". Note that all day events are not included. ```yaml -# Example configuration.yaml entry +# Example configuration.yaml entry for nextcloud calendar: - platform: caldav - url: https://baikal.my-server.net/cal.php/calendars/john.doe@test.com/default - username: john.doe@test.com + 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: 'HomeOffice' - calendar: 'Agenda' - search: 'HomeOffice' + - 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 658dae1f2b..9825c5f9cc 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 +minimum: + 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_availablilty**: (*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 f18e94902c..4b69b5e6fe 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 65401ebc64..c416ddb50d 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 a95b6d2fcf..2aa3da2313 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 2c1a042c87..73a6ca444f 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 04c6e41d8e..8aa3455faa 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 1d66a90bbf..a634e8d8d9 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 0000000000..660a9504c5 --- /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 23695c7905..ec725b06ec 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 8661690eb6..bd6f8a58b9 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 index bf7c029bc7..8e5f07f461 100644 --- a/source/_components/camera.canary.markdown +++ b/source/_components/camera.canary.markdown @@ -13,6 +13,20 @@ ha_release: "0.60" ha_iot_class: "Cloud Polling" --- -The `canary` camera platform allows you to view the latest camera image (triggered by motion) by your [Canary](https://canary.is) device in Home Assistant. +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/). +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 62395dc993..26eb74febc 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 55fcb419f8..ce23d94672 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.ffmpeg.markdown b/source/_components/camera.ffmpeg.markdown index 86e6355c8d..481c835a15 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 ea90a82984..c9d1aabd50 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 c6f41ac337..bec1ec5ffe 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 @@ -60,7 +60,7 @@ camera: ### {% linkable_title Local image with Hass.io %} -You can show an static image with this platform. Just place the image here: `/config/www/your_image.png` +You can show a static image with this platform. Just place the image here: `/config/www/your_image.png` ```yaml camera: @@ -68,3 +68,14 @@ camera: name: Some Image still_image_url: https://127.0.0.1:8123/local/your_image.png ``` + +### {% linkable_title Sharing a camera feed from one Home Assistant instance to another %} + +If you are running more than one Home Assistant instance (let's call them the 'host' and 'receiver' instances) you may wish to display the camera feed from the host instance on the receiver instance. You can use the [REST API](/developers/rest_api/#get-apicamera_proxycameraltentity_id) to access the camera feed on the host (IP address 127.0.0.5) and display it on the receiver instance by configuring the receiver with the the following: + +```yaml +camera: + - platform: generic + name: Host instance camera feed + still_image_url: https://127.0.0.5:8123/api/camera_proxy/camera.live_view +``` diff --git a/source/_components/camera.local_file.markdown b/source/_components/camera.local_file.markdown index 6dade4b4c5..b2b953041d 100644 --- a/source/_components/camera.local_file.markdown +++ b/source/_components/camera.local_file.markdown @@ -13,9 +13,9 @@ ha_iot_class: "Local Polling" ha_release: 0.22 --- -The `local_file` camera platform allows you to integrate any readable image file from disk into Home Assistant as a camera. If the image is updated on the file system the image displayed in Home Assistant will also be updated. +The `local_file` camera platform allows you to integrate an image file from disk into Home Assistant as a camera. If the image is updated on the file system the image displayed in Home Assistant will also be updated. The service `local_file_update_file_path` can be used to update the image using an automation. -This can for example be used with various camera platforms that save a temporary images locally. It can also be used to display a graph that you render periodically and will then be displayed in Home Assistant. +The `local_file` camera can for example be used with various camera platforms that save a temporary images locally. It can also be used to display a graph that you render periodically and will then be displayed in Home Assistant. To enable this camera in your installation, add the following to your `configuration.yaml` file: @@ -31,7 +31,11 @@ Configuration variables: - **file_path** (*Required*): File to serve as the camera. - **name** (*Optional*): Name of the camera --The given `file_path` must be an existing file because the camera platform setup make a readable check on it. -
+### {% linkable_title Service `camera.local_file_update_file_path` %} +Use this service to change the file displayed by the camera. + +| Service data attribute | Description | +| -----------------------| ----------- | +| `entity_id` | String of the `entity_id` of the camera to update. | +| `file_path` | The full path to the new image file to be displayed. | diff --git a/source/_components/camera.markdown b/source/_components/camera.markdown index 21629b68d8..8d3c12c7e6 100644 --- a/source/_components/camera.markdown +++ b/source/_components/camera.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Camera" -description: "Instructions how to integrate cameras within Home Assistant." +description: "Instructions on how to integrate cameras within Home Assistant." date: 2015-11-09 08:36 sidebar: true comments: false @@ -40,7 +40,7 @@ Take a snapshot from a camera. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | -| `entity_id` | no | Name(s) of entities to create a snopshot from, e.g., `camera.living_room_camera`. | +| `entity_id` | no | Name(s) of entities to create a snapshot from, e.g., `camera.living_room_camera`. | | `filename ` | no | Template of a file name. Variable is `entity_id`, e.g., {% raw %}`/tmp/snapshot_{{ entity_id }}`{% endraw %}. | The path part of `filename` must be an entry in the `whitelist_external_dirs` in your [`homeassistant:`](/docs/configuration/basic/) section of your `configuration.yaml` file. diff --git a/source/_components/camera.mjpeg.markdown b/source/_components/camera.mjpeg.markdown index 6a01c70872..de03528200 100644 --- a/source/_components/camera.mjpeg.markdown +++ b/source/_components/camera.mjpeg.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Generic MJPEG 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-11-09 08:36 sidebar: true comments: false diff --git a/source/_components/camera.mqtt.markdown b/source/_components/camera.mqtt.markdown index 852140ddf9..f0e903a37a 100644 --- a/source/_components/camera.mqtt.markdown +++ b/source/_components/camera.mqtt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MQTT Camera" -description: "Instructions how to use an MQTT image message as a Camera within Home Assistant." +description: "Instructions on how to use an MQTT image message as a Camera within Home Assistant." date: 2017-04-14 00:45 sidebar: true comments: false diff --git a/source/_components/camera.neato.markdown b/source/_components/camera.neato.markdown index 4fccb0b413..3b959c0bc3 100644 --- a/source/_components/camera.neato.markdown +++ b/source/_components/camera.neato.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Neato Camera" -description: "Instructions how to setup the Neato cleaning maps within Home Assistant." +description: "Instructions on how to setup the Neato cleaning maps within Home Assistant." date: 2017-04-05 13:10 sidebar: true comments: false diff --git a/source/_components/camera.nest.markdown b/source/_components/camera.nest.markdown index e597fcb19d..607a88c516 100644 --- a/source/_components/camera.nest.markdown +++ b/source/_components/camera.nest.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Nest Camera" -description: "Instructions how to integrate Nest cameras into Home Assistant." +description: "Instructions on how to integrate Nest cameras into Home Assistant." date: 2016-12-03 08:10 sidebar: true comments: false diff --git a/source/_components/camera.netatmo.markdown b/source/_components/camera.netatmo.markdown index 5ad8ebe38e..e452d26b41 100644 --- a/source/_components/camera.netatmo.markdown +++ b/source/_components/camera.netatmo.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Netatmo Camera" -description: "Instructions how to integrate Netatmo cameras into Home Assistant." +description: "Instructions on how to integrate Netatmo cameras into Home Assistant." date: 2016-06-02 08:10 sidebar: true comments: false diff --git a/source/_components/camera.onvif.markdown b/source/_components/camera.onvif.markdown index 9c48b6b424..ed01e31d37 100644 --- a/source/_components/camera.onvif.markdown +++ b/source/_components/camera.onvif.markdown @@ -30,7 +30,21 @@ Configuration variables: - **name** (*Optional*): Override the name of your camera. - **username** (*Optional*): The username for the camera. - **password** (*Optional*): The password for the camera. -- **port** (*Optional*): The port for the camera. This defaults to 5000 +- **port** (*Optional*): The port for the camera. This defaults to 5000. +- **profile** (*Optional*): Video profile that will be used to obtain the stream. This defaults to 0. More details below. +- **extra_arguments** (*Optional*): Extra options to pass to `ffmpeg`, e.g., image quality or video filter options. More details in [FFmpeg component](/components/ffmpeg). +Most of the Onvif cameras support more than one audio/video Profile. Each profile provides different image quality. Usually, the first profile has the highest quality, and it is the profile used by default. However, you may want to use a lower quality image. One of the reasons may be that your hardware isn't able to render the highest quality image in real-time - especially when running on Raspberry Pi. Therefore you can choose which profile do you want to use by setting in config `profile` variable. + +### {% linkable_title Service `camera.onvif_ptz` %} + +If your ONVIF camera supports PTZ, you will be able to pan, tilt or zoom your camera. + +| Service data attribute | Description | +| -----------------------| ----------- | +| `entity_id` | String or list of strings that point at `entity_id`s of cameras. Else targets all. +| `tilt` | Tilt direction. Allowed values: `UP`, `DOWN` +| `pan` | Pan direction. Allowed values: `RIGHT`, `LEFT` +| `zoom` | Zoom. Allowed values: `ZOOM_IN`, `ZOOM_OUT` If you are running into trouble with this sensor, please refer to the [Troubleshooting section](/components/ffmpeg/#troubleshooting). diff --git a/source/_components/camera.proxy.markdown b/source/_components/camera.proxy.markdown new file mode 100644 index 0000000000..e8a38d4b23 --- /dev/null +++ b/source/_components/camera.proxy.markdown @@ -0,0 +1,90 @@ +--- +layout: page +title: "Camera Proxy" +description: "Instructions on how to integrate a camera proxy within Home Assistant." +date: 2018-03-08 19:00 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Camera +ha_release: 0.65 +--- + + +The `proxy` camera platform allows you to pass another camera's output through post-processing routines and generate a new camera with the post-processed output. + +The current post-processing supports resizing the image/MJPEG as well as limiting the maximum refresh rate. + +The current proxy capabilities are intended to reduce the camera bandwidth for slower internet connections. + +To enable this camera in your installation, you must first have an existing working camera configured in Home Assistant. Next, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +camera: + - platform: proxy + entity_id: camera.+Currently, version 0.1.4-beta2 of the custom firmware is the highest supported. Firmwares higher than this version use [Pure-FTPd](https://www.pureftpd.org/project/pure-ftpd), which has a bug that prevents FFmpeg from correctly rendering video files. +
+ ++Hassbian users: don't forget to install ffmpeg support on your platform, otherwise, you'll not see video. +
+Some alternative Yi firmwares enable an experimental RTSP server, which will allow you to connect to your camera via other Home Assistant camera platforms. However, this RTSP server disables the ability to use the supremely-useful Yi Home app. In order to maintain both Home Assistant compatibility _and_ the native app, this platform retrieves videos via FTP.
@@ -64,7 +72,7 @@ Configuration variables: - **password** (*Required*): The password to the FTP server on the camera (from above). - **path** (*Optional*): The path to the raw MP4 files. Defaults to `/tmp/sd/record`. - **username** (*Optional*): The user that can access the FTP server. Defaults to `root`. -- **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). ## {% linkable_title Image quality %} diff --git a/source/_components/canary.markdown b/source/_components/canary.markdown index 425055f48a..186d704e17 100644 --- a/source/_components/canary.markdown +++ b/source/_components/canary.markdown @@ -15,6 +15,8 @@ ha_iot_class: "Cloud Polling" The `canary` component allows you to integrate your [Canary](https://canary.is) devices in Home Assistant. +## {% linkable_title Configuration %} + You will need your Canary login information (username, usually your email address, and password) to use this module. To set it up, add the following to your `configuration.yaml` file: @@ -22,8 +24,8 @@ To set it up, add the following to your `configuration.yaml` file: ```yaml # Example configuration.yaml entry canary: - username: you@example.com - password: secret + username: YOUR_USERNAME + password: YOUR_PASSWORD ``` {% configuration %} @@ -42,8 +44,6 @@ canary: default: 10 {% endconfiguration %} - - Once loaded, your front end will have the following components: * A camera image triggered by motion for each camera. diff --git a/source/_components/climate.daikin.markdown b/source/_components/climate.daikin.markdown new file mode 100644 index 0000000000..2201872a15 --- /dev/null +++ b/source/_components/climate.daikin.markdown @@ -0,0 +1,51 @@ +--- +layout: page +title: "Daikin AC" +description: "Instructions on how to integrate Daikin AC(s) with Home Assistant." +date: 2017-12-03 05:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: daikin.png +ha_category: Climate +ha_release: 0.59 +ha_iot_class: "Local Polling" +--- + + +The `daikin` climate platform integrates Daikin air conditioning systems into Home Assistant, enabling control of setting the following parameters: + +- **mode** (cool, heat, dry, fan only or auto) +- **fan speed** (on supported models) +- **target temperature** +- **swing mode** (on supported models) + +Current temperature is displayed. + ++Please note, the `daikin` platform integrates **ONLY the european versions of Daikin ACs (models BRP069A41, 42, 43, 45)** into Home Assistant. BRP069A42 does not support setting of fan speed or fan swing mode. +
+ +The platform has been integrated with discovery so all your Daikin AC's climate devices can be automatically discovered. + +To enable the platform, add the following lines to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +climate: + - platform: daikin + host: 10.0.0.1 +``` + +{% configuration %} +host: + description: IP or hostname of the device. + required: true + type: string +name: + description: If the device has a name previously set by the user than that name will be used. + required: false + type: string +{% endconfiguration %} + diff --git a/source/_components/climate.ecobee.markdown b/source/_components/climate.ecobee.markdown index 4c06cbbf90..b92b001f37 100644 --- a/source/_components/climate.ecobee.markdown +++ b/source/_components/climate.ecobee.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Ecobee Thermostat" -description: "Instructions how to setup the Ecobee thermostats within Home Assistant." +description: "Instructions on how to setup the Ecobee thermostats within Home Assistant." date: 2016-08-26 18:00 sidebar: true comments: false @@ -240,7 +240,7 @@ For 'temp', the current temperature is taken as the target temperature. When None is provided as parameter, the hold_mode is turned off. It is not possible to set a vacation hold; such hold has to be defined on the thermostat directly. However, a vacation hold can be -cancelled. +canceled. | Service data attribute | Optional | Description | | ---------------------- | -------- | ----------- | diff --git a/source/_components/climate.econet.markdown b/source/_components/climate.econet.markdown new file mode 100644 index 0000000000..704c6ebf0e --- /dev/null +++ b/source/_components/climate.econet.markdown @@ -0,0 +1,64 @@ +--- +layout: page +title: "EcoNet water heater" +description: "Instructions on how to integrate Rheem EcoNet water heaters into Home Assistant." +date: 2017-12-28 14:51 +sidebar: true +comments: false +sharing: true +footer: true +logo: econet.png +ha_category: Climate +ha_release: 0.61.0 +ha_iot_class: "Cloud Polling" +--- + + +The `econet` water heater platform is consuming the information provided by a [EcoNet enabled Rheem water heater](http://www.rheem.com/EcoNet/Home). This component allows you to set the temperature, the operation mode, and enable vaction mode. + +To enable the `econet` water heater platform add the following to your config. + + +```yaml +# Example configuration.yaml entry +climate: + - platform: econet + username: YOUR_ECONET_EMAIL + password: YOUR_ECONET_PASSWORD +``` + +{% configuration %} +username: + description: The username used to connect to your EcoNet account. + required: true + type: string +password: + description: The password used to connect to your EcoNet account. + required: true + type: string +{% endconfiguration %} + + +### {% linkable_title Service `econet_add_vacation` %} + +You can use the service econet/add_vacation to create a new vacation for your EcoNet water heaters. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | yes | The entity id of the water heater to add the vaction to. +| `start_date` | yes | This is a Unix timestamp for when the vaction should start. +| `end_date` | yes | this is a Unix timestamp for when the vaction should end. + ++The Unix timestamps can be obtained from the input_datetime component. This will allow you to graphically set the start and end date. +
+ +### {% linkable_title Service `econet_delete_vacation` %} + +You can use the service econet/delete_vacation to remove all vactions from an EcoNet water heater. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | yes | The entity id of the water heater to remove the vaction from. + + diff --git a/source/_components/climate.eq3btsmart.markdown b/source/_components/climate.eq3btsmart.markdown index 5cfa52ae40..ce833566ff 100644 --- a/source/_components/climate.eq3btsmart.markdown +++ b/source/_components/climate.eq3btsmart.markdown @@ -1,7 +1,7 @@ --- layout: page title: "EQ3 Bluetooth Smart Thermostats" -description: "Instructions how to integrate EQ3 Bluetooth Smart Thermostats into Home Assistant." +description: "Instructions on how to integrate EQ3 Bluetooth Smart Thermostats into Home Assistant." date: 2016-04-18 22:00 sidebar: true comments: false diff --git a/source/_components/climate.flexit.markdown b/source/_components/climate.flexit.markdown index 078b840985..0281b50756 100644 --- a/source/_components/climate.flexit.markdown +++ b/source/_components/climate.flexit.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Flexit A/C controller" -description: "Instructions how to integrate Flexit A/C unit into Home Assistant." +description: "Instructions on how to integrate Flexit A/C unit into Home Assistant." date: 2017-06-02 16:30 +0200 sidebar: true comments: false diff --git a/source/_components/climate.fritzbox.markdown b/source/_components/climate.fritzbox.markdown new file mode 100644 index 0000000000..65975ca77c --- /dev/null +++ b/source/_components/climate.fritzbox.markdown @@ -0,0 +1,28 @@ +--- +layout: page +title: "Fritzbox Thermostat" +description: "Instructions on how to integrate the AVM Fritzbox thermostat." +date: 2017-11-12 17:10 +sidebar: true +comments: false +sharing: true +footer: true +logo: avm.png +ha_category: Climate +ha_release: 0.68 +ha_iot_class: "Local Polling" +--- + ++To get AVM fritzbox thermostat follow the instructions for the general [Fritzbox](/components/fritzbox/). +
+ +### {% linkable_title Attributes %} + +The are several attributes that can be useful for automations and templates. + +| Attribute | Description | +| --------- | ----------- | +| `device_locked` | The state of the key lock at the device. +| `locked` | The state of the lock for configuring the device via the app or the Fritzbox web interface. +| `low_battery` | The low battery state indication. diff --git a/source/_components/climate.generic_thermostat.markdown b/source/_components/climate.generic_thermostat.markdown index 180f67f04e..19e1a1f1cd 100644 --- a/source/_components/climate.generic_thermostat.markdown +++ b/source/_components/climate.generic_thermostat.markdown @@ -14,7 +14,7 @@ ha_iot_class: "Local Polling" --- -The `generic_thermostat` climate platform is a thermostat implemented in Home Assistant. It uses a sensor and a switch connected to a heater under the hood. If the measured temperature is cooler then the target temperature, the heater will be turned on and turned off when required temperature is reached. +The `generic_thermostat` climate platform is a thermostat implemented in Home Assistant. It uses a sensor and a switch connected to a heater or air conditioning under the hood. When in heater mode, if the measured temperature is cooler then the target temperature, the heater will be turned on and turned off when the required temperature is reached. When in air conditioning mode, if the measured temperature is hotter then the target temperature, the air conditioning will be turned on and turned off when required temperature is reached. ```yaml # Example configuration.yaml entry @@ -28,20 +28,25 @@ climate: Configuration variables: - **name** (*Required*): Name of thermostat -- **heater** (*Required*): `entity_id` for heater switch, must be a toggle device. +- **heater** (*Required*): `entity_id` for heater switch, must be a toggle device. Becomes air conditioning switch when `ac_mode` is set to `True` - **target_sensor** (*Required*): `entity_id` for a temperature sensor, target_sensor.state must be temperature. - **min_temp** (*Optional*): Set minimum set point available (default: 7) - **max_temp** (*Optional*): Set maximum set point available (default: 35) -- **target_temp** (*Optional*): Set initial target temperature. Failure to set this variable will result in target temperature being set to null on startup. As of version 0.59 it will retain the target temperature set before restart if this variable is not configured. +- **target_temp** (*Optional*): Set initial target temperature. Failure to set this variable will result in target temperature being set to null on startup. As of version 0.59, it will retain the target temperature set before restart if available. - **ac_mode** (*Optional*): Set the switch specified in the *heater* option to be treated as a cooling device instead of a heating device. - **min_cycle_duration** (*Optional*): Set a minimum amount of time that the switch specified in the *heater* option must be in it's current state prior to being switched either off or on. - **cold_tolerance** (*Optional*): Set a minimum amount of difference between the temperature read by the sensor specified in the *target_sensor* option and the target temperature that must change prior to being switched on. For example, if the target temperature is 25 and the tolerance is 0.5 the heater will start when the sensor equals or goes below 24.5. - **hot_tolerance** (*Optional*): Set a minimum amount of difference between the temperature read by the sensor specified in the *target_sensor* option and the target temperature that must change prior to being switched off. For example, if the target temperature is 25 and the tolerance is 0.5 the heater will stop when the sensor equals or goes above 25.5. -- **keep_alive** (*Optional*): Set a keep-alive interval. If set, the switch specified in the *heater* option will be triggered every time the interval elapses. Use with heaters and A/C units that shut off if they don't receive a signal from their remote for a while. +- **keep_alive** (*Optional*): Set a keep-alive interval. If set, the switch specified in the *heater* option will be triggered every time the interval elapses. Use with heaters and A/C units that shut off if they don't receive a signal from their remote for a while. Use also with switches that might lose state. The keep-alive call is done with the current valid climate component state (either on or off). - **initial_operation_mode** (*Optional*): Set the initial operation mode. Valid values are `off` or `auto`. Value has to be double quoted. If this parameter is not set, it is preferable to set a *keep_alive* value. This is helpful to align any discrepancies between *generic_thermostat* and *heater* state. +- **away_temp** (*Optional*): Set the temperature used by "away_mode". If this is not specified, away_mode feature will not get activated. A full configuration example looks like the one below. `min_cycle_duration` and `keep_alive` must contain at least one of the following entries: `days:`, `hours:`, `minutes:`, `seconds:` or `milliseconds:`. +Currently the `generic_thermostat` climate platform supports 'heat', 'cool' and 'off' operation modes. You can force your `generic_thermstat` to avoid starting by setting Operation to 'off'. + +Please note that changing Away Mode you will force a target temperature change as well that will get restored once the Away Mode is turned off. + ```yaml # Full example configuration.yaml entry climate: @@ -51,6 +56,7 @@ climate: target_sensor: sensor.study_temperature min_temp: 15 max_temp: 21 + ac_mode: False target_temp: 17 cold_tolerance: 0.3 hot_tolerance: 0 @@ -59,4 +65,5 @@ climate: keep_alive: minutes: 3 initial_operation_mode: "off" + away_temp: 16 ``` diff --git a/source/_components/climate.heatmiser.markdown b/source/_components/climate.heatmiser.markdown index b772e9923b..b1478034e9 100644 --- a/source/_components/climate.heatmiser.markdown +++ b/source/_components/climate.heatmiser.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Heatmiser Thermostat" -description: "Instructions how to integrate Heatmiser thermostats within Home Assistant." +description: "Instructions on how to integrate Heatmiser thermostats within Home Assistant." date: 2015-12-11 12:35 sidebar: true comments: false diff --git a/source/_components/climate.hive.markdown b/source/_components/climate.hive.markdown index a6c40b1462..12f4688553 100644 --- a/source/_components/climate.hive.markdown +++ b/source/_components/climate.hive.markdown @@ -14,12 +14,15 @@ ha_iot_class: "Cloud Polling" --- -The 'hive' climate component integrates your Hive thermostat and hot water into Home Assistant, enabling control of setting the **mode** and setting the **target temperature**. +The `hive` climate platform integrates your Hive thermostat and hot water into Home Assistant, enabling control of setting the **mode** and setting the **target temperature**. -The Hive climate component supports the following Hive products: -- **Hive Active Heating** -- **Hive Multizone** -- **Hot water control** +A short boost for Hive Heating or Hive Hot water can be set by using the **Aux Heat** function, this will turn on the boost feature for Hive Heating or Hive Hot water for 30 minutes at 0.5 degrees higher than the current temperature. + +The platform supports the following Hive products: + +- Hive Active Heating +- Hive Multizone +- Hot water controldiff --git a/source/_components/climate.homematic.markdown b/source/_components/climate.homematic.markdown index ac5458d592..86e38fdb49 100644 --- a/source/_components/climate.homematic.markdown +++ b/source/_components/climate.homematic.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Homematic Thermostats" -description: "Instructions how to integrate Homematic thermostats within Home Assistant." +description: "Instructions on how to integrate Homematic thermostats within Home Assistant." date: 2016-06-28 08:30 sidebar: true comments: false diff --git a/source/_components/climate.honeywell.markdown b/source/_components/climate.honeywell.markdown index 8a50fc5dd6..855d009cda 100644 --- a/source/_components/climate.honeywell.markdown +++ b/source/_components/climate.honeywell.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Honeywell Thermostat" -description: "Instructions how to integrate Honeywell thermostats within Home Assistant." +description: "Instructions on how to integrate Honeywell thermostats within Home Assistant." date: 2016-02-07 22:01 sidebar: true comments: false @@ -36,5 +36,5 @@ Configuration variables: - **region** (*Optional*): Region identifier (either 'eu' or 'us'). Defaults to 'eu' if not provided. - **scan_interval**(*Optional*): Scan interval is expressed in seconds. Recommended value of 600 seconds. Default value is 120 seconds. Omitting scan_interval may result in too-frequent polling and cause you to rate-limited by Honeywell. - **away_temperature** (*Optional*) (*only for eu region*): Heating setpoint when away mode is on. If omitted it defaults to 16.0 deg C. -- **cool_away_temperature** (*Optional*) (*only for us region*): Cooling setpoint when away mode is on. If omitted it defaults to 30.0 deg C. -- **heat_away_temperature** (*Optional*) (*only for us region*): Heating setpoint when away mode is on. If omitted it defaults to 16.0 deg C. +- **away_cool_temperature** (*Optional*) (*only for us region*): Cooling setpoint when away mode is on. If omitted it defaults to 30.0 deg C. +- **away_heat_temperature** (*Optional*) (*only for us region*): Heating setpoint when away mode is on. If omitted it defaults to 16.0 deg C. diff --git a/source/_components/climate.markdown b/source/_components/climate.markdown index ce47cc8a3c..fd41b437cd 100644 --- a/source/_components/climate.markdown +++ b/source/_components/climate.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Climate" -description: "Instructions how to setup climate control devices within Home Assistant." +description: "Instructions on how to setup climate control devices within Home Assistant." date: 2016-08-26 19:00 sidebar: true comments: false @@ -23,7 +23,7 @@ climate: ## {% linkable_title Services %} ### {% linkable_title Climate control services %} -Available services: `climate.set_aux_heat`, `climate.set_away_mode`, `climate.set_temperature`, `climate.set_humidity`, `climate.set_fan_mode`, `climate.set_operation_mode`, `climate.set_swing_mode`, `climate.set_hold_mode` +Available services: `climate.set_aux_heat`, `climate.set_away_mode`, `climate.set_temperature`, `climate.set_humidity`, `climate.set_fan_mode`, `climate.set_operation_mode`, `climate.set_swing_mode`, `climate.set_hold_mode`, `climate.turn_on`, `climate.turn_off`
Not all climate services may be available for your platform. Be sure to check the available services Home Assistant has enabled by checking 
**Services**.
@@ -222,6 +222,22 @@ automation:
entity_id: climate.kitchen
swing_mode: 1
```
+### {% linkable_title Service `climate.turn_on` %}
+
+Turn climate device on
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Targets all when omitted.
+
+### {% linkable_title Service `climate.turn_off` %}
+
+Turn climate device off
+
+| Service data attribute | Optional | Description |
+| ---------------------- | -------- | ----------- |
+| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Targets all when omitted.
+
#### {% linkable_title Customization %}
The step for the setpoint can be adjusted (default to 0,5 increments) by adding the following line into configuration
diff --git a/source/_components/climate.melissa.markdown b/source/_components/climate.melissa.markdown
new file mode 100644
index 0000000000..9d648a83b5
--- /dev/null
+++ b/source/_components/climate.melissa.markdown
@@ -0,0 +1,20 @@
+---
+layout: page
+title: "Melissa Climate"
+description: "Instructions on how to integrate Melissa climate system (HVAC) into Home Assistant."
+date: 2018-01-08 20:21
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: mclimate.png
+ha_category: Climate
+ha_iot_class: "Cloud Polling"
+ha_release: 0.63
+---
+
+The `Melissa` climate platform allows you to control your [Melissa Climate](http://seemelissa.com/) from within Home Assistant.
+
+The climate platform will be automatically configured if Melissa component is configured.
+
+For more configuration information see the [Melissa component](/components/melissa/) documentation.
diff --git a/source/_components/climate.modbus.markdown b/source/_components/climate.modbus.markdown
new file mode 100644
index 0000000000..eeb376ef8e
--- /dev/null
+++ b/source/_components/climate.modbus.markdown
@@ -0,0 +1,71 @@
+---
+layout: page
+title: "Modbus"
+description: "Instructions how to integrate a Modbus thermostat within Home Assistant."
+date: 2018-01-29 9:35
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: modbus.png
+ha_category: Thermostat
+ha_release: 0.68
+ha_iot_class: "Local Polling"
+---
+
+
+The `modbus` thermostat allows you to use a sensor value (current temperature) and target value (target temperature) from [Modbus](http://www.modbus.org/) registers.
+
+## {% linkable_title Configuration %}
+
+To use your Modbus thermostat in your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+climate:
+ - platform: modbus
+ name: Watlow F4T
+ slave: 1
+ target_temp_register: 2782
+ current_temp_register: 27586
+```
+
+{% configuration %}
+name:
+ description: Name of the device
+ required: true
+ type: string
+slave:
+ description: The number of the slave (Optional for tcp and upd Modbus, use 1).
+ required: true
+ type: int
+target_temp_register:
+ description: Register number for target temperature (Setpoint).
+ required: true
+ type: int
+current_temp_register:
+ description: Register number for current temperature (Process value).
+ required: true
+ type: int
+data_type:
+ description: Response representation (int, uint, float, custom). If float selected, value will converted to IEEE 754 floating point format.
+ required: false
+ type: string
+ default: float
+count:
+ description: Number of registers to read.
+ required: false
+ type: int
+precision:
+ description: Number of valid decimals.
+ required: false
+ type: int
+ default: 0
+{% endconfiguration %}
+
+
+### {% linkable_title Services %}
+
+| Service | Description |
+| ------- | ----------- |
+| set_temperature | Set Temperature. Requires `value` to be passed in, which is the desired target temperature. `value` should be in the same type as `data_type` |
diff --git a/source/_components/climate.mqtt.markdown b/source/_components/climate.mqtt.markdown
index 94a9bf27e7..958974869a 100644
--- a/source/_components/climate.mqtt.markdown
+++ b/source/_components/climate.mqtt.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "MQTT HVAC"
-description: "Instructions how to integrate MQTT HVAC into Home Assistant."
+description: "Instructions on how to integrate MQTT HVAC into Home Assistant."
date: 2017-07-31 19:59
sidebar: true
comments: false
@@ -28,38 +28,181 @@ climate:
temperature_command_topic: /sensors/hvac_study/target_temp
```
-Configuration variables *except* for MQTT topics:
+{% configuration %}
+name:
+ description: The name of the HVAC.
+ required: false
+ type: string
+ default: MQTT HVAC
+qos:
+ description: The maximum QoS level to be used when receiving and publishing messages.
+ required: false
+ type: integer
+ default: 0
+retain:
+ description: Defines if published messages should have the retain flag set.
+ required: false
+ type: boolean
+ default: false
+send_if_off:
+ description: "Set to `false` to suppress sending of all MQTT messages when the current mode is `Off`."
+ required: false
+ type: boolean
+ default: true
+initial:
+ description: Set the initial target temperature.
+ required: false
+ type: number
+ default: 21
+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
+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
+value_template:
+ description: Default template to render the payloads on *all* `*_state_topic`s with.
+ type: template
+ required: false
+current_temperature_topic:
+ description: The MQTT topic on which to listen for the current temperature.
+ required: false
+ type: string
+power_command_topic:
+ description: The MQTT topic to publish commands to change the power state. This is useful if your device has a separate power toggle in addition to mode.
+ required: false
+ type: string
+mode_command_topic:
+ description: The MQTT topic to publish commands to change the HVAC operation mode.
+ required: false
+ type: string
+mode_state_topic:
+ description: The MQTT topic to subscribe for changes of the HVAC operation mode. If this is not set, the operation mode works in optimistic mode (see below).
+ required: false
+ type: string
+mode_state_template:
+ description: A template to render the value received on the `mode_state_topic` with.
+ required: false
+ type: template
+temperature_command_topic:
+ description: The MQTT topic to publish commands to change the target temperature.
+ required: false
+ type: string
+temperature_state_topic:
+ description: The MQTT topic to subscribe for changes in the target temperature. If this is not set, the target temperature works in optimistic mode (see below).
+ required: false
+ type: string
+temperature_state_template:
+ description: A template to render the value received on the `temperature_state_topic` with.
+ required: false
+ type: template
+fan_mode_command_topic:
+ description: The MQTT topic to publish commands to change the fan mode.
+ required: false
+ type: string
+fan_mode_state_topic:
+ description: The MQTT topic to subscribe for changes of the HVAC fan mode. If this is not set, the fan mode works in optimistic mode (see below).
+ required: false
+ type: string
+fan_mode_state_template:
+ description: A template to render the value received on the `fan_mode_state_topic` with.
+ required: false
+ type: template
+swing_mode_command_topic:
+ description: The MQTT topic to publish commands to change the swing mode.
+ required: false
+ type: string
+swing_mode_state_topic:
+ description: The MQTT topic to subscribe for changes of the HVAC swing mode. If this is not set, the swing mode works in optimistic mode (see below).
+ required: false
+ type: string
+swing_mode_state_template:
+ description: A template to render the value received on the `swing_mode_state_topic` with.
+ required: false
+ type: template
+away_mode_command_topic:
+ description: The MQTT topic to publish commands to change the away mode.
+ required: false
+ type: string
+away_mode_state_topic:
+ description: The MQTT topic to subscribe for changes of the HVAC away mode. If this is not set, the away mode works in optimistic mode (see below).
+ required: false
+ type: string
+away_mode_state_template:
+ description: A template to render the value received on the `away_mode_state_topic` with.
+ required: false
+ type: template
+hold_command_topic:
+ description: The MQTT topic to publish commands to change the hold mode.
+ required: false
+ type: string
+hold_state_topic:
+ description: The MQTT topic to subscribe for changes of the HVAC hold mode. If this is not set, the hold mode works in optimistic mode (see below).
+ required: false
+ type: string
+hold_state_template:
+ description: A template to render the value received on the `hold_state_topic` with.
+ required: false
+ type: template
+aux_command_topic:
+ description: The MQTT topic to publish commands to switch auxiliary heat.
+ required: false
+ type: string
+aux_state_topic:
+ description: The MQTT topic to subscribe for changes of the auxiliary heat mode. If this is not set, the auxiliary heat mode works in optimistic mode (see below).
+ required: false
+ type: string
+aux_state_template:
+ description: A template to render the value received on the `aux_state_topic` with.
+ required: false
+ type: template
+{% endconfiguration %}
-- **name** (*Required*): Name of MQTT HVAC.
-- **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.
-- **send_if_off** (*Optional*): Set to `false` to suppress sending of all MQTT messages when the current mode is `Off`. Defaults to `true`.
-- **initial** (*Optional*): Set the initial target temperature. Defaults to 21 degrees.
-- **payload_on** (*Optional*): For MQTT topics that control an `on` / `off` value (e.g., `aux_command_topic`), set the value that should be sent for `on`. Defaults to 'ON'.
-- **payload_off** (*Optional*): For MQTT topics that control an `on` / `off` value (e.g., `aux_command_topic`), set the value that should be sent for `off`. Defaults to 'OFF'.
+#### {% linkable_title Optimistic mode %}
-Configuration of the MQTT topics:
+If a property works in *optimistic mode* (when the corresponding state topic is not set), Home Assistant will assume that any state changes published to the command topics did work and change the internal state of the entity immediately after publishing to the command topic. If it does not work in optimistic mode, the internal state of the entity is only updated when the requested update is confirmed by the device through the state topic.
-- **current_temperature_topic** (*Optional*): The MQTT topic on which to listen for the current temperature
-- **power_command_topic** (*Optional*): The MQTT topic to publish commands to change the power state. This is useful if your device has a separate power toggle in addition to mode.
-- **mode_command_topic** (*Optional*): The MQTT topic to publish commands to change the HVAC operation mode.
-- **mode_state_topic** (*Optional*): The MQTT topic to subscribe for changes of the HVAC operation mode. If this is not set, the operation mode works in optimistic mode (see below).
-- **temperature_command_topic** (*Optional*): The MQTT topic to publish commands to change the target temperature.
-- **temperature_state_topic** (*Optional*): The MQTT topic to subscribe for changes in the target temperature. If this is not set, the target temperature works in optimistic mode (see below).
-- **fan_mode_command_topic** (*Optional*): The MQTT topic to publish commands to change the fan mode.
-- **fan_mode_state_topic** (*Optional*): The MQTT topic to subscribe for changes of the HVAC fan mode. If this is not set, the fan mode works in optimistic mode (see below).
-- **swing_mode_command_topic** (*Optional*): The MQTT topic to publish commands to change the swing mode.
-- **swing_mode_state_topic** (*Optional*): The MQTT topic to subscribe for changes of the HVAC swing mode. If this is not set, the swing mode works in optimistic mode (see below).
-- **away_mode_command_topic** (*Optional*): The MQTT topic to publish commands to change the away mode.
-- **away_mode_state_topic** (*Optional*): The MQTT topic to subscribe for changes of the HVAC away mode. If this is not set, the away mode works in optimistic mode (see below).
-- **hold_command_topic** (*Optional*): The MQTT topic to publish commands to change the hold mode.
-- **hold_state_topic** (*Optional*): The MQTT topic to subscribe for changes of the HVAC hold mode. If this is not set, the hold mode works in optimistic mode (see below).
-- **aux_command_topic** (*Optional*): The MQTT topic to publish commands to switch auxiliary heat.
-- **aux_state_topic** (*Optional*): The MQTT topic to subscribe for changes of the auxiliary heat mode. If this is not set, the auxiliary heat mode works in optimistic mode (see below).
+#### {% linkable_title Using Templates %}
-#### Optimistic mode
+For all `*_state_topic`s, a template can be specified that will be used to render the incoming payloads on these topics. Also, a default template that applies to all state topis can be specified as `value_template`. This can be useful if you received payloads are e.g., in JSON format. Since in JSON, a quoted string (e.g., `"foo"`) is just a string, this can also be used for unquoting.
+
+Say you receive the operation mode `"auto"` via your `mode_state_topic`, but the mode is actually called just `auto`, here's what you could do:
+
+{% raw %}
+```yaml
+climate:
+ - platform: mqtt
+ name: Study
+ modes:
+ - off
+ - on
+ - auto
+ mode_command_topic: "study/ac/mode/set"
+ mode_state_topic: "study/ac/mode/state"
+ mode_state_template: "{{ value_json }}"
+```
+{% endraw %}
+
+This will parse the incoming `"auto"` as JSON, resulting in `auto`. Obviously, in this case you could also just set `value_template: {% raw %}"{{ value_json }}"{% endraw %}`.
-If a property works in *optimistic mode* (when the corresponding state topic is not set), home assistant will assume that any state changes published to the command topics did work and change the internal state of the entity immediately after publishing to the command topic. If it does not work in optimistic mode, the internal state of the entity is only updated when the requested update is confirmed by the device through the state topic.
### {% linkable_title Example %}
diff --git a/source/_components/climate.mysensors.markdown b/source/_components/climate.mysensors.markdown
index a61fae33f9..6f5379449b 100644
--- a/source/_components/climate.mysensors.markdown
+++ b/source/_components/climate.mysensors.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "MySensors HVAC"
-description: "Instructions how to integrate MySensors climate into Home Assistant."
+description: "Instructions on how to integrate MySensors climate into Home Assistant."
date: 2016-10-01 15:00 +0200
sidebar: true
comments: false
diff --git a/source/_components/climate.nest.markdown b/source/_components/climate.nest.markdown
index be9adf6d41..4d99423734 100644
--- a/source/_components/climate.nest.markdown
+++ b/source/_components/climate.nest.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Nest Thermostat"
-description: "Instructions how to integrate Nest thermostats within Home Assistant."
+description: "Instructions on how to integrate Nest thermostats within Home Assistant."
date: 2015-03-23 19:59
sidebar: true
comments: false
diff --git a/source/_components/climate.netatmo.markdown b/source/_components/climate.netatmo.markdown
index 72c4f0de00..a90a1f4353 100644
--- a/source/_components/climate.netatmo.markdown
+++ b/source/_components/climate.netatmo.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Netatmo Thermostat"
-description: "Instructions how to integrate Netatmo thermostat into Home Assistant."
+description: "Instructions on how to integrate Netatmo thermostat into Home Assistant."
date: 2016-10-11 08:10
sidebar: true
comments: false
diff --git a/source/_components/climate.nuheat.markdown b/source/_components/climate.nuheat.markdown
new file mode 100644
index 0000000000..46a8e84c5a
--- /dev/null
+++ b/source/_components/climate.nuheat.markdown
@@ -0,0 +1,139 @@
+---
+layout: page
+title: "NuHeat Thermostat"
+description: "Instructions on how to integrate your NuHeat Signature thermostats within Home Assistant."
+date: 2017-11-11 18:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: nuheat.png
+ha_category: Climate
+ha_release: 0.61
+ha_iot_class: "Cloud Polling"
+---
+
+
+To get your [NuHeat Signature](http://www.nuheat.com/products/thermostats/signature-thermostat) thermostats working within Home Assistant, please follow the instructions for the general [NuHeat component](/components/nuheat) +
+ +## {% linkable_title Concepts %} + +The NuHeat Thermostat supports the following key concepts. + +The `target temperature` is the temperature that the device attempts to achieve. The target temperature is either determined by the schedule programmed into the thermostat (`auto mode`) or may be overridden. When the target temperature is set by Home Assistant, the thermostat will hold this temperature until the schedule is resumed. + + +## {% linkable_title Attributes %} + +The following attributes are provided by the NuHeat thermostat: `name`, `temperature_unit`, `current_temperature`, `target_temperature`, `current_hold_mode`, `current_operation`, `operation_list`, `min_temp` and `max_temp`. + + +### {% linkable_title Attribute `name` %} + +Returns the name of the NuHeat Thermostat. + +| Attribute type | Description | +| ---------------| ----------- | +| String | Name of the thermostat + +### {% linkable_title Attribute `temperature_unit` %} + +Returns the unit of measurement used for temperature by the thermostat. + +| Attribute type | Description | +| ---------------| ----------- | +| String | Name of the temperature unit + +### {% linkable_title Attribute `current_temperature` %} + +Returns the current temperature measured by the thermostat. + +| Attribute type | Description | +| ---------------| ----------- | +| Integer | Currently measured temperature + +### {% linkable_title Attribute `target_temperature` %} + +Returns the target temperature of the thermostat, when the thermostat is +not in auto operation mode. + +| Attribute type | Description | +| ---------------| ----------- | +| Integer | Target temperature + +### {% linkable_title Attribute `current_hold_mode` %} + +Returns the current temperature hold, if any. + +| Attribute type | Description | +| ---------------| ----------- | +| String | 'temperature', 'temporary_temperature', 'auto', etc. + +### {% linkable_title Attribute `current_operation` %} + +Returns the current operation of the thermostat. + +| Attribute type | Description | +| ---------------| ----------- | +| String | 'heat', 'idle' + +### {% linkable_title Attribute `operation_list` %} + +Returns the list of available operation modes. + +| Attribute type | Description | +| ---------------| ----------- | +| List of String | Available operation modes + +### {% linkable_title Attribute `min_temp` %} + +Returns the minimum supported temperature by the thermostat + +| Attribute type | Description | +| ---------------| ----------- | +| Integer | Minimum supported temperature + +### {% linkable_title Attribute `max_temp` %} + +Returns the maximum supported temperature by the thermostat + +| Attribute type | Description | +| ---------------| ----------- | +| Integer | Maximum supported temperature + + +## {% linkable_title Services %} + +The following services are provided by the NuHeat Thermostat: `set_temperature`, `set_hold_mode`, `nuheat_resume_program`. + +The services `fan_min_on_time`, `set_aux_heat`, `set_away_mode`, `set_humidity`, `set_fan_mode`, `set_operation_mode` and `set_swing_mode` offered by the [Climate component](/components/climate/) are not implemented for this thermostat. + +### {% linkable_title Service `set_temperature` %} + +Puts the thermostat into an indefinite hold at the given temperature. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `temperature` | no | Desired target temperature (when not in auto mode) + +Only the target temperatures relevant for the current operation mode need to +be provided. + +### {% linkable_title Service `set_hold_mode` %} + +Sets the thermostat's hold mode. The NuHeat thermostat supports "auto" (to run the thermostat's programmed schedule), "temperature" (to indefinitely hold the thermostat's current target temperature), or "temporary_temperature" (to hold the thermostat's current target temperature until the thermostat's next scheduled event). + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. +| `hold_mode` | no | New value of hold mode. + +### {% linkable_title Service `nuheat_resume_program` %} + +Resumes the currently active schedule. + +| Service data attribute | Optional | Description | +| ---------------------- | -------- | ----------- | +| `entity_id` | yes | String or list of strings that point at `entity_id`'s of climate devices to control. Else targets all. diff --git a/source/_components/climate.oem.markdown b/source/_components/climate.oem.markdown index c123b0e0f7..2b7b401229 100644 --- a/source/_components/climate.oem.markdown +++ b/source/_components/climate.oem.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenEnergyMonitor WiFi Thermostat" -description: "Instructions how to integrate an OpenEnergyMonitor thermostat with Home Assistant." +description: "Instructions on how to integrate an OpenEnergyMonitor thermostat with Home Assistant." date: 2017-01-27 11:15 sidebar: true comments: false @@ -15,7 +15,7 @@ ha_iot_class: "Local Polling" This platform supports the ESP82666 based "WiFi MQTT Relay / Thermostat" sold by [OpenEnergyMonitor](https://shop.openenergymonitor.com/wifi-mqtt-relay-thermostat/). The underlying [library](http://oemthermostat.readthedocs.io/) only supports this single relay variant of the [original device](https://harizanov.com/2014/12/wifi-iot-3-channel-relay-board-with-mqtt-and-http-api-using-esp8266/). -This platform controls the setpoint of the thermostat in it's "manual" mode, therefore there is a configuration option the away setpoint. +This platform controls the setpoint of the thermostat in its "manual" mode, therefore there is a configuration option the away setpoint. To set it up, add the following information to your `configuration.yaml` file: diff --git a/source/_components/climate.proliphix.markdown b/source/_components/climate.proliphix.markdown index 74227c0a98..b089ef586d 100644 --- a/source/_components/climate.proliphix.markdown +++ b/source/_components/climate.proliphix.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Proliphix Thermostat" -description: "Instructions how to integrate Proliphix thermostats within Home Assistant." +description: "Instructions on how to integrate Proliphix thermostats within Home Assistant." date: 2016-01-15 08:00 sidebar: true comments: false diff --git a/source/_components/climate.radiotherm.markdown b/source/_components/climate.radiotherm.markdown index f3cf3bd919..f4d08db107 100644 --- a/source/_components/climate.radiotherm.markdown +++ b/source/_components/climate.radiotherm.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Radio Thermostat (3M Filtrete) Thermostat" -description: "Instructions how to integrate Radio Thermostat (3M Filtrete) thermostats within Home Assistant." +description: "Instructions on how to integrate Radio Thermostat (3M Filtrete) thermostats within Home Assistant." date: 2015-10-18 17:15 sidebar: true comments: false diff --git a/source/_components/climate.sensibo.markdown b/source/_components/climate.sensibo.markdown index 9b9771bc42..02003d4aa6 100644 --- a/source/_components/climate.sensibo.markdown +++ b/source/_components/climate.sensibo.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Sensibo A/C controller" -description: "Instructions how to integrate Sensibo A/C controller into Home Assistant." +description: "Instructions on how to integrate Sensibo A/C controller into Home Assistant." date: 2017-04-01 15:00 +0200 sidebar: true comments: false diff --git a/source/_components/climate.toon.markdown b/source/_components/climate.toon.markdown index 57d8708aa3..61e4258847 100644 --- a/source/_components/climate.toon.markdown +++ b/source/_components/climate.toon.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Toon Thermostat" -description: "Instructions how to integrate Toon thermostats within Home Assistant." +description: "Instructions on how to integrate Toon thermostats within Home Assistant." date: 2017-10-22 12:00 sidebar: true comments: false diff --git a/source/_components/climate.touchline.markdown b/source/_components/climate.touchline.markdown new file mode 100644 index 0000000000..0f7f271946 --- /dev/null +++ b/source/_components/climate.touchline.markdown @@ -0,0 +1,32 @@ +--- +layout: page +title: "Roth Touchline" +description: "Instructions on how to integrate Roth Touchline within Home Assistant." +date: 2018-01-03 12:35 +sidebar: true +comments: false +sharing: true +footer: true +logo: roth.png +ha_category: Climate +ha_release: 0.61 +ha_iot_class: "Local Polling" +--- + +The `touchline` climate platform let you control [ROTH Touchline](http://www.roth-nordic.dk/dk/roth-touchline-tradloes-gulvvarmeregulering-1475.htm) floor heating thermostats from Roth. + + +To set it up, add the following information to your `configuration.yaml` file: + +```yaml +climate: + - platform: touchline + host: YOUR_IPADDRESS +``` + +{% configuration %} +host: + description: The IP address of your controller, e.g., http://192.168.1.1. + required: false + type: string +{% endconfiguration %} diff --git a/source/_components/climate.venstar.markdown b/source/_components/climate.venstar.markdown new file mode 100644 index 0000000000..f054465f72 --- /dev/null +++ b/source/_components/climate.venstar.markdown @@ -0,0 +1,77 @@ +--- +layout: page +title: "Venstar Thermostat" +description: "Instructions for how to integrate Venstar WiFi thermostats within Home Assistant." +date: 2018-01-14 00:04 +sidebar: true +comments: false +sharing: true +footer: true +logo: venstar.png +ha_category: Climate +ha_release: 0.62 +ha_iot_class: "Local Polling" +--- + + +The `venstar` climate platform allows you to control [Venstar](http://www.venstar.com) thermostats from Home Assistant. +Venstar thermostats feature a local API that allows for automation without the need for a cloud service. + +Currently supported and tested thermostats: + +- Color Touch T7900 + +Currently supported functionality: +- Setting heat/cool temperature when the thermostat is in the appropriate mode. +- Changing the operation mode of the thermostat (heat/cool/off/auto) +- Turning the fan on/off +- Setting the humidity level + +Note - Please ensure you update your thermostat to the latest firmware. Currently tested on firmware 5.10. + +To set it up, add the following information to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +climate: + - platform: venstar + host: IP_OR_HOSTNAME_OF_THERMOSTAT +``` + +{% configuration %} +host: + description: Address of your thermostat, e.g., 192.168.1.32. + required: true + type: string +username: + description: Username for the thermostat. + required: false + type: string +password: + description: Password for the thermostat. + required: false + type: string +ssl: + description: Whether to use SSL or not when communicating. + required: false + type: boolean + default: False +timeout: + description: Number of seconds for API timeout. + required: false + type: int + default: 5 +{% endconfiguration %} + +## {% linkable_title Full configuration sample %} + +```yaml +# Example configuration.yaml entry +climate: + - platform: venstar + host: IP_OR_HOSTNAME_OF_THERMOSTAT + ssl: True/False + username: OPTIONAL_AUTH_USER_HERE + password: OPTIONAL_AUTH_PASS_HERE + timeout: 5 +``` diff --git a/source/_components/climate.vera.markdown b/source/_components/climate.vera.markdown index bc8a9fdc58..c46b8fdff9 100644 --- a/source/_components/climate.vera.markdown +++ b/source/_components/climate.vera.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Vera Thermostat" -description: "Instructions how to integrate Vera thermostats into Home Assistant." +description: "Instructions on how to integrate Vera thermostats into Home Assistant." date: 2016-09-19 21:00 sidebar: true comments: false diff --git a/source/_components/climate.wink.markdown b/source/_components/climate.wink.markdown index 3a41d2c81d..be8623cb08 100644 --- a/source/_components/climate.wink.markdown +++ b/source/_components/climate.wink.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Wink Climate" -description: "Instructions how to setup the Wink climate devices within Home Assistant." +description: "Instructions on how to setup the Wink climate devices within Home Assistant." date: 2016-11-01 22:36 sidebar: true comments: false diff --git a/source/_components/climate.zwave.markdown b/source/_components/climate.zwave.markdown index 3c5f96f724..e1b20babc6 100644 --- a/source/_components/climate.zwave.markdown +++ b/source/_components/climate.zwave.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Z-Wave Climate" -description: "Instructions how to setup the Z-Wave thermostat or HVAC within Home Assistant." +description: "Instructions on how to setup the Z-Wave thermostat or HVAC within Home Assistant." date: 2016-04-03 9:52 sidebar: true comments: false @@ -46,12 +46,12 @@ automation: at: "20:00:00" action: - service: climate.set_operation_mode - entity_id: climate.remotec_zxt120_heating_1_id data: + entity_id: climate.remotec_zxt120_heating_1_id operation_mode: Heat - service: climate.set_temperature - entity_id: climate.remotec_zxt120_heating_1_39 data: + entity_id: climate.remotec_zxt120_heating_1_39 temperature: 24 ``` @@ -65,8 +65,8 @@ automation: at: "21:00:00" action: - service: climate.set_operation_mode - entity_id: climate.remotec_zxt120_heating_1_id data: + entity_id: climate.remotec_zxt120_heating_1_id operation_mode: 'Off' ``` diff --git a/source/_components/cloud.markdown b/source/_components/cloud.markdown index 3710eeff24..3008a52cac 100644 --- a/source/_components/cloud.markdown +++ b/source/_components/cloud.markdown @@ -1,6 +1,6 @@ --- layout: page -title: "Cloud" +title: "Home Assistant Cloud" description: "Enable the Home Assistant Cloud integration." date: 2017-11-17 20:00 sidebar: true @@ -8,100 +8,20 @@ comments: false sharing: true footer: true logo: home-assistant.png -ha_release: 0.60 +ha_release: "0.60" ha_category: Voice ha_iot_class: "Cloud Push" --- -The Home Assistant Cloud allows you to quickly integrate your local Home Assistant with various cloud services. Any processing of services from other cloud services is handled by your local Home Assistant. +The Home Assistant Cloud allows you to quickly integrate your local Home Assistant with various cloud services like Amazon Alexa. [Learn more.](/cloud) ```yaml # Example configuration.yaml entry to enable the cloud component cloud: ``` -Once activated, go to the configuration panel in Home Assistant and create an account and log in. There is no need to configure your router or expose your instance to the internet in any other way. - -If you are not seeing the **Configuration** panel, make sure you have the following option enabled in your configuration.yaml` file. +Once activated, go to the configuration panel in Home Assistant and create an account and log in. If you are not seeing the **Configuration** panel, make sure you have the following option enabled in your configuration.yaml` file. ```yaml config: ``` - -### {% linkable_title Amazon Alexa %} - -The Alexa integration allows users to control the entities via the [Home Assistant Smart Home skill for Alexa][alexa skill]. This means that you can say things like "Alexa, turn on the kitchen light" to control your local instance. - -```yaml -# Example configuration.yaml entry configuring Alexa -cloud: - alexa: - filter: - include_entities: - - light.kitchen - include_domains: - - switch - exclude_entities: - - light.living_room - exclude_domains: - - script -``` - -{% configuration %} -alexa: - description: Configuration options for the Amazon Alexa integration. - required: false - type: map - keys: - filter: - description: Filters for entities to include/exclude from Alexa. - required: false - type: map - keys: - include_entities: - description: Entity IDs to include. - required: false - type: list - include_domains: - description: Domains to include. - required: false - type: list - exclude_entities: - description: Entity IDs to exclude. - required: false - type: list - exclude_domains: - description: Domains to exclude. - required: false - type: list -{% endconfiguration %} - -### {% linkable_title Possible values for customize %} - -| Attribute | Description | -| --------- | ----------- | -| `alexa_hidden` | Hide the entity from the Alexa smart home devices. -| `alexa_name` | Defines name of the entity for a Alexa smart home device. Useful if you have an entity with a friendly name in a local language that you want to access using an English sounding name. -| `alexa_description` | The description of the device in the Alexa smart home device list. -| `alexa_display_categories` | Set displayCategories, useful for things like media_player (TV/SPEAKERS) or scene (ACTIVITY_TRIGGER/SCENE_TRIGGER). More info can be found [here](https://developer.amazon.com/docs/device-apis/alexa-discovery.html#display-categories). - -### {% linkable_title Available domains %} -Currently, the following domains are available to be used with Alexa: -- alert -- automation (enables/disables) -- cover -- fan (supports on/off and set speed) -- group -- input_boolean -- light -- lock (lock and unlock, but unlock is untested as Amazon has disabled unlock for now) -- media_player (play, pause, stop, set volume, adjust volume, next track and previous track) -- scene -- script (enables/disables) -- switch - -[alexa skill]: https://alexa.amazon.com/spa/index.html#skills/dp/B0772J1QKB/?ref=skill_dsk_skb_sr_2 - -### {% linkable_title Frequently Asked Questions %} - -You can find a list of frequently asked questions (and their answers) in [this blog post](https://home-assistant.io/blog/2017/12/17/introducing-home-assistant-cloud/#faq). diff --git a/source/_components/coinbase.markdown b/source/_components/coinbase.markdown new file mode 100644 index 0000000000..f5d657ab4f --- /dev/null +++ b/source/_components/coinbase.markdown @@ -0,0 +1,46 @@ +--- +layout: page +title: "coinbase" +description: "Instructions for how to add Coinbase sensors to Home Assistant." +date: 2017-12-08 17:54 +sidebar: true +comments: false +sharing: true +footer: true +logo: coinbase.png +ha_release: 0.61 +ha_iot_class: "Cloud Polling" +--- + + +The `coinbase` component lets you access account balances and exchange rates from [coinbase](https://coinbase.com). + +You will need to obtain an API key from coinbase's [developer site](https://www.coinbase.com/settings/api) to use this component. You need to give read access to `wallet:accounts` in order for the component to access relevant data. + +To set it up, add the following information to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +coinbase: + api_key: asdfghjklqwertyuiopzxcvbnm + api_secret: nkjnewncfghjklqwertyuiopzxcvbnm + exchange_rate_currencies: + - BTC + - ETH + - LTC +``` + +{% configuration %} +api_key: + description: Your API key to access coinbase. + required: true + type: string +api_secret: + description: Your API secret to access coinbase. + required: true + type: string +exchange_rate_currencies: + description: List of currencies to create exchange rate sensors for. + required: false + type: list +{% endconfiguration %} diff --git a/source/_components/comfoconnect.markdown b/source/_components/comfoconnect.markdown index fcce2b619f..7394042b84 100644 --- a/source/_components/comfoconnect.markdown +++ b/source/_components/comfoconnect.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Zehnder ComfoAir Q Ventilation" -description: "Instructions how to integrate Zehnder ComfoAir Q350/450/600 ventilation systems into Home Assistant." +description: "Instructions on how to integrate Zehnder ComfoAir Q350/450/600 ventilation systems into Home Assistant." date: 2017-06-28 18:00 sidebar: true comments: false diff --git a/source/_components/config.markdown b/source/_components/config.markdown index 514840e7f7..29aa9ce2ae 100644 --- a/source/_components/config.markdown +++ b/source/_components/config.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Config" -description: "Instructions how to setup the configuration panel for Home Assistant." +description: "Instructions on how to setup the configuration panel for Home Assistant." date: 2017-02-24 20:00 sidebar: true comments: false diff --git a/source/_components/configurator.markdown b/source/_components/configurator.markdown index 3d9661d50b..9cabdccbb3 100644 --- a/source/_components/configurator.markdown +++ b/source/_components/configurator.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Configurator" -description: "Instructions how to integrate the configurator in your components." +description: "Instructions on how to integrate the configurator in your components." date: 2015-03-15 00:51 sidebar: true comments: false diff --git a/source/_components/conversation.markdown b/source/_components/conversation.markdown index 55b9fbb19a..e9bb86aaab 100644 --- a/source/_components/conversation.markdown +++ b/source/_components/conversation.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Conversation" -description: "Instructions how to have conversations with your Home Assistant." +description: "Instructions on how to have conversations with your Home Assistant." date: 2015-03-15 00:39 sidebar: true comments: false @@ -11,46 +11,85 @@ logo: home-assistant.png ha_category: "Voice" --- +The conversation component allows you to converse with Home Assistant. You can either converse by pressing the microphone in the frontend (supported browsers only (no iOS)) or by calling the `conversation/process` service with the transcribed text. -The `conversation` component can process sentences into commands for Home Assistant. It currently has built in functionality to recognize `turn
+ 
+ Screenshot of the conversation interface in Home Assistant.
+
-
-
- Apple iPhones do not support this feature in any browser. -
+The following configuration can handle the following sentences: + + - Change the lights to red + - Change the lights to green + - Change the lights to blue + - Change the lights to the color red + - Change the lights to the color green + - Change the lights to the color blue + +```yaml +# Example configuration.yaml entry +conversation: + intents: + ColorLight: + - Change the lights to [the color] {color} +{% raw %} +intent_script: + ColorLight: + speech: + text: Changed the lights to {{ color }}. + action: + service: light.turn_on + data_template: + rgb_color: + - "{% if color == 'red' %}255{% else %}0{% endif %}" + - "{% if color == 'green' %}255{% else %}0{% endif %}" + - "{% if color == 'blue' %}255{% else %}0{% endif %}" +{% endraw %} +``` + +#### {% linkable_title Service `conversation.process` %} + +| Service data attribute | Optional | Description | +|------------------------|----------|--------------------------------------------------| +| `text` | yes | Transcribed text | diff --git a/source/_components/counter.markdown b/source/_components/counter.markdown index 76a11fbb89..f181d4755a 100644 --- a/source/_components/counter.markdown +++ b/source/_components/counter.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Counter" -description: "Instructions how to integrate counters into Home Assistant." +description: "Instructions on how to integrate counters into Home Assistant." date: 2017-08-26 06:00 sidebar: true comments: false @@ -19,7 +19,7 @@ To add a counter to your installation, add the following to your `configuration. ```yaml # Example configuration.yaml entry counter: - counter: + my_custom_counter: initial: 30 step: 1 ``` diff --git a/source/_components/cover.abode.markdown b/source/_components/cover.abode.markdown index e67998bf0b..a80303a756 100644 --- a/source/_components/cover.abode.markdown +++ b/source/_components/cover.abode.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Abode Cover" -description: "Instructions how to integrate Abode covers into Home Assistant." +description: "Instructions on how to integrate Abode covers into Home Assistant." date: 2017-08-26 13:28 sidebar: true comments: false diff --git a/source/_components/cover.garadget.markdown b/source/_components/cover.garadget.markdown index 6ae25d44e8..0a3b5de358 100644 --- a/source/_components/cover.garadget.markdown +++ b/source/_components/cover.garadget.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Garadget Cover" -description: "Instructions how to integrate Garadget covers within Home Assistant." +description: "Instructions on how to integrate Garadget covers within Home Assistant." date: 2016-10-24 14:25 sidebar: true comments: false @@ -16,6 +16,8 @@ ha_iot_class: "Cloud Polling" The `garadget` cover platform lets you control [Garadget](http://www.garadget.com/) garage door futurizers through Home Assistant. +## {% linkable_title Configuration %} + To enable Garadget Covers in your installation, add the following to your `configuration.yaml` file: ```yaml @@ -24,8 +26,8 @@ cover: - platform: garadget covers: 190028001947343412342341: - username: UseYourLogin@garadget.com - password: abc123 + username: YOUR_USERNAME + password: YOUR_PASSWORD 4c003f001151353432134214: access_token: df4cc785ff818f2b01396c44142342fccdef ``` @@ -44,12 +46,13 @@ Configuration variables: If provided, the **access_token** will be used, otherwise the **username** and **password** will be used to automatically generate an access token at start time. +## {% linkable_title Example %} -**Example with more detail:**
The above devices are confirmed to work, but others may work as well.
- diff --git a/source/_components/cover.xiaomi_aqara.markdown b/source/_components/cover.xiaomi_aqara.markdown index d2bbdf5fa9..6f5353b9c8 100644 --- a/source/_components/cover.xiaomi_aqara.markdown +++ b/source/_components/cover.xiaomi_aqara.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Xiaomi Cover" -description: "Instructions how to setup the Xiaomi cover within Home Assistant." +description: "Instructions on how to setup the Xiaomi cover within Home Assistant." date: 2017-07-21 16:34 sidebar: true comments: false diff --git a/source/_components/cover.zwave.markdown b/source/_components/cover.zwave.markdown index 90547584ce..53477e1e00 100644 --- a/source/_components/cover.zwave.markdown +++ b/source/_components/cover.zwave.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Z-Wave Cover" -description: "Instructions how to setup the Z-Wave covers within Home Assistant." +description: "Instructions on how to setup the Z-Wave covers within Home Assistant." date: 2016-12-18 19:41 sidebar: true comments: false diff --git a/source/_components/daikin.markdown b/source/_components/daikin.markdown new file mode 100644 index 0000000000..84624b5af0 --- /dev/null +++ b/source/_components/daikin.markdown @@ -0,0 +1,58 @@ +--- +layout: page +title: "Daikin AC" +description: "Instructions on how to integrate Hive devices with Home Assistant." +date: 2017-12-10 21:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: daikin.png +ha_category: Hub +ha_release: 0.59 +ha_iot_class: "Local Polling" +--- + + +The `daikin` component integrates Daikin air conditioning systems into Home Assistant. + +To automatically add all your Daikin devices (ACs and associated sensors) into your Home Assistant installation, add the following to your 'configuration.yaml' file: + ++Please note, the Daikin platform integrates **ONLY the european versions of Daikin ACs (models BRP069A41, 42, 43, 45)** into Home Assistant. +
+ +To automatically add all your Daikin devices (ACs and associated sensors) into your Home Assistant installation, add the following to your `configuration.yaml` file: + +```yaml +# Full manual example configuration.yaml entry +daikin: + hosts: + - 192.168.4.161 + monitored_conditions: + - inside_temperature + - outside_temperature +``` + +{% configuration %} +hosts: + description: List of IP addresses or hostnames. + required: false + default: All discovered hosts + type: array +monitored_conditions: + description: List of items you want to monitor for each device. + required: false + default: All conditions + type: list + keys: + inside_temperature: + description: The current temperature measured inside the house. + outside_temperature: + description: The current temperature measured outside the house. +{% endconfiguration %} + ++Please note that some AC devices may report outside temperature only when they are turned on. +
+ diff --git a/source/_components/datadog.markdown b/source/_components/datadog.markdown index 511d51608a..7a3ec052c7 100644 --- a/source/_components/datadog.markdown +++ b/source/_components/datadog.markdown @@ -35,7 +35,7 @@ datadog: Configuration variables: -- **host** (*Optional*): The IP address or hostname of your Datadog host, e.g. 192.168.1.23. Defaults to `localhost`. +- **host** (*Optional*): The IP address or hostname of your Datadog host, e.g., 192.168.1.23. Defaults to `localhost`. - **port** (*Optional*): Port to use. Defaults to 8125. - **prefix** (*Optional*): Prefix to use. Defaults to `hass`. - **rate** (*Optional*): The sample rate of UDP packets sent to Datadog. Defaults to 1. diff --git a/source/_components/deconz.markdown b/source/_components/deconz.markdown new file mode 100644 index 0000000000..d1fde01521 --- /dev/null +++ b/source/_components/deconz.markdown @@ -0,0 +1,175 @@ +--- +layout: page +title: "deCONZ" +description: "Instructions on how to setup Conbee/Raspbee devices with deCONZ from Dresden Elektronik within Home Assistant." +date: 2017-11-12 16:30 +sidebar: true +comments: false +sharing: true +footer: true +logo: deconz.jpeg +ha_category: Hub +ha_release: "0.61" +ha_iot_class: "Local Push" +--- + +[deCONZ](https://www.dresden-elektronik.de/funktechnik/products/software/pc/deconz/) by [Dresden Elektronik](https://www.dresden-elektronik.de) is a software that communicates with Conbee/Raspbee Zigbee gateways and exposes Zigbee devices that are connected to the gateway. + +[deCONZ REST API](http://dresden-elektronik.github.io/deconz-rest-doc/). + +### {% linkable_title Supported device types %} + +- [Zigbee Lights](/components/light.deconz/) +- [Consumption Sensors](/components/sensor.deconz/) +- [Humidity Sensors](/components/sensor.deconz/) +- [Light Level Sensors](/components/sensor.deconz/) +- [OpenClose Detectors](/components/binary_sensor.deconz/) +- [Power Sensors](/components/sensor.deconz/) +- [Presence Detectors](/components/binary_sensor.deconz/) +- [Pressure Sensors](/components/sensor.deconz/) +- [Switches (Remote Controls)](/components/sensor.deconz/) +- [Temperature Sensors](/components/sensor.deconz/) + +## {% linkable_title Configuration %} + +Home Assistant will automatically discover deCONZ presence on your network, if `discovery:` is present in your `configuration.yaml` file. + +If you don't have the API key, you can generate an API key for deCONZ by using the one-click functionality similar to Philips Hue. Go to **Menu** -> **Settings** -> **Unlock Gateway** in deCONZ and then use the deCONZ configurator in Home Assistant frontend to create an API key. When you've generated the API key from Home Assistant, the API key will be stored in `.config_entries.json` inside the `.homeassistant` folder. + +You can add the following to your configuration.yaml file if you are not using the `discovery:` component: + +```yaml +# Example configuration.yaml entry +deconz: + host: IP_ADDRESS +``` + +{% configuration %} +host: + description: The IP address of your deCONZ web server. + required: false + type: string +api_key: + description: The API key to access your deCONZ web server. + required: false + type: string +port: + description: Configure port deCONZ web server is accessible from. + required: false + default: 80 + type: int +{% endconfiguration %} + +A full configuration could look like this: + +```yaml +# Example configuration.yaml entry +deconz: + host: 127.0.0.1 + api_key: 0123456789 + port: 80 +``` + +## {% linkable_title Debugging component %} + +If you have problems with deCONZ or the component you can add debug prints to the log. + +```yaml +logger: + default: info + logs: + pydeconz: debug + homeassistant.components.deconz: debug +``` + +## {% linkable_title Device services %} + +Available services: `configure`. + +#### {% linkable_title Service `deconz.configure` %} + +Set attribute of device in Deconz using [Rest API](http://dresden-elektronik.github.io/deconz-rest-doc/rest/). + +| Service data attribute | Optional | Description | +|-----------|----------|-------------| +| `field` | No | String representing a specific device in deCONZ. | +| `entity` | No | String representing a specific HASS entity of a device in deCONZ. | +| `data` | No | Data is a JSON object with what data you want to alter. | + +Field and entity are exclusive, i.e you can only use one in a request. + +{ "field": "/lights/1", "data": {"name": "light2"} } + +{ "entity": "light.light1", "data": {"name": "light2"} } + +{ "field": "/config", "data": {"permitjoin": 60} } + +## {% linkable_title Remote control devices %} + +Remote controls (ZHASwitch category) will be not be exposed as a regular entity, but as events named 'deconz_event' with a payload of 'id' and 'event'. Id will be the device name from deCONZ and Event will be the momentary state of the switch. However, a sensor entity will be created that shows the battery level of the switch as reported by deCONZ, named sensor.device_name_battery_level. + +Typical values for switches, the event codes are 4 numbers where the first and last number are of interest here. + +| Switch code | Description | +|-------------|-------------| +| 1XXX | Button #1 up to #8 | +| XXX1 | Button hold | +| XXX2 | Button short release | +| XXX3 | Button long release | + +Where for example on a Philips Hue Dimmer, 2001 would be holding the dim up button. + +For the IKEA Tradfri remote, 1 is the middle button, 2 is up, 3 is down, 4 is left, and 5 is right. + +## {% linkable_title Examples %} + +### {% linkable_title Step up and step down input number with wireless dimmer %} + +{% raw %} +```yaml +automation: + - alias: 'Toggle lamp from dimmer' + initial_state: 'on' + trigger: + platform: event + event_type: deconz_event + event_data: + id: remote_control_1 + event: 1002 + action: + service: light.toggle + entity_id: light.lamp + + - alias: 'Increase brightness of lamp from dimmer' + initial_state: 'on' + trigger: + platform: event + event_type: deconz_event + event_data: + id: remote_control_1 + event: 2002 + action: + - service: light.turn_on + data_template: + entity_id: light.lamp + brightness: > + {% set bri = states.light.lamp.attributes.brightness | int %} + {{ [bri+30, 249] | min }} + + - alias: 'Decrease brightness of lamp from dimmer' + initial_state: 'on' + trigger: + platform: event + event_type: deconz_event + event_data: + id: remote_control_1 + event: 3002 + action: + - service: light.turn_on + data_template: + entity_id: light.lamp + brightness: > + {% set bri = states.light.lamp.attributes.brightness | int %} + {{ [bri-30, 0] | max }} +``` +{% endraw %} diff --git a/source/_components/demo.markdown b/source/_components/demo.markdown index b399c9485c..f1c2573720 100644 --- a/source/_components/demo.markdown +++ b/source/_components/demo.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Demo platforms" -description: "Instructions how to use the Platform demos with Home Assistant." +description: "Instructions on how to use the Platform demos with Home Assistant." date: 2016-02-24 07:00 sidebar: true comments: false @@ -12,7 +12,7 @@ ha_category: Other --- -The `demo` platform allows you to use components which are providing a demo of their implementation. The demo entities are dummies but show you how the actual platform looks like. This way you can run own demonstration instance like the online [Home Assistant demo](https://home-assistant.io/demo/) or `hass --demo-mode` but combined with your own real/functional platforms. +The `demo` platform allows you to use components which are providing a demo of their implementation. The demo entities are dummies but show you how the actual platform looks like. This way you can run own demonstration instance like the online [Home Assistant demo](/demo/) or `hass --demo-mode` but combined with your own real/functional platforms. Available demo platforms: diff --git a/source/_components/device_sun_light_trigger.markdown b/source/_components/device_sun_light_trigger.markdown index e0a75a093c..d49c4e1565 100644 --- a/source/_components/device_sun_light_trigger.markdown +++ b/source/_components/device_sun_light_trigger.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Presence based lights" -description: "Instructions how to automate your lights with Home Assistant." +description: "Instructions on how to automate your lights with Home Assistant." date: 2015-01-20 22:36 sidebar: true comments: false diff --git a/source/_components/device_tracker.actiontec.markdown b/source/_components/device_tracker.actiontec.markdown index b292353585..fbf2119650 100644 --- a/source/_components/device_tracker.actiontec.markdown +++ b/source/_components/device_tracker.actiontec.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Actiontec" -description: "Instructions how to integrate Actiontec routers into Home Assistant." +description: "Instructions on how to integrate Actiontec routers into Home Assistant." date: 2015-08-30 19:00 sidebar: true comments: false diff --git a/source/_components/device_tracker.aruba.markdown b/source/_components/device_tracker.aruba.markdown index 0dd6102555..e84c37954b 100644 --- a/source/_components/device_tracker.aruba.markdown +++ b/source/_components/device_tracker.aruba.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Aruba" -description: "Instructions how to integrate Aruba routers into Home Assistant." +description: "Instructions on how to integrate Aruba routers into Home Assistant." date: 2015-08-31 08:45 sidebar: true comments: false @@ -36,7 +36,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.asuswrt.markdown b/source/_components/device_tracker.asuswrt.markdown index a49a066309..7889253ce9 100644 --- a/source/_components/device_tracker.asuswrt.markdown +++ b/source/_components/device_tracker.asuswrt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "ASUSWRT" -description: "Instructions how to integrate ASUSWRT based routers into Home Assistant." +description: "Instructions on how to integrate ASUSWRT based routers into Home Assistant." date: 2015-08-06 19:00 sidebar: true comments: false @@ -19,6 +19,8 @@ The `asuswrt` platform offers presence detection by looking at connected devices This platform is **NOT** available for [Microsoft Windows installations](http://pexpect.readthedocs.io/en/stable/overview.html#pexpect-on-windows). +### {% 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 %}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.bbox.markdown b/source/_components/device_tracker.bbox.markdown index 7a5cc91649..35bae013f0 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 a9a47e20a8..ce1dab5000 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 access to the bluetooth stack, see [Rootless Setup section](#rootless-setup) for further infomation + - 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: @@ -48,11 +48,11 @@ Configuration variables: - **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. ## {% linkable_title Rootless Setup %} -Normaly 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). +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 0a2a2d0632..45bd09eae3 100644 --- a/source/_components/device_tracker.bluetooth_tracker.markdown +++ b/source/_components/device_tracker.bluetooth_tracker.markdown @@ -27,6 +27,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 0000000000..4f390c5fa3 --- /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 9fd185eadd..106ba06083 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 1402e84064..589241b8eb 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 4fa4fe0af4..826046d029 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.fritz.markdown b/source/_components/device_tracker.fritz.markdown index 40d7bfa985..3e4a745d99 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,6 +15,8 @@ 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 Configuration %} +
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.
+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 component. +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 6b6a439cde..4c2889a94b 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://[IP address Home Assistant]:[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.
+- Use the domain that Home Assistant is available on the internet or the public 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 or remove any 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=[Devicename]`.
-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 3dbd197b77..aec5ac8a52 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 b9821eb522..6cdc3984b2 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 0e1827c680..4cf0ca7e5a 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 diff --git a/source/_components/device_tracker.locative.markdown b/source/_components/device_tracker.locative.markdown index 2a185c924e..02d932a7a4 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 32d0cde87b..621f70a905 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 @@ -39,7 +39,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.markdown b/source/_components/device_tracker.markdown index 25e2961498..b595407d13 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 %} @@ -37,9 +37,13 @@ The following optional parameters can be used with any platform. However device | Parameter | Default | Description | |----------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `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`) | +| `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: ```yaml @@ -65,7 +69,7 @@ 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 ``` diff --git a/source/_components/device_tracker.meraki.markdown b/source/_components/device_tracker.meraki.markdown index a88aa1d713..cbe481d39e 100644 --- a/source/_components/device_tracker.meraki.markdown +++ b/source/_components/device_tracker.meraki.markdown @@ -11,8 +11,21 @@ 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. -Follow instructions [here](https://meraki.cisco.com/technologies/location-analytics-api) how to enable Location Analytics. + +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: @@ -24,14 +37,13 @@ device_tracker: validator: meraki_validator ``` - {% configuration %} secret: - description: Secret code added in Meraki + description: Secret code added in Meraki. required: true type: string validator: - description: Validation string from Meraki + 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 0000000000..ad59c95e0d --- /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 e3e49c4846..da1dceee4d 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 d60b895c50..3640b8ad5a 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,7 +32,7 @@ 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 { diff --git a/source/_components/device_tracker.mqtt_json.markdown b/source/_components/device_tracker.mqtt_json.markdown index d7a515588c..a6cbc50b87 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 diff --git a/source/_components/device_tracker.mysensors.markdown b/source/_components/device_tracker.mysensors.markdown index 14db68931a..5366c68ea7 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 70dbbce102..8bdcacc8cd 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 0ce79dfc3a..74ace37e23 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.owntracks.markdown b/source/_components/device_tracker.owntracks.markdown index 20cf68ab97..a852ff2e50 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 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 `-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 8c0bda46b8..4816832b8e 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](https://www.ubnt.com/products/#unifi). 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: diff --git a/source/_components/device_tracker.upc_connect.markdown b/source/_components/device_tracker.upc_connect.markdown index ca0a7e57b2..1f77bc8d86 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 diff --git a/source/_components/device_tracker.xiaomi.markdown b/source/_components/device_tracker.xiaomi.markdown index 9a8f6a43fd..d38571007c 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 0000000000..ae60404393 --- /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_version: 0.67 +ha_iot_class: "Local Polling" +--- + +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 a034f72e28..bf2cc4b4e6 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 c2e26b9aa3..4554819ee2 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 19c16ce0ac..12c170a1ee 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 18ac58261c..f369ce67c1 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,30 +14,32 @@ 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/) - * [Telldus Live](https://home-assistant.io/components/tellduslive/) - * [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 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/) It will be able to add Google Chromecasts and Belkin WeMo switches automatically, for Philips Hue it will require some configuration from the user. @@ -49,6 +51,8 @@ discovery: ignore: - sonos - samsung_tv + enable: + - homekit ``` Configuration variables: @@ -78,10 +82,18 @@ Valid values for ignore are: * `sabnzbd`: SABnzbd downloader * `samsung_tv`: Samsung TVs * `sonos`: Sonos speakers + * `songpal` : Songpal * `tellduslive`: Telldus Live + * `wink`: Wink Hub * `yamaha`: Yamaha media player * `yeelight`: Yeelight Sunflower bulb - + +- **enable** (*Optional*): A list of platforms not enabled by default that `discovery` should discover. + +Valid values for enable are: + + * `homekit`: HomeKit accessories +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. @@ -97,7 +109,7 @@ If you are on Windows and you're using Python 3.5, download the [Netifaces](http
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. - + 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).
diff --git a/source/_components/dominos.markdown b/source/_components/dominos.markdown index 062c0fbfea..d6849d738f 100644 --- a/source/_components/dominos.markdown +++ b/source/_components/dominos.markdown @@ -10,12 +10,15 @@ footer: true logo: dominos.png ha_category: Other ha_version: 0.59 +ha_iot_class: "Cloud Polling" --- -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. diff --git a/source/_components/doorbird.markdown b/source/_components/doorbird.markdown index 0b7f1e4120..9db3c71d86 100644 --- a/source/_components/doorbird.markdown +++ b/source/_components/doorbird.markdown @@ -20,9 +20,10 @@ 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 + host: DOORBIRD_IP_OR_HOSTNAME + username: YOUR_USERNAME + password: YOUR_PASSWORD + hass_url_override: HASS_IP ``` Configuration variables: @@ -30,3 +31,78 @@ Configuration variables: - **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. +- **doorbell_events** (*Optional*): Setting this to `true` this will register a callback URL with the device so that events can be published to the event bus when the doorbell rings. +- **hass_url_override** (*Optional*): 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. + ++Enabling `doorbell_events` will delete all other registered push notification services with the device every time Home Assistant starts. This will not affect notifications delivered by the DoorBird mobile app. +
+ +### Doorbell Sound Examples + +You can create an automation that triggers on event `doorbird_doorbell` to play a doorbell sound when the Doorbird button is pressed. This should work with any media player. + +#### Example using SONOS + +[`SONOS`](http://www.sonos.com) players have features allowing for "snapshotting" the current state of some or all players so those state(s) can be "restored" at a later time. This feature is perfect for implementing a doorbell sound (from Doorbird or any other Doorbell setup for that matter). The [`media_player.sonos`](/components/media_player.sonos/) platform includes the [`SONOS_SNAPSHOT`](/components/media_player.sonos/#service-sonos_snapshot) and [`SONOS_RESTORE`](/components/media_player.sonos/#service-sonos_restore) features. The result of not using these features is any currently playing songs or media will not continue playing after the doorbell sound has played and you will be left with the doorbell sound queued as the last played song. This setup allows for seamless ringing of the doorbell and all SONOS devices continuing nicely on as if nothing had happened. + +The example script below takes a snapshot of three SONOS players that are not currently grouped together, joins the three players in a group (so the sound plays at the same time on all players), plays the doorbell MP3 sound, unjoins the players from the group and finally restores the players to their original state. When the players are grouped they are controlled by refering to the `master`. + +Automation file: + +```yaml +- alias: Doorbird ring + trigger: + platform: event + event_type: doorbird_doorbell + action: + service: script.turn_on + entity_id: script.doorbell +``` + +Script file: + +```yaml +doorbell: + alias: Ring Doorbell + sequence: + - service: media_player.sonos_snapshot + data: + entity_id: + - media_player.kitchen + - media_player.master_bedroom + - media_player.study + - service: media_player.sonos_join + data: + master: media_player.study + entity_id: + - media_player.kitchen + - media_player.master_bedroom + - media_player.study + - service: media_player.play_media + data: + entity_id: media_player.study # the group master + media_content_id: http://10.1.1.10/sounds/doorbell.mp3 # this is on a NAS but could be HASS local + media_content_type: music + - service: media_player.volume_set + data: + entity_id: # can still control the volume of grouped players indivdually + - media_player.study + - media_player.kitchen + - media_player.master_bedrom + volume_level: 0.50 + - delay: + seconds: 4 # wait while the sound plays + - service: media_player.sonos_unjoin + data: + entity_id: + - media_player.kitchen + - media_player.master_bedroom + - media_player.study + - service: media_player.sonos_restore + data: + entity_id: + - media_player.kitchen + - media_player.master_bedroom + - media_player.study +``` diff --git a/source/_components/downloader.markdown b/source/_components/downloader.markdown index 53063587d6..beec226876 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 a3d015001c..7c0e1ca2f3 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:-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](https://home-assistant.io/components/google_assistant/). +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 0000000000..5ebd666594 --- /dev/null +++ b/source/_components/fan.template.markdown @@ -0,0 +1,96 @@ +--- +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, and +set_oscillating 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') }}" + 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 }}" + 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 + 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 a osc state 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.wink.markdown b/source/_components/fan.wink.markdown index 23369dfad2..129db4b469 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 218a7c0da4..8fc9da3211 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_category: Fan ha_version: 0.57 ha_iot_class: "Local Polling" --- -The `xiaomi_miio` fan platform allows you to control the Xiaomi Air Purifier 2, Air Purifier 2S andd Air Purifier Pro. +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 +### 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 -* States - - power - - aqi - - humidity +* 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 fan. + required: true + type: string +token: + description: The API token of your fan. + required: true + type: string +name: + description: The name of your fan. + required: false + type: string + default: Xiaomi Air Purifier +model: + description: The model of your device. + 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 0000000000..536d9c78bd --- /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 953620ed3b..4e83a0b8a5 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 15b7212965..5a06cd4171 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,7 +20,7 @@ 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 ``` @@ -67,4 +67,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 0000000000..df9041ed35 --- /dev/null +++ b/source/_components/folder_watcher.markdown @@ -0,0 +1,81 @@ +--- +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 +- action: + - data_template: + message: 'Created {{ trigger.event.data.file }} in {{ trigger.event.data.folder }}' + title: New image captured! + data: + file: " {{ trigger.event.data.path }} " + service: notify.pushbullet + alias: New file alert + condition: [] + id: '1520092824697' + trigger: + - event_data: {"event_type":"created"} + event_type: folder_watcher + platform: event +``` +{% endraw %} diff --git a/source/_components/foursquare.markdown b/source/_components/foursquare.markdown index 10b5d6ebe6..5ec302887e 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 0000000000..960d1411d9 --- /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 0000000000..a5ca0a5f68 --- /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 92c0e8d8dd..871db22f68 100644 --- a/source/_components/frontend.markdown +++ b/source/_components/frontend.markdown @@ -39,11 +39,11 @@ frontend: required: true type: [list, string] extra_html_url: - description: "List of addtional [resources](/developers/frontend_creating_custom_ui/) to load in `latest` javascript mode." + 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 addtional [resources](/developers/frontend_creating_custom_ui/) to load in `es5` javascript mode." + description: "List of additional [resources](/developers/frontend_creating_custom_ui/) to load in `es5` javascript mode." required: false type: list development_repo: @@ -135,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 063dddcab0..43d74d72b7 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 0000000000..5632a8847d
--- /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_version: 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 1e27ce6cc3..edd0b8ebb1 100644
--- a/source/_components/google_assistant.markdown
+++ b/source/_components/google_assistant.markdown
@@ -13,14 +13,20 @@ featured: true
ha_release: 0.56
---
+
+ 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 %} + To enable this, add the following lines to your `configuration.yaml` file: ```yaml @@ -30,31 +36,96 @@ 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 + entity_config: + switch.kitchen: + name: Custom Name for Google Assistant + aliases: + - bright lights + - entry lights + light.living_room: + expose: false + room: living room ``` 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](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview) 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` - - `climate` +{% 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. +
+ +{% 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 + 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: Filter entities to available in the `Home` app. ([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: + alarm_control_panel: + description: Additional options for `alarm_control_panel` entities. + required: false + type: map + keys: + code: + description: Code to arm or disarm the alarm in the frontend. + required: false + type: string + default: '' +{% endconfiguration %} + ++ 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 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 + 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. | +| 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. | +| light | Light | Support for `on / off`, `brightness` and `rgb_color`. | +| lock | DoorLock | Support for `lock / unlock`. | +| 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 / remote / input_boolean / script | Switch | All represented as switches. | + + +## {% 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. diff --git a/source/_components/homekit_controller.markdown b/source/_components/homekit_controller.markdown new file mode 100644 index 0000000000..910c07e036 --- /dev/null +++ b/source/_components/homekit_controller.markdown @@ -0,0 +1,36 @@ +--- +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: + +- [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 73287f7420..5deaa8311a 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,16 +13,15 @@ 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: @@ -90,7 +89,7 @@ homematic: host: 127.0.0.1 username: Admin password: secret - + ``` ### {% linkable_title The `resolvenames` option %} @@ -111,7 +110,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: @@ -126,7 +125,7 @@ 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.ccu2`). 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 %} @@ -138,7 +137,7 @@ When HomeMatic devices change their state or some other internal value, the CCU/ #### {% 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. @@ -159,7 +158,17 @@ 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-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 index 46d8f2cc9f..f172c6b0ff 100644 --- a/source/_components/hue.markdown +++ b/source/_components/hue.markdown @@ -11,7 +11,7 @@ logo: philips_hue.png ha_category: Hub ha_iot_class: "Local Polling" featured: true -ha_release: 0.60 +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/). @@ -33,12 +33,20 @@ hue: 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. +- **host**: 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. +```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: @@ -54,7 +62,7 @@ You will need to convert each bridge into an entry in the new configuration styl ### {% 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. +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: @@ -103,7 +111,7 @@ More information can be found on the [Philips Hue API documentation](https://www ### {% linkable_title Using Hue Scenes in Home Assistant %} -The Hue platform has it's 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. +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. diff --git a/source/_components/ifttt.manything.markdown b/source/_components/ifttt.manything.markdown index 7288afb90b..84d0228bc1 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 764138d272..9f48303946 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**.
diff --git a/source/_components/ihc.markdown b/source/_components/ihc.markdown
new file mode 100644
index 0000000000..0030d30361
--- /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`.
+
-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`.
+
diff --git a/source/_components/light.homekit_controller.markdown b/source/_components/light.homekit_controller.markdown
new file mode 100644
index 0000000000..f3f7243a10
--- /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 b2223ae9e4..86249ce98e 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.hue.markdown b/source/_components/light.hue.markdown
index d4d37548b6..59e8b8e970 100644
--- a/source/_components/light.hue.markdown
+++ b/source/_components/light.hue.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Philips Hue Light"
-description: "Instructions how to integrate Philips Hue lights into Home Assistant."
+description: "Instructions on how to integrate Philips Hue lights into Home Assistant."
date: 2015-03-23 20:09
sidebar: true
comments: false
@@ -10,7 +10,6 @@ footer: true
logo: philips_hue.png
ha_category: Light
ha_iot_class: "Local Polling"
-featured: true
ha_release: pre 0.7
---
diff --git a/source/_components/light.hyperion.markdown b/source/_components/light.hyperion.markdown
index eccb243e37..7cba5e18f4 100644
--- a/source/_components/light.hyperion.markdown
+++ b/source/_components/light.hyperion.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Hyperion"
-description: "Instructions how to integrate Hyperion into Home Assistant."
+description: "Instructions on how to integrate Hyperion into Home Assistant."
date: 2015-10-25 22:43
sidebar: true
comments: false
@@ -29,5 +29,7 @@ Configuration variables:
- **host** (*Required*): The IP address of the device the Hyperion service is running on.
- **port** (*Optional*): The port used to communicate with the Hyperion service. Defaults to `19444`.
- **name** (*Optional*): The name of the device used in the frontend.
-- **priority** (*Optional*): The priority of the hyperion instance. Defaults to `128`.
+- **priority** (*Optional*): The priority of the Hyperion instance. Defaults to `128`.
+- **hdmi_priority** (*Optional*): The priority of the HDMI grabber of this Hyperion instance, note that this priority must be higher than all other priorities used for correct behavior. Defaults to `880`.
- **default_color** (*Optional*): The color of the light. Defaults to `[255, 255, 255]`.
+- **effect_list** (*Optional*): The list of effects that can be used. Defaults to `['HDMI', 'Cinema brighten lights', 'Cinema dim lights', 'Knight rider', 'Blue mood blobs', 'Cold mood blobs', 'Full color mood blobs', 'Green mood blobs', 'Red mood blobs', 'Warm mood blobs', 'Police Lights Single', 'Police Lights Solid', 'Rainbow mood', 'Rainbow swirl fast', 'Rainbow swirl', 'Random', 'Running dots', 'System Shutdown', 'Snake', 'Sparks Color', 'Sparks', 'Strobe blue', 'Strobe Raspbmc', 'Strobe white', 'Color traces', 'UDP multicast listener', 'UDP listener', 'X-Mas']`.
diff --git a/source/_components/light.iglo.markdown b/source/_components/light.iglo.markdown
new file mode 100644
index 0000000000..5bc12ba1d6
--- /dev/null
+++ b/source/_components/light.iglo.markdown
@@ -0,0 +1,42 @@
+---
+layout: page
+title: "iGlo"
+description: "Instructions on how to integrate iGlo lights into Home Assistant."
+date: 2017-12-17 08:00
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: iglo.png
+ha_category: Light
+ha_iot_class: "Local Polling"
+ha_release: 0.61
+---
+
+The `iglo` platform allows you to integrate your [iGlo Lights](https://www.youtube.com/watch?v=oHTS9ji_v-s) into Home Assistant.
+
+To use your iGlo light in your installation, add the following to your `configuration.yaml` file:
+
+```yaml
+# Example configuration.yaml entry
+light:
+ - platform: iglo
+ host: 192.168.1.10
+```
+
+{% configuration %}
+host:
+ required: true
+ description: The IP address for connecting to the light.
+ type: string
+name:
+ required: false
+ description: The name for this light.
+ default: iGlo Light
+ type: string
+port:
+ required: false
+ description: The port used to connect to the light.
+ default: 8080
+ type: integer
+{% endconfiguration %}
diff --git a/source/_components/light.ihc.markdown b/source/_components/light.ihc.markdown
new file mode 100644
index 0000000000..214f19564b
--- /dev/null
+++ b/source/_components/light.ihc.markdown
@@ -0,0 +1,65 @@
+---
+layout: page
+title: "IHC Light"
+description: "Instructions on how to integrate IHC lights within Home Assistant."
+date: 2017-11-27 13:35
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: ihc.png
+ha_category: Light
+ha_release: 0.62
+ha_iot_class: "Local Push"
+---
+
+Before you can use the IHC Light 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 light devices:
+
+* Wireless lamp outlet dimmer
+* Wireless dimmer
+* Wireless combi dimmer 4 buttons
+* Wireless lamp outlet relay
+* Wireless combi relay 4 buttons
+* Wireless mobile dimmer
+* Dataline lamp outlet
+
+To manually configure IHC lights insert this section in your configuration:
+
+```yaml
+light:
+ - platform: ihc
+ lights:
+ - id: 12345
+ name: tablelight
+ dimmable: True
+ - id: 12346
+ name: anotherlight
+ ...
+```
+
+{% configuration %}
+lights:
+ description: List of lights to setup manually
+ required: false
+ type: map
+ keys:
+ dimmable:
+ description: Set to True if the IHC resource is a light level
+ required: false
+ type: bool
+ default: false
+ id:
+ description: The IHC resource id.
+ required: true
+ type: int
+ name:
+ description: The name of the component
+ required: false
+ type: string
+{% endconfiguration %}
+
+In the example above 12345 is ihc resource id and "tablelight" is the name.
+The IHC resource id can be a light level for dimmers or a boolean output of a relay.
+For more information about IHC resource ids see [Manual Setup](/components/ihc/#manual-setup)
diff --git a/source/_components/light.insteon_hub.markdown b/source/_components/light.insteon_hub.markdown
index 82c4df9aa5..f581706b92 100644
--- a/source/_components/light.insteon_hub.markdown
+++ b/source/_components/light.insteon_hub.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Insteon Hub Light"
-description: "Instructions how to setup the Insteon Hub Lights within Home Assistant."
+description: "Instructions on how to setup the Insteon Hub Lights within Home Assistant."
date: 2016-09-10 08:00
sidebar: true
comments: false
diff --git a/source/_components/light.insteon_local.markdown b/source/_components/light.insteon_local.markdown
index 14f91598c9..b9aacb3250 100644
--- a/source/_components/light.insteon_local.markdown
+++ b/source/_components/light.insteon_local.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Insteon (Local) Light"
-description: "Instructions how to setup the Insteon Hub Lights locally within Home Assistant."
+description: "Instructions on how to setup the Insteon Hub Lights locally within Home Assistant."
date: 2016-12-18 08:00
sidebar: true
comments: false
@@ -15,22 +15,4 @@ ha_iot_class: "Local Push"
The `insteon_local` light component lets you control your lights connected to an [Insteon Hub](http://www.insteon.com/insteon-hub/) with Home Assistant.
-To integrate add a light, 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 lights (dimmers) to your set-up, add the platform to your light configuration:
-
-```yaml
-light:
- - platform: insteon_local
-```
-
+To get your insteon lights working with Home Assistant, follow the instructions for the general [Insteon local component](/components/insteon_local/). The lights will be automatically disovered and added to Home Assistant. The device names will be the Insteon address of the lights.
diff --git a/source/_components/light.insteon_plm.markdown b/source/_components/light.insteon_plm.markdown
index 7c95d8dfe4..65026cf576 100644
--- a/source/_components/light.insteon_plm.markdown
+++ b/source/_components/light.insteon_plm.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Insteon PLM Light"
-description: "Instructions how to setup Insteon PLM lights locally within Home Assistant."
+description: "Instructions on how to setup Insteon PLM lights locally within Home Assistant."
date: 2017-02-19 17:00
sidebar: true
comments: false
@@ -13,5 +13,5 @@ ha_iot_class: "Local Push"
ha_version: 0.39
---
-The `insteon_plm` light platform lets you control your sensors through an INSTEON PowerLinc Modem (PLM) device connected directly to your system on an USB or serial port. To add support, set up the primary [insteon_plm](/components/insteon_plm/) component.
+The `insteon_plm` light platform lets you control your dimmable light switches through an INSTEON PowerLinc Modem (PLM) device connected directly to your system on an USB or serial port. To add support, set up the primary [insteon_plm](/components/insteon_plm/) component.
diff --git a/source/_components/light.isy994.markdown b/source/_components/light.isy994.markdown
index 8ae450edfc..6c03413c8b 100644
--- a/source/_components/light.isy994.markdown
+++ b/source/_components/light.isy994.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "ISY994 Light"
-description: "Instructions how to integrate ISY994 lights into Home Assistant."
+description: "Instructions on how to integrate ISY994 lights into Home Assistant."
date: 2016-09-03 23:00
sidebar: true
comments: false
diff --git a/source/_components/light.lifx.markdown b/source/_components/light.lifx.markdown
index 805cb67e68..04f444540f 100644
--- a/source/_components/light.lifx.markdown
+++ b/source/_components/light.lifx.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "LIFX"
-description: "Instructions how to integrate LIFX into Home Assistant."
+description: "Instructions on how to integrate LIFX into Home Assistant."
date: 2016-01-27 08:00
sidebar: true
comments: false
diff --git a/source/_components/light.limitlessled.markdown b/source/_components/light.limitlessled.markdown
index bc0849cbca..2dcf4d9c7a 100644
--- a/source/_components/light.limitlessled.markdown
+++ b/source/_components/light.limitlessled.markdown
@@ -18,7 +18,7 @@ ha_release: pre 0.7
### {% linkable_title Setup %}
-Before configuring Home Assistant, make sure you can control your bulbs or LEDs with the MiLight mobile application. Discover your bridge(s) IP address. You can do this via your router or a mobile application like Fing ([android](https://play.google.com/store/apps/details?id=com.overlook.android.fing&hl=en) or [iTunes](https://itunes.apple.com/us/app/fing-network-scanner/id430921107?mt=8)). Keep in mind that LimitlessLED bulbs are controlled via groups. You can not control an individual bulb via the bridge, unless it is in a group by itself. Note that you can assign an `rgbw`, `rgbww` and `white` group to the same group number, effectively allowing 12 groups (4 `rgbww`, 4 `rgbw` and 4 `white`) per bridge.
+Before configuring Home Assistant, make sure you can control your bulbs or LEDs with the MiLight mobile application. Discover your bridge(s) IP address. You can do this via your router or a mobile application like Fing ([android](https://play.google.com/store/apps/details?id=com.overlook.android.fing&hl=en) or [iTunes](https://itunes.apple.com/us/app/fing-network-scanner/id430921107?mt=8)). Keep in mind that LimitlessLED bulbs are controlled via groups. You can not control an individual bulb via the bridge, unless it is in a group by itself. Note that you can assign an `rgbw`, `rgbww`, `white` and `dimmer` group to the same group number, effectively allowing 16 groups (4 `rgbww`, 4 `rgbw`, 4 `white` and 4 `dimmer`) per bridge.
To add `limitlessled` to your installation, add the following to your `configuration.yaml` file:
@@ -38,6 +38,9 @@ light:
type: rgbw
name: Kitchen
fade: on
+ - number: 4
+ type: dimmer
+ name: Livingroom
- host: 192.168.1.11
groups:
- number: 1
@@ -56,7 +59,7 @@ Configuration variables:
- **groups** array (*Required*): The list of available groups.
- **number** (*Required*): Group number (`1`-`4`). Corresponds to the group number on the remote. These numbers may overlap only if the type is different.
- **name** (*Required*): Any name you'd like. Must be unique among all configured groups.
- - **type** (*Optional*): Type of group. Choose either `rgbww`, `rgbw`, `white`, or `bridge-led`. `rgbw` is the default if you don't specify this entry. Use `bridge-led` to control the built-in LED of newer WiFi bridges.
+ - **type** (*Optional*): Type of group. Choose either `rgbww`, `rgbw`, `white`, `bridge-led` or `dimmer`. `rgbw` is the default if you don't specify this entry. Use `bridge-led` to control the built-in LED of newer WiFi bridges.
- **fade** (*Optional*): Fade behavior. Defaults to `off`. If turned on, the group is faded out before being turned off. This makes for a more pleasing transition at the expense of wall switch usability, since the light will turn back on at the lowest brightness if it is power cycled.
### {% linkable_title Properties %}
@@ -74,9 +77,29 @@ Refer to the [light]({{site_root}}/components/light/) documentation for general
- When using a legacy WiFi bridge (before v6), you can observe on the MiLight mobile application, you can not select a specific brightness or temperature - you can only step each property up or down. There is no indication of which step you are on. This restriction, combined with the unreliable nature of LimitlessLED transmissions, means that setting white bulb properties is done on a best-effort basis. The only very reliable settings are the minimum and maximum of each property.
- *Temperature*: Wifi bridge v6 supports 101 temperature steps; older versions only 10.
- *Brightness*: Wifi bridge v6 supports 101 brightness steps; older versions only 10.
+- **Dimmer** (Only supported on v6 bridges)
+ - This type is for a single color LED dimmer like the 1CH MiLight dimmer module or similar. This type is only supported by the version 6 Wifi bridges.
+ - *Brightness*: Wifi bridge v6 supports 101 brightness steps.
- **Transitions**
- If a transition time is set, the group will transition between the current settings and the target settings for the duration specified. Transitions from or to white are not possible - the color will change immediately.
### {% linkable_title Initialization & Synchronization %}
-When starting Home Assistant, your LimitlessLED bulbs will be set to known default values. This ensures a consistent user interface and uninterrupted turning on/off. If you control your LimitlessLED lights via the MiLight mobile application or other means while Home Assistant is running, Home Assistant can not track those changes and you may observe unexpected behavior. This is due to a LimitlessLED limitation.
+When starting Home Assistant, the last recorded state will be shown. This might no longer match the actual state of the bulbs.
+
+If you control your LimitlessLED lights via the MiLight mobile application or other means while Home Assistant is running, Home Assistant can not track those changes and you may observe obsolete information.
+
+This lack of synchronization is due to a LimitlessLED limitation.
+
+
+
-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
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 54732fe5bf..6e70c8be89 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.
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 4bf9a9d28a..5f91aa43fe 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 f9ceacdb22..9cc2555fb1 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 0000000000..4f066dc7b2
--- /dev/null
+++ b/source/_components/light.nanoleaf_aurora.markdown
@@ -0,0 +1,52 @@
+---
+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 %}
+
+To enable the Aurora lights, 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 86fa342c9b..df1abeece9 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
diff --git a/source/_components/light.piglow.markdown b/source/_components/light.piglow.markdown
index d261a81648..c2664af84c 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 e1f600c98f..13f61413f6 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 0bd73b588e..cc56e6de3e 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 ee5c513fe8..b6a1b707cf 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
diff --git a/source/_components/light.scsgate.markdown b/source/_components/light.scsgate.markdown
index 5625b43cfb..07df0ca0f7 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 b2bb9dbce5..55e09b1219 100644
--- a/source/_components/light.sensehat.markdown
+++ b/source/_components/light.sensehat.markdown
@@ -1,7 +1,7 @@
---
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
diff --git a/source/_components/light.tellstick.markdown b/source/_components/light.tellstick.markdown
index a81d238464..9c66e121ec 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 58648b4735..9d1315b310 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
@@ -51,6 +51,10 @@ light:
description: Name to use in the frontend.
required: false
type: string
+ entity_id:
+ 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:
description: Defines a template to get the state of the light.
required: false
diff --git a/source/_components/light.tplink.markdown b/source/_components/light.tplink.markdown
index 68fff98395..158504bcae 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.vera.markdown b/source/_components/light.vera.markdown
index da0fc42fff..dba42ffcaf 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 a2ff553aad..1ae147ef86 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 5e7b74771e..e537c11601 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 b79a881441..45df065a49 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
diff --git a/source/_components/light.xiaomi_aqara.markdown b/source/_components/light.xiaomi_aqara.markdown
index 25e01ba22c..48bf4fb135 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 5f76deb341..991ff8c97f 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
@@ -13,9 +13,54 @@ ha_version: 0.53
ha_iot_class: "Local Polling"
---
-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,99 @@ 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.
+- **model** (*Optional*): The model of your 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.
+
+{% configuration %}
+host:
+ description: The IP address of your device.
+ required: true
+ type: string
+token:
+ description: The API token of your device.
+ required: true
+ type: string
+name:
+ description: The name of your device.
+ required: false
+ type: string
+ default: Xiaomi Philips Light
+model:
+ description: The model of your device.
+ 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 2d836c596a..8ee047b47f 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.
@@ -61,8 +61,19 @@ This component is tested to work with the following models. If you have a differ
- **YLDP03YL**: LED Bulb (Color) - E26
- **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 a 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 1b0e441970..0583084626 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 ed15a92752..b2f46b065d 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 c3b0cc2d8b..904c1e59de 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 5730043d1e..a7d8529551 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 4053e61f1d..891f63e886 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 ffe675ea0c..1c6dc56be3 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,14 +32,14 @@ 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.
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 53f2e26e79..558f9098b9 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 01d9910fda..affd029f63 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 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 8baf864dfd..a305038987 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 2e72677179..e3c2d31e85 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 1f51751b3f..a792e130a8 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
diff --git a/source/_components/lock.zwave.markdown b/source/_components/lock.zwave.markdown
index e1d6fd7b33..ba25eacd6c 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 74e493fc9b..438e747430 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"
---
-
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.
+When starting or restarting Home Assistant make sure your TV is off. This is a flaw in the TV itself.
+
+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.
+
+ The component was removed. The vendor disabled the API endpoint and a new API is not available currently.
+
+The minimal setup uses the embedded MQTT broker, however a separate broker is advised for more stability.
+
-Namecheap only supports IPv4 adresses to update.
+Namecheap only supports IPv4 addresses to update.
-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. The start/stop functionality does not work. More information on how to update here: https://support.neatorobotics.com/hc/en-us/articles/115004320694-Software-Update-4-0-for-Neato-Botvac-Connected-D3-D5-
+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. The start/stop functionality does not work. 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-).
`month`
`day` | The year, month and day of the date.
(only availabel if `has_date: true`)
+| `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 supports the `restore_state` function which restores the state after Home Assistant has started to the value it has been before Home Assistant stopped. To use this feature please make sure that the [`recorder`](/components/recorder/) component is enabled and your entity does not have a value set 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 32829baeff..44d819c39c 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/
---
+Example of the light group "Kitchen Lights".
+
+configuration.yaml
Turns one light on or multiple lights on using [groups]({{site_root}}/components/group/).
-Most lights do not support all attributes. You can check the platform documentation of your particular light for hints but in general you will have to try things out and see what works.
+Most lights do not support all attributes. You can check the platform documentation of your particular light for hints, but in general, you will have to try things out and see what works.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of lights. Else targets all.
| `transition` | yes | Number that represents the time (in seconds) the light should take to transition to the new state.
-| `profile` | yes | String with the name of one of the [built-in profiles](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/light/light_profiles.csv) (relax, energize, concentrate, reading) or one of the custom profiles defined in `light_profiles.csv` in the current working directory. Light profiles define a xy color and a brightness. If a profile is given and a brightness then the profile brightness will be overwritten.
-| `xy_color` | yes | A list containing two floats representing the xy color you want the light to be. Two comma separated floats that represent the color in XY.
-| `rgb_color` | yes | A list containing three integers representing the rgb color you want the light to be. Three comma separated integers that represent the color in RGB. You can find a great chart here: [Hue Color Chart](http://www.developers.meethue.com/documentation/hue-xy-values)
+| `profile` | yes | String with the name of one of the [built-in profiles](https://github.com/home-assistant/home-assistant/blob/master/homeassistant/components/light/light_profiles.csv) (relax, energize, concentrate, reading) or one of the custom profiles defined in `light_profiles.csv` in the current working directory. Light profiles define an xy color and a brightness. If a profile is given and a brightness then the profile brightness will be overwritten.
+| `hs_color` | yes | A list containing two floats representing the hue and saturation of the color you want the light to be. Hue is scaled 0-360, and saturation is scaled 0-100.
+| `xy_color` | yes | A list containing two floats representing the xy color you want the light to be. Two comma-separated floats that represent the color in XY. You can find a great chart here: [Hue Color Chart](https://developers.meethue.com/documentation/core-concepts#color_gets_more_complicated).
+| `rgb_color` | yes | A list containing three integers between 0 and 255 representing the RGB color you want the light to be. Three comma-separated integers that represent the color in RGB. Note that the specified RGB value will not change the light brightness, only the color.
| `white_value` | yes | Integer between 0 and 255 for how bright a dedicated white LED should be.
| `color_temp` | yes | An integer in mireds representing the color temperature you want the light to be.
| `kelvin` | yes | Alternatively, you can specify the color temperature in Kelvin.
-| `color_name` | yes | A human readable string of a color name, such as `blue` or `goldenrod`. All [CSS3 color names](https://www.w3.org/TR/2010/PR-css3-color-20101028/#svg-color) are supported.
+| `color_name` | yes | A human-readable string of a color name, such as `blue` or `goldenrod`. All [CSS3 color names](https://www.w3.org/TR/css-color-3/#svg-color) are supported.
| `brightness` | yes | Integer between 0 and 255 for how bright the color should be.
| `brightness_pct`| yes | Alternatively, you can specify brightness in percent (a number between 0 and 100).
| `flash` | yes | Tell light to flash, can be either value `short` or `long`.
| `effect`| yes | Applies an effect such as `colorloop` or `random`.
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/logger.markdown b/source/_components/logger.markdown
index 70168cf440..2f89e09096 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
diff --git a/source/_components/lutron.markdown b/source/_components/lutron.markdown
index c946160db1..6799e1feb5 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 912bd82dc4..9783766c89 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 25a0859aa9..15d5ec455f 100644
--- a/source/_components/mailbox.asterisk_mbox.markdown
+++ b/source/_components/mailbox.asterisk_mbox.markdown
@@ -1,15 +1,16 @@
---
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
---
-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 88ff203523..16bfa603b8 100644
--- a/source/_components/mailbox.markdown
+++ b/source/_components/mailbox.markdown
@@ -1,7 +1,7 @@
---
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
@@ -10,7 +10,7 @@ ha_version: 0.51
footer: true
---
-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.
diff --git a/source/_components/mailgun.markdown b/source/_components/mailgun.markdown
index 835464dfd0..2f13d2c062 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 d7e663e8e5..e776db61a3 100644
--- a/source/_components/media_player.philips_js.markdown
+++ b/source/_components/media_player.philips_js.markdown
@@ -29,3 +29,5 @@ 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`.
diff --git a/source/_components/media_player.pioneer.markdown b/source/_components/media_player.pioneer.markdown
index 66086c5ded..6bc6d1a5b0 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 ddaf3a611b..e17068d221 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 5c889727de..c7771e0f40 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 f64277c404..d944b2b3a7 100644
--- a/source/_components/media_player.samsungtv.markdown
+++ b/source/_components/media_player.samsungtv.markdown
@@ -50,12 +50,17 @@ 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)
- 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)
@@ -72,8 +77,10 @@ Currently tested but not working models:
- JS9500 - State is always "on" and unable to control (but port 8001 *is* open)
- 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.
diff --git a/source/_components/media_player.songpal.markdown b/source/_components/media_player.songpal.markdown
new file mode 100644
index 0000000000..0fd9a73f72
--- /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.sonos.markdown b/source/_components/media_player.sonos.markdown
index 3afe420ff4..862cd822f8 100644
--- a/source/_components/media_player.sonos.markdown
+++ b/source/_components/media_player.sonos.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Sonos"
-description: "Instructions how to integrate Sonos devices into Home Assistant."
+description: "Instructions on how to integrate Sonos devices into Home Assistant."
date: 2015-09-12 13:00
sidebar: true
comments: false
diff --git a/source/_components/media_player.soundtouch.markdown b/source/_components/media_player.soundtouch.markdown
index fa2a550b02..463914f236 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 ec34749834..7097e06e20 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://
-
- 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).
-
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).
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:
@@ -69,11 +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:
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 4b003d97d8..5b1ce8ed54 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 370f26be8c..4d1d83c581 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 2c014c3054..19d9c876d9 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 16bf7e992a..2491bac32e 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 4747d9a5f4..2556c82037 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 75b5419f59..3e38499010 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
diff --git a/source/_components/notify.smtp.markdown b/source/_components/notify.smtp.markdown
index 533129e36c..130f3dcf0d 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