Fast Track

Fast Track

Here is a fast pace of the requirements need to have the solution in place

Port Forwarding

Be sure to enable port forwarding for SSH in your router. The target of the forwarding should be the host running the homeassistant or a host on you network that can reach you HA host

Dynamic DNS

Be sure to have a Dynamic DNS solution in place. no-ip, dyndns or duckdns.

Create an SSH Key and user

We need to create an ssh key for an user on the host that is receiving the SSH port forward. Below is an example how to create the user and ssh key. The user on the example is 'homeassistant'

$ sudo adduser homeassistant
$ sudo su - homeassistant
$ mkdir -p ~/.ssh && touch ~/.ssh/authorized_keys
$ ssh-keygen -t rsa # The key must have a passphrase
$ cat .ssh/id_rsa.pub >> .ssh/authorized_keys
$ cat .ssh/id_rsa # Copy the content to temporary file, so you can reference it later

Create a long-lived token on HA

We will need a long-lived token to use the HA API. To create a long-lived token perform the following steps:

• Login into HA
• Click on the "Hamburger" menu, top left
• Click on the Circle with the letter inside, top left
• Scroll down to the long-lived toke section
• Select "Create Token", nad give it a name
• Copy the full legth of the generated token, and past it to a temporary file, so you can reference it later

Configure HA for Alexa

Please edit the configuration.yaml so it has the content below:

api:

alexa:
  smart_home:

Clone git hub repo

$ git clone https://github.com/asantos82/haaska.git
Cloning into 'haaska'...
remote: Enumerating objects: 30, done.
remote: Counting objects: 100% (30/30), done.
remote: Compressing objects: 100% (21/21), done.
remote: Total 672 (delta 11), reused 15 (delta 5), pack-reused 642
Receiving objects: 100% (672/672), 271.69 KiB | 912.00 KiB/s, done.
Resolving deltas: 100% (359/359), done.
$ cd haaska/
$ git checkout ssh_tunnel # Branch were the sshtunnel code is

Configure the file config.json

The config.json is on the root of the haaska folder. Bellow is an example of the config file you can set:

{
    "url": "http://localhost",
    "bearer_token": "ir45U84jioj",
    "debug": true,
    "ssl_verify": true,
    "ssl_client": [],
    "ssh_enabled": true,
    "ssh_username": "homeassistant",
    "ssh_remote_host_public_url": "myhouse.no-ip.org",
    "ssh_remote_host_public_port": 22,
    "ssh_remote_host_private_url": "localhost",
    "ssh_remote_host_private_port": 8123,
    "ssh_local_host_port": 8123,
    "ssh_key_is_encrypted": false
}

• url: If you have HA running on the same host where you are terminating the SSH tunnel set the url to http://localhost. If you have HA running on a host that is not terminating the SSH tunnel, set the url to http://HA_IP_ADDR Replace HA_IP_ADDR with the IP of the host running HA.
• bearer_token: Fill this field with the long-lived token you have created previously HERE
• ssh_username: Fill this field with the user you have configured for ssh access HERE
• ssh_remote_host_public_url": Fill this field with the public host you have created HERE
• ssh_remote_host_public_port: Fill this field with the SSH port you have opened on the router
• ssh_remote_host_private_url: Fill this field with the IP address of the server running HA. If HA is on the same server that is terminating the SSH tunnel, set to localhost. If SSH tunnel, and HA are on different hosts, set the field with the IP of the HA server
• sh_local_host_port: Fill this field with the port that HA is running
• ssh_local_host_port: Set this filed to 8123. It is still being ignored
• ssh_key_is_encrypted: Set this field to false

Time to build the Lambda Function

Place yourself on the root of haaska folder

Build Docker Image

$ docker build -t user_name/haaskabuilder .
Sending build context to Docker daemon  28.16kB
Step 1/6 : FROM python:3.6-slim-stretch
 ---> 2c7185eead34
