UPDATED Amazon Echo X10 Home Control

In my original post last August I detailed how I was able to control my X10 equipment with an Amazon Echo.  Now with the release of BWS Systems’ ha-bridge version 2.0.0+ we can make script calls! This is awesome news, I no longer need an Apache server and PHP installed on my RPi to make the exec() commands to call the HEYU scripts, I can make them from the ha-bridge. I’ll show you how.

It should be noted that you will need a physical Amazon Echo, Dot, Tap or Google Home to discover your ha-bridge devices. Discovering devices with just a Fire TV or Fire Stick with voice remote will not be successful. However, after discovery by an Echo or Dot, you will be able to use the Fire TV with voice remote to control your discovered devices.


If you use the ha-bridge, I urge you to Donate to BWS Systems (Donate link at bottom), the ha-bridge is distributed freely and continuously updated.


Step 1 – Raspberry Pi goodness?

RPiThe first step is to get your Raspberry Pi up and running. There are plenty of guides how to download and install either NOOBS, or RASPBIAN on a memory card for your RPi, so I won’t go into those details unnecessarily. Suffice it to say, you’ll need to have your RPi booted into Raspbian and configured to your location and language, including SSH enabled.

Once you have the RPi working you can SSH (remote) into it and log in as the user Pi. For PC you can use PUTTY, or MAC use the Terminal Window to SSH into the Pi. At this point I would also recommend you update and upgrade your RPi, by entering the following:

  • $ sudo apt-get update
  • $ sudo apt-get upgrade

I also recommend changing the default password.

Once updated and upgraded, power down your RPi, and make all the following connections:

  • Install batteries into the CM11A
  • Plug the control cable into the CM11A jack
  • Connect the Serial Adapter to the X10 CM11A’s serial cable
  • Plug the CM11A into a wall socket
  • Plug the USB to Serial Adapter into the RPi

In my original post I detail the parts I used, but I recommend USB TO RS-232 DB9 Serial Adapter = $15 Plugable brand – don’t go cheap here.

Power your RPi back on, and SSH back into it.

Step 2 – Heyu turn on my lights!

Let’s install heyu, which is a text-based console program for remotely controlling lights and appliances in the home or office. I put heyu in a directory I created named ‘src’.

Here are the steps I completed:

  • $ ls -l /dev/ttyUSB0
  • You should get something like the following:
    crw-rw---T 1 root dialout 188, 0 Aug 10 20:44 /dev/ttyUSB0
    Make note* of the last part, you’ll need it later.
  • $ mkdir src
  • $ cd src/
  • $ wget https://github.com/HeyuX10Automation/heyu/archive/v2.11-rc2.tar.gz
    (Or current version)
  • $ tar xfvz v2.11-rc2.tar.gz
  • $ cd heyu-2.11-rc2/
  • $ sh ./Configure.sh

The installer will run, make a cup of coffee.

  • $ make

More installation, drink the coffee you made.

  • $ sudo make install

You should then see the following:

I did not find a Heyu configuration file.
Where would you like the sample Heyu configuration file installed?
1. In directory /home/pi/.heyu/
2. In subdirectory .heyu/ under a different user home directory
3. In directory /etc/heyu (for system-wide access)
4. No thanks, I'll take care of it myself
Choice [1, 2, 3, 4] ?

Enter 3 for system wide access, and you’ll see:

Creating directory /etc/heyu
The sample configuration file will be installed as /etc/heyu/x10config

The next question the program will ask is the following:

I will add the TTY port for your CM11 to the config file
Specify /dev/ttyS0, /dev/ttyS1, etc., or the word dummy
To which port is the CM11 attached?

Enter /dev/ttyUSB0 (or whatever you noted* earlier).

Next we need to make the /etc/heyu directory writable:

  • $ sudo chmod -R 777 /etc/heyu

Now you can test the install, enter $ heyu info, and you should get an output with details about the heyu install that look similar to the following:

Heyu version 2.11-rc1
Configuration at /etc/heyu/x10config
Powerline interface on /dev/ttyUSB0
Firmware revision Level = 1
Interface battery usage = 0:00 (hh:mm)
Raw interface clock: Sat, Day 212, 14:07:35
(--> Civil Time: Sat 01 Aug 2015 15:07:35 EDT)
Uploaded schedule will expire in 154 days.
Housecode = M
0 = off, 1 = on, unit 16.......8...4..1
Last addressed device = 0x0002 (0000000000010000)
Status of monitored devices = 0x0042 (0000000000010001)
Status of dimmed devices = 0x1112 (1110000000010000)

