Get to Know MisterHouse

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.

Installing MisterHouse

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.

Getting Connected

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.

Notes for Mac OS X Users

If youíre running Mac OS X and a USB to Serial adapter, use Terminal to list the devices in /dev and look for the name of your serial adapter, then use that as the cm11_port parameter. On my system, I specify my Keyspan USA19 adapter like this:

cm11_port = /dev/tty.USA191822P1.1

If you move the serial adapter to another USB port, Mac OS X will reassign the adapterís device name and youíll have to update the cm11_port parameter with the new value.

While youíre making configuration changes, youíll probably want to turn off a couple of options. Mac OS X doesnít include Tk, gd (a graphics library), or the sound utilities that MisterHouse expects. Turning off these options as shown below will prevent MisterHouse from complaining about missing files during startup.

gd = 0

Sound_program =

tk = 0

Later, after youíre up and running and want to go further, you can install the necessary files (or their equivalents) and turn these options back on.

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.

Adding X10 Devices

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.

Scheduling Events

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.

Responding to Events

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.

Using the MisterHouse Logs

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.

Diving in

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.