Step 2/6 : RUN   apt-get update &&   apt-get install -y make jq zip &&   pip install awscli &&   apt-get clean &&   cd /var/lib/apt/lists && rm -fr *Release* *Sources* *Packages* &&   truncate -s 0 /var/log/*log
 ---> Using cache
< REMOVED >
 ---> Running in 4e408ccbae4d
Removing intermediate container 4e408ccbae4d
 ---> 2d19a6b2864c
Successfully built 2d19a6b2864c
Successfully tagged user_name/haaskabuilder:latest

Save SSH Private Key

We need to have the ssh private key created HERE, saved to the root folder of the haaska. Please create a file named ssh.key and place inside of it the key created HERE.

NOTE: The ssh.key file will not be committed to github since it is in the .gitignore file

Build the Lambda Function

The root folder of the haaska project (before building lambda) should look similar to the one below:

CHANGELOG.md
Dockerfile
LICENSE
Makefile
README.md
config
config.json
haaska.py
images
requirements-ssh.txt
requirements.txt
ssh.key
test.py

Now we will be building the Lambda Function

$ docker run -v $(pwd):/usr/src/app user_name/haaskabuilder make haaska-ssh
mkdir -p build
pip install  -t build -r requirements-ssh.txt
Collecting requests==2.22.0
  Downloading requests-2.22.0-py2.py3-none-any.whl (57 kB)
Collecting sshtunnel==0.1.5
  Downloading sshtunnel-0.1.5.tar.gz (49 kB)
< REMOVED>
  adding: cryptography-2.9.dist-info/METADATA (deflated 67%)
zip -g haaska-ssh.zip haaska.py config.json ssh.key
  adding: haaska.py (deflated 64%)
  adding: config.json (deflated 53%)
  adding: ssh.key (stored 0%)

After building the lambda function the root directory of the haask project should look similar to this:

CHANGELOG.md
Dockerfile
LICENSE
Makefile
README.md
build
config
config.json
haaska-ssh.zip
haaska.py
images
requirements-ssh.txt
requirements.txt
ssh.key
test.py

Setup AWS Developer Account

• Go to https://developer.amazon.com/
• Login with the same login you have setup for Alexa
• Go to "Developer Console" > "Settings" > "Security Profiles" > "Create a New Security Profile"
• Fill the fields with the following values:
  • Security Profile Name: haaska
  • Security Profile Description: haaska for my Home Assistant
  • Save
• Select the recently created security profile
• Select the "Web Settings" tab
• Save the content of "Client ID" and "Client Secret" for future reference

Setup Alexa Skill Set

• Go to https://developer.amazon.com/alexa/console/ask
• Click Create Skill
• Fill the fields with the following values:
  • Skill name: haaska
  • Default language: English (UK)
  • Model: Smart Home
  • Method: Provision your own
• Select "Create Skill" top right
• Save the "Your Skill ID" for future reference
• Keep this tab opened

Setup AWS Account

Create IAM Role

• On an "incognito" browser window go to https://aws.amazon.com/console/
• If you have one account login, if not create one account. The email address doesn't need to be the same of Alexa/Developer Account
• Select the IAM service > Roles > Create Role
• Select "Lambda" from the "Choose a use case" section
• Search for the policy "AWSLambdaBasicExecutionRole" and select it
• For the role name set "alexa_lambda_basic_execution"

Create Lambda Function

• Select the Lambda Service
• On the top right corner select the Europe (Ireland) Region
• Create Function
• Select the Author from scratch
• Fill the fields with the following values:
  • Function name: haaska
  • Runtime: Python 3.6
  • Choose or create an execution role > Use an existing role > Select alexa_lambda_basic_execution > Create Function
• In the Configuration Tab, on the Section Designer, select "add trigger"
• Select "Alexa Smart Home" trigger
• Fill up the Skill Id with the value for the Skill ID you have saved previously from the Developer Console HERE
• Click Add
• In the Configuration Tab, on the Section Designer, click on the name of your function (orange icon)
• On the section "Function Code", in the "Code entry type" select "upload a .zip file", and select the haaska-ssh.zip from the build we have made previously
• On the "Handler", fill the option with haaska.event_handler
• On the "Basic settings" section increase the timeout to 15 seconds, and save
• If the save on the top right corner is orange, click it to save
• On the "Environment variables" section click edit
• Select "Add Environment Variable"
• For the Key to ssh_key_pass For the Value set the passphrase that you have used to encrypt the private key HERE. Click Save
• If the save on the top right corner is orange, click it to save
• On the top right of the corner is the Lambda ARN. Copy it and save for future reference

Setup Alexa Skill Set - Continuation

• Go back to the tab you have left open on the Developer Console
• Fill the box "Default endpoint" with the ARN of the lambda function you have saved previously
• Ticket the "Europe, India" check box and fill the box with the ARN of the lambda function you have saved previously
• Click save on the top right corner
• Click "Setup Account Linking"
• Fill the fields with the following values:
  • Authorization URI: https://www.amazon.com/ap/oa
  • Access Token URI: https://api.amazon.com/auth/o2/token
  • Client ID: Value of the Client ID you have previously saved HERE
  • Client Secret: Value of the Client Secret you have previously saved HERE
  • Client Authentication Scheme: HTTP Basic
  • Scope: Click + Add Scope and enter: profile
• Copy the list of 3 Redirect URIs and save for later
• Click save on the top right corner

Only one more step :)

• Go to https://developer.amazon.com/
• Go to "Developer Console" > "Settings" > "Security Profiles" > "Web Settings" > "Edit"
• Fill the "Allowed Return URLs" with the 1st of the Redirect URIs saved previously. Add Another.
• Repeat until you have the 3 URIS
• Click Save

Alexa APP

Link Alexa to Skill

• Open up the Alexa on your mobile device
• On the "Hamburger" Icon select "Skills & Games"
• Select the "Your Skills" tab
• Slide the boxes to the left, until you find the "Dev" box
• Select your haaska skill, and press "Enable to use"

Search Devices

• On the bottom bar select "Devices"
• On the top right corner select the '+' sign > "Add Device"
• Scroll to the end of the list and select "Other" > "Discover Devices"
• If all went well your devices should show up after the scan
• Start using Alexa to control you home assistant devices