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-19 15:26:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add docs for entity_config for Google Assistant and Alexa (#4386)

Browse Source 
* Update cloud docs and google assistant docs

* Unpublish Google Assistant

* ✏️ Grammar

* ✏️ Missing comma

* ✏️ Spelling & grammar
This commit is contained in:
Paulus Schoutsen 2018-01-11 13:45:14 -08:00 committed by GitHub
parent fa13b97618
commit b4b0972cc5
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
6 changed files with 324 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

119
source/_components/cloud.alexa.markdown Normal file
View File

@ -0,0 +1,119 @@
---
layout: page
title: "Alexa via Home Assistant Cloud"
description: "Enable the Alexa integration via Home Assistant Cloud integration."
date: 2017-11-17 20:00
sidebar: true
comments: false
sharing: true
footer: true
logo: home-assistant.png
ha_release: 0.60
ha_category: Cloud
ha_iot_class: "Cloud Push"
---
The Alexa integration allows users to control the entities via the [Home Assistant Smart Home skill for Alexa][alexa skill]. This means that you can say things like "Alexa, turn on the kitchen light" to control your local Home Assistant.
To use this integration, you need to have:
- The cloud component set up. [Learn more](/components/cloud/)
- An Alexa enabled device like the Amazon Echo
- Activated the [Home Assistant Smart Home skill for Alexa][alexa skill]
<p class='note warning'>Only Amazon US is currently supported. Other regions are being certified.</p>
You can use `configuration.yaml` to configure the entities that are being shown to Alexa and how they are exposed.
```yaml
# Example configuration.yaml entry configuring Alexa
cloud:
alexa:
filter:
include_entities:
- light.kitchen
- light.kitchen_left
include_domains:
- switch
exclude_entities:
- switch.outside
entity_config:
light.kitchen:
name: Custom Name for Alexa
description: The light in the kitchen
switch.stairs:
display_categories: LIGHT
```
{% configuration %}
alexa:
description: Configuration options for the Amazon Alexa integration.
required: false
type: map
keys:
filter:
description: Filters for entities to include/exclude from Alexa.
required: false
type: map
keys:
include_entities:
description: Entity IDs to include.
required: false
type: list
include_domains:
description: Domains to include.
required: false
type: list
exclude_entities:
description: Entity IDs to exclude.
required: false
type: list
exclude_domains:
description: Domains to exclude.
required: false
type: list
entity_config:
description: Entity specific configuration for Alexa
required: false
type: map
keys:
'`<ENTITY_ID>`':
description: Entity to configure
required: false
type: map
keys:
name:
description: Name of entity to show in Alexa
required: false
type: string
description:
description: Description of entity to show in Alexa
required: false
type: string
display_categories:
description: The display category to use in Alexa. [Available categories](https://developer.amazon.com/docs/device-apis/alexa-discovery.html#display-categories)
required: false
type: string
{% endconfiguration %}
### {% linkable_title Possible values for customizing %}
_Configuration via `customize:` is no longer available. Use the entity config as described above._
### {% linkable_title Available domains %}
Currently, the following domains are available to be used with Alexa:
- alert
- automation (enables/disables)
- cover
- fan (supports on/off and set speed)
- group
- input_boolean
- light
- lock (lock and unlock, but unlock is untested as Amazon has disabled unlock for now)
- media_player (play, pause, stop, set volume, adjust volume, next track, and previous track)
- scene
- script (enables/disables)
- switch
[alexa skill]: https://alexa.amazon.com/spa/index.html#skills/dp/B0772J1QKB/?ref=skill_dsk_skb_sr_2

98
source/_components/cloud.google_assistant.markdown Normal file
View File

@ -0,0 +1,98 @@
---
layout: page
title: "Google Assistant via Home Assistant Cloud"
description: "Enable the Google Assistant via Home Assistant Cloud integration."
date: 2017-11-17 20:00
sidebar: true
comments: false
sharing: true
footer: true
logo: home-assistant.png
ha_release: 0.61
ha_category: Cloud
ha_iot_class: "Cloud Push"
published: false
---
The Google Assistant integration allows users to control the entities via the Home Assistant Smart Home skill for Google Assistant. This means that you can say things like "Ok Google, turn on the kitchen light" to control your local Home Assistant.
To use this integration, you need to have:
- The cloud component set up. [Learn more](/components/cloud/)
- A Google Assistant enabled device like the Google Home
- Activated the Home Assistant Smart Home skill for Google Assistant
You can use `configuration.yaml` to configure the entities that are being shown to Google Assistant and how they are exposed.
```yaml
# Example configuration.yaml entry configuring Google Assistant
cloud:
google_actions:
filter:
include_entities:
- light.kitchen
- light.kitchen_left
include_domains:
- switch
exclude_entities:
- switch.outside
entity_config:
switch.kitchen:
name: Custom Name for Alexa
aliases:
- bright lights
- entry lights
type: 'action.devices.types.LIGHT'
```
{% configuration %}
google_actions:
description: Configuration options for the Google Assistant integration.
required: false
type: map
keys:
filter:
description: Filters for entities to include/exclude from Alexa.
required: false
type: map
keys:
include_entities:
description: Entity IDs to include.
required: false
type: list
include_domains:
description: Domains to include.
required: false
type: list
exclude_entities:
description: Entity IDs to exclude.
required: false
type: list
exclude_domains:
description: Domains to exclude.
required: false
type: list
entity_config:
description: Entity specific configuration for Google Assistant
required: false
type: map
keys:
'`<ENTITY_ID>`':
description: Entity to configure
required: false
type: map
keys:
name:
description: Name of entity to show in Google Assistant
required: false
type: string
aliases:
description: Aliases that can also be used to refer to this entity
required: false
type: list
type:
description: Override the type of the entity in Google Assistant. [List of available types](https://developers.google.com/actions/smarthome/guides/)
required: false
type: string
{% endconfiguration %}

106
source/_components/cloud.markdown
View File

@ -1,6 +1,6 @@
---
layout: page
title: "Cloud"
title: "Home Assistant Cloud"
description: "Enable the Home Assistant Cloud integration."
date: 2017-11-17 20:00
sidebar: true
@ -13,95 +13,35 @@ ha_category: Voice
ha_iot_class: "Cloud Push"
---
The Home Assistant Cloud allows you to quickly integrate your local Home Assistant with various cloud services. Any processing of services from other cloud services is handled by your local Home Assistant.
<p class='note'>The Home Assistant Cloud is currently in open beta and will become part of the upcoming Community Support Package. [Learn more](/blog/2017/12/17/introducing-home-assistant-cloud/)</p>
The Home Assistant Cloud allows you to quickly integrate your local Home Assistant with various cloud services like Amazon Alexa.
The following integrations are currently available:
- [Amazon Alexa (Amazon Echo)](/components/cloud.alexa/)
<!-- - [Google Assistant (Google Home)](/components/cloud.google_assistant/) -->
### {% linkable_title How does it work? %}
The Home Assistant Cloud has been designed with security in mind. When you activate the Cloud component, your instance will create a secure connection to the Home Assistant Cloud. There is no need for any further configuration or to expose your instance to the internet.
Integrations like Alexa will deliver messages to our cloud which we will forward to your local instance for processing. We just forward the response back to Alexa. This means that we do not have to store the state of your house in our cloud, we’re just the messenger!
You can find a list of frequently asked questions (and their answers) in [this blog post](/blog/2017/12/17/introducing-home-assistant-cloud/#faq).
### {% linkable_title Enabling the cloud %}
The Home Assistant Cloud is enabled by default. If not, add this to your configuration:
```yaml
# Example configuration.yaml entry to enable the cloud component
cloud:
```
Once activated, go to the configuration panel in Home Assistant and create an account and log in. There is no need to configure your router or expose your instance to the internet in any other way.
If you are not seeing the **Configuration** panel, make sure you have the following option enabled in your configuration.yaml` file.
Once activated, go to the configuration panel in Home Assistant and create an account and log in. If you are not seeing the **Configuration** panel, make sure you have the following option enabled in your configuration.yaml` file.
```yaml
config:
```
### {% linkable_title Amazon Alexa %}
The Alexa integration allows users to control the entities via the [Home Assistant Smart Home skill for Alexa][alexa skill]. This means that you can say things like "Alexa, turn on the kitchen light" to control your local instance.
```yaml
# Example configuration.yaml entry configuring Alexa
cloud:
alexa:
filter:
include_entities:
- light.kitchen
include_domains:
- switch
exclude_entities:
- light.living_room
exclude_domains:
- script
```
{% configuration %}
alexa:
description: Configuration options for the Amazon Alexa integration.
required: false
type: map
keys:
filter:
description: Filters for entities to include/exclude from Alexa.
required: false
type: map
keys:
include_entities:
description: Entity IDs to include.
required: false
type: list
include_domains:
description: Domains to include.
required: false
type: list
exclude_entities:
description: Entity IDs to exclude.
required: false
type: list
exclude_domains:
description: Domains to exclude.
required: false
type: list
{% endconfiguration %}
### {% linkable_title Possible values for customize %}
| Attribute | Description |
| --------- | ----------- |
| `alexa_hidden` | Hide the entity from the Alexa smart home devices.
| `alexa_name` | Defines name of the entity for a Alexa smart home device. Useful if you have an entity with a friendly name in a local language that you want to access using an English sounding name.
| `alexa_description` | The description of the device in the Alexa smart home device list.
| `alexa_display_categories` | Set displayCategories, useful for things like media_player (TV/SPEAKERS) or scene (ACTIVITY_TRIGGER/SCENE_TRIGGER). More info can be found [here](https://developer.amazon.com/docs/device-apis/alexa-discovery.html#display-categories).
### {% linkable_title Available domains %}
Currently, the following domains are available to be used with Alexa:
- alert
- automation (enables/disables)
- cover
- fan (supports on/off and set speed)
- group
- input_boolean
- light
- lock (lock and unlock, but unlock is untested as Amazon has disabled unlock for now)
- media_player (play, pause, stop, set volume, adjust volume, next track and previous track)
- scene
- script (enables/disables)
- switch
[alexa skill]: https://alexa.amazon.com/spa/index.html#skills/dp/B0772J1QKB/?ref=skill_dsk_skb_sr_2
### {% linkable_title Frequently Asked Questions %}
You can find a list of frequently asked questions (and their answers) in [this blog post](https://home-assistant.io/blog/2017/12/17/introducing-home-assistant-cloud/#faq).

129
source/_components/google_assistant.markdown
View File

@ -18,7 +18,7 @@ The `google_assistant` component allows you to control things via Google Assista
The Google Assistant component requires a bit more setup than most due to the way Google requires Assistant Apps to be set up.
<p class='note'>
To use Google Assistant your Home Assistant configuration has to be externally accessible, with a hostname and SSL certificate. If you haven't already configured that you should do so before continuing.
To use Google Assistant, your Home Assistant configuration has to be externally accessible, with a hostname and SSL certificate. If you haven't already configured that you should do so before continuing.
</p>
To enable this, add the following lines to your `configuration.yaml` file:
@ -35,26 +35,77 @@ google_assistant:
- switch
- light
- group
entity_config:
switch.kitchen:
name: Custom Name for Alexa
aliases:
- bright lights
- entry lights
type: 'action.devices.types.LIGHT'
light.living_room:
expose: false
```
Configuration variables:
- **expose_by_default** (*Optional*): Expose devices in all supported domains by default.
- **project_id** (*Required*): Project ID from the Google Developer console (looks like `words-2ab12`)
- **client_id** (*Required*): A long random URL safe string (no spaces or special characters) that will be used for Implicit OAuth.
- **access_token** (*Required*): Another different long random URL safe string.
- **agent_user_id** (*Optional*): A string to identify the user, e.g., email address. If not provided, the component will generate one.
- **api_key** (*Optional*): An API Key generated for the project from [Google Console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview) which allows you to update devices without unlinking and relinking an account (see setup below). If not provided then the request_sync service is not exposed.
- **exposed_domains** (*Optional*): An array of Home Assistant domains to expose to Google Assistant. Options include:
- `switch`
- `light`
- `cover`
- `media_player`
- `group`
- `fan`
- `scene`
- `script`
- `climate`
{% configuration %}
project_id:
description: Project ID from the Google Developer console (looks like `words-2ab12`)
required: true
type: string
client_id:
description: A long random URL safe string (no spaces or special characters) that will be used for Implicit OAuth (example `aBcDeFgHiJkLmNoP`)
required: true
type: string
access_token:
description: Another different long random URL safe string (example `aBcDeFgHiJkLmNoP`)
required: true
type: string
agent_user_id:
description: A string to identify the user, e.g., email address. If not provided, the component will generate one.
required: false
type: string
api_key:
description: An API Key generated for the project from [Google Console](https://console.cloud.google.com/apis/api/homegraph.googleapis.com/overview) which allows you to update devices without unlinking and relinking an account (see setup below). If not provided then the request_sync service is not exposed.
required: false
type: string
expose_by_default:
description: Expose devices in all supported domains by default.
required: false
default: True
type: boolean
exposed_domains:
description: List of entity domains to expose to Google Assistant.
required: false
type: list
entity_config:
description: Entity specific configuration for Google Assistant
required: false
type: map
keys:
'`<ENTITY_ID>`':
description: Entity to configure
required: false
type: map
keys:
name:
description: Name of the entity to show in Google Assistant
required: false
type: string
expose:
description: Force an entity to be exposed/excluded.
required: false
type: boolean
aliases:
description: Aliases that can also be used to refer to this entity
required: false
type: list
type:
description: Override the type of the entity in Google Assistant. [List of available types](https://developers.google.com/actions/smarthome/guides/)
required: false
type: string
{% endconfiguration %}
It's very important that you use very long strings for `client_id` and `access_token`. Those are essentially the credentials to your Home Assistant instance. You can generate them with the following command:
@ -64,31 +115,6 @@ $ cat /dev/urandom | fold -w 120 | head -n 1 | base64 -w 0 | tr -dc '0-9A-Za-z'
If you're not using Linux, you can use sites such as [this one](https://www.browserling.com/tools/random-string) to generate a random string (containing mixed case letters and numbers) of up to 80 characters.
You can also customize your devices similar to other components by adding keys to entities:
```yaml
homeassistant:
customize:
master_bedroom_light:
google_assistant: true
google_assistant_name: bedroom light
bedroom_blinds:
aliases:
- bedroom shades
- bedroom covers
hallway_ceiling_switch:
google_assistant: true
google_assistant_type: light
```
Entity Customization Keys:
- **google_assistant**: True exposes entity, false will hide it.
- **google_assistant_name**: Can be used to override the primary name of an entity. By default the `friendly_name` of an entity is used.
- **google_assistant_type**: Can be used to override the domain/type of an entity. For example a switch can be treated as a light
- **aliases**: Provides "nicknames" to Google Assistant. These function as alternate names for an entity that Assistant will understand when spoken.
### {% linkable_title Setup %}
1. Download the [gactions CLI](https://developers.google.com/actions/tools/gactions-cli) (you'll use this later) - you can download and run this anywhere and on any machine, just remember where you put it for later (and don't forget to run `chmod +x gactions`to make it executable on mac or linux)
@ -132,8 +158,8 @@ Entity Customization Keys:
8. If you haven't already added the component configuration to `configuration.yaml` and restarted Home Assistant, you'll be unable to continue until you have.
8. Open the Google Assistant app and go into `Settings > Home Control`
9. Click the `+` sign, and near the bottom, you should have `[test] your app name`. Selecting that should lead to you the screen where you can set rooms for your devices or nicknames for your devices.
10. If you want to allow other houshold users to control the devices:
1. Go to the developer console using address from point 4.
10. If you want to allow other household users to control the devices:
1. Go to the developer console using the address from point 4.
2. Under the gear icon, click `Permissions`
3. Click `Add`, type the new user's e-mail address and choose `Project -> Editor` role
4. Have the new user go to [developer console](https://console.actions.google.com/) and repeat steps starting from point 7.
@ -143,11 +169,14 @@ Entity Customization Keys:
3. Go to Credentials and select API Key from Create Credentials
4. Note down the generated API Key and use this in the configuration
*Note:* The request_sync service requires that the initial sync from Google includes the agent_user_id. If not, the service will log an error that reads something like "Request contains an invalid argument". If this happens, then [unlink the account](https://support.google.com/googlehome/answer/7506443?hl=en-GB) from Home Control and relink.
### {% linkable_title Troubleshooting the request_sync service %}
*Note:* The request_sync service may fail with a 404 if the project_id of the Homegraph API differs from the project_id of the Actions SDK found in the preferences of your project on [developer console](https://console.actions.google.com). Resolve this by:
1. Removing your project on the [developer console](https://console.actions.google.com).
2. Add a new project in the [cloud console](https://console.cloud.google.com). Here you get a new project_id.
The request_sync service requires that the initial sync from Google includes the agent_user_id. If not, the service will log an error that reads something like "Request contains an invalid argument". If this happens, then [unlink the account](https://support.google.com/googlehome/answer/7506443?hl=en-GB) from Home Control and relink.
The request_sync service may fail with a 404 if the project_id of the Homegraph API differs from the project_id of the Actions SDK found in the preferences of your project on [developer console](https://console.actions.google.com). Resolve this by:
1. Removing your project from the [developer console](https://console.actions.google.com).
2. Add a new project to the [cloud console](https://console.cloud.google.com). Here you get a new project_id.
3. Enable Homegraph API to the new project.
4. Generete a new API key.
5. Again create a new project in the [developer console](https://console.actions.google.com/). Described above. But at the step 'Build under the Actions SDK box' choose your newly created project. By this they share the same project_id.
4. Generate a new API key.
5. Again create a new project in the [developer console](https://console.actions.google.com/). Described above. But at the step 'Build under the Actions SDK box' choose your newly created project. By this, they share the same project_id.

4
source/_posts/2017-12-17-introducing-home-assistant-cloud.markdown
View File

@ -14,7 +14,9 @@ Today we’re introducing the next step in the Home Assistant saga: the Home Ass
The first service that is supported via the Home Assistant Cloud is the Amazon Alexa Smart Home skill. This integration will allow you to control all your devices in Home Assistant via Amazon Alexa. You will be able to say _“Alexa, turn on the kitchen lights”_ and your local Home Assistant will turn on the lights. Because Alexa talks to Home Assistant, it doesn’t matter what kind of lights they are! Anything that is linked to Home Assistant will work. IKEA lights, a 10 year old X10 switch or something you’ve made yourself. As long as Home Assistant can control it, you can control it via Alexa.
We have designed the Home Assistant Cloud with security in mind. When you activate the new Cloud component, your instance will setup a secure connection to the Home Assistant Cloud. Alexa will deliver messages to our cloud which we will forward to your local instance for processing. We just forward the response back to Alexa. This means that we do not have to store the state of your house in our cloud, we’re just the messenger!
We have designed the Home Assistant Cloud with security in mind. When you activate the new Cloud component, your instance will create a secure connection to the Home Assistant Cloud. There is no need for any further configuration or to expose your instance to the internet.
Integrations like Alexa will deliver messages to our cloud which we will forward to your local instance for processing. We just forward the response back to Alexa. This means that we do not have to store the state of your house in our cloud, we’re just the messenger!
We are making the beta of the Home Assistant Cloud publicly available today. During the beta period the Home Assistant Cloud will be free to use. We are currently planning to run a beta till March 1, 2018 0:00 UTC. Once the beta ends, the Home Assistant Cloud will be part of our Community Support package which will run at $5 USD/month.

2
source/index.html
View File

@ -38,7 +38,7 @@ description: Open-source home automation platform running on Python 3. Track and
Use Alexa to control Home Assistant.
<div class='links'>
<a href='/blog/2017/12/17/introducing-home-assistant-cloud/'>LEARN MORE</a>
<a href='/components/cloud/'>LEARN MORE</a>
</div>
</div>