Hardware


090506

Guide: Web-based control of X10 Home Automation (CM15A) on Ubuntu Linux

I have stopped using this home automation technique and can no longer support this guide.
Here is a step-by-step guide to getting the X10 CM15A USB module to work under Ubuntu on a personal home computer, and then to further get the iPhone Home Controller web-based interface to connect with that module. For those that know what all that means, great! For those that don't, well in the simplest of terms, it allows me to turn the lights in my house on/off or dimmed - just by accessing a website via my iPhone or computer. This process requires several different packages of files and programs, etc. so follow the steps very carefully! I use the sudo command a lot in the Terminal, go here to find out what sudo does, and means.

Step 1:

You need to have a flavour of Linux installed on your PC with Apache, MySQL and PHP setup correctly. I used the Ubuntu Server Edition (Jaunty Jackalope). If you are unsure of how to set this up I suggest reading up about it here first (this is a guide for the previous version of Ubuntu, but should still apply to the current version). NOTE: Please write down ALL of the passwords and usernames you make/use in the installation process of Ubuntu as you will need these to perform certain commands and/or access certain applications throughout the rest of this guide.

Step 2:

After you have installed Ubuntu Server Edition, you may not be savvy with a command line interface for operating the system. As servers go, it's not recommended to run a GUI on them, however if it makes it easier for you (and it did with me in this process), venture here to learn how to install one.

Step 3:

Unfortunately, I still recommend using a command line interface to compile the drivers and the interface, so get to know the Terminal application within the GUI (under the Ubuntu OS menubar: Application > Accessories ). It will allow you to run commands and install additional applications down the road. With that said, you need to now install the latest sources of the gcc compiler library. Load up Terminal and type the following at the command line and press enter: sudo apt-get install gcc build-essential If this command asks you to enter the password (as it did with installing the GUI for Ubuntu), then enter it. Let the computer do its thing, and if it asks to install a certain amount of megabytes of programs, agree to it and continue.

Step 4:

Once that is all completed, you should now be all set up to start installing the drivers and controllers. There are a number of attempts at people trying to program a driver to communicate with the CM15A USB transceiver out there, but the only one that seemed to still be actively developed (as of today), where the developer actually managed to work with me on the implementation, and whose programming code I had the pleasure of compiling successfully was/is by Jim at Eclipse Home Automation. His controller requires the stabilized USB library and also the Compatibility layers required for the USB library. The controller interfaces with the USB library, which in turn sends commands to the transceiver. Load up your browser (the default browser in Ubuntu is Firefox) and download the following files to your desktop on Ubuntu: libusb-1.0 from Sourceforge libusb-compat-0.1 from Sourceforge Jim's CM15A demo controller from his site

Step 5:

After those have been downloaded, you'll see a number of tar.bz2/tar.gz files on your desktop. These are compressed files packages that contain the driver libraries and controllers. Decompress these packages by double clicking on them and extracting the files to appropriately named directories (aka "folders") for each package so as to not merge their contents with each other.

Step 6:

