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-08 01:46:50 +00:00
Code Issues Packages Projects Releases Wiki Activity

Line formatting, whitespace fixes, utterances as lists.

Browse Source
This commit is contained in:
ochlocracy 2020-01-27 16:56:27 -05:00
parent 37bebbc6cb
commit fd79ab90aa
1 changed files with 154 additions and 256 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

354
source/_integrations/alexa.smart_home.markdown
View File

@ -7,17 +7,11 @@ ha_category:
ha_release: "0.54"
---
Amazon Alexa provides a Smart Home API for richer home automation control and supports the ability to use simple, intuitive utterances without saying the skill name, such as:
<kbd>
_Alexa, turn off the light._
_Alexa, set the thermostat to cool._
_Alexa, is the garage door open?_
</kbd>
Amazon Alexa provides a Smart Home API for richer home automation control without requiring the the user to say the skill name, such as:
* _"Alexa, turn off the light."_
* _"Alexa, set the thermostat to cool."_
* _"Alexa, is the garage door open?"_
It takes considerable effort to configure. Your Home Assistant instance must be accessible from the Internet, and you need to create an Amazon Developer account and an Amazon Web Services (AWS) account. An easier solution is to use [Home Assistant Cloud](/integrations/cloud/).
@ -35,6 +29,7 @@ For Home Assistant Cloud Users, documentation can be found [here](https://www.na
## Amazon Alexa Smart Home
##### Steps to Integrate an Amazon Alexa Smart Home Skill with Home Assistant
- [Requirements](#requirements)
- [Create your Amazon Alexa Smart Home Skill](#create-your-amazon-alexa-smart-home-skill)
- [Create your Lambda function](#create-your-lambda-function)
@ -319,7 +314,6 @@ alexa:
type: string
{% endconfiguration %}
#### Alexa Locale
The `locale` should match the location and language used for your Amazon echo devices. Supported locales are `de-DE`, `en-AU`, `en-CA`, `en-GB`, `en-IN`, `en-US`, `es-ES`, `es-MX`, `fr-CA`, `fr-FR`, `it-IT`, `ja-JP`.
@ -371,7 +365,6 @@ Filters are applied as follows:
See the [troubleshooting](#troubleshooting) if for issues setting up the integration.
#### Alexa Display Categories
Configure a display category to override the display category and iconography each entity is shown in the Alexa app. This makes it easier to find and monitor devices.
@ -428,14 +421,10 @@ The following integrations are currently supported:
Arm and disarm Alarm Control Panel entities. Ask Alexa for the state of the Alarm Control Panel entity.
<kbd>
_Alexa, arm my home in away mode._
_Alexa, arm my home._
_Alexa, disarm my home._
_Alexa, is my home armed?_
</kbd>
* _"Alexa, arm my home in away mode."_
* _"Alexa, arm my home."_
* _"Alexa, disarm my home."_
* _"Alexa, is my home armed?"_
##### Arming
@ -468,14 +457,9 @@ The existing code is never communicated to Alexa from Home Assistant. During dis
Turn on and off Alerts, Automations, Groups, and Input Boolean entities as switches.
<kbd>
_Alexa, turn on the front door alert._
_Alexa, turn off energy saving automations._
_Alexa, Downstairs to on._
</kbd>
* _"Alexa, turn on the front door alert."_
* _"Alexa, turn off energy saving automations."_
* _"Alexa, Downstairs to on."_
#### Binary Sensor
@ -494,11 +478,7 @@ Binary Sensors with a [`device_class`](/integrations/binary_sensor/#device-class
Ask Alexa for the state of a contact sensor.
<kbd>
_Alexa, is the bedroom window open?_
</kbd>
* _"Alexa, is the bedroom window open?"_
##### Routines
@ -513,7 +493,6 @@ Use the [Entity Customization Tool](/docs/configuration/customizing-devices/#cus
Requires [Proactive Events](#proactive-events) enabled.
Configure a `binary_sensor` with `display_category` of `DOORBELL` in the [`entity_config`](#entity_config) to gain access to the doorbell notification settings in the Alexa App.
```yaml
alexa:
smart_home:
@ -551,7 +530,7 @@ alexa:
display_categories: CAMERA
```
Alexa will announce on all echo devices <samp><q>Person detected at [entity name]</q></samp>.
Alexa will announce on all echo devices _"Person detected at [entity name]"_.
<div class="note">
@ -567,24 +546,18 @@ Each Echo device will need the communication and Announcements setting enabled,
[Image Processing](#image-processing) entities also support this notification.
#### Climate
Single, double, and triple set-point thermostats are supported. The temperature value from the thermostat will also be exposed at a separate [temperature sensor](#sensor).
Single, double, and triple set-point thermostats are supported. The temperature value from the thermostat will also be exposed at a separate [temperature sensor](#sensor).
##### Set Thermostat Temperature
<kbd>
Alexa, set thermostat to 20.
Alexa, set the AC to 75.
Alexa, make it warmer in here.
Alexa, make it cooler in here.
</kbd>
##### Thermostat Mode
<kbd>
_Alexa, set living room thermostat to automatic._
</kbd>
* _"Alexa, set living room thermostat to automatic."_
- `DRY` is shown in Alexa app as `DEHUMIDIFY`
- `ECO` is handled as a `preset` in Home Assistant, and will not display in the Alexa app.
@ -592,33 +565,26 @@ _Alexa, set living room thermostat to automatic._
To change the thermostat mode the exact utterance must be used:
<kbd>
* _"Alexa, set [entity name] to [mode utterance]."_
_Alexa, set [entity name] to [mode utterance]._
If the climate entity supports on/off, use _turn on_ and _turn off_ utterances with the entity name or the mode utterance.
</kbd>
If the climate entity supports on/off, use <kbd>_turn on_</kbd> and <kbd>_turn off_</kbd> utterances with the entity name or the mode utterance.
<kbd>
_Alexa, turn on the [mode utterance]._
_Alexa, turn off the [entity name]._
</kbd>
* _"Alexa, turn on the [mode utterance]."_
* _"Alexa, turn off the [entity name]."_
Alexa supports the following utterances value for climate thermostat mode:
|HA Climate Mode | Alexa Mode Utterances |
|--- |--- |
|`AUTO` | <kbd>_auto_, _automatic_</kbd>|
|`COOL` | <kbd>_cool_, _cooling_</kbd>|
|`HEAT` | <kbd>_heat_, _heating_</kbd>|
|`ECO` | <kbd>_eco_, _economical_</kbd>|
|`DRY` | <kbd>_dehumidify_</kbd>|
|`OFF` | <kbd>_off_</kbd>|
|`AUTO` | _auto_, _automatic_|
|`COOL` | _cool_, _cooling_|
|`HEAT` | _heat_, _heating_|
|`ECO` | _eco_, _economical_|
|`DRY` | _dehumidify_|
|`OFF` | _off_|
#### Cover
Covers should be configured with the appropriate `device_class`.
Covers with a `device_class` of `blind`, `shade`, `curtin` are shown as an Interior Blind in the Alexa App and Covers with a `window`, `awning`, or `shutter` will show as an Exterior Blind.
@ -628,59 +594,48 @@ Covers with the `device_class` of `garage` are shown as a [Garage Door](#garage-
Use the [Entity Customization Tool](/docs/configuration/customizing-devices/#customization-using-the-ui) to override the `device_class` attribute to correctly expose a `cover` to Alexa.
##### Open/Close/Raise/Lower
Home Assistant configures covers with semantics that provide <kbd>_raise_, _lower_, _open_, _close_</kbd> utterances for covers. In addition to semantics <kbd>_turn on_ / _turn off_</kbd> utterances will also work.
<kbd>
Home Assistant configures covers with semantics that provide _raise_, _lower_, _open_, _close_ utterances for covers. In addition to semantics _turn on_ / _turn off_ utterances will also work.
_Alexa, open the garage door._
_Alexa, close the curtain._
_Alexa, lower the shades._
_Alexa, raise the roof!_
</kbd>
The <kbd>_raise_, _lower_, _open_, _close_</kbd> semantics are assigned based on the features supported by the cover. If the cover supports tilt functionality, <kbd>_open/close_</kbd> semantics are assigned to the tilt functionality, and <kbd>_raise/lower_</kbd> semantics are assigned to the position functionality.
If the cover does not support tilt, all semantics <kbd>_raise_, _lower_, _open_, _close_</kbd> are assigned to the position functionality.
* _"Alexa, open the garage door."_
* _"Alexa, close the curtain."_
* _"Alexa, lower the shades."_
* _"Alexa, raise the roof!"_
The _raise_, _lower_, _open_, _close_ semantics are assigned based on the features supported by the cover. If the cover supports tilt functionality, _open/close_ semantics are assigned to the tilt functionality, and _raise/lower_ semantics are assigned to the position functionality.
If the cover does not support tilt, all semantics _raise_, _lower_, _open_, _close_ are assigned to the position functionality.
##### Set Cover Position
Covers that `SUPPORT_SET_POSITION` can be controlled using percentages.
<kbd>
_Alexa, set the [entity name] position to thirty percent._
_Alexa, increase [entity name] position by ten percent._
_Alexa, decrease [entity name] position by twenty percent._
</kbd>
* _"Alexa, set the [entity name] position to thirty percent."_
* _"Alexa, increase [entity name] position by ten percent."_
* _"Alexa, decrease [entity name] position by twenty percent."_
|Locale|Friendly Name Synonyms|
|---|---|
|`en-US`|<kbd>_position_, _opening_</kbd>|
|`en-US`|_position_, _opening_|
Currently Alexa only supports friendly name synonyms for the `en-US` locale.
##### Set Cover Tilt
Covers that `SUPPORT_SET_POSITION_TILT` can be controlled using percentages.
<kbd>
_Alexa, set the [entity name] tilt to thirty percent._
_Alexa, increase [entity name] tilt by ten percent._
_Alexa, decrease [entity name] tilt by twenty percent._
</kbd>
* _"Alexa, set the [entity name] tilt to thirty percent."_
* _"Alexa, increase [entity name] tilt by ten percent."_
* _"Alexa, decrease [entity name] tilt by twenty percent."_
|Locale|Friendly Name Synonyms|
|---|---|
|`en-US`|<kbd>_tilt_, _angle_, _direction_</kbd>|
|`en-US`|_tilt_, _angle_, _direction_|
Currently Alexa only supports friendly name synonyms for the `en-US` locale.
##### Garage Doors
Covers with a `device_class` of `garage` support the Open by Voice PIN feature in the Alexa app. Configure a 4 digit PIN code to open the garage door in the Alexa app.
<p class='img'>
@ -693,17 +648,14 @@ Covers with a `device_class` of `garage` support the Open by Voice PIN feature i
Control fan speed, direction, and oscillation.
##### Fan Speed
The fan device must support the `speed` attribute. `speed` can be set using a percentage or a range value determined from the `speed_list` attribute.
<kbd>
_Alexa, set the fan speed to three._
_Alexa, set the fan speed to fifty percent._
_Alexa, set the fan power level to fifty percent._
_Alexa, turn up the speed on the tower fan._
_Alexa, set the air speed on the tower fan to maximum._
</kbd>
* _"Alexa, set the fan speed to three."_
* _"Alexa, set the fan speed to fifty percent."_
* _"Alexa, set the fan power level to fifty percent."_
* _"Alexa, turn up the speed on the tower fan."_
* _"Alexa, set the air speed on the tower fan to maximum."_
The `speed_list` attribute is used to determine the range value. For example, using a `speed_list` consisting of `[off, low, medium, high]` the range values would be `0:off`, `1:low`, `2:medium`, `3:high`.
@ -711,55 +663,49 @@ The following table lists the possible friendly name synonyms available for a fa
|Fan Range|Friendly Name Synonyms|
|---|---|
|0|<kbd>_zero_, _off_</kbd>|
|1|<kbd>_one_, _thirty three percent_, _low_, _minimum_, _min_</kbd>|
|2|<kbd>_two_, _sixty six percent_, _medium_</kbd>|
|3|<kbd>_three_, _one hundred percent_, _high_, _maximum_, _max_</kbd>|
|0|_zero_, _off_|
|1|_one_, _thirty three percent_, _low_, _minimum_, _min_|
|2|_two_, _sixty six percent_, _medium_|
|3|_three_, _one hundred percent_, _high_, _maximum_, _max_|
The following synonyms can be used for <kbd>_fan speed_</kbd>
The following synonyms can be used for _fan speed_
|Locale|Friendly Name Synonyms|
|---|---|
|`en-US`|<kbd>_fan speed_, _airflow speed_, _wind speed_, _air speed_, _air velocity_, _power level_</kbd>|
|`en-US`|_fan speed_, _airflow speed_, _wind speed_, _air speed_, _air velocity_, _power level_|
Currently Alexa only supports friendly name synonyms for the `en-US` locale.
##### Fan Direction
The fan device must support the `direction` attribute.
<kbd>
_Alexa, set the fan direction to forward._
_Alexa, set the fan direction to reverse._
</kbd>
* _"Alexa, set the fan direction to forward."_
* _"Alexa, set the fan direction to reverse."_
##### Fan Oscillation
The fan device must support the `oscillating` attribute.
<kbd>
_Alexa, is oscillate on for the tower fan?_
_Alexa, turn on swivel for the tower fan._
_Alexa, turn on oscillation mode for the table fan._
</kbd>
* _"Alexa, is oscillate on for the tower fan?"_
* _"Alexa, turn on swivel for the tower fan."_
* _"Alexa, turn on oscillation mode for the table fan."_
|Locale|Friendly Name Synonyms|
|---|---|
|`en-US`|<kbd>_oscillate_, _swivel_, _oscillation_, _spin_, _back and forth_</kbd>|
|`en-US`|_oscillate_, _swivel_, _oscillation_, _spin_, _back and forth_|
Currently Alexa only supports friendly name synonyms for the `en-US` locale.
#### Image Processing
Requires [Proactive Events](#proactive-events) enabled.
##### Presence Detection Notification
All `image_processing` entities support the presence detected notification settings in the Alexa App. Any state change will trigger the notification.
Alexa will announce on all echo devices <samp><q>Person detected at [entity name]</q></samp>.
Alexa will announce on all echo devices _"Person detected at [entity name]"_.
<p class='img'>
<a href='/images/integrations/alexa/alexa_app_person_detection.png' target='_blank'>
@ -773,188 +719,140 @@ Display category will default to `CAMERA` to enable presence detected notificati
</div>
#### Input Number
Control an `input_number` entity with Alexa. Configures Alexa with the `min`, `max`, `step`, and `unit_of_measurement` attributes for the entity.
<kbd>
_Alexa, set [entity name] to forty five [unit of measurement]._
_Alexa, increase the [entity name] by two._
_Alexa, set the [entity name] to maximum._
</kbd>
* _"Alexa, set [entity name] to forty five [unit of measurement]."_
* _"Alexa, increase the [entity name] by two."_
* _"Alexa, set the [entity name] to maximum."_
The following table lists the possible friendly name synonyms available for a Input Number with `min: -90, max: 90, step: 45, unit_of_measurement: degrees`.
|Fan Range|Friendly Name Synonyms|
|---|---|
|-90|<kbd>_negative ninety_, _minimum_, _min_</kbd>|
|-45|<kbd>_negative forty five_</kbd>|
|0|<kbd>_zero_</kbd>|
|45|<kbd>_forty five_</kbd>|
|90|<kbd>_ninety_, _maximum_, _max_</kbd>|
|-90|_negative ninety_, _minimum_, _min_|
|-45|_negative forty five_|
|0|_zero_|
|45|_forty five_|
|90|_ninety_, _maximum_, _max_|
#### Light
<kbd>
_Alexa, dim the bathroom light._
_Alexa, set the bedroom light to fifty percent._
</kbd>
* _"Alexa, dim the bathroom light."_
* _"Alexa, set the bedroom light to fifty percent."_
#### Lock
<kbd>
_Alexa, lock my front door._
_Alexa, unlock the dungeon._
</kbd>
* _"Alexa, lock my front door."_
* _"Alexa, unlock the dungeon."_
##### Locking
##### Unlocking
To unlock, Alexa will require a 4 digit voice personal identification number (PIN) for unlocking. Configure a 4 digit PIN in the Alexa app to unlock locks.
#### Media Player
##### Change Channel
<kbd>
_Alexa, change the channel to 200 on the Living Room TV._
_Alexa, change the channel to PBS on the TV._
_Alexa, next channel on the Living Room TV._
_Alexa, channel up on the TV._
_Alexa, channel down on the TV._
</kbd>
* _"Alexa, change the channel to 200 on the Living Room TV."_
* _"Alexa, change the channel to PBS on the TV."_
* _"Alexa, next channel on the Living Room TV."_
* _"Alexa, channel up on the TV."_
* _"Alexa, channel down on the TV."_
##### Speaker Volume
<kbd>
_Alexa, set the volume of the speakers to 50._
_Alexa, turn the volume down on the stereo by 20._
_Alexa, turn the volume down on Living Room TV._
_Alexa, mute speakers._
_Alexa, unmute speakers._
_Alexa, lower the volume on the stereo._
_Alexa, volume up 20 on the speakers._
</kbd>
* _"Alexa, set the volume of the speakers to 50."_
* _"Alexa, turn the volume down on the stereo by 20."_
* _"Alexa, turn the volume down on Living Room TV."_
* _"Alexa, mute speakers."_
* _"Alexa, unmute speakers."_
* _"Alexa, lower the volume on the stereo."_
* _"Alexa, volume up 20 on the speakers."_
##### Equalizer Mode
Supports changing the Media Player `sound_mode` from the preset `sound_mode_list`.
<kbd>
_Alexa, set mode to movie on the TV._
</kbd>
* _"Alexa, set mode to movie on the TV."_
Alexa only supports the following modes: `movie`, `music`, `night`, `sport`, `tv`.
##### Inputs
Supports changing the Media Player `source` from the preset `source_list`.
<kbd>
_Alexa, change the input to DVD on the Living Room TV._
</kbd>
* _"Alexa, change the input to DVD on the Living Room TV."_
Home Assistant will attempt to translate the the `media_player` `source_list` into a valid `source` name for Alexa. Alexa only supports the following input names:
`AUX 1`, `AUX 2`, `AUX 3`, `AUX 4`, `AUX 5`, `AUX 6`, `AUX 7`, `BLURAY`, `CABLE`, `CD`, `COAX 1`, `COAX 2`, `COMPOSITE 1`, `DVD`, `GAME`, `HD RADIO`, `HDMI 1`, `HDMI 2`, `HDMI 3`, `HDMI 4`, `HDMI 5`, `HDMI 6`, `HDMI 7`, `HDMI 8`, `HDMI 9`, `HDMI 10`, `HDMI ARC`, `INPUT 1`, `INPUT 2`, `INPUT 3`, `INPUT 4`, `INPUT 5`, `INPUT 6`, `INPUT 7`, `INPUT 8`, `INPUT 9`, `INPUT 10`, `IPOD`, `LINE 1`, `LINE 2`, `LINE 3`, `LINE 4`, `LINE 5`, `LINE 6`, `LINE 7`, `MEDIA PLAYER`, `OPTICAL 1`, `OPTICAL 2`, `PHONO`, `PLAYSTATION`, `PLAYSTATION 3`, `PLAYSTATION 4`, `SATELLITE`, `SMARTCAST`, `TUNER`, `TV`, `USB DAC`, `VIDEO 1`, `VIDEO 2`, `VIDEO 3`, `XBOX`
##### Playback State
Requires [Proactive Events](#proactive-events) enabled.
##### Seek
<kbd>
_Alexa, skip 30 seconds on device._
_Alexa, go back 10 seconds on device._
</kbd>
* _"Alexa, skip 30 seconds on device."_
* _"Alexa, go back 10 seconds on device."_
#### Scene
Activate scenes with scene name, or turn on utterance. Home Assistant does not support deactivate or turn off for scenes at this time.
<kbd>
_Alexa, Party Time._
_Alexa, turn on Party Time._
</kbd>
* _"Alexa, Party Time."_
* _"Alexa, turn on Party Time."_
#### Script
Run script with script name, or turn on utterance. Deactivate a running script with turn off utterance.
<kbd>
_Alexa, Party Time._
_Alexa, turn on Party Time._
_Alexa, turn off Party Time._
</kbd>
* _"Alexa, Party Time."_
* _"Alexa, turn on Party Time."_
* _"Alexa, turn off Party Time."_
#### Sensor
Requires [Proactive Events](#proactive-events) enabled.
Only temperature sensors are configured at this time.
<kbd>
_Alexa, what's the temperature in the kitchen?_
_Alexa, what's the upstairs temperature?_
_Alexa, what's the temperature of my ex-girlfriend's heart?_
</kbd>
* _"Alexa, what's the temperature in the kitchen?"_
* _"Alexa, what's the upstairs temperature?"_
* _"Alexa, what's the temperature of my ex-girlfriend's heart?"_
#### Switch
Support turn on and turn off utterances.
<kbd>
_Alexa, turn on the vacuum._
_Alexa, turn off the lights._
</kbd>
* _"Alexa, turn on the vacuum."_
* _"Alexa, turn off the lights."_
#### Timer
Start, Pause, and Restart Timer entities in Home Assistant.
<kbd>
_Alexa, pause the microwave._
_Alexa, hold the sous vide._
_Alexa, restart the microwave._
</kbd>
* _"Alexa, pause the microwave."_
* _"Alexa, hold the sous vide."_
* _"Alexa, restart the microwave."_
<div class="note">
To avoid issues with Alexa built in timer functionality. The timer entity can not include the word "timer" in the friendly name.
</div>
#### Vacuum
Support turn on and turn off utterances. Pause and Resume
<kbd>
_Alexa, turn on the vacuum._
_Alexa, pause the vacuum._
_Alexa, restart the vacuum._
</kbd>
* _"Alexa, turn on the vacuum."_
* _"Alexa, pause the vacuum."_
* _"Alexa, restart the vacuum."_
### Alexa web-based app
The following is a list of regions and the corresponding URL for the web-based Alexa app:
* United States: `https://alexa.amazon.com`
* United Kingdom: `https://alexa.amazon.co.uk`
@ -968,11 +866,13 @@ The following is a list of regions and the corresponding URL for the web-based A
### Troubleshooting
#### Binary Sensor not available in Routine Trigger
Binary Sensors with a [`device_class`](/integrations/binary_sensor/#device-class) attribute of `door` `garage_door` `opening` `window` `motion` `presense` are supported.
Use the [Entity Customization Tool](/docs/configuration/customizing-devices/#customization-using-the-ui) to override the `device_class` attribute to expose a `binary_sensor` to Alexa.
#### Token invalid and no refresh token available
Disable and re-enable the skill using the Alexa App; then restart Home Assistant.
### Debugging
@ -998,8 +898,6 @@ logger:
hass_nabucasa.iot: debug
```
[alexa-dev-console]: https://developer.amazon.com/alexa/console/ask
[emulated-hue-component]: /integrations/emulated_hue/
[generate-long-lived-access-token]: https://developers.home-assistant.io/docs/en/auth_api.html#long-lived-access-token