Home Automation with X10, Raspberry Pi, Linux and Ruby on Rails

X10 is a communication protocol used for electrical devices to communicate over the powerline. It was first introduced in 1975, but it remains popular because the technology is rather inexpensive (especially compared to other newer technologies). And since the patents on the X10 protocol are expired there are now multiple companies that offer devices for reasonable prices and new devices are introduced to the market frequently.

Control x10 with Raspberry Pi

Control x10 with Raspberry Pi

When I bought my house in 2009, I took the time to install X10 modules all over the place so that I could automate all lights in the house. Since I had already a Linux box running as a HTPC, I used this machine to control my lights using a great nifty command line tool called heyu. Heyu talks to a X10 PC interface module to control the lighting in our house. In my case I used a CM11 module hooked up by a USB cable to the Pi (for the record, I also own a CM15Pro module, but I never got this to work on Linux). Heyu allows me to use the Bash terminal to operate my lights, which is great because I usually have a terminal window open. However, operating lights using the terminal is a bit cumbersome at times… An app for my iPhone would be really great! Inspired by this thought I searched the web for options and finally decided to build the application myself. Using a Raspberry Pi, Linux and Ruby on Rails I managed to build a simple web application that looks and acts as a smartphone app and runs on all popular mobile operating systems. The web application is available for download on Github. You can use the tutorial below as a guide to setup your own system.

Setup your Raspberry Pi

Given it’s low price and low power consumption, I chose the Raspberry Pi, a very small computer that runs on Linux. I used the latest NOOBS to install Linux on my SD card. Detailed instructions on how to do this can be found on the Raspberry Pi homepage and Github. In this tutorial, I’m going to assume you have a working Raspberry Pi up and running and connected your network. I highly recommend you use SSH to connect to your Pi to complete the rest of this tutorial. Furthermore, I’m using the default user ‘pi’ to install the software.

Installing Heyu

The software that makes controlling lights using a Linux box possible is ‘Heyu’. Heyu has been around for many years and can be compiled on most Unix platforms, including Linux. Download the latest tarball from the Heyu homepage. Let’s compile Heyu.

$ mkdir src
$ cd src/
$ wget http://www.heyu.org/download/heyu-2.11-rc1.tar.gz # replace this with the most recent version of heyu
$ tar xfvz heyu-2.11-rc1.tar.gz
$ cd heyu-2.11-rc1/
$ ./configure
$ make
$ sudo make install

You can check if everything was compiled and installed correctly by running heyu on the terminal. You should see a similar output as below:

$ heyu
Heyu version 2.11-rc1
X10 Automation for Linux, Unix, and Mac OS X
Copyright Charles W. Sullivan and Daniel B. Suthers
Usage: heyu [options]   (Enter 'heyu help' for commands.)

Heyu uses a configuration file that you need to edit in order make our web application work. Heyu looks for the configuration in the ~/.heyu folder of the pi user. To make sure, you can run the following command, and check the output:

$ heyu info
Heyu version 2.11-rc1
Configuration at /home/pi/.heyu/x10config #<<<< Check this line >>>>>>
Powerline interface on /dev/ttyUSB0
Firmware revision Level = 8
Interface battery usage = Unknown

Since we are not running heyu as root, it may be necessary to create some directories for heyu, that need to be given read/write permissions:

sudo mkdir -p /usr/local/var/tmp/heyu
sudo chmod 777 /usr/local/var/tmp/heyu
sudo mkdir -p /usr/local/var/lock
sudo chmod 777 /usr/local/var/lock

You might want to look in the Heyu config file. If you are using an USB interface such as the CM11 module you should see that heyu talks through TTY /dev/ttyUSB0. Most of the config file is commented out and not very interesting for our purpose at this time. Time to see if our Heyu is working, by playing with our lamps. Obviously, replace A2 with whatever X10 module address you have installed.

$ heyu on A2
$ heyu dim A2 10
$ heyu bright A2 10
$ heyu off A2