Now within Terminal, navigate to the directory that contains the libusb-1.0 files. Within the Ubuntu GUI, you can use Nautilus (a similar application to Windows File Explorer or Apple Mac's Finder) to see all of the files within the directory on your computer, however some tasks cannot or should not be performed with Nautilus. Go here for tips on how to navigate the files and directories in Terminal). Within that directory you should have a series of sub files and sub-directories related to the USB library. We need to now configure, build and install this library. To do this begin typing this at the Terminal command prompt: sudo ./configure Once that has been completed, type the next command: sudo make And after that has completed, install the library with this command: sudo make install

Step 7:

In my case, all three previous commands performed flawlessly. So the next step is to install the compatibility layer for the USB Library. Navigate in your Terminal to the directory that contains your extracted compatibility layer files. And again, you should notice another set of files and directories that contain the source files. To install the compatibility layer, we perform the exact three same commands in Terminal as we used for the USB library: sudo ./configure After completed, type the next command: sudo make Now install: sudo make install

Step 8:

With any luck, Step 6 and 7 should have installed the USB library. Now it's time to install the CM15A controller. Navigate in Terminal to your directory that contains Jim's CM15A interface controller source files. All we have to do is compile the source files for this one, and this can be done by typing at the Terminal command prompt: sudo make The compiler will create a new file called cm15ademo within the same directory as the source files. Check to see if it is there by doing a directory listing ( dir ) at the Terminal command prompt. If the file is there, then everything worked properly. If not, I would see to make sure you are in the right directory and I would review all of the previous steps just to make sure you followed everything I've outlined here.

Step 9:

Congratulations if everything above went properly, you're computer should now be able to start sending commands to the CM15A transceiver to turn on/off/dim the lights! Before we any further, we should test to see if all of the steps above were performed correctly. If you know the dial-code for some of the plugged-in light modules/switches in your house and have your CM15A USB transceiver plugged into your computer and into an electrical outlet, then lets begin by testing a couple commands on the interface at the Terminal command prompt - the format for this is as follows: sudo ./cm15ademo xx cmnd Where xx stands for the dial-code of the light module/switch. In my case most of my modules are set up as: a1 a2 a3 a4 a5 a6 etc. The cmnd stands for the commands you can send to the light modules as follows: on off dim ## bri ## In the case for dim and bri, the ## represents a unit of decrease or increase (out of 100 units total) to the brightness of the light. So in my case, to turn on my kitchen ceiling lights I would use the following command: sudo ./cm15ademo a4 on To turn my kitchen lights off I used: sudo ./cm15ademo a4 off To dim my kitchen lights by a degree of 40 units: sudo ./cm15ademo a4 dim 40 To brighten my kitchen lights by a degree of 10 units: sudo ./cm15ademo a4 bri 10 Try modifying the codes above and turning on and off your light/switch modules in your house with the above command.

Step 10:

Step 9 should confirm that your computer is communicating with the CM15A USB transceiver. We can now install the iPhone Home Controller (iPHC) web-based interface. Because the iPHC was scripted to run on a Windows-based system with the Apache web server with MySQL and PHP (aka WAMP or XAMPP Server), I had to make some small modifications to the scripts to get it to work on Ubuntu's Linux web-server (LAMP). I have packaged up my modifications into tar.bz compressed file that you can easily download from my server with your web browser: iPHC zipfile You can use Nautilus to find and decompress this zip file into its own directory (aptly named "iPHC"). Now within the iPHC directory you should see three sub-directories and a bunch of php files. You need to place the main iPHC directory onto the system file-tree that Apache serves the web pages from. The default location for the Apache file-tree on my Ubuntu installation was found here: /var/www/ And your iPHC directory of files should copied to and reside here: /var/www/iPHC/ You can change the name of your iPHC directory to whatever you like, and for security reasons, I suggest that you later change it to a different name altogether.

Step 11:

iPHC is a wonderful little web-application that allows us to create list of buttons for all of lights within your x10 house configuration and name them appropriately. It remembers all of the names and the dial-codes of the light-modules by storing that information in a database within your web-server's MySQL. Now you don't have to know how to install MySQL (as it should be already installed and configured with the Server Edition of Ubuntu), but you will need to install PHPMyAdmin onto your server so that you can easily configure the database for iPHC. To install PHPMyAdmin onto your system, go to your Terminal and enter the following: sudo apt-get install phpmyadmin Now you should be able to log into your PHPMyAdmin from your web browser by visiting this address: http://localhost/phpmyadmin/ In my case I had to set up the access users for PHPMyAdmin, and initially started with the username root - I left the password blank and logged in. Later I created a password for the root account so that no-one could log in without knowing my password for the root user. As well, I also created a new user to separately access the iPHC database and that would have administrator permissions to create databases and access them. You can use the username iPHC and set a unique password that is different from the root user's password you just set (for security purposes). Don't forget to write your iPHC username and password - you will need this shortly. If you have any problems with installing, logging in or setting database permissions with PHPMyAdmin, the following three links may help glean some helpful tips: PHPMyAdmin Documentation on Ubuntu Forum Post re PHPMyAdmin Initial Login User Management and Authentication on PHPMyAdmin Wiki Finally, make sure you log out of root user in PHPMyAdmin when you are done setting it up.

Step 12:

Now log into PHPMyAdmin using the iPHC user and password. You should see a menu along the top. Click the button that says "Import". We are now going to import the fonehome.sql file within your iPHC folder within the /var/www/iPHC directory. Let PHPMyAdmin import the file with the default settings on that import page. Completing that means that we have successfully set up the database for iPHC, and you can now log out of PHPMyAdmin by clicking the little square "Exit" button under the PHPMyAdmin logo on the left of the webpage.

Step 13:

Now we need to connect the iPHC web-interface to the database we just created in MySQL. To do this we need to edit the connect.php file within the iPHC folder at /var/www/iPHC/. Type the following command at the Terminal prompt and press the Enter key: sudo gedit /var/www/iPHC/connect.php This should momentarily bring up a new application on your screen. This program is called GEdit, and it is a simple text editor that is useful for editing text files and PHP script files. You will notice the content of this PHP file look somewhat like the following:     Change the text YOUR USER NAME and YOUR PASSWORD with the ones you created in PHPMyAdmin for the iPHC database. Save the file and close the GEdit application.

Step 14:

If everything so far has been completed properly you should be able to see the iPHC web-interface and utilize its functions by visiting the following address: http://localhost/iPHC/ Select admin at the top of the screen and use the form to add a new module. Name and enter the address of your test module and click add. Once you have entered all of your modules, you may notice them also show up in a list when you select module at the top of the screen too. Don't get too excited, they don't work quite yet! We have one last step to perform before they are operational.

Step 15:

One of the best parts about Linux, is the amount of security that is embedded into the system. It can save people a lot of headaches because they aren't normally allowed to change or run certain files on the system and make mistakes that might cripple the computer/server altogether. Only users that are administrators can temporarily operate as a super user (also known as the root user) and access and run anything. Unfortunately this also makes it very hard for our iPHC web-interface running on Apache, to access and use the cm15ademo controller application we compiled earlier. Why?!? Because the Apache web-server in Ubuntu doesn't run as a root user (for good reason), and we need invoke the commands on cm15ademo as a super user. One might think, "well why not just use sudo???" Well, aren't they smart!!! But there's a hitch: sudo asks for a password when it is invoked from a shell command, and PHP is not programmed to create a command-line session so that it can provide a response/reply with the sudo password. Fortunately, there is a way to use sudo without having to provide a password in Linux - AND if configured correctly, you can specifically limit a "password-less" sudo command to which users, from where on the network, to which folder on the system and on what application. This is done by modifying the sudo users (aka sudoers) list, by accessing it with the Terminal application called visudo. Let's begin by typing the following in your Terminal prompt: sudo visudo The Terminal screen will then change content that takes up the entire Terminal window. In this screen is a list of codes that comprise the default sudo users list, as follows: # /etc/sudoers # # This file MUST be edited with the 'visudo' command as root. # # See the man page for details on how to write a sudoers file. # Defaults env_reset # Uncomment to allow members of group sudo to not need a password # %sudo ALL=NOPASSWD: ALL # Host alias specification # User alias specification # Cmnd alias specification # User privilege specification root ALL=(ALL) ALL # Members of the admin group may gain root privileges %admin ALL=(ALL) ALL We need to add the following code to the line below the root user privelege specification: www-data ALL=(ALL) NOPASSWD: /var/www/iPHC/cm15ademo And your file should look like this: # /etc/sudoers # # This file MUST be edited with the 'visudo' command as root. # # See the man page for details on how to write a sudoers file. # Defaults env_reset # Uncomment to allow members of group sudo to not need a password # %sudo ALL=NOPASSWD: ALL # Host alias specification # User alias specification # Cmnd alias specification # User privilege specification root ALL=(ALL) ALL www-data ALL=(ALL) NOPASSWD: /var/www/iPHC/cm15ademo # Members of the admin group may gain root privileges %admin ALL=(ALL) ALL Make sure that you DO NOT modify anything else!! Now quit visudo by pressing the keyboard keys CTRL and x at the same time. Visudo will ask you if you want to save the modified buffer, and type 'y' or yes, then hit enter twice. Visudo will return you to the Terminal command prompt and if there were any errors it will tell you in the above lines in Terminal. That means that you did not enter the above information correctly and will have to redo the above step to fix it. I'm going to hear some flack from someone out there, that this way is very risky if not implemented properly, and why not use some other PHP method like suPHP. The problem is that suPHP is known to take a huge performance hit on the system being up to 25 percent slower. The "password-less" allowance for sudo in my implementation restricts the Apache user www-data to the specific location and specific file of cm15ademo on the server, and nothing else. As well, if your apache installation is running a different user other than www-data, you can find that out typing ps -ef|grep -v root|grep apache all in one line at the Terminal prompt, noting the the name of the user running instances of Apache on your system. From this you will have to change the www-data to the name of that user.

Step 16:

Okay. You've made it this far, and I hope you have had luck following this guide from Step 1 through 15, and that it took you a fraction of time it took me to figure this all out. Load up the following link: http://localhost/iPHC/ Go to the 'Modules' page of the iPHC controller. Click the center buttons of the modules that you have listed in your house to turn off and on your lights, and the side buttons to dim or brighten your lights.

Step 17:

>Portions of Step 17 & 18 are reused from the iPhone Home Controller Website< To get this to work on your iPhone you will need to find out what IP address your computer address has. At the Terminal prompt type the following: sudo /sbin/ifconfig It should provide you with your IP address on your computer. Go here to find out more information on deciphering the IP address from all that mumbo-jumbo spit out with the /sbin/ifconfig command. If you don’t have a router with a firewall or anything else in the way like an internal firewall then you should be able to paste the IP address you found above into your browser address window to get to the main Apache homepage that your computer is serving. In my case I do have a router and have to open up port 80 on it, as well as set my computer’s firewall to allow Apache and MySQL. You will have to perform a search on Google for your specific router and firewall setup.

Step 18:

If everything works out you should be able to enter the your IP address with the iPHC sub-directory in your iPhone's Safari browser (or any other web enabled mobile device for that matter) and access your system. For example, it may look like the following: http://192.168.1.34/iPHC/

In Conclusion

I hope this worked out for everyone interested in setting this up. This took me a while to figure out and a lot of thanks goes to Jim for providing the LibUSB connector to operate the CM15A USB device.

fin

Share Button

090501

Preamble: Web-based control of X10 Home Automation (CM15A) on Ubuntu Linux

When I moved into my new place back in October last year, I couldn't figure out how to turn the lights off and on in the house as many of the switches in the house either didn't work or turned on the wrong lights. I found out later that my landlord had an X10 Home Automation setup in the house. This allows him to turn the lights on and off from a remote control. He also mentioned that he read of a way to automate the lights and access it via a website using the CM15A module that he had connected to a computer. I just happened to have a Windows-based Apache server with MySQL and PHP, and after a little research and implementation, I managed to serve a website that could control the lights in my house with a web browser. Over time I was getting more and more disappointed with the speed of my server. I had Windows Media Center running on it and a number of other programs for media streaming and file serving. As servers go, this isn't the best of setups, and because the hardware on the system wasn't to the fastest either, it made accessing the computer unbearable. So I did some research and decided to migrate the system over to the Server Edition of Ubuntu. Now that Ubuntu is installed, my system has never been faster at serving files and streaming media. The only problem is that the lights in my house aren't accessible and I couldn't control them from the web-interface I had implemented on the Windows setup. The drivers for the home automation in Windows aren't compatible with Linux. So I decided to do some more research and install ones made for Linux. Unfortunately my search came up short, with a lot of discussion around people trying to build drivers for Linux to access the CM15A module, but no hard evidence of a stable driver built by the X10 company. So that's where this article comes in: I have composed a step-by-step guide to getting the X10 CM15A USB module to work under Ubuntu, and which further allows the iPhone Home Controller web-based interface to connect the module. I will give fair warning, the setup I have only addresses how to turn off/on/dim the switch modules. The current driver-attempts for Linux do not access video cam modules, door lock modules or other home automation modules outside of the scope of the simple switch modules (that I know of). Click here for my article that outlines the steps involved to getting this to work.
Share Button