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.1.4/ha-bridge-4.1.4.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.1.4.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 -Djava.net.preferIPv4Stack=true /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
  • Dim Items:
    • Type: Execute Command/Script/Program
    • Target Item: heyu obdim M2 ${intensity.math(((X*-22)/255)+22)}
  • Off Items:
    • Type: Execute Command/Script/Program
    • Target Item: heyu off M2

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

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.

463 thoughts on “UPDATED Amazon Echo X10 Home Control

  1. Corey – I know your posts have been up for a while, and many people have already praised you more eloquently than I can, but I had to add my own praise. I am very much indebted to you for your superb tutorial! I have been a home automation enthusiast since the early 1980s (yes! with some of my X10 equipment dating to the late 70s!). I have almost 100 X10 devices installed in my home so the cost of replacing it all with new technology was prohibitive. I did buy a few WeMo switches and enjoyed the integration with Alexa, so I searched until I found your articles on how to “Alexafy” X10. After numerous repairs to my decaying switches (the house/unit code internal metal fingers separate from the plastic dials over time), and with your Raspberry Pi interface, I now have a house that is (almost) equivalent to a new technology system, at very little additional cost. So this is a LONG way to say THANK YOU VERY MUCH. I appreciate your work and your detailed instructions. I’m an electrical/computer engineer but I followed your instructions to the letter and the system worked the FIRST TIME I booted it. Wow, I couldn’t be happier!

    1. Sam,

      I was in the same boat in July/August of 2015. I too am a long time X10 fan, bought an Echo and wanted to control my X10 with it. I searched the web with no great results. There were “to-do” list control options, but that was sloppy. I wanted native control. I originally found the amazon-echo-ha-bridge built by armzilla on Github that worked. It natively spoofed as a Philips HUE bridge. BWS Systems forked it making it lighter and feature packed. He and I have collaborated on it ever since, meaning, I ask for enhancements and he graciously supports them! LOL!!! Anyway, I wrote my tutorial because I wanted X10 fans, like yourself, to be able to control their gear with an Echo too.

      I have also written a Python script that updates the state of my X10 equipment in the ha-bridge, since I control my X10 with remotes, and schedules. This way they are in sync. I run this script on a cron job every 15 mins. I’ll post that soon.

  2. Corey,
    I wanted to install this process on another SD card and as I went through the process I believe I stumbled on an error in your updated instructions. This statement returns an error when executed “tar xfvz heyu-v2.11-rc2.tar.gz” as the name is not found. This modified statement “tar xfvz v2.11-rc2.tar.gz” worked fine and I was able to successfully complete the procedure on my second SD card.

Leave a Reply

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