If all worked well, you can now control lights using the terminal. Great!

Next step, is to provide Heyu with some aliases and scenes. Heyu uses aliases to associate a logical name to X10 device so that you don’t have to remember all X10 addresses. Futhermore, the web application uses this information to provide a list of available devices in the mobile views. Scenes are similar to aliases but allow you to issue multiple X10 commands at once. I find this a very helpful feature. For example, I use this to switch and dim multiple lights in my living when we are watching a movie. Both aliases and scenes are supported by the web application. Both aliases and scenes are defined in the x10config file. Find the section in your file provide some useful labels for your devices. For example, I have the following aliases in my config:

ALIAS   kitchen_spots      A1   StdLM
ALIAS   living_spots       A2   StdLM
ALIAS   living_table       A3   StdLM
ALIAS   charger            B2   StdAM

The ALIAS directive in the first column tells Heyu an alias is being defined. The second column contains the name of the alias. The third column should provide the X10 address for your device. Finally the fourth column indicates if you are using a Standard Lamp Module or a Standard X10 Appliance module.

Do the same for scenes. You can define them in your x10config file. Note, that you can use your aliases in the scene definitions. For example:

SCENE   tv_on     on living_spots; dimb living_spots 10

The SCENE directive tells Heyu a scene is being defined. The second column provides a label for the scene. The third and final column contains a semicolon separated list of commands to be executed together. Put in as many aliases and scenes as you like and save the configuration file. Make sure the aliases and scenes can be read by heyu. You can check by:

$ heyu show alias
$ heyu show scene

The commands should give you an output similar to:

  alias  kitchen_spots       A1   StdLM  
  alias  living_spots        A2   StdLM  
  alias  living_table        A3   StdLM  
  alias  charger             B2   StdAM
  scene  tv_on  on living_spots; dimb living_spots 10

Install Ruby and Rails
The web application is written in Ruby on Rails, so to run it we need Ruby and the Ruby on Rails framework. I recommend using RVM to install Ruby. Let’s install RVM first:

$ curl -L https://get.rvm.io | bash -s stable --ruby

We need to install a Ruby version that can run our application. With RVM installed we can issue the following commands. On the Raspberry Pi this takes some time, so grab a coffee or two before continuing:

$ rvm install 2.1.0
$ rvm use 2.1.0 --default
$ rvm gemset create firstgemset
$ rvm gemset use firstgemset

This installs the latest and greatest Ruby interpreter. I’m using 2.1.0, but you can run the application from any Ruby version greater than 1.9.2. We also need bundler to install all the dependencies we need for our rails app:

$ gem install bundler

Next and final step is to download and install the web application so that you can control Heyu from your mobile phone. First let’s clone the sources for the web application from github:

$ cd
$ mkdir src
$ cd src
$ git clone https://github.com/harm/x10switch.git
$ cd x10switch/
$ ls

With bundler installed you can now install all the dependencies that are required for the application:

$ bundler install

The Rails app uses a Sqlite3 database that we need to ‘migrate’:

$ RAILS_ENV=production rake db:migrate

For Rails in production mode, we also need to compile all javascript and stylesheets:

RAILS_ENV=production bundle exec rake assets:precompile

Finally, you can start the webserver by:

$ RAILS_ENV=production rails server
=> Booting WEBrick
=> Rails 4.0.0 application starting in production on
=> Run `rails server -h` for more startup options
=> Ctrl-C to shutdown server
[2014-01-01 20:40:28] INFO  WEBrick 1.3.1
[2014-01-01 20:40:28] INFO  ruby 2.1.0 (2013-12-25) [armv6l-linux-eabihf]
[2014-01-01 20:40:28] INFO  WEBrick::HTTPServer#start: pid=20152 port=3000

Grab your iPhone or Anroid and open up a browser to connect your raspberry pi device, in my case:

You should now see the mobile interface, ready to control your lights!