Amazon Echo X10 Home Control

Updated version of this tutorial: Click Here!

Want to control your X10 home automation with your voice? I did, and now I am able to with: an Amazon Echo, a Raspberry Pi B+ (RPi), and an X10 controller and modules. I’ll detail how I went about accomplishing this feat. Let me also say that most of the ‘code’ behind this was written by some very talented people, so I can’t take much of the credit in that regard.

amazon_echo
I’ve estimated my total cost for this at $189 for everything. (This is the cost to control one light.) The break-down is as follows:

  • Amazon Echo = $99 (got in on the Prime pre-order)
  • Raspberry Pi B+ = $35 (for RPi, memory card & case)
  • USB TO RS-232 DB9 Serial Adapter = $15 (Plugable brand – don’t go cheap here)
  • X10 CM11A controller = $30 (NEW on Ebay, used can be cheaper)
  • X10 LM465 lamp module = $10 (NEW on Ebay, used can be cheaper)

Obviously, the more lights I control the more X10 modules I’d need. This works so well I now have 35 different lights I control in my home with X10 through the Echo. I’ve also recently purchased multiple X10 WS467 wall switch modules for $10 on Ebay. It allows me to control my kitchen pot lights etc with X10 or with the switch.

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

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 http://www.heyu.org/download/heyu-2.11-rc1.tar.gz
    (Or current version)
  • $ tar xfvz heyu-2.11-rc1.tar.gz
  • $ cd heyu-2.11-rc1/
  • $ 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 1 and you’ll see:

Creating directory /home/pi/.heyu
The sample configuration file will be installed as /home/pi/.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).

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 /home/pi/.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 – Are you being served?

Next we will install an Apache server and PHP5 on the RPi , here is what I did to accomplish that:

  • $ sudo apt-get install apache2 -y

After this install completes, you should be able to navigate to your RPi’s Apache server. Type the IP address of your RPi into any browser, for me it’s 192.168.1.19, and you should see an “It works!” page.

Let’s install PHP:

  • $ sudo apt-get install php5 libapache2-mod-php5 -y

The user that runs PHP exec commands on Apache installations is www-data. We’ll have to allow the www-data user permission to use the ttyUSB0 device (or what you noted* earlier in Step 2 as your USB to Serial Adapter device name). One way to do this is to modify the ttyUSB0 permissions on boot. NOTE: Due to security concerns, this should only be done on a Raspberry Pi that is not accessible from the internet!

  • $ sudo nano /etc/rc.local
  • Add chmod 666 /dev/ttyUSB0 & to the file on the line above the ‘exit 0’
  • Save and exit the file

We should also modify the ttyUSB0’s current permissions so we can move forward with our install by doing the following:

  • $ sudo chmod 666 /dev/ttyUSB0

We will also have to allow www-data permission to run heyu commands. NOTE: Due to security concerns, this should only be done on a Raspberry Pi that is not accessible from the internet!

  • $ sudo visudo
  • Add the following to the last line of this file and save: www-data ALL=(pi) NOPASSWD: /src/heyu-2.11-rc1/heyu

Step 4 – Is there an echo in here?

Now you’ll need to code a PHP page to handle URL requests for your lights. The PHP code will make an exec() call to heyu to turn on/off your lights.

  • Navigate to your server’s directory /var/www/html/ $ cd /var/www/html/
    NOTE: The directory was /var/www in Raspbian Wheezy but is now /var/www/html in Raspbian Jessie.
  • Remove all existing files from the html directory, enter the following $ ls -l to see what file(s) exist.
  • To remove files type $ rm filename, where filename is the name of the file(s) from the step above.
  • Now we will clone the files from github, $ sudo git clone https://github.com/audiofreak9/X10-Echo .

YES, the period at the end is needed so only the files are cloned, not the containing directory.

This cloned package now includes an index.php file that will be served as the default webpage. You can navigate to it by entering your RPI’s IP address in the browser.

The echo.php file’s code GET’s variables from the URL and acts on them to change the state of the requested house unit. The -c /home/pi/.heyu/x10config part of the $command variable tells the server where to find the heyu config file. I’ve added some output so you can test the URL in a browser.  Let’s test out your new echo code. In a browser enter your RPi’s URL ‘192.168.1.19’ for me, plus ‘/echo.php?’ and an ‘action’ & ‘hu’ (house unit) variables. So I’d enter:

  • 192.168.1.19/echo.php?action=on&hu=M2

