Making Amazon Echo Alexa Sing to openHAB2

Preface

The documentation on openHAB2 is somewhat lacking and scattered. But I was able to complete my journey so I thought I’d add another article to the noise.

There are a number of approaches to integrating the Echo with openHAB. I have tried some of them successfully and others less so. This tutorial focuses on what appears to be the official approach.

For those of you who like a road map, we will be building a custom Alexa Skill. When triggered, the skill will execute an AWS Lambda function that we will be creating. The Lambda function will call out to the myopenhab.org cloud service which will pass the appropriate action to your personal openHAB server. If any of that went over your head, you’re in the right place. Let’s do this.

  • Sidenote to the tin foil hats: yes, you can bypass the myopenhab.org piece and have the lambda function call your openHAB server directly, however, there is a significant amount of extra work to make that happen and I’d recommend getting comfortable with the easy route before jumping into that.

Tag Your Items

  • To expose items to Alexa, you need to tag them with Lighting, Switchable, CurrentTemperature, or TargetTemperature.  The readme is a good reference.
Switch KitchenLights "Kitchen Lights" <light> (gKitchen) [ "Lighting" ]
Dimmer BedroomLights "Bedroom Lights" <light> (gBedroom) [ "Lighting" ]

Connect to myopenhab.org

I’m going to assume you have a functioning openHAB2 instance. We need to connect it to myopenhab.org.

  • In your browser, navigate to PaperUI > Add-Ons > Misc, and install the openHAB Cloud Connector. Restart openHAB.
  • In your browser, navigate to https://myopenhab.org. Sign up for an account. You’ll need to know your uuid and secret. These values can be found in files that live in your userdata folder. I’m using docker so that is located at /openhab/userdata/, but on other platforms you’ll likely find it at /usr/share/openhab/userdata. Inside this folder, you should find a file named uuid. Additionally, you’ll find a folder named openhabcloud with a file inside named secret. These two files contain the values you’ll need to register at myopenhab.org

Amazon Setup

The readme says you’ll need an Amazon AWS account with Alexa and Lambda access as well as an OAUTH2 Provider. Each of these pieces have dependency on the others so we will be jumping around a bit.

Amazon Developer Account

  • You’ll need to sign up for a free Amazon developer account. This can be your normal Amazon user account if you’d prefer
  • You’ll also need to register for a free Amazon AWS account. You will need to enter credit card info, but if you stay under the very reasonable limits, you will not be charged
  • In the AWS Console you can select your region in the top right. You’ll need to set your region to either N.Virginia for US skills or EU (Ireland) for UK and German skills

Setup Security

  • We need to setup an access key so the openhab script can login and setup the lambda function on our behalf
    • From the AWS Console, click on your name at the top right and select My Security Credentials
    • Click Continue to Security Credentials
    • Expand Access Keys and click Create New Access Key
    • Click Show Access Key and save the Access Key ID and Secret Access Key for later

  • For the OAUTH piece, we need a security profile.
  • We will also need a role for the lambda function with appropriate privileges
    • From the IAM Console, click Roles on the left menu.
    • Click Create New Role
    • Name your role and click Next Step
    • Select AWS Lambda from the AWS Service Roles section
    • Select the checkbox for AWSLambdaExecute and click Next Step
    • Save the Role ARN for later.

Alexa Skill (Part 1)

  • From the developer portal, navigate to the Alexa section
  • In the Alexa Skills Kit box, click Get Started
  • Click on the Add a New Skill button in the upper right
  • On the skill information page choose Smart Home Skill API
  • Enter the name as openhab-development. You can specify something else, but we’ll be running a script later that expects it to be called openhab-development, so proceed at your own risk. Click Next
  • On the Interaction Model section click Next
  • At the top of the page you should now see your application ID. It should look like amzn1.ask.skill.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx. Save this for later
  •  Before we can continue with our skill, we need to setup our Lambda function.

AWS Lambda Function

  • You can certainly create the lambda function manually, but the openhab team provides a script that does the heavy lifting for you.
  • If you haven’t already, clone the repo, and copy the template config files
git clone https://github.com/openhab/openhab-alexa.git
cd openhab-alexa
cp config_sample.js config.js
cp env_sample .env
  • Open config.js and update the values as follows. USERNAME and PASSWORD should be replaced with your username and password for myopenhab.org.
 userpass: 'USERNAME:PASSWORD',
 host: 'home.myopenhab.org',
 port: 443,
 path: '/rest/items/',
  • Next edit the .env file. You’ll need your AWS Access Key, AWS Acess Key Secret and Role ARN from previous steps
  • If you are using EU (Ireland) you’ll need to set AWS_REGION to eu-west-1
  • Install dependencies with the following command. npm comes with nodejs and can be downloaded from https://nodejs.org
npm install
  • Create and upload the lambda function
node_modules/node-lambda/bin/node-lambda deploy
  • Login to the Amazon Lambda Console and select the newly created function
  • Under the Triggers tab, select Add Trigger
  • Click the grey-dashed box and choose Alexa Smart Home
  • Fill in the application ID from earlier. It’s the one that looks like amzn1.ask.skill.xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx and click Submit
  • Save the ARN from the top right corner. Note that this is different than the Role ARN we used earlier.
  • The security conscious will want to return to the AWS Security Console and either disable or delete the access key. This key was only needed by the setup script and can safely be revoked.

Alexa Skill (Part 2)

  • With our dependencies met, we can now finish the skill. Open the skill list and click the edit link next to the Alexa Skill we started earlier.
  • Click on the Configuration section.
  • Check the appropriate box for either North America or Europe
  • In the white box that appears, paste the ARN we copied from the Lambda page

  • This is a great resource for the next section, but not required reading
  • In the account linking section, enter https://www.amazon.com/ap/oa?redirect_uri=https://pitangui.amazon.com/api/skill/link/XXXXXXXXXXXXXX for the authorization url. Change the X’s to your redirect URI found later in the Account Linking section
  • Enter the Client ID from the security profile we created earlier
  • Add a scope named profile
  • Set Authorization Grant Type to Auth Code Grant
  • Set Access Token URI to https://api.amazon.com/auth/o2/token
  • Specify the Client Secret from the security profile we created earlier
  • Finally, save the redirect URL for later

  • Click Next
  • On the Test page, make sure the toggle is selected to show the skill in the Alexa app and click Next
  • There are a couple more sections that are not required to be completed since we will not be publishing the skill

Security Profile (Revisited)

  • From the Developer Console, Apps & Service then Login with Amazon.
  • Next to your security profile, select the gear icon then select Web Settings.
  • Click Edit and enter the Redirect URL from the last section in the Allowed Return URLs box. It should be of the format: https://pitangui.amazon.com/api/skill/link/XXXXXXXXXXXXXX
  • Save

Enable the Skill

  • Open the Alexa app on your phone.
  • Navigate to the Skills section.
  • In the top right, click the Your Skills button
  • Scroll to the bottom to find your skill.
  • Tap on it, Enable, Login
  • The App will prompt you to discover devices.
  • If all goes well, Alexa will find the tagged openHAB items and you will be living in the future!

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes:

<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <s> <strike> <strong>