Now let’s test to see that you can turn a light on and off. My housecode is M, but use your chosen housecode. Try the following: $ heyu on M2 and the module set to M2 should turn on, alternatively $ heyu off M2 and the module set to M2 should turn off.

You can configure your setup and upload schedules to your CM11A.

Step 3 – Hue talking to me?

X10 does not ‘interface’ with any technology that the Amazon Echo can control.  Crush from BWS Systems forked and created the ha-bridge.  It is a Phillips Hue emulator that runs as a java file (.jar) so it can be run on virtually any device.  The Amazon Echo will discover the emulator as a Phillips Hue bridge, and discover the configured devices.  When asked, the Echo will call the configured ON,OFF or DIM URL for each discovered device, this can now be script calls brilliant!  I can make the HEYU calls directly from the bridge.

The following steps download and get the bridge to run on the RPi:

Navigate to your root directory:

  • $ cd

Make a new directory named habridge:

  • $ mkdir habridge

Then navigate to the habridge directory:

  • $ cd habridge

Now download the latest JAR into the directory, you can get the latest here:

  • $ wget https://github.com/bwssytems/ha-bridge/releases/download/v4.2.1/ha-bridge-4.2.1.jar

Then rename the jar file to something ‘generic’ so we don’t have to keep changing the auto-start script when we download a new version:

  • $ mv ha-bridge-4.2.1.jar ha-bridge.jar

Now we want the ha-bridge to auto-run after reboot on your RPi, you will need to get it added into a startup script. Let’s do that now, enter the following command:

  • $ nano starthabridge.sh

Add the following to this file:
cd /home/pi/habridge
rm /home/pi/habridge/habridge-log.txt
nohup java -jar /home/pi/habridge/ha-bridge.jar > /home/pi/habridge/habridge-log.txt 2>&1 &
chmod 777 /home/pi/habridge/habridge-log.txt

Press CTRL + X, select to save the file. Then execute the following commands:

  • $ chmod u+x starthabridge.sh
  • $ sudo passwd root

Enter your RPi password (it asks twice). Next we’ll change to superuser to finish our install and autostart:

  • $ su -

It will ask you for the root password that you just created in the previous step. Enter it.
Your terminal will now switch to root@raspberrypi, enter the following commands:

  • # sudo su
  • # touch /etc/systemd/system/habridge.service
  • # chmod 664 /etc/systemd/system/habridge.service
  • # cd /etc/systemd/system/
  • # nano habridge.service

Add the following to this new file:
Description=HA Bridge
ExecStart=/usr/bin/java -jar -Dconfig.file=/home/pi/habridge/data/habridge.config /home/pi/habridge/ha-bridge.jar

Press CTRL + X, select to save the file. Then execute the following commands:

  • # systemctl daemon-reload
  • # systemctl start habridge.service
  • # systemctl enable habridge

The service should have now started and will start every time you plug in or reboot your RPi. If you want to check the status of the service type:

  • # systemctl status habridge.service -l

To return to normal user and leave superuser, enter the following command:

  • # cd
  • # exit

Once you’ve got the bridge running, add discoverable devices. The bridge comes with a configurator to make adding and editing devices a snap. As of release 3.2.0, the default HTTP port for the bridge is 80, to navigate to it I enter my RPi’s IP address in a modern browser (like Chrome, not MS EDGE):


Note: Now that the default HTTP port is 80, the “:80” portion is NOT required, this is the default HTTP port. Prior releases 3.1.0 and older use the default HTTP port of 8080.


The bridge supports dim commands from the Echo. The bridge returns three variable options, they are: ${intensity.percent} (for 1-100), ${intensity.byte} (for 0-255) or ${intensity.math} (for 0-255). By saying, “Alexa, dim the kitchen lights to 50%” that percentage will be passed in the ‘Dim URL’.  I’ve chosen to use ${intensity.math}, with X10 the dimming gets a bit tricky since X10 dim/bright is from 1 to 22. The ${intensity.math} allows me to manipulate the returned variable to fit my X10 needs, namely using ${intensity.math(((X*-22)/255)+22)} will get me the correct output.

