Amazon Echo Alexa Skill for openHAB
JavaScript
Latest commit 6b1a34a Feb 22, 2017 @paphko paphko committed with digitaldan Remove OH1 because it doesn't work with current impl (Homekit tags). (#8
)

Link added to a fork that supports OH1 via a dedicated Alexa group.

README.md

Amazon Alexa Smart Home skill for openHAB 2

This is a nodejs / lambda application that connects the Alexa Smart Home API to to a user's openHAB instance, either directly or through the openHAB Cloud service (preferred). The Smart Home API is not a general skill API, it allows the user to bypass using a application wake work and instead ask Alexa to perform a smart home action like "Alexa turn lights on"

This is designed to use the Homekit style tags in openHAB 2 to bind a user's devices to Alexa. This does not work with openHAB 1.x because there is no tagging mechanism. If you want to use the Alexa Smart Home skill with openHAB 1, you may use this fork which uses a group to bind user's devices to Alexa.

General Installation Instructions

Requirements

  • Amazon AWS account with Alexa and Lambda access
  • OAUTH2 Provider (Like Amazon Login)
  • A openHAB server that a AWS service endpoint can access

Skill Configuration

Deployment requires two configuration files, config.js for the application configuration, and .env for the node-lambda deployment app.

config.js

The app can access a openHAB installation using two different types of authorization, basic auth ("user@password") or with bearer auth (OAUTH2 token). Uncomment the "userpass" property for basic auth, otherwise a bearer token will be used.

.env

Enter your AWS credentials, specifically AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_ROLE_ARN. Other access methods may work as well (AWS_SESSION_TOKEN) but have not been tested.

Install Steps

Create Smart Home Skill

Use the following guide to setup amazon, note that the node deployment script publishes to "{AWS_FUNCTION_NAME}-{AWS_ENVIRONMENT}", so you might want to call yours "openhab-development" if your AWS_FUNCTION_NAME = "openhab". Also choose "nodejs" as the lambda runtime type.

For more in-depth guides on deploying Smart Home Skills see:

https://developer.amazon.com/public/solutions/alexa/alexa-skills-kit/docs/steps-to-create-a-smart-home-skill

https://developer.amazon.com/public/community/post/Tx34M7F8Z8U7U8B/Creating-Your-First-Alexa-Smart-Home-Skill

Create and Deploy Lambda app

  • run npm install to install the nodejs dependencies
  • copy config_sample.js to config.js
  • copy env_sample to .env
  • change config files to match your enviroment.
  • run "node-lambda deploy"
  • login to the amazon lambda console and select the newly created project,
  • Under "Event Sources" add a "smart home skill" event source, for Application Id, add the Application Id from the Alexa developer portal
  • copy the ARN value from the very top of the screen.
  • login back to the Alexa console and select "configuration"
  • Paste the ARN value from your Lambda into the "Lambda ARN" Field
  • Fill out OAUTH2 information (from your oauth server or the Amazon Login service. See this post for step-by-step instructions for Login with Amazon.)
  • MAKE SURE YOU HAVE VALID SSL CERTS AND CERT CHAINS!!!! I highly recommend using Lets Encrypt.

Item configuration

  • openHAB 2

    • Items are exposed via Homekit tags, the following is taken from the homekit binding in openHAB2:
    Switch KitchenLights "Kitchen Lights" <light> (gKitchen) [ "Lighting" ]
    Dimmer BedroomLights "Bedroom Lights" <light> (gBedroom) [ "Lighting" ]
    Number BedroomTemperature "Bedroom Temperature" (gBedroom) [ "CurrentTemperature" ]
    Group gDownstairsThermostat "Downstairs Thermostat" (gFF) [ "Thermostat" ]
    Number DownstairsThermostatCurrentTemp "Downstairs Thermostat Current Temperature" (gDownstairsThermostat) [ "CurrentTemperature" ]
    Number DownstairsThermostatTargetTemperature "Downstairs Thermostat Target Temperature" (gDownstairsThermostat) [ "TargetTemperature" ]
    String DownstairsThermostatHeatingCoolingMode "Downstairs Thermostat Heating/Cooling Mode" (gDownstairsThermostat) [ "homekit:HeatingCooling
    
    • By default all temperatures are in Celsius, for Fahrenheit add the tag temperatureFormat:fahrenheit to the thermostat group item (which should also be tagged with Thermostat)
    • In addition you can tag Rollershutter items by [ "Switchable" ] and get support for setPercentage, incrementPercentageand decrementPercentage commands. Example:
    Rollershutter Shutter_GF_Kitchen "Rollershutter Kitchen" [ "Switchable" ]
    
    • With commands like Alexa, set rollershutter kitchen to 100% you control the rollershutter in the kitchen.
    • If your rollershutters or blinds happen not to support aperture by percentage the following rule helps to achieve opening and closing:
    rule Rollershutter_Kitchen
    when
        Item Shutter_GF_Kitchen received command
    then
        if (receivedCommand < 50) { // in germany alexa often recognizes "0" as "9"
          sendCommand(Shutter_GF_Kitchen, UP)
        } else {
          sendCommand(Shutter_GF_Kitchen, DOWN)
        }
    end
    

Example Voice Commands

Here are some example voice commands:

  • Alexa turn on Office Lights
  • Alexa turn off Pool Waterfall
  • Alexa turn on House Fan
  • Alexa turn on Home Theater Scene
  • Alexa dim Kitchen Lights to 30 percent
  • Alexa set house temperature to 70 degrees