Wednesday, November 09, 2016 REST API and Amazon Alexa Smart Home Skills

If you have an Amazon Echo with Alexa, and you make your own home automation devices, then you will no doubt want to interface the two together and have a powerful voice controlled home automation system.

Well, if you use OpenHAB then it's easy.

First follow the instructions to add to your existing working openhab controller -

Next, create an Alexa Smart Home Skill and link it to your Amazon account with LWA (Login.With.Amazon).

Alexa requires OAuth2.0 authentication with a service to function, but it was easier to link to LWA rather than try to work out the intricacies of, seeing as I know my credentials anyway.

After you have created an account with, follow the instructions here:

In the AWS lambda function.lambda_handler (I used python, but you can use JavaScript or Java too), for the event namespaces below:

    if event['header']['namespace'] == 'Alexa.ConnectedHome.Discovery':
        return handleDiscovery(context, event)

    elif event['header']['namespace'] == 'Alexa.ConnectedHome.Control':
        return handleControl(context, event)

You will write the handleDiscovery and handleControl methods and return the following:

    return { 'header': header,
             'payload': payload

Just define the header as shown in the example step-by-step skill adaptor example on the Amazon developer website and fill in your device details in the payload instead of the examples.

Now, the bit that you actually need to know.
How do you get the device details and states of your home automation devices through and how do you control those devices?

When you ask Alexa to 'Discover devices', your handleDiscovery method will be called.

To get a list of all OpenHAB devices, make a GET request to :


To get just a known devices details do:

To get just the state of a known device do:

This will return an XML response similar to this:


In the handleDiscovery method, find the items like "SwitchItem" in the XML and add them to the payload by name to build your list of devices that Alexa can control using ON/OFF commands.
Just look at the Amazon example code to see what the payload should look like.

Then, when you ask Alexa to turn something on or off, your handleControl method will be called.
This is where you send the ON or OFF to your device in openHAB.

Make a POST request to the device's specific URL:

In the POST body, put the plain text command ON or OFF
Make sure you set the Content-Type header to 'text/plain' or it won't work.

In the URLs, if your username or password has '@' or '.' characters in it, then be sure to escape them using %40 and %2E respectively, as mentioned in this wiki: 

Or, if you have issues with passing the credentials in the URL, then encode them as base64 and put them in the headers, like so in bold below:

Python example

import base64
post_data = "OFF"
post_header = { 'Content-Type' : 'text/plain' }
req = urllib2.Request(openhab_url, post_data, post_header)
base64string = base64.encodestring('%s:%s' % (username, password))[:-1]
req.add_header("Authorization", "Basic %s" % base64string)
response = urllib2.urlopen(req)

That's it.

No comments:

Post a Comment