Enter the Name of your new device, the On URL and the Off URL, and click Add Device. For my example device of M2, I would enter the following:

  • Name: kitchen
  • Device Type (Informational): Execute Script/Program
  • Map Type (Legacy): Execute Command/Script/Program
  • On Items:
    • Type: Execute Command/Script/Program
    • Target Item: heyu on M2

    Click the green “Add” button to the right.

  • Dim Items:
    • Type: Execute Command/Script/Program
    • Target Item: heyu dimb M2 ${intensity.math(((X*-22)/255)+22)}

    Click the green “Add” button to the right.
    (See Notes below…)

  • Off Items:
    • Type: Execute Command/Script/Program
    • Target Item: heyu off M2

    Click the green “Add” button to the right.

Click the ‘Add Bridge Device’ button. That’s it, you configured your first device.  Add all your devices.

Note 1: I chose to use dimb, this turns the X10 module on first then dims to the requested level. The dimb command more closely follows how Philips HUE dim commands will work with Alexa, since successive X10 dim commands will progressively dim the module to maximum dim level. Philips HUE devices will go dim or bridge to the reach the requested dim level rather than successively getting dimmer, hence the usage of the dimb command in my example.
Note 2: If using the X20 wall switch WS467 I suggest using obdim because these switches have a last dim level memory.

Step 4 – Alexa take control!

alexaOnce you have a device(s) configured, it’s time to tell your Amazon Echo to discover your devices.  Simply say, “Alexa, discover my devices”, she will go into discovery mode (approx. 20 second), and find the devices you’ve configured above.  Of note, you can manage the devices the Echo has discovered by visiting: http://echo.amazon.com going to ‘Settings’ -> ‘Smart Home’, or directly at http://echo.amazon.com/#smart-home.  This can be helpful if you remove or rename a device on your Hue Bridge Emulator.

Once discovered, the fun can begin, ask Alexa to turn your lights on and off!  For me house code M2 is my kitchen.  So I can say, “Alexa, turn on the kitchen”, and viola they turn on.

Step 5 – Easy ha-bridge version updates?

So, how do you update the ha-bridge jar file when a new release comes out? I’ll show you, replace the {version} text below with the version you wish to download.
Navigate to the ha-bridge folder:
$ cd habridge
Halt the ha-bridge systemctl service:
$ sudo systemctl stop habridge
Download the latest ha-bridge from github:
$ wget https://github.com/bwssytems/ha-bridge/releases/download/{version}/ha-bridge-{version}.jar
Rename the current ha-bridge file for reference:
$ mv ha-bridge.jar ha-bridge_LAST.jar
Rename the one you downloaded to the generic “ha-bridge.jar”:
$ mv ha-bridge-{version}.jar ha-bridge.jar
Restart the ha-bridge systemctl service:
$ sudo systemctl start habridge


