UPDATE: I am only a haaska user, not one of the developers. If you have any issues following any of the steps below, please take it up with the developers on Github, not here with me, as I can’t help you.

I used to have my Has.io installation working quite nicely with Amazon Alexa through the Home Assistant Cloud. It integrated my Philips Hue lights, Sonoff light switches, Logitech remote, Sonos speakers and Aqara sensors quite nicely. Then Nabu Casa decided they were going to charge US$ 5.00 a month for the pleasure. Now I’m a bit of a tightarse… I pay less for my VPN which gives me access to US Netflix, Pandora (Now that they’ve pulled out of NZ) and a host of other nice things – so for what you get, it really didn’t seem like value for money.

After a bit of reading, I came across haaska. It looked like it would fit the bill, only one problem – the documentation relating to setting it up is, shall we say “A little challenging”; There’s a fair bit of prior knowledge assumed which prompted me to author this.

So after struggling through it for a few hours including going off and getting information that is really lacking, here is my idiots guide to getting it working. Please note, I’m making the assumption that you have a working python installation, including pip, and a working GNU development environment. Without these two prerequisites, you will not be able to get this working (I really don’t know why the developer has not provided a zip file with a blank config.json file that can be uploaded to AWS, as the function files CAN be edited in the Lambda console…!). You must also be able to set up port forwarding in your router. As all three of these prerequisites are highly environment specific, they are out of the scope of this guide.

1. Be running HA  0.62 or better

2. You will be building an Alexa skill on Amazon Web services. There are two things to bear in mind here: Your skill will need to connect to your HA installation, and for your own sake, it will need to do so via HTTPS, NOT HTTP. With that in mind, there’s a lovely little HA add-on that does what we need, but first we need to set up our account with the dynamic DNS provider:

2.1. Go to Duck DNS. Create an account and log in.

2.2. In the Domains tile, type a subdomain name that means something to you in the empty text box labeled “sub domain”. Click the “add domain” button.

2.3. Copy the token value in the top tile

2.4. On your HA console, click Hass.io, select the Add-On store and click the Duck DNS tile then click install

2.5. Update the Duck DNS Add-on config so it looks like this:

{
  "lets_encrypt": {
    "accept_terms": true,
    "certfile": "fullchain.pem",
    "keyfile": "privkey.pem"
  },
  "token": "<your token from step 2.3.>",
  "domains": [
    "<your subdomain from step 2.2.>.duckdns.org"
  ],
  "seconds": 300
}

2.6. Slide the sliders next to “Start on boot” and “Auto update” to the right.

2.7. In your configuration.yaml file, add or edit the http: section so that it looks similar:

http:
  base_url: https://<your subdomain from step 2.2.>.duckdns.org:8123
  ssl_certificate: /ssl/fullchain.pem
  ssl_key: /ssl/privkey.pem

2.8. Add the following two entries into your configuration.yaml file:

api:

alexa:
  smart_home:

2.9. Note that you have now enabled SSL on your Hassio installation. Accordingly, you will have to update your plugins if they open a frame (Like Configurator or TasmoAdmin for example) – in the plugin config, set SSL to true

2.10. Restart Hassio. Bear in mind that you have enabled SSL, so use https:// not http://

3. Create the zip file to upload to AWS as per the following steps:

3.1. In the top left hand corner of the HA console, you will see a blue circle with a letter in it (The letter is the first letter of your HA user name), just to the right of the “Home Assistant” text. Click this, scroll to the bottom and in the “Long Lived Access Tokens” tile, click “Create Token”. Enter “haaska” (without the quotes) as the name, and copy the access token that is generated to the clipboard

3.2. Download the repository zip file from GitHub

3.3. Unzip the zip file. In the resulting directory, go to the config directory and copy config.json.sample to config.json

3.4. Edit the config.json file as follows:

{
  "url": "https://<your subdomain from step 2.2>.duckdns.org/api",
  "bearer_token": "<the token you created in step 3.1>",
  "debug": true,
  "ssl_verify": true,
  "ssl_client": []
}

3.5. Go one directory level up from the config directory and run make. This will create a file called haaska.zip if everything is working properly. If it isn’t, you’ve got a problem with your environment as noted above in the third paragraph of this guide – Please don’t ask me to fix it for you, as I’m not sitting in front of your machine.

4. Set up port forwarding on your router. You will need to forward ports 443 and 8123 on the WAN interface to port 8123 on the IP address your Hass.io machine. Again, if you don’t know how to do this, please don’t ask me to fix it for you, I’m not sitting in front of your router.

5. Register with Login with Amazon as follows:

