jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-24 01:37:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3082 from home-assistant/release-0-50

Browse Source 
0.50
This commit is contained in:
Fabian Affolter 2017-07-29 23:55:02 +02:00 committed by GitHub
commit cf78b5a188
60 changed files with 2172 additions and 358 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
_config.yml
View File

@ -142,12 +142,12 @@ social:
# Home Assistant release details
current_major_version: 0
current_minor_version: 49
current_patch_version: 1
date_released: 2017-07-24
current_minor_version: 50
current_patch_version: 0
date_released: 2017-07-29
# Either # or the anchor link to latest release notes in the blog post.
# Must be prefixed with a # and have double quotes around it.
# Major release:
patch_version_notes: "#release-0491---july-24"
patch_version_notes: "#"
# Minor release (Example #release-0431---april-25):

80
source/_components/alarm_control_panel.manual_mqtt.markdown Normal file
View File

@ -0,0 +1,80 @@
---
layout: page
title: "Manual Alarm Control Panel with MQTT Support"
description: "Instructions how to integrate manual alarms into Home Assistant with MQTT support."
date: 2017-07-02 9:10
sidebar: true
comments: false
sharing: true
footer: true
logo: home-assistant.png
ha_category: Alarm
ha_release: "0.50"
---
This platform extends the [manual alarm](/components/alarm_control_panel.manual/) by adding support for MQTT control of the alarm by a remote device. It can be used to create external keypads which simply change the state of the manual alarm in Home Assistant.
It's essentially the opposite of the [MQTT Alarm Panel](/components/alarm_control_panel.mqtt/) which allows Home Assistant to observe an existing, fully-featured alarm where all of the alarm logic is embedded in that physical device.
The component will accept the following commands from your Alarm Panel via the `command_topic`:
- `DISARM`
- `ARM_HOME`
- `ARM_AWAY`
When the state of the manual alarm changes, Home Assistant will publish one of the following states to the `state_topic`:
- 'disarmed'
- 'armed_home'
- 'armed_away'
- 'pending'
- 'triggered'
```yaml
# Example configuration.yaml entry
alarm_control_panel:
- platform: manual_mqtt
state_topic: home/alarm
command_topic: home/alarm/set
```
Configuration variables:
All configuration variables from the base manual alarm platform are available:
- **name** (*Optional*): The name of the alarm. Default is "HA Alarm".
- **code** (*Optional*): If defined, specifies a code to enable or disable the alarm in the frontend. This code is not required for MQTT interactions.
- **pending_time** (*Optional*): The time in seconds of the pending time before arming the alarm. Default is 60 seconds.
- **trigger_time** (*Optional*): The time in seconds of the trigger time in which the alarm is firing. Default is 120 seconds.
- **disarm_after_trigger** (*Optional*): If true, the alarm will automatically disarm after it has been triggered instead of returning to the previous state.
Additionally, the following MQTT configuration variables are also available:
- **state_topic** (*Required*): The MQTT topic HA will publish state updates to.
- **command_topic** (*Required*): The MQTT topic HA will subscribe to to receive commands from a remote device to change the alarm state.
- **qos** (*Optional*): The maximum QoS level for subscribing and publishing to MQTT messages. Default is 0.
- **payload_disarm** (*Optional*): The payload to disarm this Alarm Panel. Default is "DISARM".
- **payload_arm_home** (*Optional*): The payload to set armed-home mode on this Alarm Panel. Default is "ARM_HOME".
- **payload_arm_away** (*Optional*): The payload to set armed-away mode on this Alarm Panel. Default is "ARM_AWAY".
## {% linkable_title Examples %}
Refer to the [Manual Alarm Control page](/components/alarm_control_panel.manual/#examples) for some real life examples of how to use this panel.
## {% linkable_title MQTT Control %}
The state of this alarm can be controlled using [MQTT](/components/mqtt/). Ensure you've configured that before adding this component.
To change the state of the alarm, publish one of the following messages to the `command_topic`:
- `DISARM`
- `ARM_HOME`
- `ARM_AWAY`
To receive state updates from HA, subscribe to the `state_topic`. Home Assistant will publish a new message whenever the state changes:
- `disarmed`
- `armed_home`
- `armed_away`
- `pending`
- `triggered`

147
source/_components/alexa.markdown
View File

@ -15,42 +15,14 @@ ha_release: 0.10
There are a few ways that you can use Amazon Echo and Home Assistant together.
- [Turning devices on and off](#i-just-want-to-turn-devices-on-and-off-using-echo)
- [Build custom commands to use](#i-want-to-build-custom-commands-to-use-with-echo)
- [Create a new Flash Briefing source](#flash-briefing-skills)
No matter which method(s) you decide to use, please remember that Amazon Echo requires an active Internet connection to function. If your Internet is down or experiencing issues (or Amazon's infrastructure is having issues), none of these methods will work.
- Alternative: use the [Emulated Hue component][emulated-hue-component] to trick Alexa to thinking Home Assistant is a Philips Hue hub.
Amazon has released [Echosim], a website that simulates the Alexa service in your browser. That way it is easy to test your skills without having access to a physical Amazon Echo.
[Echosim]: https://echosim.io/
## {% linkable_title I just want to turn devices on and off using Echo %}
If you just want to be able to turn anything with a switch (like lights, switches, media players, etc) on and off, you should enable the [Emulated Hue][emulated-hue-component] component. It makes your Home Assistant appear as if it were a Phillips Hue bridge, which Echo works with natively.
[emulated-hue-component]: https://home-assistant.io/components/emulated_hue/
Enabling the Emulated Hue component means you can turn things on and off by simply saying
> Alexa, turn the living room lights on.
or
> Alexa, set the living room lights to twenty percent.
instead of
> Alexa, tell Home Assistant to turn the living room lights on.
or
> Alexa, tell Home Assistant to set the living room lights to twenty percent.
In addition, you would need to build custom intents for each device and on/off combination using the below method, whereas everything just works without any extra work by using Emulated Hue.
Please note that you can use Emulated Hue and the built-in Alexa component side-by-side without issue if you wish.
## {% linkable_title I want to build custom commands to use with Echo %}
The built-in Alexa component allows you to integrate Home Assistant into Alexa/Amazon Echo. This component will allow you to query information and call services within Home Assistant by using your voice. Home Assistant offers no built-in sentences but offers a framework for you to define your own.
@ -121,54 +93,7 @@ This means that we can now ask Alexa things like:
## {% linkable_title Configuring Home Assistant %}
Out of the box, the component will do nothing. You have to teach it about all intents you want it to answer to. The way it works is that the answer for each intent is based on [templates] that you define. Each template will have access to the existing states via the `states` variable but will also have access to all variables defined in the intent.
You can use [templates] for the values of `speech/text`, `card/title` and `card/content`.
Actions are using the [Home Assistant Script Syntax] and also have access to the variables from the intent.
[Home Assistant Script Syntax]: /getting-started/scripts/
Configuring the Alexa component for the above intents would look like this:
```yaml
{% raw %}# Example configuration.yaml entry
alexa:
intents:
WhereAreWeIntent:
speech:
type: plaintext
text: >
{%- if is_state('device_tracker.paulus', 'home') and
is_state('device_tracker.anne_therese', 'home') -%}
You are both home, you silly
{%- else -%}
Anne Therese is at {{ states("device_tracker.anne_therese") }}
and Paulus is at {{ states("device_tracker.paulus") }}
{% endif %}
LocateIntent:
action:
service: notify.notify
data_template:
message: The location of {{ User }} has been queried via Alexa.
speech:
type: plaintext
text: >
{%- for state in states.device_tracker -%}
{%- if state.name.lower() == User.lower() -%}
{{ state.name }} is at {{ state.state }}
{%- elif loop.last -%}
I am sorry, I do not know where {{ User }} is.
{%- endif -%}
{%- else -%}
Sorry, I don't have any trackers registered.
{%- endfor -%}
card:
type: simple
title: Sample title
content: Some more content{% endraw %}
```
When activated, the Alexa component will have Home Assistant's native intent support handle the incoming intents. If you want to run actions based on intents, use the [`intent_script`](/components/intent_script) component.
### {% linkable_title Working With Scenes %}
@ -203,17 +128,18 @@ Add a sample utterance:
ActivateSceneIntent activate {Scene}
```
Then add the intent to your Alexa Section in your HA config file:
Then add the intent to your intent_script section in your HA config file:
```yaml
ActivateSceneIntent:
action:
service: scene.turn_on
data_template:
entity_id: scene.{% raw %}{{ Scene | replace(" ", "_") }}{% endraw %}
speech:
type: plaintext
text: OK
intent_script:
ActivateSceneIntent:
action:
service: scene.turn_on
data_template:
entity_id: scene.{% raw %}{{ Scene | replace(" ", "_") }}{% endraw %}
speech:
type: plain
text: OK
```
Here we are using [templates] to take the name we gave to Alexa e.g. `downstairs on` and replace the space with an underscore so it becomes `downstairs_on` as Home Assistant expects.
@ -250,17 +176,18 @@ Add a sample utterance:
RunScriptIntent run {Script}
```
Then add the intent to your Alexa Section in your HA config file:
Then add the intent to your intent_script section in your HA config file:
```yaml
RunScriptIntent:
action:
service: script.turn_on
data_template:
entity_id: script.{% raw %}{{ Script | replace(" ", "_") }}{% endraw %}
speech:
type: plaintext
text: OK
intent_script:
RunScriptIntent:
action:
service: script.turn_on
data_template:
entity_id: script.{% raw %}{{ Script | replace(" ", "_") }}{% endraw %}
speech:
type: plain
text: OK
```
Now say `Alexa ask homeassistant to run <some script>` and Alexa will run that script for you.
@ -306,35 +233,6 @@ text: !include alexa_confirm.yaml
Alexa will now respond with a random phrase each time. You can use the include for as many different intents as you like so you only need to create the list once.
<p class='note'>
As of April 2017, the random filter has been somewhat broken. You'll get a random response the first time this runs, but subsequent commands will reply with the same randomly-chosen phrase. On reboot, Home Assistant will pick a new random choice, but you're stuck with that choice till you reboot. To get around that, use the following code in alexa_confirm.yaml:
</p>
```text
{% raw %} >
{% set responses = [
"OK",
"Sure",
"If you insist",
"Done",
"No worries",
"I can do that",
"Leave it to me",
"Consider it done",
"As you wish",
"By your command",
"Affirmative",
"Yes oh revered one",
"I will",
"As you decree, so shall it be",
"No Problem"
] %}
{% set rindex = (range(0, (responses | length - 1) )|random) -%}
{{responses[rindex]}}
{% endraw %}
```
## {% linkable_title Flash Briefing Skills %}
As of version [0.31][zero-three-one] Home Assistant supports the new [Alexa Flash Briefing Skills API][flash-briefing-api]. A Flash Briefing Skill adds a new Flash Briefing source that is generated by Home Assistant.
@ -395,3 +293,4 @@ Please refer to the [Amazon documentation][flash-briefing-api-docs] for more inf
[templates]: /topics/templating/
[zero-three-one]: /blog/2016/10/22/flash-briefing-updater-hacktoberfest/
[alexa-settings-site]: http://alexa.amazon.com/
[emulated-hue-component]: /components/emulated_hue/

103
source/_components/apiai.markdown
View File

@ -58,35 +58,7 @@ Take a look to "Integrations", in the left menu, to configure third parties.
### {% linkable_title Configuring Home Assistant %}
Out of the box, the component will do nothing. You have to teach it about all intents you want it to answer to. The way it works is that the answer for each intent is based on [templates] that you define. Each template will have access to the existing states via the `states` variable but will also have access to all variables defined in the intent.
You can use [templates] for setting `speech`.
Actions are using the [Home Assistant Script Syntax] and also have access to the variables from the intent.
[Home Assistant Script Syntax]: /getting-started/scripts/
Example of an Api.ai for the above configuration:
```yaml
{% raw %}# Example configuration.yaml entry
apiai:
intents:
GetTemperature:
speech: We have {{ states.sensor.temperature }} degrees
async_action: False
action:
service: notify.notify
data_template:
message: Api.ai has send a request
{% endraw %}
```
Inside an intent we can define this variables:
- **speech** (*Optional*): Text or template to return to Api.ai
- **action** (*Optional*): Script definition
- **async_action** (*Optional*): If Home Assistant should execute the action asynchronously (returning response to Api.ai without waiting the action to finish). Should be set to `True` if Api.ai is returning the "Cannot connect to Home Assistant or it is taking to long" message, but then you will not be able to use values based on the result of the action. Defaults to `False`.
When activated, the Alexa component will have Home Assistant's native intent support handle the incoming intents. If you want to run actions based on intents, use the [`intent_script`](/components/intent_script) component.
## {% linkable_title Examples %}
@ -95,43 +67,44 @@ Download [this zip](https://github.com/home-assistant/home-assistant.github.io/b
```yaml
{% raw %}# Example configuration.yaml entry
apiai:
intents:
Temperature:
speech: The temperature at home is {{ states('sensor.home_temp') }} degrees
LocateIntent:
speech: >
{%- for state in states.device_tracker -%}
{%- if state.name.lower() == User.lower() -%}
{{ state.name }} is at {{ state.state }}
{%- elif loop.last -%}
I am sorry, I do not know where {{ User }} is.
intent_script:
Temperature:
speech: The temperature at home is {{ states('sensor.home_temp') }} degrees
LocateIntent:
speech: >
{%- for state in states.device_tracker -%}
{%- if state.name.lower() == User.lower() -%}
{{ state.name }} is at {{ state.state }}
{%- elif loop.last -%}
I am sorry, I do not know where {{ User }} is.
{%- endif -%}
{%- else -%}
Sorry, I don't have any trackers registered.
{%- endfor -%}
WhereAreWeIntent:
speech: >
{%- if is_state('device_tracker.adri', 'home') and
is_state('device_tracker.bea', 'home') -%}
You are both home, you silly
{%- else -%}
Bea is at {{ states("device_tracker.bea") }}
and Adri is at {{ states("device_tracker.adri") }}
{% endif %}
TurnLights:
speech: Turning {{ Room }} lights {{ OnOff }}
action:
- service: notify.pushbullet
data_template:
message: Someone asked via apiai to turn {{ Room }} lights {{ OnOff }}
- service_template: >
{%- if OnOff == "on" -%}
switch.turn_on
{%- else -%}
switch.turn_off
{%- endif -%}
{%- else -%}
Sorry, I don't have any trackers registered.
{%- endfor -%}
WhereAreWeIntent:
speech: >
{%- if is_state('device_tracker.adri', 'home') and
is_state('device_tracker.bea', 'home') -%}
You are both home, you silly
{%- else -%}
Bea is at {{ states("device_tracker.bea") }}
and Adri is at {{ states("device_tracker.adri") }}
{% endif %}
TurnLights:
speech: Turning {{ Room }} lights {{ OnOff }}
action:
- service: notify.pushbullet
data_template:
message: Someone asked via apiai to turn {{ Room }} lights {{ OnOff }}
- service_template: >
{%- if OnOff == "on" -%}
switch.turn_on
{%- else -%}
switch.turn_off
{%- endif -%}
data_template:
entity_id: "switch.light_{{ Room | replace(' ', '_') }}"
data_template:
entity_id: "switch.light_{{ Room | replace(' ', '_') }}"
{% endraw %}
```

146
source/_components/apple_tv.markdown Normal file
View File

@ -0,0 +1,146 @@
---
layout: page
title: "Apple TV"
description: "Instructions how to integrate Apple TV devices into Home Assistant."
date: 2017-06-26 20:47
sidebar: true
comments: false
sharing: true
footer: true
logo: apple.png
ha_category: Hub
ha_iot_class: "Local Push"
ha_release: 0.49
featured: true
---
The `apple_tv` platform allows you to control an Apple TV (3rd and 4th generation). See the [remote platform](/components/remote.apple_tv/) if you want to send remote control buttons, e.g. arrow keys.
<p class='note'>
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.
</p>
To use this component, you must first install some system libraries and a compiler. For Debian or a similar system, this should be enough:
```shell
$ sudo apt-get install build-essential libssl-dev libffi-dev python-dev
```
If you want to automatically discover new devices, just make sure you have `discovery:` in your `configuration.yaml` file. To manually add one or more Apple TVs to your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
apple_tv:
- host: IP_1
login_id: LOGIN_ID_1
name: NAME_1
start_off: START_OFF_1
credentials: CREDENTIALS_1
- host: IP_2
login_id: LOGIN_ID_2
name: NAME_2
start_off: START_OFF_2
credentials: CREDENTIALS_2
```
Configuration variables:
- **host** (*Required*): The IP-address of the device.
- **login_id** (*Required*): An identifier used to login to the device, see below.
- **name** (*Optional*): The name of the device used in the frontend.
- **start_off** (*Optional*): Set to true if device should start in fake standby.
- **credentials** (*Optional*): Credentials used for AirPlay playback.
In order to connect to the device you need a *login id*. The easiest way to obtain this identifier is to use the `apple_tv_scan` service (described below). Additional information about `start_off` and `credentials` can also be found under the guides section.
## {% linkable_title Guides %}
### {% linkable_title Scanning for devices %}
To scan for devices, press the icon in the upper left corner and select the leftmost icon according to the image:
<img src='/images/screenshots/developer-tools.png' />
Select `apple_tv` as domain and `apple_tv_scan` as service then press the button:
<img src='/images/components/apple_tv/scan_start.jpg' />
Scanning will be done for three seconds and notification will be shown in the state view with all found devices:
<img src='/images/components/apple_tv/scan_result.jpg' />
Alternatively you may use the application ``atvremote``. Install it with ``pip3 install --upgrade pyatv`` in your Home Assistant environment (note: do *not* use sudo). Then run ``atvremote scan`` to scan for all devices (try again if a device is missing):
```bash
$ atvremote scan
Found Apple TVs:
- Apple TV at 10.0.10.22 (login id: 00000000-1234-5678-9012-345678901234)
Note: You must use 'pair' with devices that have home sharing disabled
```
Just copy and paste the login id from the device you want to add. For more details about `atvremote`, see: [this page](http://pyatv.readthedocs.io/en/master/atvremote.html).
### {% linkable_title My Apple TV turns on when I restart Home Assistant %}
The Apple TV will automatically turn on if a request is sent to it, e.g. if a button is pressed, something is streamed to it via AirPlay or if current state (currently playing) is accessed. This is how Apple has designed it and it will cause problems if you are using HDMI CEC. Every time Home Assistant is started, a new request is sent to the device to figure out what is currently playing. When using CEC, this will wake up your TV and other devices you have configured.
So, if your TV is randomly turning on, this is probably the reason. As stated, this is by design and there is no real fix for it. There's also no known way to turn off the Apple TV via the procotol used for communication. You basically have the following options:
- Do not use this platform
- Disable HDMI CEC on your Apple TV
- Use "fake standby"
The first two points are quite obvious. Fake standby is a concept implemented in this platform that disables all requests to the device and make it appear as being "off" in the web interface. This will make sure that the device is not woken up, but it will of course not show any information or allow you to control it. It is however easy to turn it on (or off) in the web interface or using an automation with `turn_on`. To make it more useful, you can write automations that turns it on or off depending on some other device, like the input source on your receiver.
To put a device into fake standby when starting Home Assistant, add `start_off: true` to your configuration.
<p class='note warning'>
Turning the device on/off in the user interface will *not* turn the physical device on/off according to description above.
</p>
### {% linkable_title Setting up device authentication %}
If you, when playing media with `play_url`, get the following error message:
*“This AirPlay connection requires iOS 7.1 or later, OS X 10.10 or later, or iTunes 11.2 or later.”*
then device authentication is required. Press the icon in the upper left corner and select the leftmost icon according to the image below:
<img src='/images/screenshots/developer-tools.png' />
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:
<img src='/images/components/apple_tv/auth_start.jpg' />
If no dialog appears, go back to the states view and display it from there (press `CONFIGURE` as displayed in the image):
<img src='/images/components/apple_tv/auth_pin.jpg' />
A PIN code should now be visible on your TV, just enter it into the dialog and press "Confirm". You should see if it succeeded in the state view. Copy the credentials and insert it into your configuration (make sure you copy everything, it should be 81 characters) after ``credentials:`` with no line-break:
```yaml
# Example configuration.yaml entry
apple_tv:
- host: 10.0.0.20
login_id: 00000000-1234-5678-9012-345678901234
credentials: 1B8C387DDB59BDF6:CF5ABB6A2C070688F5926ADB7C010F6DF847252C15F9BDB6DA3E09D6591E90E5
```
Restart Home Assistant and you should now be able to use `play_url` as before.
## {% linkable_title Services %}
### {% linkable_title Service `apple_tv_authenticate` %}
In order to play media on an Apple TV with device authentication enabled (e.g. ATV4 with tvOS 10.2+), Home Assistant must properly authenticated. This method starts the process and presents the credentials needed for playback as a persistent notification. Please see guide above for usage.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of Apple TVs.
### {% linkable_title Service `apple_tv_scan` %}
Scans the local network for Apple TVs. All found devices are presented as a persistent notification.

42
source/_components/binary_sensor.velbus.markdown Normal file
View File

@ -0,0 +1,42 @@
---
layout: page
title: "Velbus sensors"
description: "Access and control your Velbus sensors."
date: 2017-06-17 16.58
sidebar: true
comments: false
sharing: true
footer: true
logo: velbus.png
ha_category: Binary Sensor
ha_iot_class: "Local Push"
ha_release: 0.49
---
The `velbus` binary_sensor allows you to control [Velbus](http://www.velbus.eu) connected wall switches.
To use your Velbus wall switches in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
binary_sensor:
- platform: velbus
devices:
- name: Wall Switch 1
module: 0xda
channel: 4
- name: Wall Switch 2
module: 0xbc
channel: 1
is_pushbutton: true
```
Configuration variables:
- **devices** array (*Required*): The array contains the binary sensors to configure
- **name** (*Required*): Name of the binary sensor.
- **module** (*Required*): The hexadecimal module address
- **channel** (*Required*): The channel number in the module.
- **is_pushbutton** (*Optional*): Booelan to indicate if a wall switch is a push button or not (default: false)
For hub configuration, see [the Velbus component](/components/velbus/).

294
source/_components/binary_sensor.xiaomi.markdown Normal file
View File

@ -0,0 +1,294 @@
---
layout: page
title: "Xiaomi Binary Sensor"
description: "Instructions how to setup the Xiaomi binary sensors within Home Assistant."
date: 2017-07-21 16:34
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Binary Sensor
ha_release: "0.50"
ha_iot_class: "Local Polling"
---
The `xiaomi` binary sensor platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) binary sensors.
The requirement is that you have setup the [`xiaomi` component](/components/xiaomi/).
### {% linkable_title Type of sensors supported %}
- Motion
- Door / Window
- Smoke
- Gas
- Xiaomi Wireless Button
- Xiaomi Cube
### {% linkable_title Automation examples %}
#### {% linkable_title Motion %}
```yaml
- alias: If there is motion and its dark turn on the gateway light
trigger:
platform: state
entity_id: binary_sensor.motion_sensor_158d000xxxxxc2
from: 'off'
to: 'on'
condition:
condition: numeric_state
entity_id: sensor.illumination_34ce00xxxx11
below: 300
action:
service: light.turn_on
entity_id: light.gateway_light_34ce00xxxx11
data:
brightness: 5
- alias: If there no motion for 5 minutes turn off the gateway light
trigger:
platform: state
entity_id: binary_sensor.motion_sensor_158d000xxxxxc2
from: 'on'
to: 'off'
for:
minutes: 5
action:
service: light.turn_off
entity_id: light.gateway_light_34ce00xxxx11
```
#### {% linkable_title Door and/or Window %}
```yaml
- alias: If the window is open turn off the radiator
trigger:
platform: state
entity_id: binary_sensor.door_window_sensor_158d000xxxxxc2
from: 'off'
to: 'on'
action:
service: climate.set_operation_mode
entity_id: climate.livingroom
data:
operation_mode: 'Off'
- alias: If the window is closed for 5 minutes turn on the radiator again
trigger:
platform: state
entity_id: binary_sensor.door_window_sensor_158d000xxxxxc2
from: 'on'
to: 'off'
for:
minutes: 5
action:
service: climate.set_operation_mode
entity_id: climate.livingroom
data:
operation_mode: 'Smart schedule'
```
#### {% linkable_title Smoke %}
```yaml
- alias: Send notification on fire alarm
trigger:
platform: state
entity_id: binary_sensor.smoke_sensor_158d0001574899
from: 'off'
to: 'on'
action:
- service: notify.html5
data:
title: Fire alarm!
message: Fire/Smoke detected!
- service: xiaomi.play_ringtone
data:
gw_mac: xxxxxxxxxxxx
ringtone_id: 2
ringtone_vol: 100
```
#### {% linkable_title Gas %}
```yaml
- alias: Send notification on gas alarm
trigger:
platform: state
entity_id: binary_sensor.natgas_sensor_158dxxxxxxxxxx
from: 'off'
to: 'on'
action:
- service: notify.html5
data_template:
title: Gas alarm!
message: 'Gas with a density of {% raw %}{{ states.binary_sensor.natgas_sensor_158dxxxxxxxxxx.attributes.density }}{% endraw %} detected.'
```
#### {% linkable_title Xiaomi Wireless Button %}
Available events are `single`, `double`, `hold`, `long_click_press` and `long_click_release`. For Square version (Aqara brand) only `single` and `double` events are supported. Furthermore the space between two clicks to generate a double click must be quite large now.
```yaml
- alias: Toggle dining light on single press
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.switch_158d000xxxxxc2
click_type: single
action:
service: switch.toggle
entity_id: switch.wall_switch_left_158d000xxxxx01
- alias: Toggle couch light on double click
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.switch_158d000xxxxxc2
click_type: double
action:
service: switch.toggle
entity_id: switch.wall_switch_right_158d000xxxxx01
- alias: Let a dog bark on long press
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.switch_158d000xxxxxc2
click_type: long_click_press
action:
service: xiaomi.play_ringtone
data:
gw_mac: xxxxxxxxxxxx
ringtone_id: 8
ringtone_vol: 8
```
#### {% linkable_title Xiaomi Cube %}
Available events are `flip90`, `flip180`, `move`, `tap_twice`, `shake_air`, `swing`, `alert`, `free_fall` and `rotate`.
```yaml
- alias: Cube event flip90
trigger:
platform: event
event_type: cube_action
event_data:
entity_id: binary_sensor.cube_15xxxxxxxxxxxx
action_type: flip90
action:
- service: light.turn_on
entity_id: light.gateway_light_28xxxxxxxxxx
data:
color_name: "springgreen"
- alias: Cube event flip180
trigger:
platform: event
event_type: cube_action
event_data:
entity_id: binary_sensor.cube_15xxxxxxxxxxxx
action_type: flip180
action:
- service: light.turn_on
entity_id: light.gateway_light_28xxxxxxxxxx
data:
color_name: "darkviolet"
- alias: Cube event move
trigger:
platform: event
event_type: cube_action
event_data:
entity_id: binary_sensor.cube_15xxxxxxxxxxxx
action_type: move
action:
- service: light.turn_on
entity_id: light.gateway_light_28xxxxxxxxxx
data:
color_name: "gold"
- alias: Cube event tap_twice
trigger:
platform: event
event_type: cube_action
event_data:
entity_id: binary_sensor.cube_15xxxxxxxxxxxx
action_type: tap_twice
action:
- service: light.turn_on
entity_id: light.gateway_light_28xxxxxxxxxx
data:
color_name: "deepskyblue"
- alias: Cube event shake_air
trigger:
platform: event
event_type: cube_action
event_data:
entity_id: binary_sensor.cube_15xxxxxxxxxxxx
action_type: shake_air
action:
- service: light.turn_on
entity_id: light.gateway_light_28xxxxxxxxxx
data:
color_name: "blue"
```
#### #### {% linkable_title Aqara Wireless Switch %}
The Aqara Wireless Switch is available as single-key and double-key version. Each key behaves like the Wireless Button limited to the click event `single`. The double key version adds a third device called `binary_sensor.wall_switch_both_158xxxxxxxxx12` which reports a click event called `both` if both keys are pressed.
```yaml
- alias: Decrease brightness of the gateway light
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.wall_switch_left_158xxxxxxxxx12
click_type: single
action:
service: light.turn_on
entity_id: light.gateway_light_34xxxxxxxx13
data_template:
brightness: {% raw %}>-
{% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness %}
{% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness - 60 >= 10 %}
{{states.light.gateway_light_34xxxxxxxx13.attributes.brightness - 60}}
{% else %}
{{states.light.gateway_light_34xxxxxxxx13.attributes.brightness}}
{% endif %}
{% else %}
10
{% endif %}{% endraw %}
- alias: Increase brightness of the gateway light
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.wall_switch_right_158xxxxxxxxx12
click_type: single
action:
service: light.turn_on
entity_id: light.gateway_light_34xxxxxxxx13
data_template:
brightness: {% raw %}>-
{% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness %}
{% if states.light.gateway_light_34xxxxxxxx13.attributes.brightness + 60 <= 255 %}
{{states.light.gateway_light_34xxxxxxxx13.attributes.brightness + 60}}
{% else %}
{{states.light.gateway_light_34xxxxxxxx13.attributes.brightness}}
{% endif %}
{% else %}
10
{% endif %}{% endraw %}
- alias: Turn off the gateway light
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.wall_switch_both_158xxxxxxxxx12
click_type: both
action:
service: light.turn_off
entity_id: light.gateway_light_34xxxxxxxx13
```

15
source/_components/conversation.markdown
View File

@ -12,7 +12,7 @@ ha_category: "Voice"
---
The conversation component can process sentences into commands for Home Assistant. It currently has built in functionality to recognize `turn <Friendly Name> <on/off>`, but custom phrases can be added through configuration.
The `conversation` component can process sentences into commands for Home Assistant. It currently has built in functionality to recognize `turn <Friendly Name> <on/off>`, but custom phrases can be added through configuration.
To enable the conversation option in your installation, add the following to your `configuration.yaml` file:
@ -23,6 +23,7 @@ conversation:
```
To add custom phrases to be recognized:
```yaml
# Example configuration.yaml entry with custom phrasesconversation
conversation:
@ -32,11 +33,17 @@ conversation:
service: input_boolean.toggle
```
The action keyword uses [script
syntax](https://home-assistant.io/docs/scripts/).
The action keyword uses [script syntax](https://home-assistant.io/docs/scripts/).
To use the `conversation` component with the [`shopping list` component](/components/shopping_list/) add an intent.
```yaml
# Example configuration.yaml entry
conversation:
intents:
ShoppingListAddItem:
- Add {item} to my shopping list
```
When this component is active and you are using a supported browser voice commands will be activated in the frontend. Browse to [the demo](/demo/) using Chrome or Chromium to see it in action.

20
source/_components/cover.xiaomi.markdown Normal file
View File

@ -0,0 +1,20 @@
---
layout: page
title: "Xiaomi Cover"
description: "Instructions how to setup the Xiaomi cover within Home Assistant."
date: 2017-07-21 16:34
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Cover
ha_release: "0.50"
ha_iot_class: "Local Polling"
---
The `xiaomi` cover platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) covers.
The requirement is that you have setup [Xiaomi](/components/xiaomi/).

2
source/_components/dyson.markdown
View File

@ -36,7 +36,7 @@ Configuration variables:
- **username** (*Required*): Dyson account username (email address)
- **password** (*Required*): Dyson account password
- **language** (*Required*): Dyson account language country code. Known working codes: `FR`, `NL`, `UK`, `AU`. But others codes should work.
- **language** (*Required*): Dyson account language country code. Known working codes: `FR`, `NL`, `GB`, `AU`. But others codes should work.
- **devices** (*Optional*): List of devices
- **device_id** (*Required*): Device ID. Available in the mobiles applications (*Settings* page)
- **device_ip** (*Required*): Device IP address

41
source/_components/fan.velbus.markdown Normal file
View File

@ -0,0 +1,41 @@
---
layout: page
title: "Velbus Fans"
description: "Access and control your Velbus fans."
date: 2017-06-17 16.58
sidebar: true
comments: false
sharing: true
footer: true
logo: velbus.png
ha_category: Fan
ha_iot_class: "Local Push"
ha_release: 0.49
---
The `velbus` fan allows you to control [Velbus](http://www.velbus.eu) connected fans.
To use your Velbus fans in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
fan:
- platform: velbus
devices:
- name: Fan 1
module: 0xda
channel_low: 4
channel_medium: 3
channel_high: 2
```
Configuration variables:
- **devices** array (*Required*): The array contains the fans to configure
- **name** (*Required*): Name of the fan.
- **module** (*Required*): The hexadecimal module address
- **channel_low** (*Required*): The channel number in the module for low-speed.
- **channel_medium** (*Required*): The channel number in the module for medium-speed.
- **channel_high** (*Required*): The channel number in the module for high-speed.
For hub configuration, see [the Velbus component](/components/velbus/).

9
source/_components/feedreader.markdown
View File

@ -52,14 +52,13 @@ automation:
service: persistent_notification.create
data_template:
title: "New HA Podcast available"
message: {% raw %}"New Podcast available - {{ as_timestamp(now()) | timestamp_custom('%I:%M:%S %p %d%b%Y', true) }}"
notification_id: "{{ trigger.event.data.title }}"{% endraw %}
message: {% raw %}"New Podcast available - {{ as_timestamp(now()) | timestamp_custom('%I:%M:%S %p %d%b%Y', true) }}"{% endraw %}
notification_id: {% raw %}"{{ trigger.event.data.title }}"{% endraw %}
```
*Any field under the `<entry>` tag in the feed can be used for example `trigger.event.data.content` will get the body of the feed entry.
Any field under the `<entry>` tag in the feed can be used for example `trigger.event.data.content` will get the body of the feed entry.
For more advanced use cases, a custom component registering to the `feedreader` event type could be used instead:
For a drop in packaged complete example of Feedreader, you can use the [PodCast notifier](https://github.com/CCOSTAN/Home-AssistantConfig/blob/master/packages/hasspodcast.yaml).
```python
EVENT_FEEDREADER = "feedreader"
@ -67,3 +66,5 @@ hass.bus.listen(EVENT_FEEDREADER, event_listener)
```
To get started developing custom components, please refer to the [developers](/developers) documentation
For a drop in packaged complete example of Feedreader, you can use the [PodCast notifier](https://github.com/CCOSTAN/Home-AssistantConfig/blob/master/packages/hasspodcast.yaml).

36
source/_components/intent_script.markdown Normal file
View File

@ -0,0 +1,36 @@
---
layout: page
title: "Intent Script"
description: "Instructions on how to setup scripts to run on intents."
date: 2016-02-10 17:11
sidebar: true
comments: false
sharing: true
footer: true
logo: home-assistant.png
ha_category: Intent
ha_release: "0.50"
---
The intent_script component allows users to configure actions and responses to intents. Intents can be fired by any component that supports it. Examples are Alexa (Amazon Echo), API.ai (Google Assistant) and Snips.
```yaml
# Example configuration.yaml entry
intent_script:
GetTemperature: # Intent type
speech:
text: We have {% raw %}{{ states.sensor.temperature }}{% endraw %} degrees
action:
service: notify.notify
data_template:
message: Hello from an intent!
```
Configuration variables:
Inside an intent we can define these variables:
- **intent** (*Required*): Name of the intent. Multiple entries are possible.
- **speech** (*Optional*): Text or template to return.
- **action** (*Optional*): [Script syntax](/docs/scripts/).
- **async_action** (*Optional*): Set to True to have Home Assistant not wait for the script to finish before returning the intent response.

40
source/_components/light.tplink.markdown Normal file
View File

@ -0,0 +1,40 @@
---
layout: page
title: "TPLink Bulb"
description: "Instructions how to integrate TPLink bulbs into Home Assistant."
date: 2017-07-25 08:00
sidebar: true
comments: false
sharing: true
footer: true
logo: tp-link.png
ha_category: Light
ha_iot_class: "Local Polling"
ha_release: "0.50"
---
The `tplink` light platform allows you to control the state of your [TPLink smart bulb](http://www.tp-link.com/en/products/list-5609.html).
Supported units:
- LB100
- LB110
- LB120
- LB130
To use your TPLink light in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
light:
- platform: tplink
host: IP_ADDRESS
```
Configuration variables:
- **host** (*Required*): The IP address of your TP-Link bulb, eg. `192.168.1.32`.
- **name** (*Optional*): The name to use when displaying this bulb.

40
source/_components/light.velbus.markdown Normal file
View File

@ -0,0 +1,40 @@
---
layout: page
title: "Velbus lights"
description: "Access and control your Velbus lights."
date: 2017-06-17 16.58
sidebar: true
comments: false
sharing: true
footer: true
logo: velbus.png
ha_category: Light
ha_iot_class: "Local Push"
ha_release: 0.49
---
The `velbus` light allows you to control [Velbus](http://www.velbus.eu) lights.
To use your Velbus lights in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
light:
- platform: velbus
devices:
- name: Light 1
module: 0xda
channel: 4
- name: Light 2
module: 0xbc
channel: 1
```
Configuration variables:
- **devices** array (*Required*): The array contains the lights to configure
- **name** (*Required*): Name of the light.
- **module** (*Required*): The hexadecimal module address
- **channel** (*Required*): The channel number in the module.
For hub configuration, see [the Velbus component](/components/velbus/).

20
source/_components/light.xiaomi.markdown Normal file
View File

@ -0,0 +1,20 @@
---
layout: page
title: "Xiaomi Light"
description: "Instructions how to setup the Xiaomi light within Home Assistant."
date: 2017-07-21 16:34
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Light
ha_release: "0.50"
ha_iot_class: "Local Polling"
---
The `xiaomi` light platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) lights.
The requirement is that you have setup [Xiaomi](/components/xiaomi/).

31
source/_components/media_extractor.markdown
View File

@ -13,7 +13,10 @@ ha_release: 0.49
---
The `media_extractor` component gets a stream URL and sends it to a media player entity.
The `media_extractor` component gets an stream URL and send it to a media player entity. This component can extract entity specific streams if configured accordingly.
<p class='note'>
Media extractor doesn't transcode streams, it just tries to find stream that match requested query.
</p>
To use the media extractor service in your installation, add the following to your `configuration.yaml` file:
@ -22,6 +25,32 @@ To use the media extractor service in your installation, add the following to yo
media_extractor:
```
Configuration variables:
- **default_query** (*Optional*): Set default stream query for all devices ('best' by default).
- **customize** (*Optional*): Set entity specific values. For example:
```yaml
# Example configuration.yaml entry
media_extractor:
default_query: worst
customize:
media_player.my_sonos:
video: bestvideo
music: bestaudio[ext=mp3]
```
This configuration sets query for all service calls like: ```{"entity_id": "media_player.my_sonos", "media_content_id": "https://soundcloud.com/bruttoband/brutto-11", "media_content_type": "music"}``` to 'bestaudio' with mp3 extention.
Query examples with explanations:
* **bestvideo** - best video only stream
* **best** - best video + audio stream
* **bestaudio[ext=m4a]** - best audio stream with m4a extension
* **worst** - worst video + audio stream
* **bestaudio[ext=m4a]/bestaudio[ext=ogg]/bestaudio** - best m4a audio, otherwise best ogg audio and only then any best audio
More info about queries [here](https://github.com/rg3/youtube-dl#format-selection)
### {% linkable_title Use the service %}
Go to the "Developer Tools," then to "Call Service," and choose `media_extractor/play_media` from the list of available services. Fill the "Service Data" field as shown in the example below and hit "CALL SERVICE."

115
source/_components/media_player.apple_tv.markdown
View File

@ -11,119 +11,6 @@ logo: apple.png
ha_category: Media Player
ha_iot_class: "Local Push"
ha_release: 0.38
featured: true
---
The `apple_tv` platform allows you to control an Apple TV (3rd and 4th generation).
<p class='note'>
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.
</p>
If you want to automatically discover new devices, just make sure you have `discovery:` in your `configuration.yaml` file. To manually add an Apple TV to your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
media_player:
- platform: apple_tv
host: IP_ADDRESS
login_id: LOGIN_ID
start_off: false
credentials: CREDENTIALS
```
Configuration variables:
- **host** (*Required*): The IP-address of the device
- **login_id** (*Required*): An identifier used to login to the device, see below
- **name** (*Optional*): The name of the device used in the frontend
- **start_off** (*Optional*): Set to true if device should start in fake standby
- **credentials** (*Optional*): Credentials used for AirPlay playback
In order to connect to the device you need a *login id*. The easiest way to obtain this identifier is to use the application ``atvremote``. It should be available in the same environment as you installed Home-Assistant. To install this utility, run ``pip3 install --upgrade pyatv``. The run atvremote scan for all devices (try again if a device is missing):
```bash
$ atvremote scan
Found Apple TVs:
- Apple TV at 10.0.10.22 (login id: 00000000-1234-5678-9012-345678901234)
Note: You must use 'pair' with devices that have home sharing disabled
```
Just copy and paste the login id from the device you want to add. For more details about `atvremote`, see: [this page](http://pyatv.readthedocs.io/en/master/atvremote.html).
## {% linkable_title Guides %}
### {% linkable_title My Apple TV turns on when I restart Home Assistant %}
The Apple TV will automatically turn on if a request is sent to it, e.g. if a button is pressed, something is streamed to it via AirPlay or if current state (currently playing) is accessed. This is how Apple has designed it and it will cause problems if you are using HDMI CEC. Every time Home Assistant is started, a new request is sent to the device to figure out what is currently playing. When using CEC, this will wake up your TV and other devices you have configured.
So, if your TV is randomly turning on, this is probably the reason. As stated, this is by design and there is no real fix for it. There's also no known way to turn off the Apple TV via the procotol used for communication. You basically have the following options:
- Do not use this platform
- Disable HDMI CEC on your Apple TV
- Use "fake standby"
The first two points are quite obvious. Fake standby is a concept implemented in this platform that disables all requests to the device and make it appear as being "off" in the web interface. This will make sure that the device is not woken up, but it will of course not show any information or allow you to control it. It is however easy to turn it on (or off) in the web interface or using an automation with `turn_on`. To make it more useful, you can write automations that turns it on or off depending on some other device, like the input source on your receiver.
To put a device into fake standby when starting Home Assistant, add `start_off: true` to your configuration.
<p class='note warning'>
Turning the device on/off in the user interface will *not* turn the physical device on/off according to description above.
</p>
### {% linkable_title Setting up device authentication %}
If you, when playing media with `play_url`, get the following error message:
*“This AirPlay connection requires iOS 7.1 or later, OS X 10.10 or later, or iTunes 11.2 or later.”*
then device authentication is required. Press the icon in the upper left corner and select the leftmost icon according to the image below:
<img src='/images/screenshots/developer-tools.png' />
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:
<img src='/images/components/apple_tv/authenticate.png' />
If no dialog appears, go back to the states view and show it from there. A PIN code should now be visible on your TV, just enter it into the dialog and press "Confirm". You should see if it succeeded in the state view:
<img src='/images/components/apple_tv/credentials.png' />
Copy the credentials and insert it into your configuration (make sure you copy everything, it should be 81 characters):
```yaml
# Example configuration.yaml entry
media_player:
- platform: apple_tv
host: 10.0.0.20
login_id: 00000000-1234-5678-9012-345678901234
credentials: 1B8C387DDB59BDF6:CF5ABB6A2C070688F5926ADB7C010F6DF847252C15F9BDB6DA3E09D6591E90E5
```
Restart Home Assistant and now you should be able to use `play_url` as before.
## {% linkable_title Services %}
### {% linkable_title Service `apple_tv_authenticate` %}
In order to play media on an Apple TV with device authentication enabled (e.g. ATV4 with tvOS 10.2+), Home Assistant must properly authenticated. This method starts the process and presents the credentials needed for playback as a persistent notification. Please see guide above for usage.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of Apple TVs.
### {% linkable_title Service `apple_tv_press_buttons` %}
Send one or more button presses to the device.
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | yes | String or list of strings that point at `entity_id`s of Apple TVs.
| `buttons` | no | List of buttons. Supported buttons are: `up`, `down`, `left`, `right`, `menu`, `top_menu` and `select`.
## {% linkable_title Notes and Limitations %}
- Pairing is currently not supported
- Updates is sometimes not propagated correctly on ATV4
To setup the `apple_tv` platform, please follow the instructions on the [Apple TV Component page](/components/apple_tv/).

167
source/_components/media_player.kodi.markdown
View File

@ -35,7 +35,8 @@ Configuration variables:
- **proxy_ssl** (*Optional*): Connect to kodi with HTTPS and WSS. Defaults to `false`. Useful if Kodi is behind an SSL proxy.
- **username** (*Optional*): The XBMC/Kodi HTTP username.
- **password** (*Optional*): The XBMC/Kodi HTTP password.
- **turn_off_action** (*Optional*): The desired turn off action. Options are `none`, `quit`, `hibernate`, `suspend`, `reboot`, or `shutdown`. Default `none`.
- **turn_on_action** (*Optional*): Home Assistant script sequence to call when turning on.
- **turn_off_action** (*Optional*): Home Assistant script sequence to call when turning off.
- **enable_websocket** (*Optional*): Enable websocket connections to Kodi via the TCP port. Defaults to `true`. The websocket connection allows Kodi to push updates to Home Assistant and removes the need for Home Assistant to poll. If websockets don't work on your installation this can be set to `false`.
- **timeout** (*Optional*): Set timeout for connections to Kodi. Defaults to 5 seconds.
@ -75,23 +76,171 @@ input: <input parameters of the service call>
result: <data received from the Kodi API>
```
### {% linkable_title Kodi turn on/off samples %}
With the `turn_on_action` and `turn_off_action` parameters you can run any combination of Home Assistant actions to turn on/off your Kodi instance. Here are a few examples of this usage, including the **migration instructions for the old `turn_off_action` list of options**.
#### Turn on Kodi with Wake on LAN
With this configuration, when calling `media_player/turn_on` on the Kodi device, a _magic packet_ will be sent to the specified MAC address. To use this service, first you need to config the [`wake_on_lan`](/components/wake_on_lan) component in Home Assistant, which is achieved simply by adding `wake_on_lan:` to your `configuration.yaml`.
```yaml
media_player:
- platform: kodi
host: 192.168.0.123
turn_on_action:
- service: wake_on_lan.send_magic_packet
data:
mac: aa:bb:cc:dd:ee:ff
broadcast_address: 192.168.255.255
```
#### Turn off Kodi with API calls
Here are the equivalent ways to configure each of the old options to turn off Kodi (`quit`, `hibernate`, `suspend`, `reboot`, or `shutdown`):
- **Quit** method (before was `turn_off_action: quit`)
```yaml
media_player:
- platform: kodi
host: 192.168.0.123
turn_off_action:
service: media_player.kodi_call_method
data:
entity_id: media_player.kodi
method: Application.Quit
```
- **Hibernate** method (before was `turn_off_action: hibernate`)
```yaml
media_player:
- platform: kodi
host: 192.168.0.123
turn_off_action:
service: media_player.kodi_call_method
data:
entity_id: media_player.kodi
method: System.Hibernate
```
- **Suspend** method (before was `turn_off_action: suspend`)
```yaml
media_player:
- platform: kodi
host: 192.168.0.123
turn_off_action:
service: media_player.kodi_call_method
data:
entity_id: media_player.kodi
method: System.Suspend
```
- **Reboot** method (before was `turn_off_action: reboot`)
```yaml
media_player:
- platform: kodi
host: 192.168.0.123
turn_off_action:
service: media_player.kodi_call_method
data:
entity_id: media_player.kodi
method: System.Reboot
```
- **Shutdown** method (before was `turn_off_action: shutdown`)
```yaml
media_player:
- platform: kodi
host: 192.168.0.123
turn_off_action:
service: media_player.kodi_call_method
data:
entity_id: media_player.kodi
method: System.Shutdown
```
#### Turn on and off the TV with the Kodi JSON-CEC Addon
For Kodi devices running 24/7 attached to a CEC capable TV (OSMC / OpenElec and systems alike running in Rasperry Pi's, for example), this configuration enables the optimal way to turn on/off the attached TV from Home Assistant while Kodi is always active and ready:
```yaml
media_player:
- platform: kodi
host: 192.168.0.123
turn_on_action:
service: media_player.kodi_call_method
data:
entity_id: media_player.kodi
method: Addons.ExecuteAddon
addonid: script.json-cec
params:
command: activate
turn_off_action:
- service: media_player.media_stop
data:
entity_id: media_player.kodi
- service: media_player.kodi_call_method
data:
entity_id: media_player.kodi
method: Addons.ExecuteAddon
addonid: script.json-cec
params:
command: standby
```
### {% linkable_title Kodi services samples %}
#### Simple script to turn on the TV with the Kodi JSON-CEC Addon
#### Simple script to turn on the PVR in some channel as a time function
```yaml
script:
activate_tv:
alias: Turn on TV
play_kodi_pvr:
alias: Turn on the silly box
sequence:
- alias: TV on
service: media_player.turn_on
data:
entity_id: media_player.kodi
- alias: Play TV channel
service: media_player.play_media
data_template:
entity_id: media_player.kodi
media_content_type: "CHANNEL"
media_content_id: >
{% raw %}{% if (now().hour < 14) or ((now().hour == 14) and (now().minute < 50)) %}
10
{% elif (now().hour < 16) %}
15
{% elif (now().hour < 20) %}
2
{% elif (now().hour == 20) and (now().minute < 50) %}
10
{% elif (now().hour == 20) or ((now().hour == 21) and (now().minute < 15)) %}
15
{% else %}
10
{% endif %}{% endraw %}
```
#### Trigger a Kodi video library update
```yaml
script:
update_library:
alias: Update Kodi Library
sequence:
- alias: Call Kodi update
service: media_player.kodi_call_method
data:
entity_id: media_player.kodi
method: Addons.ExecuteAddon
addonid: script.json-cec
params:
command: activate
entity_id: media_player.kodi
method: VideoLibrary.Scan
```
For a more complex usage of the `kodi_call_method` service, with event triggering of Kodi API results, you can have a look at this [example](/cookbook/kodi_dynamic_input_select/)

4
source/_components/media_player.sonos.markdown
View File

@ -61,7 +61,7 @@ Take a snapshot of what is currently playing on one or more speakers. This servi
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of coordinator speakers.
| `entity_id` | yes | String or list of strings that point at `entity_id`s of coordinator speakers.
| `with_group` | yes | Should be also snapshot the group state of the speaker.
### {% linkable_title Service `sonos_restore` %}
@ -70,7 +70,7 @@ Restore a previously taken snapshot of one or more speakers. If no `entity_id` i
| Service data attribute | Optional | Description |
| ---------------------- | -------- | ----------- |
| `entity_id` | no | String or list of strings that point at `entity_id`s of coordinator speakers.
| `entity_id` | yes | String or list of strings that point at `entity_id`s of coordinator speakers.
| `with_group` | yes | Should be also restore the group state of the speaker. Only if was snapshot with group.
### {% linkable_title Service `sonos_join` %}

44
source/_components/remote.apple_tv.markdown Normal file
View File

@ -0,0 +1,44 @@
---
layout: page
title: "Apple TV"
description: "Instructions how to integrate Apple TV remote into Home Assistant."
date: 2017-06-26 20:50
sidebar: true
comments: false
sharing: true
footer: true
logo: apple.png
ha_category: Remote
ha_iot_class: "Local Push"
ha_release: 0.49
---
The `apple_tv` remote platform allows you to send remote control buttons to an Apple TV. It is automatically setup when an Apple TV is configured, please see [Apple TV Component](/components/apple_tv/) for configuration details.
At the moment, the following buttons are supported:
- up
- down
- left
- right
- menu
- top_menu
- select
A typical service call for press several buttons looks like this.
```yaml
service: remote.send_command
data:
entity_id: remote.apple_tv
command:
- left
- left
- menu
- select
device: ''
```
Please note that `device` must be specified (because of validation) but is not used by this platform. So you may specify any value.

3
source/_components/rpi_pfio.markdown
View File

@ -13,5 +13,6 @@ ha_release: 0.45
ha_iot_class: "Local Push"
---
The `rpi_pfio` component is the base for all related [PiFace Digital I/O (PFIO)](http://www.piface.org.uk/) platforms in Home Assistant. There is no setup needed for the component itself, for the platforms please check their corresponding pages.
The `rpi_pfio` component is the base for all related [PiFace Digital I/O (PFIO)](http://www.piface.org.uk/) platforms in Home Assistant. There is no setup needed for the component itself; for the platforms, please check their corresponding pages.
Set the jumpers on the PiFace board for address 0 (JP1: 1-2, JP2: 1-2).

1
source/_components/sensor.fitbit.markdown
View File

@ -63,6 +63,7 @@ activities/tracker/steps
body/bmi
body/fat
body/weight
devices/battery
sleep/awakeningsCount
sleep/efficiency
sleep/minutesAfterWakeup

40
source/_components/sensor.google_wifi.markdown Normal file
View File

@ -0,0 +1,40 @@
---
layout: page
title: "Google Wifi"
description: "Instructions how to integrate Google Wifi/OnHub routers into Home Assistant."
date: 2017-07-15 21:22
sidebar: true
comments: false
sharing: true
footer: true
ha_category: System Monitor
logo: google_wifi.png
ha_iot_class: "Local Polling"
ha_release: "0.50"
---
The `google_wifi` sensor platform is displaying the exposed status of a [Google Wifi](https://madeby.google.com/wifi/) (or OnHub) router.
The sensor is able to report network status, up-time, current IP address, and firmware versions.
To enable this sensor, add the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
sensor:
- platform: google_wifi
```
Configuration variables:
- **host** (*Optional*): The address to retreive status from the router. Defaults to `testwifi.here` (other options include `onhub.here` and your router's IP such as `192.168.86.1`).
- **name** (*Optional*): Name to give the Google Wifi sensor. Defaults to `google_wifi`.
- **monitored_conditions** (*Optional*): Defines the data to monitor as sensors. Defaults to all of the listed options below.
- **current_version**: Current firmware version of the router.
- **new_version**: Latest availiable firmware version. If router is up-to-date, this value defaults to `Latest`.
- **uptime**: Days since router has been turned on.
- **last_restart**: Date of last restart. Format is `YYYY-MM-DD HH:mm:SS`.
- **local_ip**: Local public IP address.
- **status**: Reports whether the router is or is not connected to the internet.

1
source/_components/sensor.metoffice.markdown
View File

@ -33,6 +33,7 @@ sensor:
- wind_direction
- wind_gust
- visibility
- visibility_distance
- uv
- precipitation
- humidity

12
source/_components/sensor.pi_hole.markdown
View File

@ -31,7 +31,11 @@ Configuration variables:
- **ssl** (*Optional*): If `true`, use SSL/TLS to connect to the Pi-Hole system. Defaults to `False`.
- **verify_ssl** (*Optional*): Verify the certification of the system. Default to `True`.
- **monitored_conditions** (*Optional*): Defines the stats to monitor as sensors.
- **dns_queries_today**: Total number of DNS queries handled by Pi-Hole today
- **ads_blocked_today**: Total number of blocked ads today
- **ads_percentage_today**: Percentage of blocked ads
- **ads_blocked_today**: Total number of blocked ads today.
- **ads_percentage_today**: Percentage of blocked ads.
- **dns_queries_today**: Total number of DNS queries handled by Pi-Hole today.
- **domains_being_blocked**: Total number of domains blocked by Pi-Hole.
- **queries_cached**: Total number of cache queries on the last 24 hours.
- **queries_forwarded**: Total number of forwarded queries on the last 24 hours.
- **unique_clients**: Total number of unique clients on the last 24 hours.
- **unique_domains**: Total number of unique domains on the last 24 hours.

4
source/_components/sensor.pushbullet.markdown
View File

@ -14,9 +14,9 @@ ha_iot_class: "Cloud Polling"
---
The `pushbullet` sensor platform reads messages from [Pushbullet](https://www.pushbullet.com/), a free service to send information between your phones, browsers, and friends.
This sensor platform provide sensors that show the properties of the latest recevied pushbullet notification mirror.
This sensor platform provides sensors that show the properties of the latest received Pushbullet notification mirror.
Notification Mirroring allows users to see their Android device's notifications on their computer. It must be first enabled in the app and is currently only available on the Android platform. For more information, please see [this announcement](https://blog.pushbullet.com/2013/11/12/real-time-notification-mirroring-from-android-to-your-computer/) on the Pushbullet Blog
Notification Mirroring allows users to see their Android device's notifications on their computer. It must be first enabled in the app and is currently only available on the Android platform. For more information, please see [this announcement](https://blog.pushbullet.com/2013/11/12/real-time-notification-mirroring-from-android-to-your-computer/) on the Pushbullet Blog.
To enable the Pushbullet sensor in your installation, add the following to your `configuration.yaml` file:

122
source/_components/sensor.uk_transport.markdown Normal file
View File

@ -0,0 +1,122 @@
---
layout: page
title: "UK transport"
description: "Display the current status of UK train and bus departures."
date: 2017-07-07 18:00
sidebar: true
comments: false
sharing: true
footer: true
logo: train.png
ha_category: Transport
ha_iot_class: "Cloud Polling"
ha_release: "0.50"
---
The `uk_transport` sensor will display the time in minutes until the next departure in a specified direction from of a configured train station or bus stop. The sensor uses [transportAPI](http://www.transportapi.com/) to query live departure data and requires a developer application ID and key which can be obtained [here](https://developer.transportapi.com/). The [free tier](http://www.transportapi.com/plans/) allows 1000 requests daily, which is sufficient for a single sensor refreshing every 87 seconds.
<p class='note warning'>
Additional sensors can be added but at the expense of a reduced refresh rate. 2 sensors can be updated every 2*87 = 174 seconds, and so on.
</p>
Queries are entered as a list, with the two transport modes available being `bus` and `train`.
Train departure sensors require three character long `origin` and `destination` station codes which are searchable on the [National Rail enquiries](http://www.nationalrail.co.uk/times_fares/ldb.aspx) website (e.g. `WAT` is London Waterloo). The validity of a route can be checked by performing a GET request to `/uk/train/station/{station_code}/live.json` in the [API reference webpage](https://developer.transportapi.com/docs?raml=https://transportapi.com/v3/raml/transportapi.raml##request_uk_train_station_station_code_live_json).
To add a single train departure sensor add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry for a single sensor
sensor:
- platform: uk_transport
app_id: abc123
app_key: efg456
queries:
- mode: train
origin: MAL
destination: WAT
```
Configuration variables:
- **app_id** (*Required*): Your application id
- **app_key** (*Required*): Your application key
- **queries** array (*Required*): At least one entry required.
- **mode** (*Required*): One of `bus` or `train`.
- **origin** (*Required*): Specify the three character long origin station code.
- **destination** (*Required*): Specify the three character long destination station code.
A large amount of information about upcoming departures is available within the attributes of the sensor. The example above creates a sensor with ID `sensor.next_train_to_wat` with the attribute `next_trains` which is a list of the next 25 departing trains. The status of the next departing train is accessed using the [template sensor](https://home-assistant.io/components/sensor.template/) below, as are the train origin, estimated and scheduled departure times, and the departure platform.
```yaml
# Example configuration.yaml entry for a template sensor to access the attributes of the next departing train.
- platform: template
sensors:
next_train_status:
friendly_name: 'Next train status'
value_template: '{{states.sensor.next_train_to_wat.attributes.next_trains[0].status}}'
next_trains_origin:
friendly_name: 'Next train origin'
value_template: '{{states.sensor.next_train_to_wat.attributes.next_trains[0].origin_name}}'
next_trains_estimated:
friendly_name: 'Next train estimated'
value_template: '{{states.sensor.next_train_to_wat.attributes.next_trains[0].estimated}}'
next_trains_scheduled:
friendly_name: 'Next train scheduled'
value_template: '{{states.sensor.next_train_to_wat.attributes.next_trains[0].scheduled}}'
next_trains_platform:
friendly_name: 'Next train platform'
value_template: '{{states.sensor.next_train_to_wat.attributes.next_trains[0].platform}}'
```
Bus sensors require as their `origin` a bus stop ATCO code which can be found by browsing OpenStreetMap data as
follows:
1. On [OpenStreetMap.org](http://www.openstreetmap.org/) zoom right in on a bus
stop you're interested in
2. Click the layers picker button on the right hand side
3. Tick the 'map data' layer, and wait for clickable objects to load
4. Click the bus stop node to reveal its tags on the left
The `destination` must be a valid location returned by the transportAPI query. Valid destinations can be checked by performing a GET query to `/uk/bus/stop/{atcocode}/live.json` in the [API reference webpage](https://developer.transportapi.com/docs?raml=https://transportapi.com/v3/raml/transportapi.raml##bus_information). A bus sensor is added in the following `configuration.yaml` file entry:
```yaml
# Example configuration.yaml entry for multiple sensors
sensor:
- platform: uk_transport
app_id: abc123
app_key: efg456
queries:
- mode: bus
origin: 340000368SHE
destination: Wantage
- mode: train
origin: MAL
destination: WAT
```
And the template sensor for viewing the next bus attributes.
```yaml
# Example configuration.yaml entry for a template sensor to access the attributes of the next departing bus.
- platform: template
sensors:
next_bus_route:
friendly_name: 'Next bus route'
value_template: '{{states.sensor.next_bus_to_wantage.attributes.next_buses[0].route}}'
next_bus_direction:
friendly_name: 'Next bus direction'
value_template: '{{states.sensor.next_bus_to_wantage.attributes.next_buses[0].direction}}'
next_bus_scheduled:
friendly_name: 'Next bus scheduled'
value_template: '{{states.sensor.next_bus_to_wantage.attributes.next_buses[0].scheduled}}'
next_bus_estimated:
friendly_name: 'Next bus estimated'
value_template: '{{states.sensor.next_bus_to_wantage.attributes.next_buses[0].estimated}}'
```
Powered by [transportAPI](http://www.transportapi.com/)

2
source/_components/sensor.wunderground.markdown
View File

@ -137,7 +137,7 @@ sensor:
- weather_4n_metric
group:
dialy_forecast:
daily_forecast:
name: Daily Forecast
entities:
- sensor.pws_weather_1d_metric

20
source/_components/sensor.xiaomi.markdown Normal file
View File

@ -0,0 +1,20 @@
---
layout: page
title: "Xiaomi Sensor"
description: "Instructions how to setup the Xiaomi sensor within Home Assistant."
date: 2017-07-21 16:34
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Sensor
ha_release: "0.50"
ha_iot_class: "Local Polling"
---
The `xiaomi` sensor platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) sensors.
The requirement is that you have setup [Xiaomi](/components/xiaomi/).

23
source/_components/shopping_list.markdown Normal file
View File

@ -0,0 +1,23 @@
---
layout: page
title: "Shopping List"
description: "Instructions on how to integrate a Shopping list into Home Assistant using Intent."
date: 2017-07-29 13:00
sidebar: true
comments: false
sharing: true
footer: true
logo: home-assistant.png
ha_category: Intent
ha_release: "0.50"
---
The `shopping_list` component is a feature for the [`intent_script` component](/components/intent_script/).
```yaml
# Example configuration.yaml entry
shopping_list:
```
Eg. check the [`conversion`](/components/conversation/) about how to add and delete items from the list.

2
source/_components/snips.markdown
View File

@ -100,7 +100,7 @@ mqtt:
```
### Triggering actions
In Home Assistant, we trigger actions based on intents produced by Snips. This is done in `configuration.yaml`. For instance, the following block handles `ActivateLightColors` intents (included in the Snips IoT intent bundle) to change light colors:
In Home Assistant, we trigger actions based on intents produced by Snips using the [`intent_script`](/components/intent_script) component. For instance, the following block handles `ActivateLightColors` intents (included in the Snips IoT intent bundle) to change light colors:
```yaml
snips:

14
source/_components/statsd.markdown
View File

@ -28,6 +28,18 @@ Configuration variables:
- **prefix** (*Optional*): Prefix to use. Defaults to `hass`.
- **rate** (*Optional*): The sample rate. Defaults to 1.
- **log_attributes** (*Optional*): Log state and attribute changes. This changes the default stats path.
- **value_mapping** (*Optional*): Map non-numerical values to numerical ones.
Full example:
```yaml
# Example configuration.yaml entry
statsd:
prefix: home
rate: 5
value_mapping:
cooling: 1
heating: 10
```
StatsD supports various [backends](https://github.com/etsy/statsd/blob/master/docs/backend.md).

44
source/_components/switch.velbus.markdown Normal file
View File

@ -0,0 +1,44 @@
---
layout: page
title: "Velbus Switches"
description: "Access and control your Velbus Switches."
date: 2017-06-17 16.58
sidebar: true
comments: false
sharing: true
footer: true
logo: velbus.png
ha_category: Switch
ha_iot_class: "Local Push"
ha_release: 0.49
---
The `velbus` switch allows you to control [Velbus](http://www.velbus.eu) connected switches.
To use your Velbus switches in your installation, add the following to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
light:
- platform: velbus
devices:
- name: Switch 1
type: single
module: 0xda
channel: 4
- name: Switch 2
type: double
module: 0xbc
open_channel: 1
close_channel: 2
```
Configuration variables:
- **devices** array (*Required*): The array contains the switches to configure
- **name** (*Required*): Name of the switch.
- **module** (*Required*): The hexadecimal module address
- **type** (*Required*): Either `single` or `double`. If single, only `channel` attribute is required. If double, both `open_channel` and `close_channel` attributes are required
- **channel** (*Required*): The channel number in the module.
For hub configuration, see [the Velbus component](/components/velbus/).

20
source/_components/switch.xiaomi.markdown Normal file
View File

@ -0,0 +1,20 @@
---
layout: page
title: "Xiaomi Switch"
description: "Instructions how to setup the Xiaomi switch within Home Assistant."
date: 2017-07-21 16:34
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Switch
ha_release: "0.50"
ha_iot_class: "Local Polling"
---
The `xiaomi` switch platform allows you to get data from your [Xiaomi](http://www.mi.com/en/) switches.
The requirement is that you have setup [Xiaomi](/components/xiaomi/).

25
source/_components/velbus.markdown Normal file
View File

@ -0,0 +1,25 @@
---
layout: page
title: "Velbus"
description: "Access and control your Velbus devices."
date: 2017-06-17 16.58
sidebar: true
comments: false
sharing: true
footer: true
logo: velbus.png
ha_category: Hub
ha_iot_class: "Local Push"
ha_release: 0.49
---
The `velbus` component supports the Velbus USB and Serial gateways.
The gateway needs to be configured by adding the following lines to your `configuration.yaml` file:
```yaml
# Example configuration.yaml entry
velbus:
port: '/dev/ttyUSB00'
```

3
source/_components/weather.yweather.markdown
View File

@ -13,7 +13,7 @@ ha_release: 0.47
---
The `yweather` platform uses [Yahoo Weather](https://www.yahoo.com/news/weather/) as an source for current meteorological data. The `forecast` will show you the condition for 5 days, 0 is the current day.
The `yweather` platform uses [Yahoo Weather](https://www.yahoo.com/news/weather/) as an source for current meteorological data. This component will show you the condition and tempratures for max. 10 days.
<p class='note warning'>
Use of the Yahoo Weather API should not exceed reasonable request volume. Access is limited to 2000 signed calls per day.
@ -32,7 +32,6 @@ weather:
Configuration variables:
- **woeid** (*Optional*): See above.
- **forecast** (*Optional*): Day of forecast. The default is the current day to display conditions.
- **name** (*Optional*): The name of the sensor. To easily recognize each sensor when adding more than one Yahoo weather sensor, it is recommended to use the name option. Defaults to `Yweather`.

26
source/_components/wink.markdown
View File

@ -26,24 +26,26 @@ Check the related componets pages for actual devices that are support.
Home Assistant offers multiple ways to authenticate to the Wink API. Each authentication method is described below.
### Authentication with an access token.
### Authenticate using [developer.wink.com](https://developer.wink.com)
To use this form of authentication obtain a token from the form below and insert it into your `configuration.yaml`
This method will require you to setup a developer account with Wink. This process can take a few days to get approved, but is the recommanded form of authentication. If you would like to use Wink in Home Assistant while you wait, you can use the email and password authentication below.
<iframe src="https://winkbearertoken.appspot.com"
style='width: 100%; height: 200px; border: 0; margin: 0 auto 15px; border-left: 2px solid #049cdb; padding-left: 15px;'></iframe>
This form of authentication doesn't require any settings in the configuration.yaml other than `wink:` this is because you will be guided through setup via the configurator on the frontend.
<p class='note'>
When using the configurator make sure the initial setup is performed on the same local network as the Home Assistant server, if not from the same box Home Assistant is running on. This will allow for authentication redirects to happen correctly.
</p>
```yaml
wink:
access_token: YOUR_ACCESS_TOKEN
```
### Authentication with your Wink email and password.
This method uses the same form from above to obtain an access token, but does so without the user needing to manually do so.
This method pulls a new token on every startup of Home Assistant.
This method pulls a new token on every startup of Home Assistant from this [URL](https://winkbearertoken.appspot.com)
```yaml
wink:
@ -51,12 +53,10 @@ wink:
password: YOUR_WINK_PASSWORD
```
### Full oath authentication. (This is the best option!)
### Full oauth authentication (legacy).
This should be used for users that obtained their client_id and client_secret via email from Wink support.
You can also request API access via Wink's [contact us](http://www.wink.com/help/contact/) page.
You will be provided with a client ID and a client secret via email. These can then be used in your configuration in place of the access_token this will prevent you from having to manually refresh your access token.
```yaml
wink:
@ -68,14 +68,12 @@ wink:
Configuration variables:
- **access_token** (*Required if the below aren't present.*): The retrieved access token.
- **email** (*Required if access token isn't provided*): Your Wink login email.
- **password** (*Required if access token isn't provided*): Your Wink login password.
- **client_id** (*Required if access token isn't provided*): Your provided Wink client_id.
- **client_secret** (*Required if access token isn't provided*): Your provided Wink client_secret.
- **user_agent** (*Optional*): The user-agent passed in the API calls to Wink.
This will connect to the Wink API and automatically set up any switches, lights, locks, fans, climate devices, covers, and sensors.
This will connect to the Wink API and automatically set up any switches, lights, locks, fans, climate devices, covers, sensors, and alarms.
### {% linkable_title Service `refresh_state_from_wink` %}

120
source/_components/xiaomi.markdown Normal file
View File

@ -0,0 +1,120 @@
---
layout: page
title: "Xiaomi Gateway"
description: "Instructions how to integrate your Xiaomi Gateway within Home Assistant."
date: 2017-07-21 16:34
sidebar: true
comments: false
sharing: true
footer: true
logo: xiaomi.png
ha_category: Hub
ha_release: "0.50"
ha_iot_class: "Local Polling"
---
The `xiaomi_gw` platform allows you to integrate the following [Xiaomi](http://www.mi.com/en/) devices into Home Assistant.
- Temperature and Humidity Sensor (old and new version)
- Motion Sensor (old and new version)
- Door and Window Sensor (old and new version)
- Button (old and new version)
- Plug aka Socket (ZigBee version, reports power consumed, power load, state and if device in use)
- Wall Plug (reports power consumed, power load and state)
- Aqara Wall Switch (Single)
- Aqara Wall Switch (Double)
- Aqara Wall Switch LN (Single)
- Aqara Wall Switch LN (Double)
- Aqara Wireless Switch (Single)
- Aqara Wireless Switch (Double)
- Cube
- Gas Leak Detector (reports alarm and density)
- Smoke Detector (reports alarm and density)
- Gateway (Light, Illumination Sensor, Ringtone play)
- Intelligent Curtain
- Battery
What's not available?
- Gateway Radio
- Gateway Button
- Water Sensor
- Aqara Air Conditioning Companion
- Aqara Intelligent Air Conditioner Controller Hub
- Decoupled mode of the Aqara Wall Switches (Single & Double)
- Additional alarm events of the Gas and Smoke Detector: Analog alarm, battery fault alarm (smoke detector only), sensitivity fault alarm, I2C communication failure
Follow the setup process using your phone and Mi Home app. From here you will be able to retrieve the key from within the app following [this tutorial](https://community.home-assistant.io/t/beta-xiaomi-gateway-integration/8213/1832)
To enable Xioami gateway in your installation, add the following to your `configuration.yaml` file:
One Gateway
```yaml
# You can leave mac empty if you only have one gateway.
xiaomi:
gateways:
- mac:
key: xxxxxxxxxxxxxxxx
```
Multiple Gateway
```yaml
# 12 characters mac can be obtained from the gateway.
xiaomi:
gateways:
- mac: xxxxxxxxxxxx
key: xxxxxxxxxxxxxxxx
- mac: xxxxxxxxxxxx
key: xxxxxxxxxxxxxxxx
```
Configuration variables:
- **mac** (*Optional*): The MAC of your gateway. Required if you have more than one.
- **key** (*Optional*): The key of your gateway. Required if you also want to control lights and switches; sensors and binary sensors will still work.
- **discovery_retry** (*Optional*): Amount of times Home Assitant should try to reconnect to the Xiaomi Gateway. Default is 3.
- **interface** (*Optional*): Which network interface to use. Default to any.
## {% linkable_title Services %}
The gateway provides two services: `xiaomi.play_ringtone` and `xiaomi.stop_ringtone`. To play ringtones by Home Assistant the version of the gateway firmware must be `1.4.1_145` at least. A `ringtone_id` and `gw_mac` must be supplied. The parameter `ringtone_vol` (percent) is optional. Allowed values of the `ringtone_id` are:
- alarm ringtones [0-8]
- doorbell ring [10-13]
- alarm clock [20-29]
- custom ringtones (uploaded by mi home app) starting from 10001
Automation example
```yaml
- alias: Let a dog bark on long press
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.switch_158d000xxxxxc2
click_type: long_click_press
action:
service: xiaomi.play_ringtone
data:
gw_mac: xxxxxxxxxxxx
ringtone_id: 8
ringtone_vol: 8
- alias: Stop barking immediately on single click
trigger:
platform: event
event_type: click
event_data:
entity_id: binary_sensor.switch_158d000xxxxxc2
click_type: single
action:
service: xiaomi.stop_ringtone
data:
gw_mac: xxxxxxxxxxxx
```

2
source/_cookbook/configuration_yaml_by_ciquattrofpv.markdown
View File

@ -1,6 +1,6 @@
---
layout: page
title: "Configuration.yaml by Nicolo Steffe"
title: "Configuration.yaml by Ciquattro"
description: ""
date: 2017-06-13 12:00
sidebar: true

3
source/_docs/automation/trigger.markdown
View File

@ -94,9 +94,6 @@ automation:
<p class='note warning'>
Use quotes around your values for `from` and `to` to avoid the YAML parser interpreting values as booleans.
</p>
<p class='note warning'>
Using `state` as an alias for `to` is deprecated.
</p>
### {% linkable_title Sun trigger %}
Trigger when the sun is setting or rising. An optional time offset can be given to have it trigger for example 45 minutes before sunset, when dusk is setting in.

23
source/_docs/configuration/secrets.markdown
View File

@ -91,3 +91,26 @@ Please enter password for encrypted keyring:
<p class='note warning'>
If you are using the Python Keyring, [autostarting](/getting-started/autostart/) of Home Assistant will no longer work.
</p>
### {% linkable_title Storing passwords in a keyring managed by your OS %}
Using [Credstash](https://github.com/fugue/credstash) is an alternative way to `secrets.yaml`. They can be managed from the command line via the credstash script.
Before using credstash, you need to set up AWS credentials either via the `aws` command line tool, or using environment variables as explained in the [AWS CLI docs](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html) as well as creating a KMS key named 'credstash' as explained in the [credstash readme](https://github.com/fugue/credstash#setting-up-kms). After that is complete, you can use the provided script to add secrets to your Home Assistant secret store in credstash
```bash
$ hass --script credstash --help
```
To store a password in credstash, replace your password or API key with `!secret` and an identifier in `configuration.yaml` file.
```yaml
http:
api_password: !secret http_password
```
Create an entry in your credstash store.
```bash
$ hass --script credstash set http_password
```

17
source/_docs/configuration/yaml.markdown
View File

@ -61,3 +61,20 @@ sensor:
state_topic: sensor2/topic
```
### {% linkable_title Using Environment Variables %}
You can include values from your system's environment variables with `!env_var`.
```yaml
http:
api_password: !env_var PASSWORD
```
#### Default Value
If an environment variable is not set, you can fallback to a default value.
```yaml
http:
api_password: !env_var PASSWORD default_password
```

4
source/_docs/z-wave.markdown
View File

@ -88,6 +88,10 @@ Depending on what's plugged into your USB ports, the name found above may change
To add a Z-Wave device to your system, go to the Services menu and select the `zwave` domain, and select the `add-node` service. Then find your device's add button and press that as well.
<p class='note'>
Some Z-Wave controllers like Aeotec ZW090 Z-Stick Gen5 have ability to add devices to the network using their own contol buttons. This method should be avoided as it is prone to errors. Devices added to the Z-Wave network using this method may not function well.
</p>
### {% linkable_title Adding Security Devices %}
Security Z-Wave devices require a network key before being added to the network using the `zwave.add_node_secure` service. You must set the *network_key* configuration variable to use a network key before adding these devices.

8
source/_includes/asides/developers_navigation.html
View File

@ -54,6 +54,14 @@
<li>{% active_link /developers/component_discovery/ Component Discovery %}</li>
</ul>
</li>
<li>
{% active_link /developers/intent/ Intents (handling voice responses) %}
<ul>
<li>{% active_link /developers/intent/firing/ Firing intents %}</li>
<li>{% active_link /developers/intent/handling/ Handling intents %}</li>
<li>{% active_link /developers/intent/conversation/ Registering sentences %}</li>
</ul>
</li>
<li>
{% active_link /developers/asyncio/ Asynchronous Programming %}
<ul>

18
source/_posts/2017-07-17-hasspodcast-ep-4.markdown Normal file
View File

@ -0,0 +1,18 @@
---
layout: post
title: "Home Assistant Podcast #4"
description: "We quickly cover off a few community items including the move to Discord and Carlo talks with Phil about his use of Floorplan."
date: 2017-07-17 00:01:00 +0000
date_formatted: "July 17, 2017"
author: Phil Hawthorne
author_twitter: philhawthorne
comments: true
categories: Media
og_image: /images/hasspodcast.jpg
---
We quickly cover off a few community items including the move to Discord and Carlo talks with Phil about his use of Floorplan.
[Listen online][episode]
[episode]: https://hasspodcast.io/ha004/

397
source/_posts/2017-07-29-release-50.markdown Normal file
View File

@ -0,0 +1,397 @@
---
layout: post
title: "0.50: Voice control, History improvements, and Xiaomi"
description: "Use your voice to control your Home."
date: 2017-07-29 00:11:05
date_formatted: "July 29, 2017"
author: Paulus Schoutsen
author_twitter: balloob
comments: true
categories: Release-Notes
og_image: /images/blog/2017-07-0.50/components.png
---
<a href='/components/#version/0.50'><img src='/images/blog/2017-07-0.50/components.png' style='border: 0;box-shadow: none;'></a>
Last Wednesday we released [Hass.io](https://home-assistant.io/hassio/), an operating system to take care of all the updating hassles that come with running home automation at home and so much more. This is a major milestone for Home Assistant as it is our first step to offering a fully integrated solution using a bring your own hardware approach.
The launch has been crazy successful. The [20 minute introduction video][hassio-intro] by BRUHAutomation already has 12.5k views in just 4 days with no less than 150 comments.
Hass.io will be a great foundation for bigger and better integrated features. Stay tuned.
### {% linkable_title Adding the power of voice to integrations %}
Hass.io will be a great foundation for bigger and better integrated features. Stay tuned.
But enough about Hass.io, let's not forget about Home Assistant. This release has completely revamped the way how we deal with voice integrations. We turned Home Assistant into a platform to write voice apps, no matter where the processing of the voice happens. This can be done by Alexa, Google Assistant or in the Home Assistant user interface.
We are super excited about the new functionality and hope that it will trigger a new type of applications and systems to be built on top of Home Assistant. This release includes a shopping list to show the new functionality. As a user you can add any item to the shopping list with your voice and also ask what is on your shopping list.
```yaml
# Example configuration.yaml entry
shopping_list:
```
To make testing these applications easier, we've updated the conversation component. The component will now allow sentences to be configured that hook directly into the new voice functionality. Combined with the new interface it will allow for some great interactions!
<iframe width="100%" height="166" scrolling="no" frameborder="no"
src="https://www.youtube.com/watch?v=Ij0zDF3qwmE">
</iframe>
### {% linkable_title History improvements %}
[@OverloadUT] has been recently spending a lot of time on optimizing the history database queries. This release includes PR [#8632], the first in a list of improvements that he is working on. This PR greatly improves requests for single entities by using an optimized query for this use case.
The performance change in some of his tests shows this change to be about 300x faster (30 seconds to 0.1 seconds!) (There is no theoretical upper limit due to the issue with multi-entity queries getting worse the longer the current recorder run has been going.)
[hassio-intro]: https://www.youtube.com/watch?v=XWPluWcYRMI&feature=youtu.be
### {% linkable_title Xiaomi integration %}
Yes, it has happened! After being in beta for a while, the Xiaomi support is now available to all. [@danielhiversen] did an amazing job and we now support sensors, switches, lights and covers.
### {% linkable_title Velbus integration %}
Another awesome integration is that of the Velbus home automation system which has been contributed by [@thomasdelaet]. It integrates their sensors, covers, fans, lights and switches.
### {% linkable_title Manual alarm with MQTT control %}
A new version of the manual alarm component is now available with full MQTT control thanks to [@colinodell]. Using this you can build your own control panel to remotely arm/disarm the alarm. For example, using a [Raspberry Pi to create an alarm](https://www.hackster.io/colinodell/diy-alarm-control-panel-for-home-assistant-ac1813).
## {% linkable_title New Platforms %}
- Initial support for Google Wifi/OnHub ([@fronzbot] - [#8485]) ([sensor.google_wifi docs]) (new-platform)
- Xiaomi gw support ([@danielhiversen] - [#8555]) ([xiaomi docs]) ([binary_sensor.xiaomi docs]) ([cover.xiaomi docs]) ([light.xiaomi docs]) ([sensor.xiaomi docs]) ([switch.xiaomi docs]) (new-platform)
- Add Intent component ([@balloob] - [#8434]) ([alexa docs]) ([intent docs]) ([intent_script docs]) ([shopping_list docs]) ([snips docs]) (breaking change) (new-platform)
- Manual alarm with MQTT control ([@colinodell] - [#8257]) ([alarm_control_panel.manual_mqtt docs]) (new-platform)
- Add component Light TPLink ([@gollo] - [#8643]) ([light.tplink docs]) (new-platform)
- Velbus ([@thomasdelaet] - [#8076]) ([velbus docs]) ([binary_sensor.velbus docs]) ([light.velbus docs]) (new-platform)
- Add uk_transport component. ([@robmarkcole] - [#8600]) ([sensor.uk_transport docs]) (new-platform)
## {% linkable_title If you need help... %}
...don't hesitate to use our very active [forums][forum] or join us for a little [chat][discord]. The release notes have comments enabled but it's preferred if you use the former communication channels. Thanks.
## {% linkable_title Reporting Issues %}
Experiencing issues introduced by this release? Please report them in our [issue tracker][issue]. Make sure to fill in all fields of the issue template.
<!--more-->
## {% linkable_title Breaking Changes %}
- Automations: The state trigger keyword `state` and the time trigger keyword `after` were deprecated in 0.46. They have now been removed. ([@amelchio] - [#8510]) ([automation.state docs]) ([automation.time docs]) (breaking change)
- Wink: the component is no longer supporting the `access_token` in the config. Use the new OAuth authentication or add your username and password to the config. ([@w1ll1am23] - [#8208]) ([wink docs]) (breaking change)
- Alexa/API.AI/Snips.ai/Conversation: configuring responses to intents/sentences has been moved to a new component called `intent_script`. Conversation now allows configuring sentences to map to intents. ([@balloob] - [#8434]) ([alexa docs]) ([intent docs]) ([intent_script docs])
([shopping_list docs]) ([snips docs]) (breaking change) (new-platform)
```yaml
alexa:
snips:
apiai:
intent_script:
LightKitchen:
speech:
type: plain
text: I did the work, yay.
card:
type: simple
title: Lights Card
content: I have turned on the lights.
action:
service: light.turn_on
data:
entity_id: light.kitchen
conversation:
intents:
LightKitchen:
- The kitchen is magic
```
- Switch fritzdect: attributes have been renamed to use underscores and no capital letters ([@thomasklingbeil] - [#8436]) ([switch.fritzdect docs]) (breaking change)
- Yahoo Weather: no longer allow configuring forecasts but include all instead. ([@fanthos] - [#8626]) ([weather.yweather docs]) (breaking change)
- The Home Assistant Z-Wave Cover implementation has been updated to support the latest development version of OpenZWave. If you are currently applying a workaround to your OpenZWave installation to support the barrier command class, you'll need to make sure you update your workaround to the latest development version of OpenZWave. ([@firstof9] - [#8574]) ([cover docs]) ([cover.zwave docs]) (breaking change)
## {% linkable_title All changes %}
- Make deps directory persistent over upgrades ([@MartinHjelmare] - [#7801])
- Fix check for running inside venv ([@MartinHjelmare] - [#8481])
- Bump to KNXIP 0.5 ([@open-homeautomation] - [#8492]) ([knx docs])
- Expose all components on hass [Concept] ([@balloob] - [#8490]) ([light docs])
- Add bind_hass to components ([@balloob] - [#8502])
- Persistent notification import ([@balloob] - [#8507])
- Added additional attributes to OwnTracks device_tracker ([@binarybucks] - [#8503]) ([device_tracker.owntracks docs])
- Added sensor state rounding ([@fronzbot] - [#8499]) ([sensor.pi_hole docs])
- fix for a bug introduced with media support in #8282 ([@MikeChristianson] - [#8513]) ([notify.twitter docs])
- handle timeout errors without logging.exception when updating hue lights; double quotes in log msgs ([@azogue] - [#8524]) ([light.hue docs])
- Remove deprecated automation keywords ([@amelchio] - [#8510]) ([automation.state docs]) ([automation.time docs]) (breaking change)
- Citybikes: Allow None as result for empty slots ([@janLo] - [#8528]) ([sensor.citybikes docs])
- Return a 0 temperature value when none is found ([@phil-lavin] - [#8518]) ([climate.maxcube docs])
- Fix #6469 and #6828 ([@titilambert] - [#8537]) ([sensor.hydroquebec docs])
- Update docstrings ([@fabaff] - [#8536])
- Upgrade TwitterAPI to 2.4.6 ([@fabaff] - [#8535]) ([notify.twitter docs])
- Decora: Fix set brightness and improve reconnection ([@titilambert] - [#8522]) ([light.decora docs])
- Initial support for Google Wifi/OnHub ([@fronzbot] - [#8485]) ([sensor.google_wifi docs]) (new-platform)
- Fix exception dlib_face_identify when image is not recognized by face_recognition module ([@tchellomello] - [#8552]) ([image_processing.dlib_face_identify docs])
- [media_extractor] Add support for custom stream queries for media_extractor ([@minchik] - [#8538]) ([media_extractor docs])
- Report Harmony remote off if state is unknown ([@jawilson] - [#8547]) ([remote.harmony docs])
- Upgrade the alarmdecoder dependency library from 0.12.1 to 0.12.3. ([@viswa-swami] - [#8542]) ([alarmdecoder docs])
- turn_on_action and turn_off_action with script syntax ([@azogue] - [#8558]) ([media_player.kodi docs])
- Extends Pi-hole sensor to support the new sensors: ([@tchellomello] - [#8549]) ([sensor.pi_hole docs])
- Support for Wink Switch and Light groups also fix fan speed selection ([@w1ll1am23] - [#8501]) ([wink docs]) ([fan.wink docs]) ([light.wink docs]) ([switch.wink docs])
- Added a service to write to KNX group addressed including documentation ([@open-homeautomation] - [#8491]) ([knx docs])
- Handle manual edits to emulated_hue_ids.json ([@jawilson] - [#8560]) ([emulated_hue docs])
- Enhance python_script to support "_getitem_" ([@sdague] - [#8541]) ([python_script docs])
- Update persistent deps dir version in config.py ([@balloob] - [#8479])
- Xiaomi gw support ([@danielhiversen] - [#8555]) ([xiaomi docs]) ([binary_sensor.xiaomi docs]) ([cover.xiaomi docs]) ([light.xiaomi docs]) ([sensor.xiaomi docs]) ([switch.xiaomi docs]) (new-platform)
- fix #8263 corrected Adafruit DHT library version from 1.3.0 to 1.3.2 ([@namadori] - [#8562]) ([sensor.dht docs])
- xiaomi bug fix ([@danielhiversen] - [#8576]) ([binary_sensor.xiaomi docs])
- Bumped python-simplisafe version ([@bachya] - [#8578]) ([alarm_control_panel.simplisafe docs])
- Added Time Remaining and Time Elapsed sensors for octoprint ([@w1ll1am23] - [#8581]) ([sensor.octoprint docs])
- upgade xiaomi lib to 0.2 ([@danielhiversen] - [#8584]) ([xiaomi docs])
- Device support for different new sensors of the xiaomi aqara gateway ([@syssi] - [#8577]) ([xiaomi docs]) ([binary_sensor.xiaomi docs]) ([sensor.xiaomi docs]) ([switch.xiaomi docs])
- Extends Fitbit sensors to track the device battery level ([@tchellomello] - [#8583]) ([sensor.fitbit docs])
- xiaomi binary sensor bug fix ([@danielhiversen] - [#8586]) ([binary_sensor.xiaomi docs])
- upgrade pywebpush and PyJWT ([@perosb] - [#8588]) ([notify.html5 docs])
- Support for Wink oauth application authorization ([@w1ll1am23] - [#8208]) ([wink docs]) (breaking change)
- Add Intent component ([@balloob] - [#8434]) ([alexa docs]) ([intent docs]) ([intent_script docs]) ([shopping_list docs]) ([snips docs]) (breaking change) (new-platform)
- Remove code in wink.py overwriting hass.data configurator ([@w1ll1am23] - [#8595]) ([wink docs])
- bump python-mirobo version for more robust protocol handling, make the platform to update on startup ([@rytilahti] - [#8602]) ([switch.xiaomi_vacuum docs])
- Binary sensor ping fixed for hassio ([@gollo] - [#8573]) ([binary_sensor.ping docs])
- Simplified percent conversion, better logging ([@open-homeautomation] - [#8568]) ([sensor.knx docs])
- make attributes in the fritzdect module easier to process ([@thomasklingbeil] - [#8436]) ([switch.fritzdect docs]) (breaking change)
- Allow set_cover_position in scenes ([@peckham] - [#8613])
- better but still not great ([@cribbstechnologies] - [#8618])
- Upgrade youtube_dl to 2017.7.23 ([@fabaff] - [#8617]) ([media_extractor docs])
- Upgrade mypy to 0.520 ([@fabaff] - [#8616])
- REST binary sensor value_template optional ([@philhawthorne] - [#8596]) ([binary_sensor.rest docs])
- added onvif camera fix for non-virtual env installations ([@matt2005] - [#8592]) ([camera.onvif docs])
- Cleanup old device_tracker stuff ([@pvizeli] - [#8627])
- Add support for using credstash as a secret store ([@justin8] - [#8494])
- Added support for default value when environment variable is missing ([@devspacenine] - [#8484])
- Manual alarm with MQTT control ([@colinodell] - [#8257]) ([alarm_control_panel.manual_mqtt docs]) (new-platform)
- Catch and log Lyft API errors ([@armills] - [#8635]) ([sensor.lyft docs])
- Tweak conversation/intent/shopping list ([@balloob] - [#8636]) ([conversation docs]) ([shopping_list docs])
- Update dependencies cast + discovery ([@balloob] - [#8646]) ([media_player.cast docs])
- Add component Light TPLink ([@gollo] - [#8643]) ([light.tplink docs]) (new-platform)
- Fixes Fitbit sensor to report battery level with the expected device ([@tchellomello] - [#8647]) ([sensor.fitbit docs])
- Upgrade aiolifx ([@amelchio] - [#8648]) ([light.lifx docs])
- Velbus ([@thomasdelaet] - [#8076]) ([velbus docs]) ([binary_sensor.velbus docs]) ([light.velbus docs]) (new-platform)
- Yahoo Weather update, supports forecast for more days ([@fanthos] - [#8626]) ([weather.yweather docs]) (breaking change)
- History performance improvements for single-entity requests ([@OverloadUT] - [#8632]) ([history docs])
- Add transition support to light.zha ([@jawilson] - [#8548]) ([light.zha docs])
- Add uk_transport component. ([@robmarkcole] - [#8600]) ([sensor.uk_transport docs]) (new-platform)
- Added support for SerenaHoneycombShades to Lutron Caseta ([@809694+kfcook] - [#8662]) ([cover.lutron_caseta docs])
- MQTT Switch: add availability_topic for online/offline status ([@abmantis] - [#8593]) ([mqtt docs]) ([switch.mqtt docs])
- Adding support for mapping keys to value in statsd ([@Khabi] - [#8665]) ([statsd docs])
- Upgrade fuzzywuzzy to 0.15.1 ([@fabaff] - [#8671]) ([conversation docs])
- Upgrade libnacl to 1.5.2 ([@fabaff] - [#8670]) ([device_tracker.owntracks docs])
- Upgrade sqlalchemy to 1.1.12 ([@fabaff] - [#8669]) ([recorder docs])
- Upgrade pyhomematic to 0.1.30 ([@danielperna84] - [#8673]) ([homematic docs])
- Hass.io: logo support / timeout handling ([@pvizeli] - [#8668]) ([hassio docs])
- Updated pysnmp to 4.3.9 ([@bgehrich] - [#8675]) ([device_tracker.snmp docs]) ([sensor.snmp docs])
- Fix COMMAND_CLASS_BARRIER_OPERATOR for dev branch of OpenZwave ([@firstof9] - [#8574]) ([cover docs]) ([cover.zwave docs]) (breaking change)
- Shopping List: edit name / complete status ([@balloob] - [#8666]) ([shopping_list docs])
- Support for Wink local control ([@w1ll1am23] - [#8607]) ([wink docs])
- Persist shopping list + clear completed ([@balloob] - [#8697]) ([shopping_list docs])
[#7801]: https://github.com/home-assistant/home-assistant/pull/7801
[#8076]: https://github.com/home-assistant/home-assistant/pull/8076
[#8208]: https://github.com/home-assistant/home-assistant/pull/8208
[#8257]: https://github.com/home-assistant/home-assistant/pull/8257
[#8434]: https://github.com/home-assistant/home-assistant/pull/8434
[#8436]: https://github.com/home-assistant/home-assistant/pull/8436
[#8479]: https://github.com/home-assistant/home-assistant/pull/8479
[#8481]: https://github.com/home-assistant/home-assistant/pull/8481
[#8484]: https://github.com/home-assistant/home-assistant/pull/8484
[#8485]: https://github.com/home-assistant/home-assistant/pull/8485
[#8490]: https://github.com/home-assistant/home-assistant/pull/8490
[#8491]: https://github.com/home-assistant/home-assistant/pull/8491
[#8492]: https://github.com/home-assistant/home-assistant/pull/8492
[#8494]: https://github.com/home-assistant/home-assistant/pull/8494
[#8499]: https://github.com/home-assistant/home-assistant/pull/8499
[#8501]: https://github.com/home-assistant/home-assistant/pull/8501
[#8502]: https://github.com/home-assistant/home-assistant/pull/8502
[#8503]: https://github.com/home-assistant/home-assistant/pull/8503
[#8507]: https://github.com/home-assistant/home-assistant/pull/8507
[#8510]: https://github.com/home-assistant/home-assistant/pull/8510
[#8513]: https://github.com/home-assistant/home-assistant/pull/8513
[#8518]: https://github.com/home-assistant/home-assistant/pull/8518
[#8522]: https://github.com/home-assistant/home-assistant/pull/8522
[#8524]: https://github.com/home-assistant/home-assistant/pull/8524
[#8528]: https://github.com/home-assistant/home-assistant/pull/8528
[#8535]: https://github.com/home-assistant/home-assistant/pull/8535
[#8536]: https://github.com/home-assistant/home-assistant/pull/8536
[#8537]: https://github.com/home-assistant/home-assistant/pull/8537
[#8538]: https://github.com/home-assistant/home-assistant/pull/8538
[#8541]: https://github.com/home-assistant/home-assistant/pull/8541
[#8542]: https://github.com/home-assistant/home-assistant/pull/8542
[#8547]: https://github.com/home-assistant/home-assistant/pull/8547
[#8548]: https://github.com/home-assistant/home-assistant/pull/8548
[#8549]: https://github.com/home-assistant/home-assistant/pull/8549
[#8552]: https://github.com/home-assistant/home-assistant/pull/8552
[#8555]: https://github.com/home-assistant/home-assistant/pull/8555
[#8558]: https://github.com/home-assistant/home-assistant/pull/8558
[#8560]: https://github.com/home-assistant/home-assistant/pull/8560
[#8562]: https://github.com/home-assistant/home-assistant/pull/8562
[#8568]: https://github.com/home-assistant/home-assistant/pull/8568
[#8573]: https://github.com/home-assistant/home-assistant/pull/8573
[#8574]: https://github.com/home-assistant/home-assistant/pull/8574
[#8576]: https://github.com/home-assistant/home-assistant/pull/8576
[#8577]: https://github.com/home-assistant/home-assistant/pull/8577
[#8578]: https://github.com/home-assistant/home-assistant/pull/8578
[#8581]: https://github.com/home-assistant/home-assistant/pull/8581
[#8583]: https://github.com/home-assistant/home-assistant/pull/8583
[#8584]: https://github.com/home-assistant/home-assistant/pull/8584
[#8586]: https://github.com/home-assistant/home-assistant/pull/8586
[#8588]: https://github.com/home-assistant/home-assistant/pull/8588
[#8592]: https://github.com/home-assistant/home-assistant/pull/8592
[#8593]: https://github.com/home-assistant/home-assistant/pull/8593
[#8595]: https://github.com/home-assistant/home-assistant/pull/8595
[#8596]: https://github.com/home-assistant/home-assistant/pull/8596
[#8600]: https://github.com/home-assistant/home-assistant/pull/8600
[#8602]: https://github.com/home-assistant/home-assistant/pull/8602
[#8607]: https://github.com/home-assistant/home-assistant/pull/8607
[#8613]: https://github.com/home-assistant/home-assistant/pull/8613
[#8616]: https://github.com/home-assistant/home-assistant/pull/8616
[#8617]: https://github.com/home-assistant/home-assistant/pull/8617
[#8618]: https://github.com/home-assistant/home-assistant/pull/8618
[#8626]: https://github.com/home-assistant/home-assistant/pull/8626
[#8627]: https://github.com/home-assistant/home-assistant/pull/8627
[#8632]: https://github.com/home-assistant/home-assistant/pull/8632
[#8635]: https://github.com/home-assistant/home-assistant/pull/8635
[#8636]: https://github.com/home-assistant/home-assistant/pull/8636
[#8643]: https://github.com/home-assistant/home-assistant/pull/8643
[#8646]: https://github.com/home-assistant/home-assistant/pull/8646
[#8647]: https://github.com/home-assistant/home-assistant/pull/8647
[#8648]: https://github.com/home-assistant/home-assistant/pull/8648
[#8662]: https://github.com/home-assistant/home-assistant/pull/8662
[#8665]: https://github.com/home-assistant/home-assistant/pull/8665
[#8666]: https://github.com/home-assistant/home-assistant/pull/8666
[#8668]: https://github.com/home-assistant/home-assistant/pull/8668
[#8669]: https://github.com/home-assistant/home-assistant/pull/8669
[#8670]: https://github.com/home-assistant/home-assistant/pull/8670
[#8671]: https://github.com/home-assistant/home-assistant/pull/8671
[#8673]: https://github.com/home-assistant/home-assistant/pull/8673
[#8675]: https://github.com/home-assistant/home-assistant/pull/8675
[#8697]: https://github.com/home-assistant/home-assistant/pull/8697
[@809694+kfcook]: https://github.com/809694+kfcook
[@Khabi]: https://github.com/Khabi
[@MartinHjelmare]: https://github.com/MartinHjelmare
[@MikeChristianson]: https://github.com/MikeChristianson
[@OverloadUT]: https://github.com/OverloadUT
[@abmantis]: https://github.com/abmantis
[@amelchio]: https://github.com/amelchio
[@armills]: https://github.com/armills
[@azogue]: https://github.com/azogue
[@bachya]: https://github.com/bachya
[@balloob]: https://github.com/balloob
[@bgehrich]: https://github.com/bgehrich
[@binarybucks]: https://github.com/binarybucks
[@colinodell]: https://github.com/colinodell
[@cribbstechnologies]: https://github.com/cribbstechnologies
[@danielhiversen]: https://github.com/danielhiversen
[@danielperna84]: https://github.com/danielperna84
[@devspacenine]: https://github.com/devspacenine
[@fabaff]: https://github.com/fabaff
[@fanthos]: https://github.com/fanthos
[@firstof9]: https://github.com/firstof9
[@fronzbot]: https://github.com/fronzbot
[@gollo]: https://github.com/gollo
[@janLo]: https://github.com/janLo
[@jawilson]: https://github.com/jawilson
[@justin8]: https://github.com/justin8
[@matt2005]: https://github.com/matt2005
[@minchik]: https://github.com/minchik
[@namadori]: https://github.com/namadori
[@open-homeautomation]: https://github.com/open-homeautomation
[@peckham]: https://github.com/peckham
[@perosb]: https://github.com/perosb
[@phil-lavin]: https://github.com/phil-lavin
[@philhawthorne]: https://github.com/philhawthorne
[@pvizeli]: https://github.com/pvizeli
[@robmarkcole]: https://github.com/robmarkcole
[@rytilahti]: https://github.com/rytilahti
[@sdague]: https://github.com/sdague
[@syssi]: https://github.com/syssi
[@tchellomello]: https://github.com/tchellomello
[@thomasdelaet]: https://github.com/thomasdelaet
[@thomasklingbeil]: https://github.com/thomasklingbeil
[@titilambert]: https://github.com/titilambert
[@viswa-swami]: https://github.com/viswa-swami
[@w1ll1am23]: https://github.com/w1ll1am23
[alarm_control_panel.manual_mqtt docs]: https://home-assistant.io/components/alarm_control_panel.manual_mqtt/
[alarm_control_panel.simplisafe docs]: https://home-assistant.io/components/alarm_control_panel.simplisafe/
[alarmdecoder docs]: https://home-assistant.io/components/alarmdecoder/
[alexa docs]: https://home-assistant.io/components/alexa/
[automation.state docs]: https://home-assistant.io/docs/automation/trigger/#state-trigger
[automation.time docs]: https://home-assistant.io/docs/automation/trigger/#time-trigger
[binary_sensor.ping docs]: https://home-assistant.io/components/binary_sensor.ping/
[binary_sensor.rest docs]: https://home-assistant.io/components/binary_sensor.rest/
[binary_sensor.velbus docs]: https://home-assistant.io/components/binary_sensor.velbus/
[binary_sensor.xiaomi docs]: https://home-assistant.io/components/binary_sensor.xiaomi/
[camera.onvif docs]: https://home-assistant.io/components/camera.onvif/
[climate.maxcube docs]: https://home-assistant.io/components/climate.maxcube/
[conversation docs]: https://home-assistant.io/components/conversation/
[cover docs]: https://home-assistant.io/components/cover/
[cover.lutron_caseta docs]: https://home-assistant.io/components/cover.lutron_caseta/
[cover.xiaomi docs]: https://home-assistant.io/components/cover.xiaomi/
[cover.zwave docs]: https://home-assistant.io/components/cover.zwave/
[device_tracker.owntracks docs]: https://home-assistant.io/components/device_tracker.owntracks/
[device_tracker.snmp docs]: https://home-assistant.io/components/device_tracker.snmp/
[emulated_hue docs]: https://home-assistant.io/components/emulated_hue/
[fan.wink docs]: https://home-assistant.io/components/fan.wink/
[hassio docs]: https://home-assistant.io/components/hassio/
[history docs]: https://home-assistant.io/components/history/
[homematic docs]: https://home-assistant.io/components/homematic/
[image_processing.dlib_face_identify docs]: https://home-assistant.io/components/image_processing.dlib_face_identify/
[intent docs]: https://home-assistant.io/components/intent/
[intent_script docs]: https://home-assistant.io/components/intent_script/
[knx docs]: https://home-assistant.io/components/knx/
[light docs]: https://home-assistant.io/components/light/
[light.decora docs]: https://home-assistant.io/components/light.decora/
[light.hue docs]: https://home-assistant.io/components/light.hue/
[light.lifx docs]: https://home-assistant.io/components/light.lifx/
[light.tplink docs]: https://home-assistant.io/components/light.tplink/
[light.velbus docs]: https://home-assistant.io/components/light.velbus/
[light.wink docs]: https://home-assistant.io/components/light.wink/
[light.xiaomi docs]: https://home-assistant.io/components/light.xiaomi/
[light.zha docs]: https://home-assistant.io/components/light.zha/
[media_extractor docs]: https://home-assistant.io/components/media_extractor/
[media_player.cast docs]: https://home-assistant.io/components/media_player.cast/
[media_player.kodi docs]: https://home-assistant.io/components/media_player.kodi/
[mqtt docs]: https://home-assistant.io/components/mqtt/
[notify.html5 docs]: https://home-assistant.io/components/notify.html5/
[notify.twitter docs]: https://home-assistant.io/components/notify.twitter/
[python_script docs]: https://home-assistant.io/components/python_script/
[recorder docs]: https://home-assistant.io/components/recorder/
[remote.harmony docs]: https://home-assistant.io/components/remote.harmony/
[sensor.citybikes docs]: https://home-assistant.io/components/sensor.citybikes/
[sensor.dht docs]: https://home-assistant.io/components/sensor.dht/
[sensor.fitbit docs]: https://home-assistant.io/components/sensor.fitbit/
[sensor.google_wifi docs]: https://home-assistant.io/components/sensor.google_wifi/
[sensor.hydroquebec docs]: https://home-assistant.io/components/sensor.hydroquebec/
[sensor.knx docs]: https://home-assistant.io/components/sensor.knx/
[sensor.lyft docs]: https://home-assistant.io/components/sensor.lyft/
[sensor.octoprint docs]: https://home-assistant.io/components/sensor.octoprint/
[sensor.pi_hole docs]: https://home-assistant.io/components/sensor.pi_hole/
[sensor.snmp docs]: https://home-assistant.io/components/sensor.snmp/
[sensor.uk_transport docs]: https://home-assistant.io/components/sensor.uk_transport/
[sensor.xiaomi docs]: https://home-assistant.io/components/sensor.xiaomi/
[shopping_list docs]: https://home-assistant.io/components/shopping_list/
[snips docs]: https://home-assistant.io/components/snips/
[statsd docs]: https://home-assistant.io/components/statsd/
[switch.fritzdect docs]: https://home-assistant.io/components/switch.fritzdect/
[switch.mqtt docs]: https://home-assistant.io/components/switch.mqtt/
[switch.wink docs]: https://home-assistant.io/components/switch.wink/
[switch.xiaomi docs]: https://home-assistant.io/components/switch.xiaomi/
[switch.xiaomi_vacuum docs]: https://home-assistant.io/components/switch.xiaomi_vacuum/
[velbus docs]: https://home-assistant.io/components/velbus/
[weather.yweather docs]: https://home-assistant.io/components/weather.yweather/
[wink docs]: https://home-assistant.io/components/wink/
[xiaomi docs]: https://home-assistant.io/components/xiaomi/
[forum]: https://community.home-assistant.io/
[issue]: https://github.com/home-assistant/home-assistant/issues
[discord]: https://discord.gg/c5DvZ4e

27
source/developers/intent/conversation.markdown Normal file
View File

@ -0,0 +1,27 @@
---
layout: page
title: "Registering sentences"
description: "Register sentences with the conversation component."
date: 2017-07-23 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
The conversation component handles incoming commands from the frontend and converts them to intents. It does this based on registered sentences.
As a component, you can register sentences with the conversation component to allow it to be remote controlled. Refer to named slots by putting the slot name between curly braces: `{item}`.
Example code:
```python
@asyncio.coroutine
def async_setup(hass, config):
hass.components.conversation.async_register('MyCoolIntent', [
'I think that {object} is very cool',
'Nothing is cooler than {object}'
])
```
If a sentence like "I think that beer is very cool" comes in, the conversation component will generate an intent of type `MyCoolIntent` and with 1 slot, named `object` and value `beer`.

59
source/developers/intent/firing.markdown Normal file
View File

@ -0,0 +1,59 @@
---
layout: page
title: "Firing intents"
description: "How to fire intents to be handled by Home Assistant."
date: 2017-07-23 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
When you fire an intent, you will get a response back or an error will be raised. It is up to the component to return the result to the user.
Example code to handle an intent in Home Assistant.
```python
from homeassistant.helpers import intent
intent_type = 'TurnLightOn'
slots = {
'entity': { 'value': 'Kitchen' }
}
try:
intent_response = yield from intent.async_handle(
hass, 'example_component', intent_type, slots
)
except intent.UnknownIntent as err:
_LOGGER.warning('Received unknown intent %s', intent_type)
except intent.InvalidSlotInfo as err:
_LOGGER.error('Received invalid slot data: %s', err)
except intent.IntentError:
_LOGGER.exception('Error handling request for %s', intent_type)
```
The intent response is an instance of `homeassistant.helpers.intent.IntentResponse`.
| Name | Type | Description |
| ---- | ---- | ----------- |
| `intent` | Intent | Instance of intent that triggered response. |
| `speech` | Dictionary | Speech responses. Each key is a type. Allowed types are `plain` and `ssml`. |
| `card` | Dictionary | Card responses. Each key is a type. |
Speech dictionary values:
| Name | Type | Description |
| ---- | ---- | ----------- |
| `speech` | String | The text to say
| `extra_data` | Any | Extra information related to this speech.
Card dictionary values:
| Name | Type | Description |
| ---- | ---- | ----------- |
| `title` | String | The title of the card
| `content` | Any | The content of the card

49
source/developers/intent/handling.markdown Normal file
View File

@ -0,0 +1,49 @@
---
layout: page
title: "Handling intents"
description: "How to handle intents that are fired in Home Assistant."
date: 2017-07-23 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
Any component can register to handle intents. This allows a single component to handle intents fired from multiple voice assistants.
A component has to register an intent handler for each type that it wants to handle. Intent handlers have to extend `homeassistant.helpers.intent.IntentHandler`
```python
import asyncio
from homeassistant.helpers import intent
DATA_KEY = 'example_key'
@asyncio.coroutine
def async_setup(hass, config):
hass.data[DATA_KEY] = 0
intent.async_register(hass, CountInvocationIntent())
class CountInvocationIntent(intent.IntentHandler):
"""Handle CountInvocationIntent intents."""
# Type of intent to handle
intent_type = 'CountInvocationIntent'
# Optional. A validation schema for slots
# slot_schema = {
# 'item': cv.string
# }
@asyncio.coroutine
def async_handle(self, intent_obj):
"""Handle the intent."""
intent_obj.hass.data[DATA_KEY] += 1
response = intent_obj.create_response()
response.async_set_speech(
"This intent has been invoked {} times".format(
intent_obj.hass.data[DATA_KEY]))
return response
```

37
source/developers/intent/index.markdown Normal file
View File

@ -0,0 +1,37 @@
---
layout: page
title: "Intents"
description: "Intents are helping Home Assistant to gather "
date: 2017-07-23 20:00
sidebar: true
comments: false
sharing: true
footer: true
---
An intent is a description of a user's intention. Intents are generated by user actions, like asking Amazon Echo to turn on a light.
<p class='img'>
<a href='https://docs.google.com/drawings/d/1i9AsOQNCBCaeM14QwEglZizV0lZiWKHZgroZc9izB0E/edit'><img src='/images/architecture/intents.png' /></a>
Architectural overview of intents in Home Assistant
</p>
Intents are fired by components that receive them from external sources/services. Conversation, Alexa, API.ai and Snips are currently sourcing intents.
Any component can handle intents. This makes it very easy for developers to integrate with all voice assistants at once.
Intents are implemented using the `homeassistant.helpers.intent.Intent` class. It contains the following properties:
| Name | Type | Description |
| ---- | ---- | ----------- |
| `hass` | Home Assistant | The Home Assistant instance that fired the intent.
| `platform` | string | The platform that fired the intent
| `intent_type` | string | The type (name) of the intent
| `slots` | dictionary | Contains the slot values keyed by slot name.
| `text_input` | string | Optional. The raw text input that initiated the intent.
Description of the slots dictionary values.
| Name | Type | Description |
| ---- | ---- | ----------- |
| Value | anything | Value of the slot.

BIN
source/images/architecture/intents.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 61 KiB

BIN
source/images/blog/2017-07-0.50/components.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 39 KiB

BIN
source/images/components/apple_tv/auth_pin.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

BIN
source/images/components/apple_tv/auth_start.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

BIN
source/images/components/apple_tv/scan_result.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

BIN
source/images/components/apple_tv/scan_start.jpg Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 21 KiB

BIN
source/images/supported_brands/google_wifi.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 19 KiB

BIN
source/images/supported_brands/velbus.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 59 KiB

BIN
source/images/supported_brands/yeelight.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 78 KiB

After

Width:  |  Height:  |  Size: 21 KiB