to turn on unit M2, alternatively:

  • 192.168.1.19/echo.php?action=off&hu=M2

to turn off unit M2.

Dimming a modules is easy, just add the ‘percent’ variable to the URL. Here is an example that will dim the module M2 to 80% brightness:

  • 192.168.1.19/echo.php?action=on&hu=M2&percent=80

I’ve also written php code for my default index.php page, this is what I can browse to on my phones, tablets and desktops to control my lighting as well. Here is a link to that code.

Step 5 – Hue talking to me?

At the time of writing this how-to, the Amazon Echo can control WeMo, Phillips Hue and Wink brand IoT smart devices.  Of course X10 does not ‘interface’ with those technologies.  Another group whose devices that currently do not interface with the Echo is Vera (SmartThings).  A very smart person, Armzilla over at the Vera forums wrote a Phillips Hue bridge emulator. Another very smart person at the Vera forums, Crush forked the bridge to create a lighter version which now includes Harmony Hub and Nest Thermostat integration. These emulators are java files (.jar) so they can be run on virtually any device.  I have personally switched to Crush’s version, and prefer it, but both are suitable and working, my tutorial uses Crush’s version. The Amazon Echo will discover the emulator as a Hue bridge, and discover the configured devices.  When asked, the Echo will call the configured on or off URL for each discovered device, brilliant!  I can use my echo.php URLs in place of the Vera URLs devised by the creator!  If you are planning on installing and running this bridge emulator, I suggest reading the entire forum thread, most problems you will run into have been solved in detail.

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

  1. On the Raspberry Pi create a directory to house the JAR in:
    $ mkdir echobridge
  2. Change Directory into your new directory:
    cd echobridge/
  3. Now download the latest JAR into the directory, you can get the latest here:
    $ wget https://github.com/bwssytems/ha-bridge/releases/download/v1.4.2/ha-bridge-1.4.2.jar
  4. To test that everything works, run this command to launch the JAR:
    java -jar -Dupnp.config.address=<your RPi IP address> /home/pi/echobridge/ha-bridge-1.4.2.jar

If you’d like this to survive a reboot on your RPi, you will need to get it added into a startup script. Open up the /etc/rc.local file:

$ sudo nano /etc/rc.local

Add the following below the “fi”:

For the ha-bridge to auto-start on reboot:
nohup java -jar -Dupnp.config.address=<RPi IP> /home/pi/echobridge/ha-bridge-1.4.2.jar 2>&1 &

If you are using the ttyUSB0 and HEYU with your X10 equipment (as in this tutorial) also add the following two lines:
chmod 666 /dev/ttyUSB0 &
su -l -c "heyu start" pi &

Press CTRL + X, select to save the file.

The first line you added will allow your Raspberry Pi to automatically run the java process that runs the Echo Bridge. The second line allows the ttyUSB0 device to be accessed by the PHP server. The last line starts heyu on reboot, so there is not a delay on the first heyu command on reboot.

If you’d like to verify it is running, you can type: ps -ef | grep java.

Once you’ve got the bridge running (it takes a minute or more to fully boot), in a browser enter your RPi’s IP, plus ‘:8080/api/devices’, to navigate to the api/devices page. For me this is:

  • 192.168.1.19:8080/api/devices

You should see some JSON output, here is my output with all my devices configured, your output will look different based on number of configured devices or lack there of.

The bridge also supports dim commands from the Echo. The bridge returns two variable options, they are ${intensity.percent} (for 1-100) or ${intensity.byte} (for 0-255). By saying, “Alexa, dim the kitchen lights to 50%” that percentage will be passed in the ‘On URL’, I’ve chosen to use ${intensity.percent}. With X10 this gets a bit tricky since X10 dim/bright is from 1 to 22. We will need to do some math within the code to get the dim level command correct.

To add discoverable devices, the bridge comes with a configurator to make adding and editing devices a snap. To navigate to it I enter:

  • http://192.168.1.19:8080


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
  • On URL: http://localhost/echo.php?action=on&hu=M2&percent=${intensity.percent}
  • Off URL: http://localhost/echo.php?action=off&hu=M2