Below I’ll compile information discovered along the way.

  • If you already have a real Phillips Hue bridge, you have to disconnect it first before searching for devices. – (Thanks Mitch)
  • If most of your X10 stuff is setup to run off radio, you can install a CM17A inline with the CM11a. – (Thanks Mitch)
  • The X10 “All lights on” command is: heyu lightson – (Thanks Mitch)
  • If your RPi is on WiFi, you’ll need to have Alexa and the Pi on the same wifi SID. This was essential. These days almost everyone uses WPA2 with AES so you need to reconfigure raspbian a bit ( https://coderwall.com/p/v290ta/raspberry-pi-wifi-setup-with-wpa2-psk-aes ). – (Thanks Elmer)
  • Java 8 is required for the ha-bridge to run. To check your Java version type $ java -version if it is not JAVA 8, then enter the following command $ sudo apt-get install oracle-java8-jdk. If you are getting “Unsupported major.minor version” error messages, then enter $ sudo update-alternatives --config javac and $ sudo update-alternatives --config java. This will set your RPi to use Java 8 globally. – (Thanks Max)
  • To control multiple modules (m1, m3, m4, m8, m10 & m16 for example) with one command, create the On and Off URLs just like any other module On/Off, but use this format for the house unit portion of the URL: heyu on m1,3,4,9,10,16. This will act on each device from one command. Also if you have units in succession, like m3, m4, m5 & m6 it can be expressed as m3-6. – (Thanks Frank)
  • Using the Raspberry Pi with a Firecracker CM17A is possible. HEYU is Firecracker compatible, you need to use the HEYU Firecracker “f” command construct. The ‘turn’ command also supports the CM17A commands fon, foff, fdim, fbright, flightson, flightsoff, falloff, and the applicable “fast” implementations of these commands. William reports, “I installed between the cm11 and the usb/serial interface, plugged in a receiver module tuned to appropriate house code and transmits a much stronger signal over the powerline. I had to change the scripts in the HA Bridge from “heyu on A1” to “heyu fon A1” or off to foff to activate the firecracker and viola it works.” (Thanks William)

I wrote a complimentary Bridge Control interface coded in PHP, that post is here.  It allows you to control all your configured ha-bridge devices on any PC, tablet or phone connected to your home’s internet.

566 thoughts on “UPDATED Amazon Echo X10 Home Control

  1. Hi Corey,
    I can’t get past this error message:
    root@raspberrypi:/etc/systemd/system# systemctl daemon-reload
    root@raspberrypi:/etc/systemd/system# systemctl start habridge.service
    Failed to start habridge.service: Unit habridge.service failed to load: Bad message. See system logs and ‘systemctl status habridge.service’ for details.
    root@raspberrypi:/etc/systemd/system# systemctl enable habridge
    Failed to execute operation: Bad message
    root@raspberrypi:/etc/systemd/system# nano habridge.service
    root@raspberrypi:/etc/systemd/system# systemctl daemon-reload
    root@raspberrypi:/etc/systemd/system# systemctl start habridge.service
    Failed to start habridge.service: Unit habridge.service failed to load: Bad message. See system logs and ‘systemctl status habridge.service’ for details.
    root@raspberrypi:/etc/systemd/system# systemctl daemon-reload
    root@raspberrypi:/etc/systemd/system# systemctl start habridge.service
    Failed to start habridge.service: Unit habridge.service failed to load: Bad message. See system logs and ‘systemctl status habridge.service’ for details.
    I have tried all versions of NOOBS going back to 2.0.0, but still cannot get past this error. I am following your directions perfectly. Can you tell me what I am doing incorrectly?

    1. Systemctl is not accepting the new habridge.service file you are creating.

      So you are loading Raspbian from NOOBS rather than an image correct?

      Be sure you are running a full version of Raspbian, not the LITE version. What do you get from this command, $ cat /etc/os-release. It might be best to flash a memory card with the latest Raspbian Jessie image with PIXEL.

      The “habridge.service” file you are creating, how many lines is it, including the blank lines? It should be 11 lines of code. The “ExecStart=/usr/bin/java -jar -Dconfig.file=/home/pi/habridge/data/habridge.config -Djava.net.preferIPv4Stack=true /home/pi/habridge/ha-bridge.jar” should be in one line.

      Can you check the System Logs as suggested by the error “See system logs and ‘systemctl status habridge.service’ for details.”, found in “/var/log/”?

  2. Hi Corey,

    I am still getting the same “bad message, failed to load” response after flashing Raspbian Jessie with PIXEL.

    The habridge.service file is the one downloaded from your instructions:

    Description=HA Bridge
    ExecStart=/usr/bin/java -jar -Dconfig.file=/home/pi/habridge/data/habridge.config -Djava.net.preferIPv4Stack=true /home/pi/habridge/ha-bridge.jar

    Sadly, I don’t know how to access the System Logs to get to /var/log/.

    Thanks for your help.


      1. Hi Corey,
        I’m making progress, but when I get to step 5, I get this error:
        root@raspberrypi:~/habridge# wget https://github.com/bwssytems/ha-bridge/releases/download/{version}/ha-bridge-{version}.jar
        –2017-05-13 23:21:33– https://github.com/bwssytems/ha-bridge/releases/download/%7Bversion%7D/ha-bridge-%7Bversion%7D.jar
        Resolving github.com (github.com)…,
        Connecting to github.com (github.com)||:443… connected.
        HTTP request sent, awaiting response… 404 Not Found
        2017-05-13 23:21:33 ERROR 404: Not Found.
        Any suggestions?

        1. You need to replace the text {version} with numbers, like 4.5.0, which is the current version.

          1. Hi Corey,
            I’m happy to say that I now can control my switches via Alexa. The problems I had were solved when I plugged the CM11A into a wall socket instead of the strip was using. D’Oh!
            I should have paid more close attention to your directions.
            I still needed to download the habridge.service file from the git.hub as you suggested.
            I hope this will help someone else in the future.
            Many, many thanks for your expertise.

            1. Hi Corey,
              My system stopped working, so I restarted from scratch, but now I get this problem:
              root@raspberrypi:/etc/systemd/system# systemctl start habridge.service
              Failed to start habridge.service: Unit habridge.service failed to load: Bad message. See system logs and ‘systemctl status habridge.service’ for details.
              root@raspberrypi:/etc/systemd/system# systemctl status habridge.service
              ● habridge.service – HA Bridge
              Loaded: error (Reason: Bad message)
              Active: inactive (dead)

              Jun 14 09:14:39 raspberrypi systemd[1]: [/etc/systemd/system/habridge.servic….
              Jun 14 09:15:26 raspberrypi systemd[1]: [/etc/systemd/system/habridge.servic….
              Hint: Some lines were ellipsized, use -l to show in full.
              root@raspberrypi:/etc/systemd/system# systemctl status habridge.service -l
              ● habridge.service – HA Bridge
              Loaded: error (Reason: Bad message)
              Active: inactive (dead)

              Jun 14 09:14:39 raspberrypi systemd[1]: [/etc/systemd/system/habridge.service:5] Missing ‘=’.
              Jun 14 09:15:26 raspberrypi systemd[1]: [/etc/systemd/system/habridge.service:5] Missing ‘=’.
              Jun 14 09:16:05 raspberrypi systemd[1]: [/etc/systemd/system/habridge.service:5] Missing ‘=’.

              I would appreciate your help again.

            2. Make sure there are only 3 lines of code in the [Service] portion of the habridge.service file you are creating:

              1) “Type=…”
              2) “WorkingDirectory=…”
              3) “ExecStart=…”

              It would seem you copied a word-wrapped example and the “Dconfig.file=…” is on a 4th line.

  3. Hey Corey

    Everything had been working fine until i got a new router. I made sure the UPnP was enabled and here is what is happening now. my pi is at i can control my lights on the HA Bridge, with the test on test off. When i ask Alexa to discover she does not find the devices, when i go to the Alexa app the devices are discovered but they show as the name of the device that was entered on HA Bridge with (offline) showing next to the name and under the description shows Lux Light. Any thoughts on what it might be? thanks again for all you do. Stu

    1. Make sure your RPi’s IP address is correct in the ha-bridge’s Bridge Control settings page.

      If the IP address is entered properly are you able to have the devices discovered by the Echo.

      Have you recently updated the ha-bridge from an older v3 version? The numbering of the devices changed with version v4+.

      You might try a Forget All Devices and rediscover.

  4. Corey,

    I am using version 4.2.1 and after my Echo discovered the devices they show up as Lux devices. Is there something else that I need to do to make the show up a Hue devices?

    1. Hey Dean,

      This is how they should appear in your Alexa’s Smart Home list. “Lux” is the line of the older variant of the Philips Hue family of non-color changing smart bulbs, and this is how the ha-bridge reports them to Alexa when discovered.

    2. Thanks. It does work with my Echo. Also, have you tested this HA-Bridge with OpenRemote? They have connectivity instructions for Philips Hue bridges and I was wondering if they work the same on HA-Bridge.

      1. OpenRemote should be able to discover the ha-bridge as if it were a real Hue Bridge. I have not tested it with ha-bridge. I used to use OpenRemote 3 to 4 years ago. I created an elaborate set of rooms with pictures that would toggle when you touched the images, very powerful software.

  5. I’ve got this up and running using your older instructions. What is the advantage to using this newer setup. I know it eliminate the need for Apache and PHP, but was is the real world effect of that? Does it run quicker, more reliably?

    1. It is a bit faster with the newer version of the ha-bridge, by a fraction of a second. But this is only because the PHP relay part is removed. The ha-bridge now calls the HEYU command directly. So if you are happy with your current setup and response time, then there is no need to upgrade.

      The new version does makes the whole install easier, and eases the HEYU permissions issues, for initial install, but you are past that as well.

      I will say the new ha-bridge does have a ton of new features, you can check it out and see if it provides features you’de be interested in.

  6. HI Corey,
    Please ignore my last request. I was able to fix my errors by going to GitHub and downloading the habridge.service file from there (as you suggested before). Thanks again.

  7. I new to Rasberry PI.
    Will this method work with CM15A interface?

    How do I identify the correct model Rasberry Pi to purchase?

    1. I would recommend at least a Raspberry Pi B+ or newer (Model 3), but it will run on any RPi. The RPi ZERO however is not well suited due to it’s micro USB only port.

      No it will not work with the CM15A interface. HEYU only works with a CM11A or Firecracker. Others have used MOCHAD in place of HEYU with the CM15A.

Leave a Reply

Your email address will not be published. Required fields are marked *