By Gordon Meyer (http://www.gordonmeyer.com), author of Smart Home Hacks (http://www.oreilly.com/catalog/smarthomehks/)
Originally published at O’Reilly ONLamp, November 2004. (http://www.onlamp.com/pub/a/onlamp/2004/11/11/smrthome_hks1.html) Reprinted with permission
Of all the grand promises from futurists—the flying car and personal robotic assistants—home automation is one of the few technologies that you can enjoyably, and relatively inexpensively, implement today. In fact, if you’re at all technically inclined and enjoy tinkering, it’s a fun hobby that you can enjoy and everyone else in your household can benefit from. To get started you’ll need a computer, some X10-based lighting and appliance control modules, and home automation software that you program to manage it all.
While X10 gets a bit of bad rap at times, it’s your best all around choice for automating your home, particularly when you’re just getting started. It’s a power-line carrier technology, which means it’s a method of transmitting data over your existing AC electrical system. That means you don’t have to retrofit your home; most X10 modules simply plug into a wall outlet. Additionally, because X10 has been around for so long (since 1978) modules are easy to find and inexpensive, especially when compared with newer, competing technologies. The basic idea of X10 is that modules “listen” to the power-line for commands sent from your computer, remote controls, or other modules such as motion detectors. When a module receives a command that matches its address, it reacts to the command. If the module is connected to a lamp, the command might be “dim to half-power”. If it’s a fan or radio, the command could be “turn off.”
While it’s possible to somewhat automate your home without using a computer, the methods for doing so are quite limiting. You’ll only be able to turn devices on or off at scheduled times, or have simple macros that control a series of devices in an exact sequence. By using a computer to control your system, your home can be much smarter. For example, instead of turning on the porch light every night at 7:00PM, your computer can turn on the porch light only if you’re not already at home. To accomplish this, you’ll need home automation software.
In this article I’ll cover the basics of automating your home with MisterHouse (http://www.misterhouse.net/), an open source home automation application for Linux, Windows, and Mac OS X. MisterHouse was started by Bruce Winter in 1999 and has benefited from other contributors enhancing the program to support a staggering array of options and automation-related hardware. The result is a program that’s feature-packed, but more than a little intimidating for a home automation newbie. In this article, I’ll sort out the basics and point out some interesting paths to explore once you’re ready for some serious spelunking.
Also, this article is organized similarly to articles in Smart Home Hacks (http://www.oreilly.com/catalog/smarthomehks/) that examine the commercial home automation packages HomeSeer (http://HomeSeer.com), XTension (http://www.shed.com/), and Indigo (http://www.perceptiveautomation.com/). That way you can use this as a guide for translating the techniques in the book to MisterHouse, or if you have yet to decide which application to use you can more easily compare the capabilities and approaches used by each of the programs.
MisterHouse is available for downloading at the project’s web site (http://www.misterhouse.net/).
If you’re a Linux or Unix user, the MisterHouse web site has the details you need for downloading and installing the appropriate packages for your system.
On Windows, unless you’ve already got your system all set up for Perl, you’ll probably want the compiled version of MisterHouse. You’ll also have to download the source distribution, however, because it includes the documentation and support files that you need. If you do have a Perl installation, you’ll do just fine with just the source package.
Mac OS X uses the basic Unix version, but you’ll need to make a few configuration changes in order to avoid having to install several additional libraries and packages to complete the setup. The recommended changes are discussed in the Getting Connected section of this article.
There are several ways to interact with MisterHouse: via the command line, over a telnet connection, using a Tk-based interface, using spoken commands and speech recognition, or using a web browser. For the purposes of this article, I’ll focus on the browser-based interface. That’s not to dismiss Tk or the other interesting methods, but clearly using a web browser to control server-based application, from any computer on the network, is a familiar and useful approach that’s suited to most home automators.
For more details on installation options and the latest skinny about versions and requirements, be sure to consult the MisterHouse web site at http://www.misterhouse.net.
MisterHouse can adeptly handle all the home automation tasks you can throw at it, but to send commands to X10 modules it needs a power-line interface. MisterHouse works with several controllers, including the commonly-used CM11(http://www.x10.com/automation/x10_ck11a_1.htm) and LynX-10 PLC (http://www.marrickltd.com/lynx105.htm) , both of which are standard serial devices. If your computer has a USB port, you’ll need a USB to Serial adapter, such as the Keyspan USA-19HS (http://www.keyspan.com/products/usb/USA19HS/) , to make the right connections.
MisterHouse supports an impressive array of interfaces and add-ons. Everything from LCD displays and IR modules to weather stations. As you would expect from an open source project, if there’s an interesting I/O device somebody has probably already tackled the task of getting it to work, in some fashion or another.
After you’ve connected the power-line interface to your computer, you’ll need to configure MisterHouse. The main configuration file is mh\bin\mh.ini, but instead of editing that file, it’s better to simply override the default options that you need to change by modifying the mh.private.ini file instead. MisterHouse reads the private configuration file after the main one, so the private settings are the ones that take precedence.
If you’re using a CM11 power line interface, specify where the serial port is connected as shown below.
cm11_port = /dev/ttys0
The example above is typical for a Unix system, on Windows you’ll specify COM1 or similar. If you’re using a controller other than the CM11, check the comments in the Category = Serial section of the mh.ini file for the parameters needed for your controller.
|
|
MisterHouse also works with wireless X10 receivers such as the X10 MR26 RF Receiver (http://www.x10.com/products/x10_mr26a.htm) and WGL Design’s W800RF32 (http://www.wgldesigns.com/w800.html). These devices are excellent methods for improving the response time and reliability of wireless motion detectors and the like, but wireless X10 is not a replacement for the power-line controllers discussed earlier. If you’re just getting started, don’t worry about wireless X10 yet. Just know that MisterHouse is ready for it when you’re ready to go there.
Now that you’ve got MisterHouse set up, let’s start adding the details it will need to run your home.
MisterHouse needs to know about the X10 devices you have installed in your home so that it can send commands to them in response to events or your actions. To begin, start MisterHouse running by opening the application (if you downloaded the compiled version) or from the command line.
./mh/bin/mh
If all goes well, you can then access the main MisterHouse interface by entering http://localhost:8080 into your favorite web browser. This displays the MisterHouse main menu, as shown in Figure 1.
mrhousemain.pdf
Figure 1 – MisterHouse Main Menu
To reach the configuration screens, click the Mr House Home button, and then click Setup Mr House. Then, in the second row of buttons, as shown in Figure 2, click Edit Items.
Secondbuttons.pdf
Figure 2 Setup MisterHouse Menu
The Items Menu screen allows you to edit an mht file, which is where MisterHouse keeps track of the devices you have defined. By default, you’ll be working with the sample mh/code/test/test.mht file that’s included with the MisterHouse distribution. Eventually you’ll want to either create your own file or delete all the items from the sample file, but for now let’s use it as-is because it illustrates several MisterHouse basics that you’ll need to understand before diving into a completely customized setup.
To view the lamp modules that are already defined, click the X10I link in the Item Index to scroll to the section of the page that lists the modules and their addresses, as shown in Figure 3. (Appliance modules are defined as type X10A.)
X10I_list.pdf
Figure 3 – Listing X10 Lamp Modules
The sample setup has six lamps defined, each with their corresponding X10 address, as shown in Table 1.
|
Unit Name |
X10 Address |
|
garage_light |
A1 |
|
test_light1 |
B2 |
|
test_light2 |
B2 |
|
bedroom_light1 |
C1 |
|
bedroom_light2 |
C1 |
Table 1 – Sample MisterHouse Lamp Modules
Additionally, each device is assigned to the All_Lights group, and a group appropriate for its location. For example, the bedroom lights are assigned to the BedRoom group. Using groups is a great technique for simplifying your home automation system and are discussed in more detail later in this article.
Notice that the two bedroom lights are both assigned to the same address, C1. This is perfectly valid in X10 and is quite useful when you want to control more than one device with a single command. Here, when you have MisterHouse send an off command to the C1 address, both bedroom lights will turn off simultaneously.
While X10 addresses don’t have to be unique, each device must have a unique name as defined in MisterHouse.
The other fields you see listed on the screen, Interface and X10 Type, are used when you have more than one power-line interface connected to your computer. You can safely ignore these fields for now, and in fact, you might not ever need to utilize them unless you begin to create a particularly sophisticated system.
Let’s add a new device, say a lamp module connected to a light in the office whose X10 address is set to G10. To do this, scroll the web browser window back to the top of the Items Menu screen. Then select X10 Light (X10I) from the pop-up menu that’s next to the Create button as shown in Figure 4.
CreateLight.pdf
Figure 4 – Adding a new device
Next, enter a device name of Office_light1, the X10 address of the module, which is GA (G10 in hexadecimal), and the group that this device belongs to, All_Lights. Press Enter to add the new device. If you return to the X10I index listing, as described earlier, you’ll see that Office_light1 has been added to the device list.
If you need to correct or change an entry that you’ve already made, simply edit the appropriate fields in the index listing and press Enter. If you get confused or want to make sure your changes have been saved, click the Reload link at the top of the page to refresh all the fields with the last saved version of the configuration file.
If you want something to happen at a specific time in the future, either once or repeatedly, you set up a scheduled event. For example, you might want the air cleaner in the office, which is connected to an appliance module, to come on for three hours every other day. Or, perhaps you need to get up early tomorrow and you want the coffeepot to be started at 4:30 a.m.
To create a new scheduled event, click the Mr House Home button on the main menu, and then click Setup Mr House. In the Setup Mr House menu, click Edit Triggers. At the top of the Triggers Menu screen, fill in the fields to add a new trigger event, as shown in Figure 5.
CreateTrigger.pdf
Figure 5 – Adding a new trigger event
The first field is the name of the trigger, as you want it displayed in the scheduled triggers list that appears in the bottom portion of the window. The pop-up menu next to the name field allows you to choose among several different types of triggers. For a trigger that you want to occur at a specific time, choose time_now, then enter a time, and optionally a date, in the next input field, as shown in Figure 5. Next, choose an action from the 2nd pop-up menu. To send a power line command to an X10 device, choose set. The contents of the last input field are where you put the parameter for the action that you’ve selected. In the case of a set action, enter the device name and a command, such as $air_cleaner on.
Finally, click the Create button to schedule your new trigger event. You’ll see it listed in the trigger list in the bottom portion of the window. If you want this event to occur more than once, choose NoExpire from the pop-up next to the trigger’s action. Otherwise, the trigger will be executed at the specified time and date and then be removed from the list. If you want to temporarily stop a trigger from executing, but don’t want to delete it so you can re-activate it later, choose Disabled from the pop-up menu.
Be sure to read the MisterHouse documentation for information on the event triggers other than time_now. You can specify times using cron syntax, or define triggers that occur when variables you’ve created become true, and several other options. You might, for example, have a script that downloads the current weather conditions and sets the variable $is_raining to true, which triggers a spoken reminder to close that oft-forgotten bathroom window.
Although scheduled events are handy, having your home automation system respond to stimuli puts the “smart” in smart home. Like the man behind the curtain in The Wizard of Oz, it’s MisterHouse responding to events (motion detectors triggering, garage doors opening, etc.) that makes it all happen. And while you can do a lot with scheduled triggers, to really take advantage of MisterHouse’s power you’ll need to write a few scripts.
Every home automation software package that’s sophisticated enough to run a smart home uses some sort of scripting language. With MisterHouse, you use Perl. If you’re already familiar with Perl you’ll feel right at home when creating the logic and procedures that send, receive, and schedule events around your house. If you’re not already a Perl maven, it’s easy enough to pick up the little you need to know to get started. The built-in objects that MisterHouse provides for managing your automation system hides a lot of the scripting complexity from you, but some of the sample scripts can still be overwhelming for beginners. As with any home automation project, regardless of the software you use, it’s always best to start simple and grow your system over time; this approach works particularly well with MisterHouse.
Once you start scripting you can teach your system to perform several steps for you, based on a variety of conditions. For example, you might push a single X10 button when you’re departing for work in the morning and in response MisterHouse turns off all the lights in your home, adjusts the thermostat to save some energy, and closes the garage door after you leave. It’s all accomplished using scripting.
MisterHouse looks for scripts in the location specified with the code_dir and code_dir_common configuration settings. Drop a perl script into these locations and it will be periodically executed. In the default MisterHouse configuration, these locations are mh/code/test and mh/code/common.
This is where MisterHouse’s clever design comes in handy, you can have multiple scripts in the locations, which allows you to gradually build your system over time by adding new scripts as you create or discover them. The mh/code/public directory is filled with example scripts for you to explore, modify, and move into your working directory when you’re ready to put them into action.
The example script mh/code/public/text_x10.pl contains some handy examples to get you started. In the snippet below, MisterHouse responds to an X10 on command, sent by address A2, by printing a message to the MisterHouse log, speaking the same message aloud using the computer’s voice synthesizer, and then turning off the device named garage_light.
# Respond if the A2 button is pushed ON
$test_button = new Serial_Item('XA2');
if (state_now $test_button eq ON) {
my $remark = "You just pushed the A2 button";
print_log "$remark";
speak $remark;
set $garage_light OFF;
}
Earlier you learned how to create a trigger event using the MisterHouse browser-based interface. You can also set up triggers via scripting, as shown below.
# Turn on air cleaner at 4:30PM
if (time_now ‘4:30 pm’) {
set $air_cleaner ON;
}
# Turn on garden lights at sunset
if (time_now $Time_Sunset){
set $garden_lights_all ON;
}
In the second trigger defined above, the system variable $Time_Sunset is used to determine your local sunset time, which MisterHouse calculates based on the date and location settings of your computer. When the event is triggered, the group named garden_lights_all is turned on. Groups are a particularly handy technique for home automation because they allow you to greatly simplify your scripts. In this example, instead of specifying each light individually in the script, MisterHouse sends the on command to every member of the group for you.
You can define groups with the MisterHouse browser interface, using the Edit Items screen that described earlier while adding X10 units, or you can define groups programmatically with a script. In the example below the script first defines new X10 units, then creates a group that references each of the units.
$garden1 = new X10_Item('C1');
$garden2 = new X10_Item(‘C2’);
$garden3 = new X10_Item(‘C4’);
$garden_lights_all = new Group($garden1, $garden2, $garden3);
These have been simple examples, but they demonstrate the essence of home automation scripting. Your scripts, in response to commands from X10 devices or at scheduled intervals, evaluate current conditions and states then react in logical, and hopefully helpful, ways. If you’re an experienced scripter you’re probably already imagining how you can expand these ideas to incorporate other sources of information about your home, your network, or the outside world. For example, in Smart Home Hacks, the hack Educate Your Alarm Clock describes how to script a personalized alarm clock that automatically silences itself on weekends, holidays, and when you’re out of town.
MisterHouse keeps an extensive record that enables you to see exactly what’s going on with your home automation system. Not only does the log keep track of everything MisterHouse does, but also, because the application is listening to the power line, you’ll see X10 commands that are sent from other sources, too, Learning to interpret the log files is essential for debugging your system, particularly when you’re developing new scripts and experimenting with new techniques.
MisterHouse log files are located, by default, in the mh/data/logs directory. You can change this location by setting the data_dir parameter in your mh.private.ini file. One of the most useful logs for understanding what’s happening with your system is print.log. It records the execution of events and triggers, and you can add your own messages to the log by calling the print_log function, as demonstrated in one of the script examples earlier in this article.
The errors.log file contains important messages internal to MisterHouse, and the server_http.log file keeps track of all the pages and actions related to the browser-based interface.
Now you know enough about MisterHouse to begin building your system, and to begin exploring the samples and documentation that come with the program. You’ll definitely want to also visit the archives of the MisterHouse User forum (http://sourceforge.net/mailarchive/forum.php?forum_id=5118). You’re sure to find helpful advice about add-ons and techniques for creating a smart home that’s suits you and your family. You’ll also want to visit Neil Cherry’s Linux Home Automation web site (http://home.comcast.net/~ncherry/), which is a treasure trove of links and resources.