Notice I have used “localhost” rather than my RPi’s IP Address, it’s a hostname that means this computer. I use it in my ha-bridge settings so they are more portable. If my RPi’s IP changes I don’t need to update all my configured devices in the bridge.

Step 6 – 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.  If you have any trouble with Alexa discovering devices, as I stated before, reference the Vera Forum, most discovery problems are solved in detail.  Also of note, you can manage the devices the Echo has discovered by visiting: http://echo.amazon.com going to ‘Settings’ -> ‘Connected Home’, or directly at http://echo.amazon.com/#settings/connected-home.  This can be helpful if you remove or rename a device on your Hue Bridge Emulator.

Some have reported having more success with the Amazon Echo discovering devices while having more than one device in the list, I was able to discover just one, but I thought it was worth mentioning.

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 the kitchen lights on”, and viola they turn on.  There isn’t even a delay in the relay between devices and action, maybe a quarter second at most!  Excellent, now I can control my house lights with my voice through my Echo!

Notes:

Below I’ll compile information discovered along the way.

  • If you already have a 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: http://192.168.1.19/echo.php?action=lightson&hu=A – (Thanks Mitch)
  • Since originally writing this post, I have switched to a lighter version of the bridge forked by BWS Systems. You can get the latest .jar from their Git Hub. My write up now includes this version.
  • 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)
  • Using the configurator, in the manual add section you can put the calls like, “http://192.168.1.149/echo.php?action=unitsoff&hu=A”, the working complement to lightson by the way. But there are now two dropdown boxes below the calls. I had to select GET in the verb box, and application/json in the content box. You can leave the text boxes below the dropboxes empty. – (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: hu=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 hu=m3-6. – (Thanks Frank)
  • If you configured devices while the bridge was started from the command line, when/if you autostart the HA Bridge via rc.local, you will need to point it to the existing device database. Add the “-Dupnp.device.db” option to the rc.local start command like this:
    nohup java -jar -Dupnp.device.db=/home/pi/echobridge/data/device.db -Dupnp.config.address= /home/pi/echobridge/ha-bridge-1.3.7.jar 2>&1 & – (Thanks Eric)