5.1. Go to the Amazon Developer Console. If you have an account, sign in, otherwise create an account

5.2. Once signed in, click on the “Login with Amazon” link on the top menu ribbon

5.3 Click on the “Create a New Security Profile” button. Give the profile any name you like and enter anything for the privacy URL. Save it

5.4. Click the dropdown next to the profile (With the gear on it) and click “Web settings”. Leave this tab open, you’ll be coming back to it later

6. Create an Alexa skill and a lambda function. These are a bit of chicken and egg, as you need the Alexa skill ID in the Lambda function, and you need the Lambda function ID in the Alexa skill – Yes, a bit dumb…

6.1. Open a new browser tab, and go to the developer console. Hover over the Alexa menu item and click on Alexa Skills Kit

6.2. Click the “Create Skill” button.

6.3. Enter the skill name (I suggest “haaska”), the default language (I would suggest the language you have set in your Alexa devices) and click the “Smart Home” tile to select it. Then click the “Create Skill” button

6.4. Select v3 for the payload version.

6.5. Leave the skill tab open, and log into your AWS account. If you don’t have one, create it and log in. A word of warning – you will be required to provide credit card details when creating your account. There should be nothing to worry about, as all of what we’re going to use should be free forever, but just keep an eye on your statements just in case.

6.6. If you have never used Lambda before, you will need to create an IAM Lambda Basic Execution role. If you  have already done this, skip to 6.7:

6.6.1. Click on the “Services” flyout on the top menu ribbon, and select “IAM” under the “Security, Identity and Compliance” heading

6.6.2. On the left hand side, click “Roles”

6.6.3. Click the “Create role” button

6.6.4. Ensure the AWS service tile is selected and Click “Lambda”, then the “Next: Permissions” button

6.6.5. type “basic” into the filter box, click the checkbox next to  “AWSLambdaBasicExecutionRole” and click the “Next: Tags” button. Don’t add tags, just click the “Next: Review” button

6.6.6. Enter “lambda_basic_execution” in the “Role name” box and click the “Create role” button

6.7. *CRITICALLY IMPORTANT* There is a dropdown to the right of your username in the top right corner. You *MUST* select the correct location according to the entry in the “Lambda Function Region” column associated with the default language of your skill set in step 6.3 as per the following table:

6.8. Click on the “Services” flyout on the top menu ribbon, and select “Lambda” under the “Compute” heading

6.9. Click on the “Create Function” button and select the “Author from scratch” tile

6.10. Enter “haaska” in the Name box and select “Python 3.6” in the Runtime box

6.11. Select “Choose and existing role” in the Role box and “lambda_basic_execution” in the Existing role box. Click the “create function” button

6.12. in the “Function code” tile, select “Upload a .zip file” in the “Code entry type” dropdown

6.13. Click the “Upload” button, and select the zip file created in step 3.5

6.14. Change the entry in the “Handler” text box to “haaska.event_handler”

6.15. Ensure that the “Choose an existing role” is selected in the top dropdown of the “Execution role” tile, and that “lambda_basic_execution” is selected in the bottom drop down.

6.16. In the “Designer” tab, select “Alexa Smart Home” from the list on the left. If you don’t see it, you have an incompatible location set in step 6.7; I discovered this by setting my location to EU (London) as my language is English (UK)…NO! According to the table, your location must be EU (Ireland) for English (UK) – Go figure!

6,17. In the new “Configure Triggers” tile that appears, paste the skill ID copied from the tab left open in step 6.5 into the “Application ID” text box and click the “Add” button

6.18. Click the orange “Save” button at the top left. Leave this tab open, we will be coming back to it.

6.19. Copy the ARN as shown near the top right of the page, then paste it in the “Default endpoint” box in the tab left open in step 6.5. * CRITICALLY IMPORTANT! * You must also select the geographic region according to the “Endpoint region”  and default language in the table in step 6.7 and paste the ARN in the associated text box. Failure to do so will ensure haaska does not work

6.20. In the tab left open in step 6.5, click save and then on “Account linking”

6.21. Set “Authorization URI” to https://www.amazon.com/ap/oa, set “Access Token URI” to https://api.amazon.com/auth/o2/token, set the Client ID to the value from the tab left open in step 5.4, set “Client Secret” to the value from the tab left open in step 5.4, add a scope and enter “profile” in the resulting text box. Leave everything else as-is, click save and leave the tab open

6.22. Go back to the tab left open from step 5.4. Click the edit button Enter the “Redirect URLs from the tab left open in step 6.21 as “Allowed return URLs”

You can now test your work as per this and set it up for use as per this