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-25 10:17:23 +00:00
Code Issues Packages Projects Releases Wiki Activity

update docs for intents (#3046)

Browse Source 
* update docs for intents

* Fix alexa docs

* Fix api.ai reference
This commit is contained in:
Paulus Schoutsen 2017-07-23 23:17:13 -07:00 committed by GitHub
parent 17eab64744
commit 80814f25ca
10 changed files with 277 additions and 190 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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 %}
```

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

@ -0,0 +1,35 @@
---
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
{% raw %}# Example configuration.yaml entry
intent_script:
GetTemperature: # Intent type
speech:
text: We have {{ states.sensor.temperature }} degrees
action:
service: notify.notify
data_template:
message: Hello from an intent!
{% endraw %}
```
Inside an intent we can define these variables:
- **speech** (*Optional*): Text or template to return
- **action** (*Optional*): [Script syntax]
- **async_action** (*Optional*): Set to True to have Home Assistant not wait for the script to finish before returning the intent response.
[Script syntax]: /docs/scripts/

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:

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>

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