143 thoughts on “Amazon Echo X10 Home Control

  1. Corey,
    I’m stuck now in bridge discovery.
    I configure 8 devices X10 switch on HA Bridge web and switch can toggle via web.
    RPi is connected to router via LAN and router already enable uPNP as well.
    However I cannot discover bridge from http://alexa.amazon.com/
    What should I do next to troubleshoot this issue?

    1. Dumb question, but has worked for many, have you tried cycling the power on your RPi, router and Echo? Otherwise, there is some logging we can turn on in the bridge itself to see if the Echo is requesting info from the bridge.

  2. Can I use an old xp computer I have around, instead of buying the raspberry pi?

    1. Yes, but you’ll need to be careful of the ports you specify in the settings, since Windows uses some of the ‘default’ bridge ports.

  3. Great tutorial… Thanks! I’ve got everything working at this point, however when I go to backup the bridge settings I get this error: “Could not backup to file: habridge.config-2016-04-21-10-19-52.cfgbk message: data/habridge.config”. Any ideas? I am able to backup the device.db without any problems…

    1. It appears there is a write permission issue, but being able to back up settings means that both should work. How are you starting the bridge cmd line or rc.local?

      1. rc.local with the command: “nohup java -jar -Dupnp.config.address= /home/pi/echobridge/ha-bridge-1.4.2.jar 2>&1 &”

  4. Sorry for the noob question, but what exactly is the x10config file used for? I’ve setup my system and have all of my devices manually input into the HA Bridge and everything works fine with my Echo. I’ve never edited or touched the x10config file that Heyu is supposed to use.

    1. The x10config file configures the HEYU program with all sorts of info like: the default house code, your device and scene names, your home’s lat & lon location, auto-starting the HEYU program. It is not entirely needed, but can be handy if you want to do dawn/dusk calculations with HEYU. Do a Google search for “heyu manpage”, it is the manual for HEYU. My example config is a good starting point.

  5. Where can you get an RPi and case for $35. The cheapest I could find was $41 for the RPi alone. I had to add the case, power supply, SD card, etc. Now at $70. Do you have a current source for these items?

    1. Forgot to also mention I used an old, but hefty, cell phone charger I had collecting dust as my power source.

  6. So, working great for over a month. Had a power glitch and everything stopped. Went in (SSH) to work on things, and found zero disk space left while receiving a whole bunch of cannot write errors. I purged Wolfram-Engine and LibreOffice to get back a GB of space, rebooted and everything worked fine. Is it possible that a large number of logs are being created and never destroyed?

    1. I doubt the log has grown so large as to run your memory card out of space, unless you changed the default log buffer size of 512k. On the Bridge Control tab check the Log Message to Buffer setting.

  7. Corey, my x10 motion detectors trigger an x10 command in the AC wires. Have you made any progress getting this bridge to go both ways? For example turning x10 wall switch and motion detection into a command that will trigger a messageor alarm at the Echo, or cause my smart phone wink app to issue a notification? Thank you. Very nice work. -Andy, Fairport, NY

    1. The Amazon Echo does not accept triggers at this time, meaning you can’t send a command or trigger to the Echo to make a noise or reply with the Echo. I have a Wink Hub, but have not worked on returning feedback to it, and do not know that this is possible at this time either. You can set up macros in the CM11a that will activate when a motion detector is triggered. I’ll think this over and get back to you with my thoughts.

      1. Bridge working both ways. So forget the requirement of triggering the Echo. You are so close to building a universal X10 to Wink bidirectional bridge… This would enable so many shelved X10 devices to be placed back in service. I don’t think the industry wants to see this as it reduces sales of new zigbee items. All the more reason to strive for a solution. I’ve purchased a few boards to duplicate your work plus a Wink bridge. I’m warming up my logic analyzer! -Andy

  8. Dude, you rock! This guide was tremendously helpful.
    I made mine work in Windows 10, with Debian 8.5 running in Oracle VirtualBox 5.1.2. Had a few hiccups and had to make a couple of tweaks, but it is working like a charm!
    Thanks for the great instructions!

    1. Glad you found it helpful. If possible, would you be willing to share the ‘hiccups’ and ‘tweaks’ you had to get this running in W10? Cheers!

  9. Corey,

    Thank you for taking the time to post all of this great information! Quick question: Can I use a CM15A in lieu of the CM11A and the USB to SERIAL adapter?

    1. The answer is No and Yes. Heyu does not work with a CM15A. You will need to use MOCHAD instead. You would install MOCHAD on your device rather than HEYU, then just call the MOCHAD commands instead of HEYU’s. The second link is to the README for MOCHAD, it details installing and commands for use.

        1. Bob,
          I meant to also mention that you can use a Firecracker CM17A with HEYU. Let me know how you make out with MOCHAD, it’s very similar to HEYU. You can add the commands right in the ha-bridge, just like HEYU’s commands.

    1. I don’t think with the holidays I have the time now. Once you own a Raspberry Pi, it truly is as easy as following my directions.

  10. Hi, great job and site. I’m socked that nobody has asked this and it’s not in your How To instructions. Does this method along with your Update work with just the raspberry PI B Plus only ? Or can it work with the newer Rasbeery PI models. Such as 2 & 3 models. Please explan why or why not .

    Thanks again for all your hard work. It’s people like you that makes technology fun and executable for the noobs!

    1. This will work with any model RPi. It may not be as ‘snappy’ on models with less process power and memory (model A), but it is designed to require less resources, that is why the RPi is a perfect fit.

  11. Corey – was the use of CM11A+USB Serial Interface instead of a CM19A due to parts you already had, so you were not reliant on RF, or something else ?

    1. Stuart,

      The CM17A is a pass-through serial adapter, it would go between the CM11A’s cord serial port and the USB to Serial adapter’s serial port.

      1. I was missing the ‘f’ in the scripts – so that’s why the Firecracker wasn’t working.

    1. Hey Rick,

      Sorry I don’t sell them prepped. I have been asked a few times in the past (I think you are the 4th or 5th to ask), maybe I need to look into prepping memory cards for sale. I’ll reply if I have the time.

Leave a Reply

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