miloshdrown / haaska

Home Assistant Alexa Skill Adapter

haaska: Home Assistant Alexa Skill Adapter

haaska implements a skill adapter to bridge a Home Assistant instance and the Alexa Lighting API. In short, this allows you to control lights, switches, and scenes exposed by your Home Assistant instance using an Amazon Echo.

Examples:

• "Alexa, set kitchen to twenty percent"
• "Alexa, turn on evening scene"
• "Alexa, turn off bedroom light"

Setup

Lighting skill adapters must run on AWS Lambda, and the initial setup is unfortunately a manual process. @jbags81 wrote a tutorial that more thoroughly documents the setup process.

1. Create an AWS Lambda function using these instructions. Name the function ha-bridge and specify the handler as haaska.event_handler.

2. Follow the rest of the Lighting API provisioning steps. Note that the Lighting Skill API requires the use of OAuth; you can use Login with Amazon for this purpose; haaska does not currently perform any authentication.

   NOTE: Amazon appears to be temporarily rejecting new applications for provisioning:

   Thanks for your interest in building a skill using the Alexa Smart Home API. We are making this process simpler via a self service development portal for the Alexa Smart Home, at which point you will be able to build, test, and submit your skill for certification. In an effort to avoid rework for you to re-create your skill, we will ask for your patience as we complete this in April.

3. In the config/ directory, create a config.json file. This file must contain a single object with an ha_url key for the API endpoint of your Home Assistant instance, and ha_passwd key for the its API password. If you're using HTTPS with a self-signed certificate, put the CA certificate in the config/ directory and add a ha_cert key with the certificate's filename.

4. Run make to generate build.zip, which you can then manually upload to AWS Lambda. Alternatively, if you have the AWS CLI configured correctly, run make deploy to deploy to AWS Lambda.

5. Send a test event in AWS with:

{
  "header": {
    "payloadVersion": "1",
    "namespace": "Control",
    "name": "DiscoverAppliancesRequest"
  },
  "payload": {
      "accessToken": "whatever"
  }
}

Or, if you have the AWS CLI and jq installed, you can run make test, which will validate that haaska can communicate with your Home Assistant instance.

Customization

Sometimes the "friendly name" of an entity in Home Assistant differs from what you'd actually like to call that entity when talking to Alexa. haaska provides a mechanism to define a custom name for an entity that will be used via Alexa. This is achieved by adding your entity to a customize block in your configuration.yaml, and setting the haaska_name key to the desired name.

customize:
  light.some_long_light_name:
    haaska_name: Overhead

If there's an entity you'd like to hide from haaska, you can do that by adding a haaska_hidden tag and setting it to true; e.g.:

customize:
  switch.a_switch:
    haaska_hidden: true