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

0.50

source/developers/intent/conversation.markdown

@@ -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`.

source/developers/intent/firing.markdown

@@ -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

source/developers/intent/handling.markdown

@@ -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
+```

source/developers/intent/index.markdown

@@ -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.