Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
103 lines (73 sloc) 5.27 KB

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. There was work done to support openHAB 1.x (see oh1.js) but this is not currently working as there is no tagging mechanism in openHAB 1 and would require either overloading item names or overloading the sitemap concept to infer Alexa device types which did not seem desirable.

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