Archive


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

080618

Some things may change…

Below is an essay that I recently wrote for an entrance application to York University's joint Bachelor of Design Undergraduate program with Sheridan College. Entrants were asked to read an excerpt from an essay, summarize in our own words, the points made and then pick two of the points and find 2 examples that illustrate the points. Needless to say, I did a lot of hack and slashing. Continue reading →
Share Button

080415

Mark James Joseph Kormendy (1964-2008)

Today I mourn the loss of my brother. With his siblings and parents at his side, Mark James Joseph Kormendy peacefully passed away in Guelph General Hospital at 5 minutes to 3pm. With ironic grace there could be no better opportunity to say goodbye, with family at your side. Mark, I already miss you so much. Continue reading →
Share Button

071105

Actionscript Tip: PHP-style Variable Variables

Variable Variables may be a different concept for the need and result I came up with, but Variable Variables is what lead to my re-discovery of the powerfully dynamic set(); function in actionscript. Discovery I have been working on a small Flash CS3 project that imports and displays information stored in XML. Like many, who wouldn't want their actionscript to be:
  • simple
  • clean
  • dynamic
  • scalable
... all to the synchronous XML data and design requirements that might change down the road? Everything was going fine until I hit a little roadblock in my XML parsing loop. How do I get flash to create variably-named variables? I found out my solution after some intensive research, here's how ... Continue reading →
Share Button

071031

Photoshop Tip: Keep Rulers 'Off' When Possible

When I work in Photoshop I usually have my screen mode set full screen, so that I can use my screen to it's maximum potential and edit artwork that bleeds off the edges of the document area. I recently turned off my rulers (PC: CTRL+r MAC: Command+r) for even further maximum viewing area, and noticed that grabbing the page and moving it around was much smoother! I think the rendering of the measurement numbers and the scaling marks on the rulers in photoshop take some GPU or CPU rendering power away. Whenever I have the rulers on, it just seems to make the redraw of the entire window sluggish and choppy when I manipulate the document. I'm leaving rulers off from now on.
Share Button