Amazon Alexa Smart Home skill for openHAB 2

This is a nodejs / lambda application that connects the Alexa Smart Home API 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"

General Deployment Instructions

Intended Audience

This document describes how to configure and deploy the skill for development or private hosting purposes and it targeted towards developers and not end users of the skill

Skill Usage

For end-user documentation and general usage, see the Usage page for examples and instructions on configuring items for Alexa within openHAB.

Requirements

Alexa Skills Kit CLI with Amazon AWS and Developer Accounts

You need an AWS account and an Amazon developer account to create an Alexa Skill.

In order to use the ASK CLI features to automatically deploy and manage your Lambda skill, ensure that you have AWS credentials set up with the appropriate permissions on the computer you are installing ASK CLI, as described in this documentation.

Once you have installed ASK CLI, you need to initialize it:

$ ask init

By default, the ASK CLI deploys the lambda function in the us-east-1 region. If you want to change the default region to one closer to your location, you need to create/update your AWS general configuration file in your home directory.

$ cat ~/.aws/config
[default]
region=us-east-1
output=json

OAuth2 Provider

If you aren't using your own OAuth2 server (e.g. private openHAB Cloud Connector), it is highly recommended to use Login with Amazon. See this post to set it up for your private skill.

openHAB Server

The openHAB server you are trying to control with the skill needs to be accessible online as an AWS service endpoint. You can either use myopenHAB.org cloud service or point the skill directly to your server URL. If going with the latter, make sure to use a valid SSL certificate. It is highly recommended to use Let's Encrypt to validate your certificates.

To configure the server path and credentials, you will need to setup the application configuration in lambda/smarthome/config.js using the sample file. The app can access an openHAB installation using two different types of authorization, basic authentication (user/password) or with bearer authentication (OAuth2 token). Uncomment the "userpass" property for basic authentication, otherwise a bearer token will be used.

Deployment Steps

Create Smart Home Skill and Lambda Function

1. Clone or download this repository:

   $ git clone https://github.com/openhab/openhab-alexa.git
   

2. Deploy the skill and the lambda function in one step:

   $ ask deploy
   Profile for the deployment: [default]
   -------------------- Update Skill Project --------------------
   Skill Id: <skillId>
   Skill deployment finished.
   [Warn]: No runtime and handler settings found for alexaUsage "smartHome/default" when creating Lambda function. CLI will use "nodejs8.10" and "index.handler" as the Runtime and Handler to create Lambda. You can update the runtime and handler for the target Lambda in the project config and deploy again if you want to set differently.
   Lambda deployment finished.
   Lambda function(s) created:
     [Lambda ARN] <lambdaArn>
   [Info]: No in-skill product to be deployed.
   [Warn]: Skill api domain "smartHome" can not be enabled. Skipping the enablement.
   

3. Setup skill account linking using the skill id displayed in previous step and your OAuth2 provider configuration:

   $ ask api create-account-linking -s <skillId>
   ? Authorization URL:  https://www.amazon.com/ap/oa
   ? Client ID:  <clientId>
   ? Scopes(separate by comma):  profile
   ? Domains(separate by comma):
   ? Authorization Grant Type:  AUTH_CODE
   ? Access Token URI:  https://api.amazon.com/auth/o2/token
   ? Client Secret:  [hidden]
   ? Client Authentication Scheme:  HTTP_BASIC
   ? Optional* Default Access Token Expiration Time In Seconds:
   ? Optional* Reciprocal Access Token Url:
   Account linking created successfully.
   

4. Enable skill with account linking:

   • Go to your Alexa skill console
   • Click on the "openHAB" skill under the "Dev Skills" tab
   • Click "Enable" and go through the account linking process

Update Smart Home Skill and Lambda Function

1. Update the repository to latest commit:

   $ git pull
   

2. If updating from v2 version:

   1. Copy relevant settings from config.js (v2) to lambda/smarthome/config.js (v3).

   2. Add current skill id to ask config by using the skill id listed under your Alexa developer console.

      $ cat .ask/config
      {
        "deploy_settings": {
          "default": {
            "skill_id": "<skillId>",
            "was_cloned": false,
            "merge": {}
          }
        }
      }
      

3. Deploy the skill and the lambda function in one step:

   $ ask deploy [--force] (Force deployment if lambda manual configs were applied)
   Profile for the deployment: [default]
   -------------------- Update Skill Project --------------------
   Skill Id: <skillId>
   Skill deployment finished.
   Lambda deployment finished.
   Lambda function(s) updated:
     [Lambda ARN] <lambdaArn>
   [Info]: No in-skill product to be deployed.
   [Warn]: Skill api domain "smartHome" can not be enabled. Skipping the enablement.