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 07:17:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update alexa.smart_home.markdown (#14495)

Browse Source 
There look to have been a number of changes to the process so I've tried to document these as best I can. I have not included screenshots but the text I have provided is indicative of the setup experience I've had today (14/09/2020). I also changed some of the wording / sentence structure as it looks like English wasn't the first language for the person who wrote some of the content.
This commit is contained in:
ZuluWhiskey 2020-09-15 08:33:30 +01:00 committed by GitHub
parent 8332710fe5
commit cfd527fb8e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 31 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -85,7 +85,7 @@ OK, let's go. You first need sign in your [AWS console](https://console.aws.amaz
First thing you need to do after sing in [AWS console](https://console.aws.amazon.com/) is to create an IAM Role for Lambda execution. AWS has very strict access control, you have to specific define and assign the permissions.
- Click `Service` in top navigation bar, expand the menu to display all AWS services, click `IAM` under `Security, Identity, & Compliance` section to navigate to IAM console. Or you may use this [link](https://console.aws.amazon.com/iam/home)
- Click `Services` in top navigation bar, expand the menu to display all AWS services, click `IAM` under `Security, Identity, & Compliance` section to navigate to IAM console. Or you may use this [link](https://console.aws.amazon.com/iam/home)
- Click `Roles` in the left panel, then click `Create role`, select `AWS Service` -> `Lambda` in the first page of the wizard, then click `Next: Permissions`
- Select `AWSLambdaBasicExecutionRole` policy, then click `Next: Tags`. (Tips: you can use the search box to filter the policy)
@ -100,45 +100,50 @@ First thing you need to do after sing in [AWS console](https://console.aws.amazo
Next you need create a Lambda function.
- Click `Service` in top navigation bar, expand the menu to display all AWS services, click `Lambda` under `Compute` section to navigate to Lambda console. Or you may use this [link](https://console.aws.amazon.com/lambda/home)
- **IMPORTANT** Your current region will be displayed on the top right corner, make sure you select right region base on your Amazon account's country:
- Click `Services` in top navigation bar, expand the menu to display all AWS services, click `Lambda` under `Compute` section to navigate to Lambda console. Or you may use this [link](https://console.aws.amazon.com/lambda/home)
- **IMPORTANT - Alexa Skills are only supported in certain AWS reigons** Your current server location will be displayed on the top right corner (for example, Ohio), make sure you select the server closest to your location / region based on your Amazon account's country, whilst also ensuring that it is within one of the supported reigons for Alexa Skills otherwise this will not work!
- **US East (N.Virginia)** region for English (US) or English (CA) skills
- **EU (Ireland)** region for English (UK), English (IN), German (DE), Spanish (ES) or French (FR) skills
- **US West (Oregon)** region for Japanese and English (AU) skills.
- Click `Functions` in the left navigation bar, display list of your Lambda functions.
- Click `Create function`, select `Author from scratch`, then input a `Function name`.
- Select *Python 3.6* or *Python 3.7* as `Runtime`.
- Make sure select *Use an existing role* as `Execution role`, then select the role you just created from `Existing role` list.
- Click `Create function`, then you can configuration detail of Lambda function.
- Under `Configuration` tab, expand `Designer`, then click `Alexa Smart Home` in the left part of the panel to add a Alexa Smart Home trigger to your Lambda function.
- Scroll down little bit, you need input the `Skill ID` from the skill you created in previous step. (tips: you may need switch back to Alexa Developer Console to copy the `Skill ID`.
- Click your Lambda function icon in the middle of the diagram, scroll down you will see a `Function code` window.
- Under `Configuration` tab, expand `Designer` (if it isn't already expanded), then click `+ Add trigger` in the left part of the panel, then click `Alexa Smart Home` from the drop down list to add a Alexa Smart Home trigger to your Lambda function.
- You will then be prompted to input the `Skill ID` from the skill you created in previous step. (Tips: you may need switch back to Alexa Developer Console to copy the `Skill ID`.) Then click `Add`.
- Click your Lambda function icon in the middle of the diagram (above Layers), scroll down you will see a `Function code` window.
- Clear the example code, copy the Python script from: [https://gist.github.com/matt2005/744b5ef548cc13d88d0569eea65f5e5b](https://gist.github.com/matt2005/744b5ef548cc13d88d0569eea65f5e5b) (modified code to support Alexa's proactive mode, see details below)
- Scroll down a little bit, you will find `Environment variables`, you need add 4 environment variables:
- BASE_URL *(required)*: your Home Assistant instance's Internet accessible URL with port if needed. *Do not include the trailing `/`*.
- NOT_VERIFY_SSL *(optional)*: you can set it to *True* to ignore the SSL issue, if you don't have a valid SSL certificate or you are using self-signed certificate.
- DEBUG *(optional)*: set to *True* to log the debug message
- LONG_LIVED_ACCESS_TOKEN *(optional, not recommend)*: you will connect your Alexa Smart Home skill with your Home Assistant user account in the later steps, so that you don't need to use long-lived access token here. However, the access token you got from login flow is only valid for 30 minutes. It will be hard for you to test lambda function with the access token in test data. So for your convinces, you can remove the access token from the test data, [generate a long-lived access token][generate-long-lived-access-token] put here, then the function will fall back to read token from environment variables. (tips: You did not enable the security storage for your environment variables, so your token saved here is not that safe. You should only use it for debugging and testing purpose. You should remove and delete the long-lived access token after you finish the debugging.)
- Scroll down a little bit, you will find `Environment variables`, you need add 1 environment variable and, if required, 3 optional variables. This is done by selecting `Manage environment variables` then adding the following:
- *(required)* Key = BASE_URL, Value = your Home Assistant instance's Internet accessible URL with port if needed. *Do not include the trailing `/`*.
- *(optional)* Key = NOT_VERIFY_SSL, Value = *True*. You can set this to *True* to ignore SSL issues, for example if you don't have a valid SSL certificate or you are using a self-signed certificate.
- *(optional)* Key = DEBUG, Value = *True*. Set this variable to log the debug message.
- *(optional, not recommend)* Key = LONG_LIVED_ACCESS_TOKEN, Value = your Home Assistant Long-Lived Access Token. To avoid the use of a long-lived access token you will connect your Alexa Smart Home skill with your Home Assistant user account in the later steps, meaning you don't need to add it here. However, the access token you got from login flow is only valid for 30 minutes. It will be hard for you to test lambda function with the access token in test data. So for your convenience, you can remove the access token from the test data, [generate a long-lived access token][generate-long-lived-access-token] put here, then the function will fall back to read token from environment variables. (tips: You did not enable the security storage for your environment variables, so your token saved here is not that safe. You should only use it for debugging and testing purpose. You should remove and delete the long-lived access token after you finish the debugging.)
<p class='img'>
<img src='/images/integrations/alexa/lambda_function_env_var.png' alt='Screenshot: Environment variables in Lambda function'>
</p>
- Now scroll up to the top, click `Save` button.
- You need copy the ARN displayed in the top of the page, which is the identify of this Lambda function. You will need this ARN to continue Alexa Smart Home skill configuration later.
- Now click the `Save` button in the bottom right hand corner.
- You will then be brought back to your function configuration. From here you need to select `Save` in the top right hand corner of the screen.
- You also need to copy the ARN displayed in the top of the page, which is the identity of this Lambda function. You will need this ARN to continue Alexa Smart Home skill configuration later.
### Test the Lambda Function
Now, you have created the Lambda function, before you can test it, you have to set up your Home Assistant. Put following minimal configuration to your configuration.yaml, it will exposures all of your supported device and automation to Alexa. Check the [configuration section](#alexa-smart-home-component-configuration) if you want more control of the exposure.
Now, you have created the Lambda function, before you can test it, you have to set up the necessary aspects of your Home Assistant configuration. Put the following minimal configuration into your `configuration.yaml` file. It will expose all of your supported devices and automations to Alexa. Check the [configuration section](#alexa-smart-home-component-configuration) if you want more control of the exposure.
```yaml
alexa:
smart_home:
```
After your Home Assistant restarted, back to `AWS Lambda Console`, you are going to do some tests.
After your Home Assistant has restarted, go back to `AWS Lambda Console`, you are going to do some tests.
On the top of your Lambda function configuration page, there is a `Test` button, click the drop down button at left of `Test` button, click `Configure test events`, you can `Create new test event` using following data:
- On the top of your Lambda function configuration page, there is a `Test` button, to the left of this button is a drop down button - click this and select `Configure test events`
- Select `Create new test event`
- Name your event, for example `Discovery`
- Enter the following data into the code box below `Event name`:
```json
{
@ -157,10 +162,11 @@ On the top of your Lambda function configuration page, there is a `Test` button,
}
}
```
- Click `Create` in the bottom right hand corner.
This test event is a `Discovery` directive, Home Assistant will response with a list of your devices Alexa can interact with. This test data is lack of `token` in `payload.scope`, your Lambda function will read the `LONG_LIVED_ACCESS_TOKEN` from environment variable.
This test event is a `Discovery` directive, your Home Assistant instance will respond with a list of devices Alexa can interact with. This test data is lack of `token` in `payload.scope`, your Lambda function will read the `LONG_LIVED_ACCESS_TOKEN` from environment variable.
Click `Test` button. If you don't have `LONG_LIVED_ACCESS_TOKEN`, you will get a `INVALID_AUTHORIZATION_CREDENTIAL` response as the execution result.
Click the `Test` button. If you don't have `LONG_LIVED_ACCESS_TOKEN`, you will get a `INVALID_AUTHORIZATION_CREDENTIAL` response as the execution result.
Now, you can login to your Home Assistant and [generate a long-lived access token][generate-long-lived-access-token]. After you put your long-lived access token to the `Environment variable`, do not forget click `Save` button before you `Test` again.
@ -168,7 +174,7 @@ This time, you will get a list of your devices in the response. 🎉
## Configure the Smart Home Service Endpoint
Now removed the long-lived access token if you want, copied the ARN of your Lambda function, then back to [Alexa Developer Console][alexa-dev-console]. You will finish the configuration of the Smart Home skill.
Now remove the long-lived access token (if you want), copy the ARN of your Lambda function, then navigate back to [Alexa Developer Console][alexa-dev-console]. You will finish the configuration of the Smart Home skill.
- Sign in [Alexa Developer Console][alexa-dev-console], go to `Alexa Skills` page if you are not.
- Find the skill you just created, click `Edit` link in the `Actions` column.
@ -195,8 +201,8 @@ Alexa can link your Amazon account to your Home Assistant account. Therefore Hom
The trailing slash is important here.
- `Client Secret`: input anything you like, Home Assistant does not check this field
- `Client Authentication Scheme`: make sure you selected *Credentials in request body*. Home Assistant does not support *HTTP Basic*.
- `Scope`: input `smart_home`, Home Assistant is not using it yet, we may use it in the future when we allow more fine-grained access control.
- `Your Authentication Scheme`: make sure you selected *Credentials in request body*. Home Assistant does not support *HTTP Basic*.
- `Scope`: Click `+ Add scope` and input `smart_home`, Home Assistant is not using it yet, we may use it in the future when we allow more fine-grained access control.
- You can leave `Domain List` and `Default Access Token Expiration Time` as empty.
<p class='img'>
@ -205,12 +211,12 @@ Alexa can link your Amazon account to your Home Assistant account. Therefore Hom
- Click `Save` button in the top right corner.
- Next, you will use Alexa Mobile App or [Alexa web-based app](#alexa-web-based-app) to link your account.
- Open the Alexa app, navigate to `Skills` -> `Your Skills` -> `Dev Skills`
- Open the Alexa app, navigate to `Skills & Games` -> `Your Skills` -> `Dev`
- Click the Smart Home skill you just created.
- Click `Enable`.
- Click `Enable to use`.
- A new window will open to direct you to your Home Assistant's login screen.
- After you success login, you will be redirected back to Alexa app.
- You can discovery your devices now.
- After you successfully login, you will be redirected back to Alexa app.
- You can discover your devices now!
- Now, you can ask your Echo or in Alexa App, _"Alexa, turn on bedroom"_ 🎉
## Alexa Smart Home Component Configuration