-`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,8 +19,7 @@ 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" + ] } ``` @@ -33,4 +28,3 @@ Configuration variables: - **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 statically. -- **interface** (*Optional*): If an interface is set, it listens only on this interface. Needs to be set for ResinOS. Normally is `eth0` for ethernet wired connection and `wlan0` for wireless connection. diff --git a/source/_addons/duckdns.markdown b/source/_addons/duckdns.markdown index 297cbb8fd9..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/ @@ -49,3 +51,5 @@ If you use a port other than `8123` or an SSL proxy, change the port number acco 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/google_assistant.markdown b/source/_addons/google_assistant.markdown index ac0765bc51..f48415638e 100644 --- a/source/_addons/google_assistant.markdown +++ b/source/_addons/google_assistant.markdown @@ -11,7 +11,7 @@ featured: true ---- If you want 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. @@ -66,7 +66,7 @@ Configuration example that uses the USB microphone and the built-in headset audi 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 %} diff --git a/source/_addons/homematic.markdown b/source/_addons/homematic.markdown index 8cf3c3b9b3..6a92bbff81 100644 --- a/source/_addons/homematic.markdown +++ b/source/_addons/homematic.markdown @@ -57,7 +57,7 @@ Use the following configuration in Home Assistant to use it: ```yaml homematic: interfaces: - BidCoS-RF: + rf: host: core-homematic port: 2001 ``` diff --git a/source/_addons/lets_encrypt.markdown b/source/_addons/lets_encrypt.markdown index fe3894e6f8..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,7 +14,7 @@ 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 addon will create a certificate on the first run and will auto-renew if the certificate is within 30 days of expiration. +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 { @@ -41,4 +41,24 @@ http: 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 673857de06..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 de3df29894..f143d9ac34 100644 --- a/source/_addons/mosquitto.markdown +++ b/source/_addons/mosquitto.markdown @@ -43,7 +43,7 @@ Configuration variables: ### {% 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 8fd22956e7..e1d8a5f01c 100644 --- a/source/_addons/nginx_proxy.markdown +++ b/source/_addons/nginx_proxy.markdown @@ -11,17 +11,29 @@ footer: true 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 a HTTP 502 error. +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 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/samba.markdown b/source/_addons/samba.markdown
index 33e573ec37..9d0f18923f 100644
--- a/source/_addons/samba.markdown
+++ b/source/_addons/samba.markdown
@@ -22,7 +22,7 @@ This addon allows you to set up a [Samba](https://samba.org/) server to access h
"addons": true,
"share": true,
"backup": true,
- "ssl": false,
+ "ssl": false
},
"username": "",
"password": "",
@@ -32,10 +32,10 @@ This addon allows you to set up a [Samba](https://samba.org/) server to access h
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 exposed. `config` is for Home Assistant configuration folder. `addons` for a local custom repository. `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 `
+`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.
+
+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.
+
+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/).
+
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
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.
+
-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*`).
+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 ef695f4601..49486d62d7 100644 --- a/source/_components/binary_sensor.hive.markdown +++ b/source/_components/binary_sensor.hive.markdown @@ -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 index 5a3d7769de..da5aac7615 100644 --- a/source/_components/binary_sensor.ihc.markdown +++ b/source/_components/binary_sensor.ihc.markdown @@ -1,7 +1,7 @@ --- layout: page title: "IHC Binary Sensor" -description: "Instructions how to integrate IHC Binary Sensors within Home Assistant." +description: "Instructions on how to integrate IHC Binary Sensors within Home Assistant." date: 2017-11-27 13:35 sidebar: true comments: false 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 781f4f4557..fe8f4a5107 100644 --- a/source/_components/binary_sensor.markdown +++ b/source/_components/binary_sensor.markdown @@ -11,6 +11,8 @@ 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. @@ -22,6 +24,7 @@ The way these sensors are displayed in the frontend can be modified in the [cust - **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) @@ -37,4 +40,9 @@ The way these sensors are displayed in the frontend can be modified in the [cust - **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.
+
+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 00bdca07f7..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: @@ -111,7 +111,7 @@ Home Assistant does its best to determine what task in each project is "most" im 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 2672c6c48e..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 diff --git a/source/_components/camera.doorbird.markdown b/source/_components/camera.doorbird.markdown index d96a1ebe9b..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 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 71a16ba40e..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 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 2d92253993..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 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 0cfa7cf453..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 -- **extra_arguments** (*Optional*): Extra options to pass to `ffmpeg`, e.g. image quality or video filter options. More details in [FFmpeg component](/components/ffmpeg). +- **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.+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.
@@ -68,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.ecobee.markdown b/source/_components/climate.ecobee.markdown index e8711168e7..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 diff --git a/source/_components/climate.econet.markdown b/source/_components/climate.econet.markdown index 3feb4aa643..704c6ebf0e 100644 --- a/source/_components/climate.econet.markdown +++ b/source/_components/climate.econet.markdown @@ -1,7 +1,7 @@ --- layout: page title: "EcoNet water heater" -description: "Instructions how to integrate Rheem EcoNet water heaters into Home Assistant." +description: "Instructions on how to integrate Rheem EcoNet water heaters into Home Assistant." date: 2017-12-28 14:51 sidebar: true comments: false 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.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 dd3fd41ca5..12f4688553 100644 --- a/source/_components/climate.hive.markdown +++ b/source/_components/climate.hive.markdown @@ -14,13 +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**. + 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 Hive climate component supports the following Hive products: -- **Hive Active Heating** -- **Hive Multizone** -- **Hot water control** +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 8104a6a77f..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 diff --git a/source/_components/climate.markdown b/source/_components/climate.markdown index 53cfc08013..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 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 504610dea4..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 @@ -178,11 +178,11 @@ aux_state_template: #### {% linkable_title Optimistic mode %} -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. +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 Using Templates %} -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. +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: 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 index 51ffd6fee4..46a8e84c5a 100644 --- a/source/_components/climate.nuheat.markdown +++ b/source/_components/climate.nuheat.markdown @@ -1,7 +1,7 @@ --- layout: page title: "NuHeat Thermostat" -description: "Instructions how to integrate your NuHeat Signature thermostats within Home Assistant." +description: "Instructions on how to integrate your NuHeat Signature thermostats within Home Assistant." date: 2017-11-11 18:00 sidebar: true comments: false diff --git a/source/_components/climate.oem.markdown b/source/_components/climate.oem.markdown index be9b8cda21..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 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 index ebc48a9df8..0f7f271946 100644 --- a/source/_components/climate.touchline.markdown +++ b/source/_components/climate.touchline.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Roth Touchline" -description: "Instructions how to integrate Roth Touchline within Home Assistant." +description: "Instructions on how to integrate Roth Touchline within Home Assistant." date: 2018-01-03 12:35 sidebar: true comments: false 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 d45e9aa15f..3008a52cac 100644 --- a/source/_components/cloud.markdown +++ b/source/_components/cloud.markdown @@ -13,27 +13,7 @@ ha_category: Voice ha_iot_class: "Cloud Push" --- -
The Home Assistant Cloud is currently in open beta and will become part of the upcoming Community Support Package. [Learn more](/blog/2017/12/17/introducing-home-assistant-cloud/)
- -The Home Assistant Cloud allows you to quickly integrate your local Home Assistant with various cloud services like Amazon Alexa. - -The following integrations are currently available: - - - [Amazon Alexa (Amazon Echo)](/components/cloud.alexa/) - - - -### {% linkable_title How does it work? %} - -The Home Assistant Cloud has been designed with security in mind. When you activate the Cloud component, your instance will create a secure connection to the Home Assistant Cloud. There is no need for any further configuration or to expose your instance to the internet. - -Integrations like Alexa will deliver messages to our cloud which we will forward to your local instance for processing. We just forward the response back to Alexa. This means that we do not have to store the state of your house in our cloud, we’re just the messenger! - -You can find a list of frequently asked questions (and their answers) in [this blog post](/blog/2017/12/17/introducing-home-assistant-cloud/#faq). - -### {% linkable_title Enabling the cloud %} - -The Home Assistant Cloud is enabled by default. If not, add this to your configuration: +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 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/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 index 6b65b08664..d1fde01521 100644 --- a/source/_components/deconz.markdown +++ b/source/_components/deconz.markdown @@ -17,29 +17,33 @@ ha_iot_class: "Local Push" [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 GUI to create an API key. When you've generated the API key from Home Assistant, the API key will be stored in deconz.conf inside the home-assistant folder. +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 + host: IP_ADDRESS ``` -#### {% linkable_title Supported Device types %} - -- [Zigbee Lights](/components/light.deconz/) -- [Humidity Sensors](/components/sensor.deconz/) -- [Light Level Sensors](/components/sensor.deconz/) -- [OpenClose Detectors](/components/binary_sensor.deconz/) -- [Presence Detectors](/components/binary_sensor.deconz/) -- [Pressure Sensors](/components/sensor.deconz/) -- [Switches (Remote Controls)](/components/sensor.deconz/) -- [Temperature Sensors](/components/sensor.deconz/) - {% configuration %} host: description: The IP address of your deCONZ web server. @@ -66,22 +70,41 @@ deconz: 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` %} +#### {% 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%} +## {% 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. @@ -96,10 +119,13 @@ Typical values for switches, the event codes are 4 numbers where the first and l 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' @@ -126,9 +152,9 @@ automation: - service: light.turn_on data_template: entity_id: light.lamp - brightness: {% raw %}> + brightness: > {% set bri = states.light.lamp.attributes.brightness | int %} - {{ [bri+30, 249] | min }}{% endraw %} + {{ [bri+30, 249] | min }} - alias: 'Decrease brightness of lamp from dimmer' initial_state: 'on' @@ -142,7 +168,8 @@ automation: - service: light.turn_on data_template: entity_id: light.lamp - brightness: {% raw %}> + brightness: > {% set bri = states.light.lamp.attributes.brightness | int %} - {{ [bri-30, 0] | max }}{% endraw %} + {{ [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 03b844f667..ce1dab5000 100644 --- a/source/_components/device_tracker.bluetooth_le_tracker.markdown +++ b/source/_components/device_tracker.bluetooth_le_tracker.markdown @@ -48,7 +48,7 @@ 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 %} 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 34465aec4f..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 @@ -39,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**.
@@ -56,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
@@ -65,8 +65,8 @@ 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.
+- 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]`.
diff --git a/source/_components/device_tracker.huawei_router.markdown b/source/_components/device_tracker.huawei_router.markdown
index 6c9647ac3c..92ee5c62d4 100644
--- a/source/_components/device_tracker.huawei_router.markdown
+++ b/source/_components/device_tracker.huawei_router.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "Huawei Router"
-description: "Instructions how to integrate Huawei Routers into Home Assistant."
+description: "Instructions on how to integrate Huawei Routers into Home Assistant."
date: 2017-07-16 01:40
sidebar: true
comments: false
@@ -12,9 +12,12 @@ ha_category: Presence Detection
ha_release: 0.51
---
-This component offers presence detection by looking at connected devices to a [Huawei router](http://m.huawei.com/enmobile/enterprise/products/network/access/pon-one/hw-371813.htm).
+The `huawei` device trakcer platform offers presence detection by looking at connected devices to a [Huawei router](http://m.huawei.com/enmobile/enterprise/products/network/access/pon-one/hw-371813.htm).
+
Currently, this was only tested with the Huawei HG8247H and HG8247Q Smart Router (used by Vodafone Portugal).
+## {% linkable_title Configuration %}
+
To use a Huawei router in your installation, add the following to your `configuration.yaml` file:
```yaml
@@ -22,15 +25,23 @@ To use a Huawei router in your installation, add the following to your `configur
device_tracker:
- platform: huawei_router
host: 192.168.1.1
- username: user
- password: pass
+ username: YOUR_USERNAME
+ password: YOUR_PASSWORD
```
-Configuration variables:
-
-- **host** (*Required*): The IP address of your router, e.g. 192.168.1.1.
-- **username** (*Required*): The username to login into the router (the same used trough the router's web interface).
-- **password** (*Required*): The password for the specified username.
-
+{% configuration %}
+host:
+ description: The IP address of your router, e.g., 192.168.1.1.
+ required: true
+ type: string
+username:
+ description: The username to login into the router (the same used trough the router's web interface).
+ required: true
+ type: string
+password:
+ description: The password for the specified username.
+ required: true
+ type: string
+{% endconfiguration %}
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.icloud.markdown b/source/_components/device_tracker.icloud.markdown
index 74f22f02f6..a57ba44d4b 100644
--- a/source/_components/device_tracker.icloud.markdown
+++ b/source/_components/device_tracker.icloud.markdown
@@ -1,7 +1,7 @@
---
layout: page
title: "iCloud"
-description: "Instructions how to use iCloud to track devices in Home Assistant."
+description: "Instructions on how to use iCloud to track devices in Home Assistant."
date: 2015-12-15 1000
sidebar: true
comments: false
@@ -33,9 +33,11 @@ Configuration variables:
- **username** (*Required*): The username for the iCloud account.
- **password** (*Required*): The password for your given username.
- **account_name** (*Optional*): The friendly name for the account_name. If this isn't given, it will use the account_name of the username (so the part before the `@` in the email address).
+- **max_interval** (*Optional*): Maximum interval in minutes between subsequent location upates. This tracker uses dynamic intervals for requesting location updates. When iphone is stationary, interval will eventually be set to `max_interval` to save battery. When iphone starts moving again interval will be dynamically updated to 1 min. Note that updating interval to 1 min might be delayed by maximum `max_interval` minutes. Default is 30 min. Minimum value is 1 min.
+- **gps_accuracy_threshold** (*Optional*): iCloud location updates come with some gps_accuracy varying from 10 to 5000 meters. This setting defines the accuracy threshold in meters for a location update. Less accurate updates will be discarded by this tracker. This allows more precise location monitoring and fewer false positive zone changes. Default is 1000 meters.
-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 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 631d8dc669..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,13 +13,8 @@ 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 iOS phones and publish it to an MQTT broker. This platform will connect to the broker and monitor for new locations. --The Android app for OwnTracks is no longer developed or supported, Zanzito is a drop in replacement for OwnTracks MQTT. -
- This component requires [the MQTT component](/components/mqtt/) to be set up and works very well together with [the zone component](/components/zone/). To integrate Owntracks in Home Assistant, add the following section to your `configuration.yaml` file: @@ -34,7 +29,7 @@ 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. @@ -59,6 +54,7 @@ device_tracker: ``` ### {% 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 `-The Android app for OwnTracks is no longer developed or supported. Consider [GPS Logger](/components/device_tracker.gpslogger/) as an alternative. -
- To integrate Owntracks tracking via HTTP in Home Assistant, add the following section to your `configuration.yaml` file: ```yaml @@ -36,5 +32,21 @@ Open OwnTracks and go to Connection preferences: - Mode: Select **Private HTTP** - Host: [Home Assistant URL]:[port]/api/owntracks/[your name]/[device name] - Identification: Turn **Authentication** on, username `homeassistant` and password is your API password that you use to login to Home Assistant. - + Host example: If I host my Home Assistant at `https://example.duckdns.org`, my name is Paulus and my phone is a Pixel I would set the host to be `https://example.duckdns.org/api/owntracks/paulus/pixel`. This will result in an entity with an ID of `device_tracker.paulus_pixel`. You can pick any name for the user and the device. + +Since the battery data is available as an attribute of the device tracker entity, it can be tracked with a [`template` sensor](/components/sensor.template/). + +{% raw %} +```yaml +# Example configuration.yaml entry +sensor: + - platform: template + sensors: + pixel_battery: + friendly_name: Pixel of Paulus + unit_of_measurement: "%" + value_template: '{{ states.device_tracker.paulus_pixel.attributes.battery|int }}' + device_class: battery +``` +{% endraw %} diff --git a/source/_components/device_tracker.ping.markdown b/source/_components/device_tracker.ping.markdown index 7979881198..1f34368012 100644 --- a/source/_components/device_tracker.ping.markdown +++ b/source/_components/device_tracker.ping.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Ping (ICMP)" -description: "Instructions how to integrate Ping (ICMP)-based presence detection into Home Assistant." +description: "Instructions on how to integrate Ping (ICMP)-based presence detection into Home Assistant." date: 2017-01-06 08:00 sidebar: true comments: false diff --git a/source/_components/device_tracker.sky_hub.markdown b/source/_components/device_tracker.sky_hub.markdown index e5a1271894..792aece8a8 100644 --- a/source/_components/device_tracker.sky_hub.markdown +++ b/source/_components/device_tracker.sky_hub.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Sky Hub" -description: "Instructions how to integrate Sky Hub routers into Home Assistant." +description: "Instructions on how to integrate Sky Hub routers into Home Assistant." date: 2017-01-28 09:00 sidebar: true comments: false diff --git a/source/_components/device_tracker.snmp.markdown b/source/_components/device_tracker.snmp.markdown index 60c14a1f87..8193abfee8 100644 --- a/source/_components/device_tracker.snmp.markdown +++ b/source/_components/device_tracker.snmp.markdown @@ -1,7 +1,7 @@ --- layout: page title: "SNMP" -description: "Instructions how to integrate SNMP into Home Assistant." +description: "Instructions on how to integrate SNMP into Home Assistant." date: 2015-10-08 12:00 sidebar: true comments: false diff --git a/source/_components/device_tracker.swisscom.markdown b/source/_components/device_tracker.swisscom.markdown index bee21be205..49c4f72ba9 100644 --- a/source/_components/device_tracker.swisscom.markdown +++ b/source/_components/device_tracker.swisscom.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Swisscom Internet-Box" -description: "Instructions how to integrate Swisscom Internet-Box into Home Assistant." +description: "Instructions on how to integrate Swisscom Internet-Box into Home Assistant." date: 2016-10-29 23:30 sidebar: true comments: false diff --git a/source/_components/device_tracker.tado.markdown b/source/_components/device_tracker.tado.markdown index bc1d91b37b..70f130c7e0 100644 --- a/source/_components/device_tracker.tado.markdown +++ b/source/_components/device_tracker.tado.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Tado" -description: "Instructions how to integrate Tado into Home Assistant." +description: "Instructions on how to integrate Tado into Home Assistant." date: 2017-01-17 12:00 sidebar: true comments: false diff --git a/source/_components/device_tracker.thomson.markdown b/source/_components/device_tracker.thomson.markdown index f9d39eb6d7..810d586d27 100644 --- a/source/_components/device_tracker.thomson.markdown +++ b/source/_components/device_tracker.thomson.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Thomson" -description: "Instructions how to integrate Thomson routers into Home Assistant." +description: "Instructions on how to integrate Thomson routers into Home Assistant." date: 2015-08-30 19:00 sidebar: true comments: false diff --git a/source/_components/device_tracker.tile.markdown b/source/_components/device_tracker.tile.markdown index 63ba3d693c..8abb07a676 100644 --- a/source/_components/device_tracker.tile.markdown +++ b/source/_components/device_tracker.tile.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Tile" -description: "Instructions how to use Tile to track devices in Home Assistant." +description: "Instructions on how to use Tile to track devices in Home Assistant." date: 2017-11-08 20:40:00 sidebar: true comments: false diff --git a/source/_components/device_tracker.tomato.markdown b/source/_components/device_tracker.tomato.markdown index 3c5eca66ca..279cd63b68 100644 --- a/source/_components/device_tracker.tomato.markdown +++ b/source/_components/device_tracker.tomato.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Tomato" -description: "Instructions how to integrate Tomato routers into Home Assistant." +description: "Instructions on how to integrate Tomato routers into Home Assistant." date: 2015-03-23 19:59 sidebar: true comments: false @@ -31,11 +31,11 @@ device_tracker: {% configuration %} host: - description: "The IP address or hostname of your router, e.g. `192.168.1.1` or `rt-ac68u`." + description: "The IP address or hostname of your router, e.g., `192.168.1.1` or `rt-ac68u`." required: false type: string port: - description: "The port number of your router, e.g. `443`." + description: "The port number of your router, e.g., `443`." required: false type: int default: 80/443 (automatically detected) @@ -45,7 +45,7 @@ ssl: type: bool default: false verify_ssl: - description: "If SSL verification for https resources needs to be turned off (for self-signed certs, etc.) this can take on boolean values `False` or `True` or you can pass a location on the device where a certificate can be used for verification e.g. `/mnt/NAS/router_cert.pem`." + description: "If SSL verification for https resources needs to be turned off (for self-signed certs, etc.) this can take on boolean values `False` or `True` or you can pass a location on the device where a certificate can be used for verification e.g., `/mnt/NAS/router_cert.pem`." required: false type: [string, bool] default: true diff --git a/source/_components/device_tracker.tplink.markdown b/source/_components/device_tracker.tplink.markdown index 89897bb1e0..29b70a143a 100644 --- a/source/_components/device_tracker.tplink.markdown +++ b/source/_components/device_tracker.tplink.markdown @@ -1,7 +1,7 @@ --- layout: page title: "TP-Link" -description: "Instructions how to integrate TP-Link routers into Home Assistant." +description: "Instructions on how to integrate TP-Link routers into Home Assistant." date: 2015-06-22 10:30 sidebar: true comments: false @@ -31,7 +31,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. @@ -41,7 +41,7 @@ For Archer C9 models running firmware version 150811 or later please use the enc 2. Type in the password you use to login into the password field. 3. Click somewhere else on the page so that the password field is not selected anymore. 4. Open the JavaScript console of your browser (usually by pressing F12 and then clicking on "Console"). -5. Type ```document.getElementById("login-password").value;```. +5. Type `document.getElementById("login-password").value;` or `document.getElementById("pcPassword").value;`, depending on your firmware version. 6. Copy the returned value to your Home Assistant configuration as password. See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. diff --git a/source/_components/device_tracker.trackr.markdown b/source/_components/device_tracker.trackr.markdown index 6337b8f787..962300ed1e 100644 --- a/source/_components/device_tracker.trackr.markdown +++ b/source/_components/device_tracker.trackr.markdown @@ -1,7 +1,7 @@ --- layout: page title: "TrackR" -description: "Instructions how to use TrackR to track devices in Home Assistant." +description: "Instructions on how to use TrackR to track devices in Home Assistant." date: 2016-12-22 1000 sidebar: true comments: false @@ -24,11 +24,18 @@ To integrate TrackR in Home Assistant, add the following section to your `config # Example configuration.yaml entry device_tracker: platform: trackr - username: USERNAME - password: PASSWORD + username: YOUR_USERNAME + password: YOUR_PASSWORD ``` -Configuration variables: +{% configuration %} +username: + description: The email address for the TrackR account. + required: true + type: string +password: + description: The password for your given username. + required: true + type: string +{% endconfiguration %} -- **username** (*Required*): The email address for the TrackR account. -- **password** (*Required*): The password for your given username. diff --git a/source/_components/device_tracker.ubus.markdown b/source/_components/device_tracker.ubus.markdown index d408fec544..3df045db24 100644 --- a/source/_components/device_tracker.ubus.markdown +++ b/source/_components/device_tracker.ubus.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenWRT (ubus)" -description: "Instructions how to integrate OpenWRT routers into Home Assistant." +description: "Instructions on how to integrate OpenWRT routers into Home Assistant." date: 2015-03-23 19:59 sidebar: true comments: false @@ -68,7 +68,7 @@ Configuration variables: - **host** (*Required*): The IP address of your router, eg. 192.168.1.1. - **username** (*Required*): The username of an user with administrative privileges, usually *root*. - **password** (*Required*): The password for your given account. -- **dhcp_software** (*Optional*): The DHCP software used in your router: `dnsmasq` or `dhcpd`. Defaults to `dnsmasq`. +- **dhcp_software** (*Optional*): The DHCP software used in your router: `dnsmasq`, `dhcpd`, or `none`. Defaults to `dnsmasq`. See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. diff --git a/source/_components/device_tracker.unifi.markdown b/source/_components/device_tracker.unifi.markdown index a71db05655..e941066770 100644 --- a/source/_components/device_tracker.unifi.markdown +++ b/source/_components/device_tracker.unifi.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Ubiquiti Unifi WAP" -description: "Instructions how to use a Unifi WAP controller as a device tracker module." +description: "Instructions on how to use a Unifi WAP controller as a device tracker module." date: 2016-02-19 20:59 sidebar: true comments: false @@ -20,8 +20,12 @@ To use this device tracker in your installation, add the following to your `conf # Example configuration.yaml entry device_tracker: - platform: unifi - username: USERNAME - password: PASSWORD + host: unifi + username: username + password: password + ssid_filter: + - 'HomeSSID' + - 'IoTSSID' ``` {% configuration %} @@ -56,8 +60,14 @@ verify_ssl: detection_time: description: How long since the last seen time before the device is marked away, specified in seconds. type: int - required: optional + required: false default: 300 +ssid_filter: + description: Filter the SSIDs that tracking will occur on. + type: list of strings + required: false + default: None + {% endconfiguration %} See the [device tracker component page](/components/device_tracker/) for instructions how to configure the people to be tracked. @@ -70,7 +80,7 @@ The Unifi controller allows you to create multiple users on it besides the main 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 dedicate virtual machine to avoid that situation. +It is recommended that you run the Unifi controller in a dedicated virtual machine to avoid that situation. ### {% linkable_title Troubleshooting and Time Synchronization %} 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 f6629e3159..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,31 +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/) - * [Wink](https://home-assistant.io/components/wink/) - * [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. @@ -50,6 +51,8 @@ discovery: ignore: - sonos - samsung_tv + enable: + - homekit ``` Configuration variables: @@ -79,11 +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. @@ -99,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 4ce686ec64..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: @@ -31,7 +32,77 @@ Configuration variables: - **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://
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 95ef0fff19..edd0b8ebb1 100644
--- a/source/_components/google_assistant.markdown
+++ b/source/_components/google_assistant.markdown
@@ -13,6 +13,10 @@ 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. @@ -21,6 +25,8 @@ The Google Assistant component requires a bit more setup than most due to the wa 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 @@ -41,9 +47,9 @@ google_assistant: aliases: - bright lights - entry lights - type: light light.living_room: expose: false + room: living room ``` Configuration variables: @@ -63,15 +69,15 @@ access_token: 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. + 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 setup below). If not provided then the request_sync service is not exposed. + 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. + 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 @@ -101,8 +107,8 @@ entity_config: description: Aliases that can also be used to refer to this entity required: false type: list - type: - description: Override how Google Assistant interprets the domain of the entity. For example, set to `light` for a switch entity to have it be handled as a light. + room: + description: Allows for associating this device to a Room in Google Assistant. required: false type: string {% endconfiguration %} @@ -110,15 +116,16 @@ entity_config: ### {% linkable_title Available domains %} Currently, the following domains are available to be used with Google Assistant, listed with their default types: -- group = switch (on/off) -- scene = scene (on) -- script = scene (on) -- switch = switch (on/off) -- fan = switch (on/off) -- light = light (on/off/brightness/rgb color/color temp) -- cover = switch (on/off/set position (brightness) ) -- media_player = switch (on/off/set volume (brightness) ) -- climate = thermostat (temperature setting) +- group (on/off) +- input boolean (on/off) +- scene (on) +- script (on) +- switch (on/off) +- fan (on/off) +- light (on/off/brightness/rgb color/color temp) +- cover (on/off/set position (via set brightness)) +- media_player (on/off/set volume (via set brightness)) +- climate (temperature setting) It's very important that you use very long strings for `client_id` and `access_token`. Those are essentially the credentials to your Home Assistant instance. You can generate them with the following command: @@ -130,58 +137,32 @@ If you're not using Linux, you can use sites such as [this one](https://www.brow ### {% linkable_title Setup %} -1. Download the [gactions CLI](https://developers.google.com/actions/tools/gactions-cli) to be used later. You can download and run this anywhere and on any machine. Just remember where you put it for later and don't forget to run `chmod +x gactions` to make it executable on Mac or Linux. -2. Create a new file named `project.json` (in the same directory you downloaded `gactions` to) and replace the `[YOUR HOME ASSISTANT URL]` below with the URL you use to access Home Assistant. - Note: This must be an HTTPS URL to work. - -```json -{ - "actions": [{ - "name": "actions.devices", - "deviceControl": { - }, - "fulfillment": { - "conversationName": "automation" - } - }], - "conversations": { - "automation": - { - "name": "automation", - "url": "https://[YOUR HOME ASSISTANT URL]/api/google_assistant" - } - } -} -``` - -3. Create a new project in the [developer console](https://console.actions.google.com/). +1. Create a new project in the [developer console](https://console.actions.google.com/). a. Add/Import project - b. Go to Build under the Actions SDK box - c. Copy the command that looks like: - - `gactions update --action_package PACKAGE_NAME --project doctest-2d0b8` -4. Replace `PACKAGE_NAME` with `project.json` and run that command in a console from the same directory you saved `project.json` in (you'll need to put `./` before `gactions` so that it reads `./gactions` if you're running it on Linux or Windows). It should output a URL like `https://console.actions.google.com/project/doctest-2d0b8/overview` - go there. -5. You'll need to fill out most of the information on that page, but none of it really matters since you won't be addressing the App directly, only through the Smart Home functionality built into Google Assistant. -6. The final item on that page `Account linking` is required for your app to interact with Home Assistant. - 1. Grant type: `Implicit` - 2. Client ID: The `client_id` from your Home Assistant configuration above - 3. Authorization URL (replace with your actual URL): `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth`. If you have set `api_password:` add this password to the URL `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth?api_password=[YOUR API PASSWORD]`) - 4. Configure your client. Add scopes for `email` and `name`. - 5. Testing instructions: Enter anything. It doesn't matter since you won't submit this app. -7. Back on the main app draft page. Click `Test Draft`. That will take you to the simulator (which won't work so just close that window). -8. If you haven't already added the component configuration to `configuration.yaml` and restarted Home Assistant, you'll be unable to continue until you have. -8. Open the Google Assistant app and go into `Settings > Home Control` -9. Click the `+` sign, and near the bottom, you should have `[test] your app name`. Selecting that should lead to you the screen where you can set rooms for your devices or nicknames for your devices. -10. If you want to allow other household users to control the devices: - 1. Go to the developer console using the address from point 4. - 2. Under the gear icon, click `Permissions` - 3. Click `Add`, type the new user's e-mail address and choose `Project -> Editor` role - 4. Have the new user go to [developer console](https://console.actions.google.com/) and repeat steps starting from point 7. -11. If you want to use the `google_assistant.request_sync` service, to update devices without unlinking and relinking, in Home Assistant, then enable Homegraph API for your project: - 1. Go to the [cloud console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview) - 2. Select your project and click Enable Homegraph API - 3. Go to Credentials and select API Key from Create Credentials - 4. Note down the generated API Key and use this in the configuration + b. Click on `BUILD` on the `Smart home` card + c. Type in your home assistant url: `https://[YOUR HOME ASSISTANT URL:PORT]/api/google_assistant`, replace the `[YOUR HOME ASSISTANT URL:PORT]` with the domain / ip address and the port under which your Home Assistant is reachable. + d. Click `Done`. Then click on `Overview`, which will lead you to the app details screen. +2. You'll need to fill out most of the information on that page, but none of it really matters since you won't be addressing the App directly, only through the Smart Home functionality built into Google Assistant. +3. The final item on that page `Account linking` is required for your app to interact with Home Assistant. + a. Grant type: `Implicit` + b. Client ID: The `client_id` from your Home Assistant configuration above + c. Authorization URL (replace with your actual URL): `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth`. If you have set `api_password:` add this password to the URL `https://[YOUR HOME ASSISTANT URL]/api/google_assistant/auth?api_password=[YOUR API PASSWORD]`) + d. Configure your client. Add scopes for `email` and `name`. + e. Testing instructions: Enter anything. It doesn't matter since you won't submit this app. +4. Back on the main app draft page. Click `Test Draft`. That will take you to the simulator (which won't work so just close that window). +5. If you haven't already added the component configuration to `configuration.yaml` and restarted Home Assistant, you'll be unable to continue until you have. +6. Open the Google Assistant app and go into `Settings > Home Control` +7. Click the `+` sign, and near the bottom, you should have `[test] your app name`. Selecting that should lead you the screen where you can set rooms for your devices or nicknames for your devices. +8. If you want to allow other household users to control the devices: + a. Go to the settings for the project you created in point 1 in the developer console. + b. Under the gear icon, click `Permissions` + c. Click `Add`, type the new user's e-mail address and choose `Project -> Editor` role + d. Have the new user go to [developer console](https://console.actions.google.com/) and repeat steps starting from point 4 +9. If you want to use the `google_assistant.request_sync` service, to update devices without unlinking and relinking, in Home Assistant, then enable Homegraph API for your project: + a. Go to the [cloud console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview) + b. Select your project and click Enable Homegraph API + c. Go to Credentials, which you can find on the left navigation bar under the key icon, and select API Key from Create Credentials + d. Note down the generated API Key and use this in the configuration ### {% linkable_title Troubleshooting the request_sync service %} @@ -190,7 +171,7 @@ The request_sync service requires that the initial sync from Google includes the The request_sync service may fail with a 404 if the project_id of the Homegraph API differs from the project_id of the Actions SDK found in the preferences of your project on [developer console](https://console.actions.google.com). Resolve this by: 1. Removing your project from the [developer console](https://console.actions.google.com). - 2. Add a new project to the [cloud console](https://console.cloud.google.com). Here you get a new project_id. + 2. Add a new project to the [cloud console](https://console.cloud.google.com). Here you get a new `project_id`. 3. Enable Homegraph API to the new project. 4. Generate a new API key. - 5. Again, create a new project in the [developer console](https://console.actions.google.com/). Described above. But at the step 'Build under the Actions SDK box' choose your newly created project. By this, they share the same project_id. + 5. Again, create a new project in the [developer console](https://console.actions.google.com/). Described above. But at the step 'Build under the Actions SDK box' choose your newly created project. By this, they share the same `project_id`. diff --git a/source/_components/group.markdown b/source/_components/group.markdown index 8f781722d2..924c55e24a 100644 --- a/source/_components/group.markdown +++ b/source/_components/group.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Group" -description: "Instructions how to setup groups within Home Assistant." +description: "Instructions on how to setup groups within Home Assistant." date: 2015-03-23 19:59 sidebar: true comments: false diff --git a/source/_components/hdmi_cec.markdown b/source/_components/hdmi_cec.markdown index 758f8d468e..ceafd717c6 100644 --- a/source/_components/hdmi_cec.markdown +++ b/source/_components/hdmi_cec.markdown @@ -1,7 +1,7 @@ --- layout: page title: "HDMI CEC" -description: "Instructions how to interact with HDMI CEC via Home Assistant." +description: "Instructions on how to interact with HDMI CEC via Home Assistant." date: 2016-06-24 19:59 sidebar: true comments: false @@ -31,32 +31,24 @@ If you are using [Hass.io](/hassio/) then just move forward to the configuration #### {% linkable_title Symlinking into virtual environment %} -Create a symlink to the `cec` installation. Keep in mind different installation methods will result in different locations of cec. +Create a symlink to the `cec` installation including the _cec.so file. Keep in mind different installation methods will result in different locations of cec. ```bash -$ ln -s /path/to/your/installation/of/cec /path/to/your/venv/lib/python3.4/site-packages +$ ln -s /path/to/your/installation/of/cec /path/to/your/venv/lib/python*/site-packages +$ ln -s /path/to/your/installation/of/_cec.so /path/to/your/venv/lib/python*/site-packages + ``` + ##### {% linkable_title Symlinking examples: %} For the default virtual environment of a [HASSbian Image for Raspberry Pi](/getting-started/installation-raspberry-pi-image/) the command would be as follows. ```bash -$ ln -s /usr/local/lib/python3.4/dist-packages/cec /srv/homeassistant/lib/python3.4/site-packages +$ ln -s /usr/local/lib/python*/dist-packages/cec /srv/homeassistant/lib/python*/site-packages +$ ln -s /usr/local/lib/python*/dist-packages/_cec.so /srv/homeassistant/lib/python*/site-packages + ``` -For the default virtual environment of a [Raspberry Pi All-In-One installation](/getting-started/installation-raspberry-pi-all-in-one/) the command would be as follows. - -```bash -$ ln -s /usr/local/lib/python3.4/site-packages/cec /srv/homeassistant/homeassistant_venv/lib/python3.4/site-packages -``` - -For the default virtual environment of a [Manual installation](/getting-started/installation-raspberry-pi/) the command would be as follows. - -```bash -$ ln -s /usr/local/lib/python3.4/site-packages/cec /srv/hass/hass_venv/lib/python3.4/site-packages -``` - -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 fb73a05824..f172c6b0ff 100644 --- a/source/_components/hue.markdown +++ b/source/_components/hue.markdown @@ -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: 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/image_processing.dlib_face_detect.markdown b/source/_components/image_processing.dlib_face_detect.markdown index 6673146847..f427590256 100644 --- a/source/_components/image_processing.dlib_face_detect.markdown +++ b/source/_components/image_processing.dlib_face_detect.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Dlib Face Detect" -description: "Instructions how to integrate Dlib Face Detect into Home Assistant." +description: "Instructions on how to integrate Dlib Face Detect into Home Assistant." date: 2017-05-05 00:00 sidebar: true comments: false diff --git a/source/_components/image_processing.dlib_face_identify.markdown b/source/_components/image_processing.dlib_face_identify.markdown index 1e47bf13e4..34690d6b8f 100644 --- a/source/_components/image_processing.dlib_face_identify.markdown +++ b/source/_components/image_processing.dlib_face_identify.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Dlib Face Identify" -description: "Instructions how to integrate Dlib Face Identify into Home Assistant." +description: "Instructions on how to integrate Dlib Face Identify into Home Assistant." date: 2017-01-25 00:00 sidebar: true comments: false @@ -13,7 +13,7 @@ featured: false ha_release: 0.44 --- -The `dlib_face_identify` image processing platform allows you to use the [Dlib](http://www.dlib.net/) through Home Assistant. This platform allow you to identify persons on camera and fire a event with identify persons. +The `dlib_face_identify` image processing platform allows you to use the [Dlib](http://www.dlib.net/) through Home Assistant. This platform allow you to identify persons on camera and fire an event with identify persons. For using the result inside an automation rule, take a look at the [component](/components/image_processing/) page. @@ -36,3 +36,7 @@ Configuration variables: - **entity_id** (*Required*): A camera entity id to get picture from. - **name** (*Optional*): This parameter allows you to override the name of your `image_processing` entity. - **faces** array (*Required*): List of faces sources. + +
+If the platform fails to load because it could not install its requirement, install cmake: `sudo apt-get install cmake`. +
diff --git a/source/_components/image_processing.markdown b/source/_components/image_processing.markdown index 6f010ebad2..1f1507bf28 100644 --- a/source/_components/image_processing.markdown +++ b/source/_components/image_processing.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Image Processing" -description: "Instructions how to setup image processing with Home Assistant." +description: "Instructions on how to setup image processing with Home Assistant." date: 2017-01-09 00:00 sidebar: true comments: false diff --git a/source/_components/image_processing.microsoft_face_detect.markdown b/source/_components/image_processing.microsoft_face_detect.markdown index 39aecb1534..06cca72d26 100644 --- a/source/_components/image_processing.microsoft_face_detect.markdown +++ b/source/_components/image_processing.microsoft_face_detect.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Microsoft Face Detect" -description: "Instructions how to integrate Microsoft Face Detect into Home Assistant." +description: "Instructions on how to integrate Microsoft Face Detect into Home Assistant." date: 2017-01-25 00:00 sidebar: true comments: false diff --git a/source/_components/image_processing.microsoft_face_identify.markdown b/source/_components/image_processing.microsoft_face_identify.markdown index 76fb2ad1be..eb6d0a110f 100644 --- a/source/_components/image_processing.microsoft_face_identify.markdown +++ b/source/_components/image_processing.microsoft_face_identify.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Microsoft Face Identify" -description: "Instructions how to integrate Microsoft Face Identify into Home Assistant." +description: "Instructions on how to integrate Microsoft Face Identify into Home Assistant." date: 2017-01-25 00:00 sidebar: true comments: false diff --git a/source/_components/image_processing.openalpr_cloud.markdown b/source/_components/image_processing.openalpr_cloud.markdown index 3a13097c87..96e180a705 100644 --- a/source/_components/image_processing.openalpr_cloud.markdown +++ b/source/_components/image_processing.openalpr_cloud.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenALPR Cloud" -description: "Instructions how to integrate licences plates with OpenALPR cloud into Home Assistant." +description: "Instructions on how to integrate licences plates with OpenALPR cloud into Home Assistant." date: 2017-01-09 00:00 sidebar: true comments: false @@ -13,7 +13,7 @@ featured: false ha_release: 0.36 --- -[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you to process licences plates from a camera. You can use them to open a garage door or trigger any other [automation](https://home-assistant.io/components/automation/). +[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you to process licences plates from a camera. You can use them to open a garage door or trigger any other [automation](/components/automation/). For using the result inside an automation rule, take a look at the [component](/components/image_processing/) page. diff --git a/source/_components/image_processing.openalpr_local.markdown b/source/_components/image_processing.openalpr_local.markdown index 593a921261..d5da4bab3e 100644 --- a/source/_components/image_processing.openalpr_local.markdown +++ b/source/_components/image_processing.openalpr_local.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenALPR Local" -description: "Instructions how to integrate licences plates with OpenALPR local into Home Assistant." +description: "Instructions on how to integrate licences plates with OpenALPR local into Home Assistant." date: 2017-01-09 00:00 sidebar: true comments: false @@ -14,7 +14,7 @@ ha_release: 0.36 redirect_from: /components/openalpr/ --- -[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you to process licences plates from a camera. You can use them to open a garage door or trigger any other [automation](https://home-assistant.io/components/automation/). +[OpenALPR](http://www.openalpr.com/) integration for Home Assistant allows you to process licences plates from a camera. You can use them to open a garage door or trigger any other [automation](/components/automation/). For using inside automation look on [component](/components/image_processing) page. diff --git a/source/_components/image_processing.opencv.markdown b/source/_components/image_processing.opencv.markdown index db6bfd2d5c..9e485ec6c3 100644 --- a/source/_components/image_processing.opencv.markdown +++ b/source/_components/image_processing.opencv.markdown @@ -1,7 +1,7 @@ --- layout: page title: "OpenCV" -description: "Instructions how to integrate OpenCV image processing into Home Assistant." +description: "Instructions on how to integrate OpenCV image processing into Home Assistant." date: 2017-01-25 00:00 sidebar: true comments: false diff --git a/source/_components/image_processing.seven_segments.markdown b/source/_components/image_processing.seven_segments.markdown index 13249bc52b..a5944d821b 100644 --- a/source/_components/image_processing.seven_segments.markdown +++ b/source/_components/image_processing.seven_segments.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Seven segments display" -description: "Instructions how to use OCR for seven segments displays into Home Assistant." +description: "Instructions on how to use OCR for seven segments displays into Home Assistant." date: 2017-05-18 08:00 sidebar: true comments: false diff --git a/source/_components/influxdb.markdown b/source/_components/influxdb.markdown index 4252068c03..9df07711f8 100644 --- a/source/_components/influxdb.markdown +++ b/source/_components/influxdb.markdown @@ -23,11 +23,11 @@ The default InfluxDB configuration doesn't enforce authentication. If you have i influxdb: ``` -You will still need to create a database named `home_assistant` via InfluxDB's web interface or command line. For instructions how to create a database check the [InfluxDB documentation](https://docs.influxdata.com/influxdb/latest/introduction/getting_started/#creating-a-database) relevant to the version you have installed. +You will still need to create a database named `home_assistant` via InfluxDB's command line interface. For instructions on how to create a database check the [InfluxDB documentation](https://docs.influxdata.com/influxdb/latest/introduction/getting_started/#creating-a-database) relevant to the version you have installed. Configuration variables: -- **host** (*Optional*): IP address of your database host, e.g. 192.168.1.10. Defaults to `localhost`. +- **host** (*Optional*): IP address of your database host, e.g., 192.168.1.10. Defaults to `localhost`. - **port** (*Optional*): Port to use. Defaults to 8086. - **username** (*Optional*): The username of the database user. The user needs read/write privileges on the database. - **password** (*Optional*): The password for the database user account. @@ -35,10 +35,9 @@ Configuration variables: - **ssl** (*Optional*): Use https instead of http to connect. Defaults to false. - **verify_ssl** (*Optional*): Verify SSL certificate for https request. Defaults to false. - **max_retries** (*Optional*): Allow the component to retry if there was a network error when transmitting data -- **retry_queue_limit** (*Optional*): If retry enabled, specify how much calls are allowed to be queued for retry. - **default_measurement** (*Optional*): Measurement name to use when an entity doesn't have a unit. Defaults to entity id. - **override_measurement** (*Optional*): Measurement name to use instead of unit or default measurement. This will store all data points in a single measurement. -- **component_config**, **component_config_domain**, **component_config_glob** (*Optional*): These attributes contains component-specific override values. See [Customizing devices and services](https://home-assistant.io/getting-started/customizing-devices/) for format. +- **component_config**, **component_config_domain**, **component_config_glob** (*Optional*): These attributes contains component-specific override values. See [Customizing devices and services](/getting-started/customizing-devices/) for format. - **override_measurement** (*Optional*): Measurement name to use for this component, takes precedence over the global 'override_measurement' and component-specific 'unit_of_measurement' attribute. - **exclude** (*Optional*): Configure which components should be excluded from recording to InfluxDB. - **entities** (*Optional*): The list of entity ids to be excluded from recording to InfluxDB. diff --git a/source/_components/input_boolean.markdown b/source/_components/input_boolean.markdown index ff2aa46ca8..b2b23aeeff 100644 --- a/source/_components/input_boolean.markdown +++ b/source/_components/input_boolean.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Boolean" -description: "Instructions how to integrate the Input Boolean component into Home Assistant." +description: "Instructions on how to integrate the Input Boolean component into Home Assistant." date: 2016-01-17 16:58 sidebar: true comments: false diff --git a/source/_components/input_datetime.markdown b/source/_components/input_datetime.markdown index 7337114357..462b309e7e 100644 --- a/source/_components/input_datetime.markdown +++ b/source/_components/input_datetime.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Datetime" -description: "Instructions how to integrate the Input Datetime component into Home Assistant." +description: "Instructions on how to integrate the Input Datetime component into Home Assistant." date: 2017-09-14 16:01 sidebar: true comments: false @@ -65,7 +65,7 @@ input_datetime: A datetime input entity's state exports several attributes that can be useful in automations and templates. | Attribute | Description | -| --------- | ----------- | +| ----- | ----- | | `has_time` | `true` if this entity has a time. | `has_date` | `true` if this entity has a date. | `year``month`
`day` | The year, month and day of the date.
(only available if `has_date: true`) @@ -75,3 +75,47 @@ A datetime input entity's state exports several attributes that can be useful in ### {% 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 348053d8ee..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/ ---
-Before version 0.55 this component was known as `input_slider` and did not have the `mode` configuration option. +Before version 0.55 this component was known as `input_slider` and did not have the `mode` configuration option. Also, service `select_value` is now `set_value`.
The `input_number` component allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. The frontend can display a slider, or a numeric input box. Changes to the slider or numeric input box generate state events. These state events can be utilized as `automation` triggers as well. @@ -39,7 +39,6 @@ input_number: mode: box ``` - {% configuration %} input_number: description: Alias for the input. Multiple entries are allowed. diff --git a/source/_components/input_select.markdown b/source/_components/input_select.markdown index bf25b89d5f..8e59002ccf 100644 --- a/source/_components/input_select.markdown +++ b/source/_components/input_select.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Select" -description: "Instructions how to integrate the Input Select component into Home Assistant." +description: "Instructions on how to integrate the Input Select component into Home Assistant." date: 2016-02-02 17:00 sidebar: true comments: false diff --git a/source/_components/input_text.markdown b/source/_components/input_text.markdown index 2fa07711af..284ab5ea36 100644 --- a/source/_components/input_text.markdown +++ b/source/_components/input_text.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Input Text" -description: "Instructions how to integrate the Input Text component into Home Assistant." +description: "Instructions on how to integrate the Input Text component into Home Assistant." date: 2016-03-15 06:00 sidebar: true comments: false @@ -12,7 +12,7 @@ ha_category: Automation ha_release: 0.53 --- -The `input_text` component allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. Changes to the value stored in the text box generate state events. These state events can be utilized as `automation` triggers as well. +The `input_text` component allows the user to define values that can be controlled via the frontend and can be used within conditions of automation. Changes to the value stored in the text box generate state events. These state events can be utilized as `automation` triggers as well. It can also be configured in password mode (obscured text). ```yaml # Example configuration.yaml entries @@ -27,6 +27,9 @@ input_text: text3: name: Text 3 pattern: '[a-fA-F0-9]*' + text4: + name: Text 4 + mode: password ``` {% configuration %} @@ -59,6 +62,11 @@ input_text: required: false type: String default: empty + mode: + description: Can specify `text` or `password`. Elements of type "password" provide a way for the user to securely enter a value. + required: false + type: String + default: text {% endconfiguration %} ### {% linkable_title Restore State %} diff --git a/source/_components/insteon_hub.markdown b/source/_components/insteon_hub.markdown index 03bf4b8a6e..5c9813bc5c 100644 --- a/source/_components/insteon_hub.markdown +++ b/source/_components/insteon_hub.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Insteon Hub" -description: "Instructions how to setup the Insteon Hub within Home Assistant." +description: "Instructions on how to setup the Insteon Hub within Home Assistant." date: 2016-01-27 08:00 sidebar: true comments: false @@ -32,6 +32,6 @@ insteon_hub: Configuration variables: -- **username** (*Required*): The username used to access the Insteon interface (e.g. the [connect.insteon.com](http://connect.insteon.com/) site). +- **username** (*Required*): The username used to access the Insteon interface (e.g., the [connect.insteon.com](http://connect.insteon.com/) site). - **password** (*Required*): The password used to access the Insteon interface. - **api_key** (*Required*): The Insteon REST API key emailed to you once you are approved in the Insteon Developer program. diff --git a/source/_components/insteon_local.markdown b/source/_components/insteon_local.markdown index fba1087171..40ed93c1d5 100644 --- a/source/_components/insteon_local.markdown +++ b/source/_components/insteon_local.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Insteon (local)" -description: "Instructions how to setup the Insteon Hub locally within Home Assistant." +description: "Instructions on how to setup the Insteon Hub locally within Home Assistant." date: 2016-12-18 08:00 sidebar: true comments: false diff --git a/source/_components/insteon_plm.markdown b/source/_components/insteon_plm.markdown index f28db9b74c..9e15bb0f7d 100644 --- a/source/_components/insteon_plm.markdown +++ b/source/_components/insteon_plm.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Insteon PLM" -description: "Instructions how to setup an Insteon USB PLM locally within Home Assistant." +description: "Instructions on how to setup an Insteon USB PLM locally within Home Assistant." date: 2017-02-19 16:00 sidebar: true comments: false @@ -16,13 +16,15 @@ ha_version: 0.39 This component adds "local push" support for INSTEON PowerLinc Modems allowing linked INSTEON devices to be used within Home Assistant as lights, switches, and binary sensors. Device support is provided by the underlying [insteonplm] -package. It is known to work with both the [2413U] USB and [2412S] -RS242 flavors of PLM. This component does not work with the IP-based hub -products. For that, you'll want the "Insteon (Local)" component instead. +package. It is known to work with the [2413U] USB and [2412S] RS242 flavors +of PLM and the [2448A7] USB stick. This component does not work with the +IP-based hub products. For that, you'll want the "Insteon (Local)" component +instead. [insteonplm]: https://github.com/nugget/python-insteonplm [2413U]: https://www.insteon.com/powerlinc-modem-usb [2412S]: https://www.insteon.com/powerlinc-modem-serial +[2448A7]: https://www.smarthome.com/insteon-2448a7-portable-usb-adapter.html ```yaml @@ -30,23 +32,83 @@ products. For that, you'll want the "Insteon (Local)" component instead. insteon_plm: port: SERIAL_PORT device_override: - - address: INSTEON_ADDRESS - platform: DEVICE_PLATFORM + - address: ADDRESS + cat: CATEGORY + subcat: SUBCATEGORY + firmware: FIRMWARE + product_key: PRODUCT_KEY ``` - Configuration variables: -- **port** (*Required*): The port for your device, e.g. `/dev/ttyUSB0` -- **device_override** (*Optional*): Override the default device platform - +- **port** (*Required*): The port for your device, e.g., `/dev/ttyUSB0` +- **device_override** (*Optional*): Override the default device definition + - *ADDRESS* is found on the device itself in the form 1A.2B.3C or 1a2b3c + - *CATEGORY* is found in the back of the device's User Guide in the form of + 0x00 - 0xff + - *SUBCATEGORY* is found in the back of the device's User Guide in the form + of 0x00 - 0xff + - *FIRMWARE* and *PRODUCT_KEY* are more advanced options and will typically + not be used. + +### {% linkable_title Autodiscovery %} + +The first time autodiscovery runs, the duration may require up to 20 seconds +per device. Subsequent startups will occur much quicker using cached device +information. If a device is not recognized during autodiscovery, you can add +the device to the **device_override** configuration. + +In order for a device to be discovered it must be linked to the PLM as either +a responder or a controller. + +### {% linkable_title Linking Devices to the PLM %} + +In order for any two Insteon devices to talk with one another, they must be +linked. For an overview of device linking please read the Insteon page on +[understanding linking]. The Insteon PLM module supports All-Linking through +[Development Tools] service calls. The following services are available: + +In order for any two Insteon devices to talk with one another, they must be +linked. For an overview of device linking, please read the Insteon page on +[understanding linking]. The Insteon PLM module supports All-Linking through +[Development Tools] service calls. The following services are available: +- **insteon_plm.add_all_link**: Tells the Insteon Modem (IM) start All-Linking +mode. Once the IM is in All-Linking mode, press the link button on the device +to complete All-Linking. +- **insteon_plm.delete_all_link**: Tells the Insteon Modem (IM) to remove an +All-Link record from the All-Link Database of the IM and a device. Once the IM +is set to delete the link, press the link button on the corresponding device +to complete the process. +- **insteon_plm.load_all_link_database**: Load the All-Link Database for a +device. WARNING - Loading a device All-Link database is very time consuming +and inconsistent. This may take a LONG time and may need to be repeated to +obtain all records. +- **insteon_plm.print_all_link_database**: Print the All-Link Database for a +device. Requires that the All-Link Database is loaded into memory. +- **insteon_plm.print_im_all_link_database**: Print the All-Link Database for +the INSTEON Modem (IM). + +If you are looking for more advanced options, you can use the +[insteonplm_interactive] command line tool that is distributed with the +[insteonplm] Python module. Please see the documentation on the [insteonplm] +GitHub site. Alternatively, you can download [HouseLinc] which runs on any +Windows PC, or you can use [Insteon Terminal] which is open source and runs +on most platforms. SmartHome no longer supports HouseLinc, but it still +works. Insteon Terminal is a very useful tool but please read the disclaimers +carefully, they are important. + +[understanding linking]: http://www.insteon.com/support-knowledgebase/2015/1/28/understanding-linking +[Development Tools]: https://www.home-assistant.io/docs/tools/dev-tools/ +[HouseLinc]: https://www.smarthome.com/houselinc.html +[Insteon Terminal]: https://github.com/pfrommerd/insteon-terminal +[insteonplm_interactive]: https://github.com/nugget/python-insteonplm#command-line-interface ### {% linkable_title Customization %} -The only configuration item that is absolutely necessary is the port so that -Home Assistant can connect to the PLM. This will expose all the supported INSTEON -devices which exist in the modem's ALL-Link database. However, devices will -only be shown by their INSTEON hex address (e.g. "1A.2B.3C") which can be a bit -unwieldy. As you link and unlink devices using the 'Set' buttons, they'll be -added and removed from Home Assistant automatically. +The only configuration item that is absolutely necessary is the port so that +Home Assistant can connect to the PLM. This will expose all the supported +INSTEON devices which exist in the modem’s ALL-Link database. However, devices +will only be shown by their INSTEON hex address (e.g., “1A.2B.3C”) which can +be a bit unwieldy. As you link and unlink devices using the ‘Set’ buttons, +they’ll be added and removed from Home Assistant automatically. You can use the normal Home Assistant [device customization] section of your configuration to assign friendly names and special icons to your devices. This @@ -58,14 +120,14 @@ devices. ### {% linkable_title Device Overrides %} INSTEON devices are added to Home Assistant using the platform(s) that make the -most sense given the model and features of the hardware. In most cases this is -unambiguous, but sometimes the component will not be able to guess the actual -usage of the device. For example, there might be a table lamp plugged into an -INSTEON appliance relay module. By default, this will show as a 'switch' -device in Home Assistant, but it really should be a 'light' device. For -exceptions like this, the component supports a device platform override. You -can set any device (by address) to explicitly use a specific platform if the -default is not correct. +most sense given the model and features of the hardware. The features of the +INSTEON device are built into the Home Assistant platform. Changing the +platform is not recommended. There are two primary uses for the +**device_override** feature. +- Devices that do not respond during autodiscovery. This is common for battery + operated devices. +- Devices that have not been fully developed. This allows an unknown device to + be mapped to a device that operates similarly to another device. ### {% linkable_title Example Configuration with Options%} @@ -83,7 +145,20 @@ homeassistant: insteon_plm: port: /dev/ttyUSB0 device_override: - - address: a1b2c3 # Icon Appliance Module for bedside lamp - platform: light # make it a light instead of a switch + - address: a1b2c3 # Hidden Door Sensor [2845-222] + cat: 0x10 + subcat: 0x11 ``` +### {% linkable_title What NOT to do %} + +Insteon PLM is a top level component and device discovery will identify +the Home Assistant platform the device belongs in. As such, do not +declare Insteon devices in other platforms. For example, this configuration +will NOT work: + +```yaml +light: + - platform: insteon_plm + address: 1a2b3c +``` diff --git a/source/_components/ios.markdown b/source/_components/ios.markdown new file mode 100644 index 0000000000..44ac2fa88e --- /dev/null +++ b/source/_components/ios.markdown @@ -0,0 +1,17 @@ +--- +layout: page +title: "iOS" +description: "Instructions on how to use the iOS companion app with Home Assistant." +date: 2018-04-06 08:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: apple.png +ha_category: Hub +featured: false +ha_release: 0.31 +ha_iot_class: depends +--- + +The `ios` component is the Home Assistant part for using the iOS companion app. For further details please check the [iOS section](/docs/ecosystem/ios/) in the documentation for further details. diff --git a/source/_components/isy994.markdown b/source/_components/isy994.markdown index 558765a764..211917fe56 100644 --- a/source/_components/isy994.markdown +++ b/source/_components/isy994.markdown @@ -1,7 +1,7 @@ --- layout: page title: "ISY994 Controller" -description: "Instructions how to setup the ISY994 controller within Home Assistant." +description: "Instructions on how to setup the ISY994 controller within Home Assistant." date: 2015-01-20 22:36 sidebar: true comments: false @@ -45,7 +45,7 @@ Once the ISY controller is configured, it will automatically import any binary s An Insteon door/window sensor will show up as a single Binary Sensor rather than two discrete devices like it does in the ISY994 admin panel. Note that when in "Two Nodes" mode, the sensor will have an UNKNOWN state until the sensor changes for the first time since the last Home Assistant reboot. If you do not use Insteon scenes that are controlled directly from the door sensor, you may prefer to set the sensor to "One Node" mode using the ISY Admin Panel. -Each Insteon leak sensor will also show up as a single Binary Sensor as opposed to the two nodes seen in the ISY994. The name of the device will be based on what the parent node is named in the ISY994, which is typically the one with "-Dry" at the end of the name. This may be confusing, because "On" means wet in Home Assistant. You can rename this node either in the ISY994 Admin Panel (which will change the entity_id in Home Assistant) or assign a `friendly_name` in the [Customization section](https://home-assistant.io/docs/configuration/customizing-devices/) of your configuration. +Each Insteon leak sensor will also show up as a single Binary Sensor as opposed to the two nodes seen in the ISY994. The name of the device will be based on what the parent node is named in the ISY994, which is typically the one with "-Dry" at the end of the name. This may be confusing, because "On" means wet in Home Assistant. You can rename this node either in the ISY994 Admin Panel (which will change the entity_id in Home Assistant) or assign a `friendly_name` in the [Customization section](/docs/configuration/customizing-devices/) of your configuration. If your leak or door/window sensor supports heartbeats, a new binary_sensor device will be added to Home Assistant to represent the battery state. The sensor will stay "Off" so long as the daily heartbeats occur. If a heartbeat is missed, the sensor will flip to "On". The name of this device will be based on the heartbeat node in the ISY. @@ -125,7 +125,7 @@ My Programs ``` A device is created by creating a directory, with the name for the device, under any of the following root directories: - * *HA.binary_sensor* will create a binary sensor (see [Customizing Devices](https://home-assistant.io/getting-started/customizing-devices/) to set the sensor class) + * *HA.binary_sensor* will create a binary sensor (see [Customizing Devices](/getting-started/customizing-devices/) to set the sensor class) * *HA.cover* will create a cover * *HA.fan* will create a fan * *HA.lock* will create a lock diff --git a/source/_components/juicenet.markdown b/source/_components/juicenet.markdown index 5015022c55..74cc2fdb89 100644 --- a/source/_components/juicenet.markdown +++ b/source/_components/juicenet.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Juicenet" -description: "Instructions how to setup WiFi-equipped Juicenet charging stations with Home Assistant." +description: "Instructions on how to setup WiFi-equipped Juicenet charging stations with Home Assistant." date: 2017-05-20 22:00 sidebar: true comments: false @@ -15,10 +15,12 @@ ha_release: 0.47 The `juicenet` sensor platform pulls data from a [JuiceNet](https://emotorwerks.com/products/juicenet/) charging station equipped with a wifi connection. It will access and make available all of the devices attached to your account. +## {% linkable_title Configuration %} + To enable the platform in your installation, add the following to your `configuration.yaml` file: ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry juicenet: access_token: ACCESS_TOKEN ``` diff --git a/source/_components/keyboard.markdown b/source/_components/keyboard.markdown index 07b3e2db26..00dad71931 100644 --- a/source/_components/keyboard.markdown +++ b/source/_components/keyboard.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Keyboard" -description: "Instructions how to simulate key presses with Home Assistant." +description: "Instructions on how to simulate key presses with Home Assistant." date: 2015-01-24 14:39 sidebar: true comments: false diff --git a/source/_components/keyboard_remote.markdown b/source/_components/keyboard_remote.markdown index f1d80bfa97..aeefd01e63 100644 --- a/source/_components/keyboard_remote.markdown +++ b/source/_components/keyboard_remote.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Keyboard Remote" -description: "Instructions how to use a keyboard to remote control Home Assistant." +description: "Instructions on how to use a keyboard to remote control Home Assistant." date: 2016-09-28 14:39 sidebar: true comments: false diff --git a/source/_components/kira.markdown b/source/_components/kira.markdown index d2c2594834..b32ae95eac 100644 --- a/source/_components/kira.markdown +++ b/source/_components/kira.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Kira" -description: "Instructions how to integrate Keene Electronics IR over IP modules (Kira) into Home Assistant." +description: "Instructions on how to integrate Keene Electronics IR over IP modules (Kira) into Home Assistant." date: 2017-05-07 00:00 sidebar: true comments: false @@ -76,7 +76,7 @@ Configuration variables: - **type** (*Optional*): The type of this code. If this field is omitted, the type will be autodetected if possible. - **repeat** (*Optional*): The number of times to repeat this code (on transmit). Default is 1. -Some manufacturers (e.g. Samsung) require an IR code to be sent a number of times in a row in rapid succession (usually 3). This doesn't apply to the vast majority of devices, but it can be helpful if needed. +Some manufacturers (e.g., Samsung) require an IR code to be sent a number of times in a row in rapid succession (usually 3). This doesn't apply to the vast majority of devices, but it can be helpful if needed. ### {% linkable_title Code Types %} diff --git a/source/_components/knx.markdown b/source/_components/knx.markdown index 4fd471efeb..7acfae7676 100644 --- a/source/_components/knx.markdown +++ b/source/_components/knx.markdown @@ -31,6 +31,7 @@ There is currently support for the following device types within Home Assistant: - [Light](/components/light.knx) - [Thermostat](/components/climate.knx) - [Notify](/components/notify.knx) +- [Scene](/components/scene.knx) ### {% linkable_title Configuration %} @@ -83,7 +84,6 @@ knx: - **fire_event** (*Optional*): If set to True, platform will write all received KNX messages to event bus - **fire_event_filter** (*Optional*): If `fire_event` is set `fire_event_filter` has to be specified. `fire_event_filter` defines a list of patterns for filtering KNX addresses. Only telegrams which match this pattern are sent to the HOme Assistant event bus. - **state_updater** (*Optional*): The component will collect the current state of each configured device from the KNX bus to display it correctly within Home-Assistant. Set this option to False to prevent this behavior. -- **time_address** (*Optional*): Broadcast current local time to KNX bus with configured group address. ### {% linkable_title Services %} @@ -98,6 +98,27 @@ Service Data: {"address": "1/0/15", "payload": 0} * **address**: KNX group address * **payload**: Payload, either an integer or an array of integers +### {% linkable_title Exposing sensor values or time to knx bus %} + +KNX component is able to expose time or sensor values to KNX bus. The component will broadcast any change of the exposed value to the KNX bus and answer read requests to the specified group address: + +```yaml +# Example configuration.yaml entry +knx: + expose:: + - type: 'temperature' + entity_id: 'sensor.owm_temperature' + address: '0/0/2' + - type: 'time' + address: '0/0/1' + - type: 'datetime' + address: '0/0/23' +``` + +* **type**: Type of the exposed value. Either time or datetime or any supported type of [KNX Sensor](/components/sensor.knx/) (e.g., "temperature" or "humidity"). +* **entity_id**: Entity id of the HASS component to be exposed. Not necessary for types time and datetime. +* **address**: KNX group address. + ### {% linkable_title Known issues %} diff --git a/source/_components/light.abode.markdown b/source/_components/light.abode.markdown index bb6d597dee..f362107791 100644 --- a/source/_components/light.abode.markdown +++ b/source/_components/light.abode.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Abode Light" -description: "Instructions how to integrate Abode lights into Home Assistant." +description: "Instructions on how to integrate Abode lights into Home Assistant." date: 2017-08-26 13:28 sidebar: true comments: false diff --git a/source/_components/light.ads.markdown b/source/_components/light.ads.markdown index b5188cf33e..aaedc1c12f 100644 --- a/source/_components/light.ads.markdown +++ b/source/_components/light.ads.markdown @@ -1,7 +1,7 @@ --- layout: page title: "ADS Light" -description: Instructions how to set up ADS lights within Home Assistant +description: Instructions on how to set up ADS lights within Home Assistant date: 2017-10-25 10:00 sidebar: true comments: false diff --git a/source/_components/light.avion.markdown b/source/_components/light.avion.markdown index 74260e9395..68c40b1aac 100644 --- a/source/_components/light.avion.markdown +++ b/source/_components/light.avion.markdown @@ -21,8 +21,6 @@ To enable these lights, add the following lines to your `configuration.yaml` fil # Example configuration.yaml entry light: - platform: avion - username: testuser@fakedomain.com - password: foobar ``` Configuration variables: diff --git a/source/_components/light.blinksticklight.markdown b/source/_components/light.blinksticklight.markdown index 9deab2be84..c11da280ac 100644 --- a/source/_components/light.blinksticklight.markdown +++ b/source/_components/light.blinksticklight.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Blinkstick" -description: "Instructions how to setup Blinkstick lights within Home Assistant." +description: "Instructions on how to setup Blinkstick lights within Home Assistant." date: 2015-10-08 10:00 sidebar: true comments: false diff --git a/source/_components/light.blinkt.markdown b/source/_components/light.blinkt.markdown index 617e81cac2..ad2d6200f8 100644 --- a/source/_components/light.blinkt.markdown +++ b/source/_components/light.blinkt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Blinkt!" -description: "Instructions how to setup Blinkt! RGB LED lights within Home Assistant." +description: "Instructions on how to setup Blinkt! RGB LED lights within Home Assistant." date: 2017-04-30 9:00 sidebar: true comments: false diff --git a/source/_components/light.decora_wifi.markdown b/source/_components/light.decora_wifi.markdown index 48ce82aa3a..7fc68d0dcf 100644 --- a/source/_components/light.decora_wifi.markdown +++ b/source/_components/light.decora_wifi.markdown @@ -8,12 +8,12 @@ comments: false sharing: true footer: true ha_category: Light -ha_iot_class: "Local Polling" +ha_iot_class: "Cloud Polling" logo: leviton.png ha_release: 0.51 --- -Support for [Leviton Decora Wi-Fi](http://www.leviton.com/en/products/lighting-controls/decora-smart-with-wifi) dimmers/switches. +Support for [Leviton Decora Wi-Fi](http://www.leviton.com/en/products/lighting-controls/decora-smart-with-wifi) dimmers/switches via the MyLeviton API. Supported devices (tested): @@ -26,13 +26,18 @@ To enable these lights, add the following lines to your `configuration.yaml` fil # Example configuration.yaml entry light: - platform: decora_wifi - username: my_leviton_user_email@email.com - password: my_leviton_password + username: YOUR_USERNAME + password: YOUR_PASSWORD ``` -Configuration variables: - -- **username** (*Required*): Your "My Leviton" app email address/user name. -- **password** (*Required*): Your "My Leviton" app password. - +{% configuration %} +username: + description: Your "My Leviton" app email address/user name. + required: true + type: string +password: + description: Your "My Leviton" app password. + required: true + type: string +{% endconfiguration %} diff --git a/source/_components/light.eufy.markdown b/source/_components/light.eufy.markdown new file mode 100644 index 0000000000..d8596c0048 --- /dev/null +++ b/source/_components/light.eufy.markdown @@ -0,0 +1,19 @@ +--- +layout: page +title: "Eufy Lights" +description: "Instructions on how to integrate Eufy LED lights into Home Assistant." +date: 2018-04-09 19:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: eufy.png +ha_category: Light +ha_iot_class: "Local Polling" +ha_release: 0.68 +--- + +The `eufy` platform allows you to control your [Eufy](http://www.eufylife.com) lights from within Home Assistant. + +They will be automatically discovered if the [Eufy](/components/eufy/) component is enabled. + diff --git a/source/_components/light.flux_led.markdown b/source/_components/light.flux_led.markdown index e74e6942d9..871ba222e2 100644 --- a/source/_components/light.flux_led.markdown +++ b/source/_components/light.flux_led.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Flux Led/MagicLight" -description: "Instructions how to setup Flux led/MagicLight within Home Assistant." +description: "Instructions on how to setup Flux led/MagicLight within Home Assistant." date: 2015-07-17 20:09 sidebar: true comments: false diff --git a/source/_components/light.greenwave.markdown b/source/_components/light.greenwave.markdown index a0cba942d4..16f8e16099 100644 --- a/source/_components/light.greenwave.markdown +++ b/source/_components/light.greenwave.markdown @@ -27,7 +27,7 @@ light: host: XXX.XXX.XXX.XXX version: 3 ``` -The version option is the major revision of your firmware, which should be 2 or 3. If you are running Version 2, there are no extra steps. If you are running Version 3, you must press the Sync button on the gateway prior to the first launch of Home Assistant, so a token can be grabbed. Once home assistant has started, you can either press the Sync button again or wait for it to time out manually. +The version option is the major revision of your firmware, which should be 2 or 3. If you are running Version 2, there are no extra steps. If you are running Version 3, you must press the Sync button on the gateway prior to the first launch of Home Assistant, so a token can be grabbed. Once Home Assistant has started, you can either press the Sync button again or wait for it to time out manually. {% configuration %} host: diff --git a/source/_components/light.group.markdown b/source/_components/light.group.markdown new file mode 100644 index 0000000000..4ec8262463 --- /dev/null +++ b/source/_components/light.group.markdown @@ -0,0 +1,63 @@ +--- +layout: page +title: "Light Group" +description: "Instructions for how to setup light groups within Home Assistant." +date: 2018-02-23 11:41 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Light +ha_release: 0.65 +ha_iot_class: "Local Push" +logo: home-assistant.png +--- + +The group light platform lets you combine multiple lights into one entity. All child lights of a light group can still be used as usual, but controlling the state of the grouped light will forward the command to each child light. + +To enable this platform in your installation, add the following to your `configuration.yaml` file: + +```yaml +# Example configuration.yaml entry +light: + - platform: group + name: Kitchen Lights + entities: + - light.kitchen_ceiling_lights + - light.kitchen_under_cabinet_lights + - light.kitchen_spot_lights + - light.pendant_lights +``` + +{% configuration %} + name: + description: The name of the light group. Defaults to "Light Group". + required: false + type: string + entities: + description: A list of entities to be included in the light group. + required: true + type: string list +{% endconfiguration %} + +
+
+Example of the light group "Kitchen Lights".
+
diff --git a/source/_components/light.homekit_controller.markdown b/source/_components/light.homekit_controller.markdown new file mode 100644 index 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 8cd9aad47e..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 diff --git a/source/_components/light.hyperion.markdown b/source/_components/light.hyperion.markdown index 7f3b23ad6c..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 diff --git a/source/_components/light.ihc.markdown b/source/_components/light.ihc.markdown index 741d2168cd..214f19564b 100644 --- a/source/_components/light.ihc.markdown +++ b/source/_components/light.ihc.markdown @@ -1,7 +1,7 @@ --- layout: page title: "IHC Light" -description: "Instructions how to integrate IHC lights within Home Assistant." +description: "Instructions on how to integrate IHC lights within Home Assistant." date: 2017-11-27 13:35 sidebar: true comments: false 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 06af902dfd..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 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. + +
+
+
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`.
-In order to apply attributes to an entity you will need to add `data:` to the configuration. See example below +In order to apply attributes to an entity, you will need to add `data:` to the configuration. See example below
```yaml diff --git a/source/_components/light.mochad.markdown b/source/_components/light.mochad.markdown index 2902cb71be..9721e9d6c9 100644 --- a/source/_components/light.mochad.markdown +++ b/source/_components/light.mochad.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Mochad Light" -description: "Instructions how to integrate X10 Mochad lights into Home Assistant." +description: "Instructions on how to integrate X10 Mochad lights into Home Assistant." date: 2017-07-14 11:29 sidebar: true comments: false @@ -11,13 +11,14 @@ ha_category: Light ha_release: 0.51 --- -The `mochad` light platform lets you control an X10 enabled dimmer/light -device. +The `mochad` light platform lets you control an X10 enabled dimmer/light device. + + To enable this sensor, you first have to set up the [mochad component](/components/mochad/) and then add the following to your `configuration.yaml` file: ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry light: - platform: mochad devices: diff --git a/source/_components/light.mqtt.markdown b/source/_components/light.mqtt.markdown index 33f76eb5cc..e92f859fb7 100644 --- a/source/_components/light.mqtt.markdown +++ b/source/_components/light.mqtt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MQTT Light" -description: "Instructions how to setup MQTT lights within Home Assistant." +description: "Instructions on how to setup MQTT lights within Home Assistant." date: 2015-11-13 08:30 sidebar: true comments: false @@ -14,6 +14,8 @@ ha_iot_class: depends The `mqtt` light platform lets you control your MQTT enabled lights. It supports setting brightness, color temperature, effects, flashing, on/off, RGB colors, transitions, XY colors and white values. +## {% linkable_title Configuration %} + In an ideal scenario, the MQTT device will have a state topic to publish state changes. If these messages are published with a `RETAIN` flag, the MQTT light will receive an instant state update after subscription and will start with the correct state. Otherwise, the initial state of the switch will be `false` / `off`. When a state topic is not available, the light will work in optimistic mode. In this mode, the light will immediately change state after every command. Otherwise, the light will wait for state confirmation from the device (message from `state_topic`). @@ -21,7 +23,7 @@ When a state topic is not available, the light will work in optimistic mode. In Optimistic mode can be forced, even if the `state_topic` is available. Try to enable it, if experiencing incorrect light operation. ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry light: - platform: mqtt command_topic: "office/rgb1/light/switch" @@ -55,7 +57,7 @@ brightness_value_template: required: false type: string color_temp_command_topic: - description: The MQTT topic to publish commands to change the light’s color temperature state. The color temperature command slider has a range of 157 to 500 mireds (micro reciprocal degrees). + description: The MQTT topic to publish commands to change the light’s color temperature state. The color temperature command slider has a range of 153 to 500 mireds (micro reciprocal degrees). required: false type: string color_temp_state_topic: @@ -95,12 +97,12 @@ payload_on: description: The payload that represents enabled state. required: false type: string - default: ON + default: "ON" payload_off: description: The payload that represents disabled state. required: false type: string - default: OFF + default: "OFF" qos: description: The maximum QoS level of the state topic. required: false @@ -120,7 +122,7 @@ rgb_command_topic: required: false type: string rgb_state_topic: - description: The MQTT topic subscribed to receive RGB state updates. + description: The MQTT topic subscribed to receive RGB state updates. The expected payload is the RGB values separated by commas, for example `255,0,127`. required: false type: string rgb_value_template: @@ -143,7 +145,7 @@ white_value_state_topic: description: The MQTT topic subscribed to receive white value updates. required: false type: string -white_value_value_template: +white_value_template: description: "Defines a [template](/docs/configuration/templating/#processing-incoming-data) to extract the white value." required: false type: string @@ -185,7 +187,7 @@ payload_not_available: ## {% 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 | ✔ | ✔ | ✔ | @@ -194,6 +196,7 @@ payload_not_available: | RGB Color | ✔ | ✔ | ✔ | | Transitions | ✘ | ✔ | ✔ | | XY Color | ✔ | ✔ | ✘ | +| HS Color | ✘ | ✔ | ✘ | | White Value | ✔ | ✔ | ✔ | ## {% linkable_title Examples %} @@ -204,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" @@ -215,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" @@ -248,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 bdcfaaab11..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", @@ -126,6 +128,11 @@ xy: 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 @@ -147,12 +154,12 @@ payload_not_available:- XY and RGB can not be used at the same time. If both are provided, XY overrides RGB. + RGB, XY and HSV can not be used at the same time in `state_topic` messages. Make sure that only one of the color models is in the "color" section of the state MQTT payload.
## {% linkable_title Comparison of light MQTT platforms %} -| Function | [`mqtt`](https://home-assistant.io/components/light.mqtt/) | [`mqtt_json`](https://home-assistant.io/components/light.mqtt_json/) | [`mqtt_template`](https://home-assistant.io/components/light.mqtt_template/) | +| Function | [`mqtt`](/components/light.mqtt/) | [`mqtt_json`](/components/light.mqtt_json/) | [`mqtt_template`](/components/light.mqtt_template/) | |-------------------|------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------------| | Brightness | ✔ | ✔ | ✔ | | Color temperature | ✔ | ✔ | ✔ | @@ -161,6 +168,7 @@ payload_not_available: | RGB Color | ✔ | ✔ | ✔ | | Transitions | ✘ | ✔ | ✔ | | XY Color | ✔ | ✔ | ✘ | +| HS Color | ✘ | ✔ | ✘ | | White Value | ✔ | ✔ | ✔ | ## {% linkable_title Examples %} @@ -215,7 +223,32 @@ Home Assistant will then convert its 8bit value in the message to and from the d ```json { "brightness": 4095, + "state": "ON" +} +``` + +### {% linkable_title HS Color %} + +To use a light with hue+saturation as the color model, set `hs` to `true` in the platform configuration: + +```yaml +light: + - platform: mqtt_json + name: mqtt_json_hs_light + state_topic: "home/light" + command_topic: "home/light/set" + hs: True +``` + +Home Assistant expects the hue values to be in the range 0 to 360 and the saturation values to be scaled from 0 to 100. For example, the following is a blue color shade: + +```json +{ "state": "ON", + "color": { + "h": 24.0, + "s": 100.0 + } } ``` @@ -227,4 +260,6 @@ Home Assistant will then convert its 8bit value in the message to and from the d - [MQTT JSON Light](https://github.com/mertenats/Open-Home-Automation/tree/master/ha_mqtt_rgbw_light_with_discovery) is another implementation for ESP8266 including [MQTT discovery](/docs/mqtt/discovery/). -- [esphomelib](https://github.com/OttoWinter/esphomelib) is a library for ESP32-based boards that has many of Home Assistant's MQTT features (like [discovery](/docs/mqtt/discovery/)) pre-implemented and provides high-level abstractions for components such as lights or sensors. +- [esphomelib](https://github.com/OttoWinter/esphomelib) is a library for ESP8266 and ESP32 boards that has many of Home Assistant's MQTT features (like [discovery](/docs/mqtt/discovery/)) pre-implemented and provides high-level abstractions for components such as lights or sensors. + +- [AiLight](https://github.com/stelgenhof/AiLight) is a custom firmware for the Ai-Thinker (and equivalent) RGBW WiFi light bulbs that has an ESP8266 onboard and controlled by the MY9291 LED driver. It implements the [MQTT JSON light](/components/light.mqtt_json/) platform and supports ON/OFF, RGBW colours, brightness, colour temperature, flashing and transitions. Also it includes [MQTT Auto Discovery](/docs/mqtt/discovery/)) and the MQTT Last Will and Testament is enabled as well. \ No newline at end of file diff --git a/source/_components/light.mqtt_template.markdown b/source/_components/light.mqtt_template.markdown index 5a13ea9dfb..11b4372672 100644 --- a/source/_components/light.mqtt_template.markdown +++ b/source/_components/light.mqtt_template.markdown @@ -123,7 +123,7 @@ payload_not_available: ## {% 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 | ✔ | ✔ | ✔ | @@ -132,6 +132,7 @@ payload_not_available: | RGB Color | ✔ | ✔ | ✔ | | Transitions | ✘ | ✔ | ✔ | | XY Color | ✔ | ✔ | ✘ | +| HS Color | ✘ | ✔ | ✘ | | White Value | ✔ | ✔ | ✔ | ## {% linkable_title Examples %} @@ -140,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 ebba128f88..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 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 71fc4e9717..158504bcae 100644 --- a/source/_components/light.tplink.markdown +++ b/source/_components/light.tplink.markdown @@ -1,7 +1,7 @@ --- layout: page title: "TP-Link Bulb" -description: "Instructions how to integrate TP-Link bulbs into Home Assistant." +description: "Instructions on how to integrate TP-Link bulbs into Home Assistant." date: 2017-07-25 08:00 sidebar: true comments: false 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 df44818d04..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 and WeMo Dimmer Switch 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 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 90e5d1359b..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,20 +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 %} -### Service fan/xiaomi_miio_set_scene +### {% 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 specific light. Else targets all. | +| `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 b098d007d5..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. @@ -62,6 +62,18 @@ This component is tested to work with the following models. If you have a differ - **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.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 6d379e04ca..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. - + - 0.9.4 defaults to using systemd for controlling the services. This is not just start/stop functionality, systemd is used to implement new features and to address shortcomings in 0.9.0. However, traditional systemV scripts are also installed and could be used although this is less tested and not really documented. + For more information have a look at `/usr/share/doc/lirc/README.Debian.gz` where the update process is explained when you have updated from jessie to stretch. ### {% linkable_title Configuring LIRC %} -Now teach LIRC about your particular remote control by preparing a lircd configuration file (`/etc/lirc/lircd.conf`). Search the [LIRC remote database](http://lirc.sourceforge.net/remotes/) for your model. If you can't find it, then you can always use the `irrecord` program to learn your remote. This will create a valid configuration file. Add as many remotes as you want by pasting them into the file. If `irrecord` doesn't work (e.g. for some air conditioner remotes), then the `mode2` program is capable of reading the codes in raw mode, followed by `irrecord -a` to extract hex codes. +Now teach LIRC about your particular remote control by preparing a lircd configuration file (`/etc/lirc/lircd.conf`). Search the [LIRC remote database](http://lirc.sourceforge.net/remotes/) for your model. If you can't find it, then you can always use the `irrecord` program to learn your remote. This will create a valid configuration file. Add as many remotes as you want by pasting them into the file. If `irrecord` doesn't work (e.g., for some air conditioner remotes), then the `mode2` program is capable of reading the codes in raw mode, followed by `irrecord -a` to extract hex codes. Next, you have to make a `~/.lircrc` file that maps keypresses to system actions. [The configuration](http://www.lirc.org/html/configure.html) is a bit tedious but it must be done. Use the `prog = home-assistant` for all keys you want to be recognized by Home Assistant. The values you set for `button` must be the same as in the `lircd.conf` file and the values you put for `config` entry will be the sensor value in Home Assistant when you press the button. An example may look like this: @@ -98,4 +98,4 @@ automation: entity_id: group.a_lights ``` -The `button_name` data values (e.g. `KEY_0`) are set by you in the `.lircrc` file. +The `button_name` data values (e.g., `KEY_0`) are set by you in the `.lircrc` file. diff --git a/source/_components/litejet.markdown b/source/_components/litejet.markdown index 3770bb024b..fb33408953 100644 --- a/source/_components/litejet.markdown +++ b/source/_components/litejet.markdown @@ -1,7 +1,7 @@ --- layout: page title: "LiteJet" -description: "Instructions how to setup the LiteJet hub within Home Assistant." +description: "Instructions on how to setup the LiteJet hub within Home Assistant." date: 2015-10-26 09:37 sidebar: true comments: false diff --git a/source/_components/lock.abode.markdown b/source/_components/lock.abode.markdown index c1e2860370..9dcc3cff90 100644 --- a/source/_components/lock.abode.markdown +++ b/source/_components/lock.abode.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Abode Lock" -description: "Instructions how to integrate Abode locks into Home Assistant." +description: "Instructions on how to integrate Abode locks into Home Assistant." date: 2017-08-26 13:28 sidebar: true comments: false diff --git a/source/_components/lock.august.markdown b/source/_components/lock.august.markdown new file mode 100644 index 0000000000..eda4f37d06 --- /dev/null +++ b/source/_components/lock.august.markdown @@ -0,0 +1,18 @@ +--- +layout: page +title: "August Lock" +description: "Instructions on how to integrate your August devices into Home Assistant." +date: 2018-02-17 22:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: august.png +ha_category: Lock +ha_release: "0.64" +ha_iot_class: "Cloud Polling" +--- + +The `august` lock platform allows you to control your [August](http://august.com) lock from within Home Assistant. + +To add `august` lock to your installation, follow instructions in [August component](/components/august/). diff --git a/source/_components/lock.bmw_connected_drive.markdown b/source/_components/lock.bmw_connected_drive.markdown new file mode 100755 index 0000000000..4c6c7a2edc --- /dev/null +++ b/source/_components/lock.bmw_connected_drive.markdown @@ -0,0 +1,20 @@ +--- +layout: page +title: "BMW Connected Drive Lock" +description: "Instructions on how to setup your BMW Connected Drive account with Home Assistant." +date: 2018-02-22 23:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: bmw.png +ha_category: Lock +ha_release: 0.66 +--- + + +The `bmw_connected_drive` platform allows you to import data on your BMW into Home Assistant. + +The lock will be automatically configured if `bmw_connected_drive` component is configured. + +For more configuration information see the [`bmw_connected_drive` component](/components/bmw_connected_drive/) documentation. diff --git a/source/_components/lock.homematic.markdown b/source/_components/lock.homematic.markdown new file mode 100644 index 0000000000..d536312e2e --- /dev/null +++ b/source/_components/lock.homematic.markdown @@ -0,0 +1,18 @@ +--- +layout: page +title: "Homematic Lock (KeyMatic)" +description: "Instructions how to integrate Homematic locks (KeyMatic) within Home Assistant." +date: 2018-01-28 03:00 +sidebar: true +comments: false +sharing: true +footer: true +logo: homematic.png +ha_category: Lock +ha_release: 0.66 +ha_iot_class: "Local Push" +--- + +The `homematic` lock platform lets you observe and control the state of the HomeMatic [Homematic](http://www.homematic.com/) KeyMatic lock through Home Assistant. + +Devices will be configured automatically. Please refer to the [component](/components/homematic/) configuration on how to setup Homematic. diff --git a/source/_components/lock.isy994.markdown b/source/_components/lock.isy994.markdown index 04109b9cd6..b019662a68 100644 --- a/source/_components/lock.isy994.markdown +++ b/source/_components/lock.isy994.markdown @@ -1,7 +1,7 @@ --- layout: page title: "ISY994 Lock" -description: "Instructions how to integrate ISY994 locks into Home Assistant." +description: "Instructions on how to integrate ISY994 locks into Home Assistant." date: 2016-09-03 23:00 sidebar: true comments: false diff --git a/source/_components/lock.lockitron.markdown b/source/_components/lock.lockitron.markdown index 418881c169..6b320e7108 100644 --- a/source/_components/lock.lockitron.markdown +++ b/source/_components/lock.lockitron.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Lockitron Lock" -description: "Instructions how to integrate Lockitron locks into Home Assistant." +description: "Instructions on how to integrate Lockitron locks into Home Assistant." date: 2017-03-24 00:00 sidebar: true comments: false diff --git a/source/_components/lock.markdown b/source/_components/lock.markdown index c2c3cc5530..67d5b6509a 100644 --- a/source/_components/lock.markdown +++ b/source/_components/lock.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Locks" -description: "Instructions how to setup your locks with Home Assistant." +description: "Instructions on how to setup your locks with Home Assistant." date: 2015-11-21 08:10 sidebar: true comments: false diff --git a/source/_components/lock.mqtt.markdown b/source/_components/lock.mqtt.markdown index 8ed47ccf4a..ff8eb05170 100644 --- a/source/_components/lock.mqtt.markdown +++ b/source/_components/lock.mqtt.markdown @@ -1,7 +1,7 @@ --- layout: page title: "MQTT Lock" -description: "Instructions how to integrate MQTT locks into Home Assistant." +description: "Instructions on how to integrate MQTT locks into Home Assistant." date: 2016-02-28 15:00 sidebar: true comments: false @@ -24,7 +24,7 @@ Optimistic mode can be forced, even if state topic is available. Try to enable i To enable MQTT locks in your installation, add the following to your `configuration.yaml` file: ```yaml -# Example configuration.yml entry +# Example configuration.yaml entry lock: - platform: mqtt command_topic: "home/frontdoor/set" 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 adabef99d1..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"
---
-
+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.
+
-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-).
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:
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 28f4d77f43..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
diff --git a/source/_components/mailgun.markdown b/source/_components/mailgun.markdown
index 78764d7507..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
diff --git a/source/_components/matrix.markdown b/source/_components/matrix.markdown
new file mode 100644
index 0000000000..1047d54053
--- /dev/null
+++ b/source/_components/matrix.markdown
@@ -0,0 +1,136 @@
+---
+layout: page
+title: "Matrix"
+description: "Matrix chatbot support"
+date: 2018-03-25 18:50
+sidebar: true
+comments: false
+sharing: true
+footer: true
+logo: matrix.png
+ha_category: Hub
+ha_version: 0.69
+---
+
+This component allows you to send messages to matrix rooms, as well as to react to messages in matrix rooms. Reacting to commands is accomplished by firing an event when one of the configured commands is triggered.
+
+```yaml
+# Example configuration.yaml entry
+matrix:
+ homeserver: https://matrix.org
+ username: "@my_matrix_user:matrix.org"
+ password: supersecurepassword
+ rooms:
+ - "#hasstest:matrix.org"
+ commands:
+ - word: my_command
+ name: my_command
+```
+
+Configuration variables:
+
+{% configuration %}
+username:
+ description: "The matrix username that home assistant should use to log in. *Note*: You must specify a full matrix ID here, including the homeserver domain, e.g. '@my_matrix_bot:matrix.org'. Please note also that the '@' character has a special meaning in YAML, so this must always be given in quotes."
+ required: true
+ type: string
+password:
+ description: The password for your Matrix account.
+ required: true
+ type: string
+homeserver:
+ description: "The full URL for your homeserver. If you use the defauls matrix.org homeserver, this is 'https://matrix.org'."
+ required: true
+ type: string
+verify_ssl:
+ description: Verify the homeservers certificate.
+ required: false
+ type: string
+ default: true
+rooms:
+ description: "The list of rooms that the bot should join and listen for commands (see below) in. While you can limit the list of rooms that a certain command applies to on a per-command basis (see below), you must still list all rooms here that commands should be received in. Rooms can be given either by their internal ID (e.g., '!cURbafjkfsMDVwdRDQ:matrix.org') or any of their aliases (e.g., '#matrix:matrix.org')."
+ required: false
+ type: [string]
+ default: empty
+commands:
+ description: "A list of commands that the bot should listen for. If a command is triggered (via its *word* or *expression*, see below), an event is fired that you can handle using automations. Every command consists of these possible configuration options:"
+ required: false
+ type: map
+ default: empty
+ keys:
+ word:
+ description: "Specifies a word that the bot should listen for. If you specify 'my_command' here, the bot will react to any message starting with '!my_command'."
+ required: false
+ type: string
+ expression:
+ description: "Specifies a regular expression (in python regexp syntax) that the bot should listen to. The bot will react to any message that matches the regular expression."
+ required: false
+ type: string
+ name:
+ description: "The name of the command. This will be an attribute of the event that is fired when this command triggers."
+ required: true
+ type: string
+ rooms:
+ description: "A list of rooms that the bot should listen for this command in. If this is not given, the *rooms* list from the main config is used. Please note that every room in this list must also be in the main *room* config."
+ required: false
+ type: [string]
+ default: empty
+{% endconfiguration %}
+
+### {% linkable_title Event Data %}
+
+If a command is triggered, a `matrix_command` event is fired. The event contains the name of the command in the `name` field. If the command is a word command that has no name set, the `name` field contains the word instead.
+
+If the command is a word command, the `data` field contains a list of the command's arguments, i.e., everything that stood behind the word, split at spaces. If the command is an expression command, the `data` field contains the [group dictionary](https://docs.python.org/3.6/library/re.html?highlight=re#re.match.groupdict) of the regular expression that matched the message.
+
+### {% linkable_title Comprehensive Configuration Example %}
+
+This example also uses the [matrix `notify` platform](/components/notify.matrix/).
+
+```yaml
+# The Matrix component
+matrix:
+ homeserver: https://matrix.org
+ username: "@my_matrix_user:matrix.org"
+ password: supersecurepassword
+ rooms:
+ - "#hasstest:matrix.org"
+ - "#someothertest:matrix.org"
+ commands:
+ - word: testword
+ rooms:
+ - "#someothertest:matrix.org"
+ - expression: "My name is (?P
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 744488bebe..d944b2b3a7 100644
--- a/source/_components/media_player.samsungtv.markdown
+++ b/source/_components/media_player.samsungtv.markdown
@@ -50,12 +50,15 @@ 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)
@@ -74,10 +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.
+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 61edbe9d8d..5b1ce8ed54 100644 --- a/source/_components/notify.pushsafer.markdown +++ b/source/_components/notify.pushsafer.markdown @@ -1,7 +1,7 @@ --- layout: page title: "Pushsafer" -description: "Instructions how to add Pushsafer notifications to Home Assistant." +description: "Instructions on how to add Pushsafer notifications to Home Assistant." date: 2018-01-05 11:15 sidebar: true comments: false @@ -42,11 +42,11 @@ Message to two devices with formatted text. "message": "Attention [b]bold[/b] text[br][url=https://www.pushsafer.com]Link to Pushsafer[/url]", "target": ["1111", "2222"], "data": { - "icon": "2", + "icon": "2", "iconcolor": "#FF0000", "sound": "2", "vibration": "1", - "url": "https://home-assistant.io/", + "url": "https://www.home-assistant.io/", "urltitle": "Open Home Assistant", "time2live": "0" } @@ -58,18 +58,18 @@ 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://home-assistant.io/]Testlink[/url]", + "message": "Attention [i]italic[/i] Text[br][url=https://www.home-assistant.io/]Testlink[/url]", "target": ["1111"], "data": { - "icon": "14", + "icon": "14", "iconcolor": "#FFFF00", "sound": "22", "vibration": "3", - "url": "https://home-assistant.io/", + "url": "https://www.home-assistant.io/", "urltitle": "Open Home Assistant", "time2live": "60", "picture1": { - "url":"https://home-assistant.io/images/components/alexa/alexa-512x512.png" + "url":"https://www.home-assistant.io/images/components/alexa/alexa-512x512.png" } } } @@ -80,14 +80,14 @@ 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://home-assistant.io/]Testlink[/url]", + "message": "Attention [i]italic[/i] Text[br][url=https://www.home-assistant.io/]Testlink[/url]", "target": ["1111","2222","gs3333"], "data": { - "icon": "20", + "icon": "20", "iconcolor": "#FF00FF", "sound": "33", "vibration": "0", - "url": "https://home-assistant.io/", + "url": "https://www.home-assistant.io/", "urltitle": "Open Home Assistant", "time2live": "10", "picture1": { @@ -99,6 +99,6 @@ Message to two devices and one device group with formatted text and local image. 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](https://home-assistant.io/images/favicon-192x192.png). +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