The Amazon Echo is an impressive piece of technology hamstrung by it's shallow feature set and half-assed app store. The language recognition is a very powerful tool, but it's wasted on "skills" that do simple things like reading the weather forecast or telling dad-jokes. To be fair, the newer models now have Zigbee controllers, but for me, the whole point of Home Assistant was to break away from cloud-based smart hubs.

This is why I was excited to stumble across the haaska project which has given Alexa new life in my home. Haaska has effectively turned my Echo Dot into a voice controller for my HA instance. I now get the best of both worlds – Amazon's voice recognition for issuing commands, and home assistant for carrying out the orders.

Alexa Routine to send the robot vacuum to the trash can (when it's time to empty the dust bin)

Haaska Setup

To set up haaska for the first time, follow the guide in the official wiki. The setup is very tedious and you must follow the steps very precisely, or it will not work. Note that the steps in the wiki differ slightly from the steps shown on the official HA documentation. Which steps you follow is up to you, but I had an easier time with the developer's guide.

Haaska is a python script which serves as a bridge between Home Assistant and Alexa. The setup involves creating an AWS Lambda to run the python script as an event-driven web service. The script runs on Amazon's cloud and it handles all of the device discovery and API commands.

AWS is free to use up to a certain amount of throughput. Haaska is unlikely to hit that limit for most users.

Device Discovery

The final step in the wiki is to test haaska by running a test script to simulate device discovery. This is a good opportunity to peek under the hood and see how the device discovery API works. Once you get a successful test, take a moment to look at the logs.

Haaska test logs

The logs show exactly what HA responds with when you initiate a device discovery from the Alexa app. If you scroll through the logs, you should recognize all of the entities from your HA instance. This includes lights, switches, sensors, scripts, automations, pretty much everything is exposed by default.

Component Configuration

At this point, you could go into your Alexa app and start discovering new devices. However, unless you have a very simple HA setup, you will definitely want to limit which entities are exposed to Alexa. If you don't, you will end up with a bunch of junk in your device list and Alexa will confuse which devices you are asking for. In my experience, you are much better off enabling devices one-at-a-time using your HA configuration.

Tip: If you cluttered up your device list and want to start over, you can forget all devices but only through the web portal. Log in, go to Smart Home > Devices > Forget All (at the bottom of the device list).

# Sample Configuration
alexa:
  smart_home:
    filter:
      include_entities:
        - light.kitchen_light
        - switch.air_purifier
        - climate.thermostat
        - script.dim_bedroom_lights
    entity_config:
      light.kitchen_light:
        name: Kitchen Light
        description: Overhead light in kitchen
        display_categories: LIGHT
      switch.air_purifier:
        name: Air Purifier
        description: Turn on/off the air purifier
        display_categories: SMARTPLUG
      climate.thermostat:
        name: Thermostat
        description: Set the desired temperature
        display_categories: THERMOSTAT
      script.dim_bedroom_lights:
        name: Dim Bedroom Lights
        description: Dim the lights in the bedroom
        display_categories: ACTIVITY_TRIGGER

The example above is a white-list of devices which will be exposed by HA when Alexa issues a request to discover devices. The entity_config property lets you tag each device with metadata to define how that device appears and behaves in the Alexa app. The name and description appear in the device info screen, and the display_categories tells Alexa what type of device she's dealing with.

HA does a fairly good job of supplying the right device category by default, but I found that it's better to explicitly define it in the configuration. HA for example won't differentiate between different switch types, like smart plugs vs. wall switches. If you define your smart plug as a SMARTPLUG, then it will show up in the Plugs category in the app and it will look like a little plug in the UI with on/off controls. On the other hand, if you define a LIGHT, it will look like a lightbulb and give you options to adjust the brightness. The category also extends to the available voice commands (you can ask Alexa to set the brightness of a Light, but not a Plug).

Here is a list of known display categories from the Alexa docs.

Value Description
ACTIVITY_TRIGGER A combination of devices set to a specific state. Use activity triggers for scenes when the state changes must occur in a specific order. For example, for a scene named "watch Netflix" you might power on the TV first, and then set the input to HDMI1.
CAMERA A media device with video or photo functionality.
CONTACT_SENSOR An endpoint that detects and reports changes in contact between two surfaces.
DOOR A door.
DOORBELL A doorbell.
FAN A fan.
LIGHT A light source or fixture.
MICROWAVE A microwave oven.
MOTION_SENSOR An endpoint that detects and reports movement in an area.
OTHER An endpoint that can't be described by one of the other categories.
SCENE_TRIGGER A combination of devices set to a specific state. Use scene triggers for scenes when the order of the state change is not important. For example, for a scene named "bedtime" you might turn off the lights and lower the thermostat, in any order.
SECURITY_PANEL A security panel.
SMARTLOCK An endpoint that locks.
SMARTPLUG A module that is plugged into an existing electrical outlet, and then has a device plugged into it. For example, a user can plug a smart plug into an outlet, and then plug a lamp into the smart plug. A smart plug can control a variety of devices.
SPEAKER A speaker or speaker system.
SWITCH A switch wired directly to the electrical system. A switch can control a variety of devices.
TEMPERATURE_SENSOR An endpoint that reports temperature, but does not control it. The temperature data of the endpoint is not shown in the Alexa app.
THERMOSTAT An endpoint that controls temperature, stand-alone air conditioners, or heaters with direct temperature control.
TV A television.

Once you have defined the devices you want Alexa to see, go into the app and choose Add Device from the hamburger menu. Scroll to the bottom and click Other, then Discover Devices. After a few moments, Alexa should find all of your white-listed devices and categorize them according to the display categories.

Discovered device categories

At this point, you can use the app to control your devices or you can say "Alexa, turn on the [device name]". The device category will determine what kinds of voice commands you can use.

Routines

As you expose more entities to Alexa, you will eventually find that the voice commands aren't always perfect. For example if you expose your garage door as a DOOR device, you would think you could say "Alexa, open the garage door." But that won't work. Alexa sees most HA entities as a binary switch with on/off states. As it turns out, if you say "Alexa, turn on the garage door" then she will understand to open the garage. This problem holds true for other complex entities like HA scripts.

The easiest way to fix this problem is by creating routines. A Routine is similar to an Automation in Home Assistant where you define a trigger and tie it to an action. In the app, choose Routines from the hamburger menu. Tap the + add a new Routine. For your trigger, choose Voice and enter your custom "Alexa, ..." command. For your action, choose Smart Home, then find the device or scene you want to trigger. You can also add another action if you want to customize how Alexa responds to your command.

Here are some routines I have set up so far:

  • Alexa, open/close the garage door
  • Alexa, vacuum the house/specific room
  • Alexa, I'm leaving (turns off lights, TV, thermostat)
  • Alexa, dim the lights
  • Alexa,  turn on/off the air purifier

Conclusion

This post detailed how I set up Home Assistant with my old Echo Dot so that I can control anything with a voice command. Any HA entity can be exposed as a device, and any voice command can be wired up to trigger that entity. The AWS Lambda service has proven to be reliable, and very responsive. Amazon doesn't mess around with their web services. I now find myself using my Echo constantly, because it's so much easier than fiddling with my phone or walking to a light switch.

Thanks for reading!