Make your home come alive with Heyu

I have used X10 modules on assorted lights and devices for home automation for several years, and although the remote control facet has always worked well, tying the system into my Linux boxes has never been easy. Numerous small, typically one-person X10 controller projects have come and gone. But one application has survived: Heyu. It runs on desktop Linux machines without requiring the overhead of a Web or database server, and it enables direct X10 control, event scheduling, and more.

For those not familiar with it, X10 is a protocol designed to transmit short serial messages over household electrical lines to plugged-in devices — in practical usage, often a simple “on” or “off” to toggle power of a lamp or appliance plugged in through an X10 receiver module. Radio frequency (RF) remote controls are the most common way to manually control the devices, but manufacturers also make serial port adapters so you can use your computer instead.

Heyu is a program written for Linux and other Unix-like operating systems that lets you do just that. It is designed primarily to use the X10 CM11A serial port interface — although other models are supported, too, including the inexpensive and popular CM17A “Firecracker” module. The CM11A gets the focus, however, because it supports two-way communication and has onboard EEPROM storage for scheduling commands, complete with battery backup. Two-way communication allows the module (and thus Heyu) to query the state of other X10 devices in the home.

The CM11A plugs into an AC outlet, and connects to your computer’s RS-232 serial port with an included cable. Through the serial port you can send X10 commands directly over the AC wiring, but the CM11A is an powerline-only module; it neither sends nor receives RF commands from remote controls.

Heyu throughout the ages

Heyu is currently maintained by Charles Sullivan. He took over from previous maintainer Dan Suthers in 2006 when Suthers decided he could no longer sustain the project’s development and end-user support. Suthers’ code, in turn, was descended from a much older (circa 1986, according to Sullivan) X10 control project by Larry Campbell.

Due to that lineage, Heyu is today distributed under its own unique license, instead of a more common alternative like the GPL (which was first published in 1988). The Heyu license grants the user the right to copy, use, and redistribute the package, but prohibits charging money for the software, altering the license, and claiming authorship of the code, and requests that any changes made be shared with the package maintainer.

Those restrictions make it difficult if not impossible for Linux distributions to bundle official Heyu packages. Sullivan says he and Suthers have discussed migrating the project to the GPL, but thus far they have been unable to locate Campbell. If no one can find Campbell, Sullivan says, they might be able to rewrite any remaining portions of Campbell’s original code (which are few) and sidestep the licensing problem.

A little searching reveals independent binary package builds maintained by individuals for Gentoo, NetBSD, and FreeBSD, but most users of major Linux distros will need to compile Heyu from source. Fortunately, this is not hard.

The current version, 2.1.3, was released last month. There are no package dependencies to worry about; all you need to do to build the program is extract the archive to a folder, then on the command line run ./Configure (yes, with a capital C), followed by make, followed by sudo make install. By default the make install step installs the binaries and support files under /usr/local, as all good locally compiled packages should.

Configuration and basic usage

At runtime Heyu looks for a config file, first at ~/.heyu/x10config, and then at the fallback location /etc/heyu/x10.conf. The file format is the same in both locations, and you can copy the example file x10config.sample included in the archive to get started.

The two most important directives are TTY and HOUSECODE. TTY tells Heyu to which serial port the CM11A is connected. Since fewer and fewer new motherboards include more than one serial port, this is likely to be /dev/ttyS0, but you can also connect the CM11A through a USB-to-serial adapter, which will likely use /dev/ttyUSB0. The HOUSECODE directive simply indicates which X10 default housecode to send with commands. Housecodes are a letter from A to P that group a set of up to 16 modules (e.g., A1 through A16). Certain commands like “all lights on” are sent to every module in the housecode, so you can use multiple housecodes for finer-grained control.

Even if you define nothing else in the config file, you can use Heyu from the command line to send direct X10 commands. The basic syntax is heyu commandHousecodeUnitcode — so heyu on A4 will send the on command to housecode A module 4. Heyu can send more than 50 different direct commands, from the basic on, off, dim, and bright supported by even the basic X10 modules, up to the status checking and hailing commands only available in more recent, “extended” models. Read man heyu for a complete list.

You can use ALIAS directives in your x10config file to assign human-readable names to your X10 modules — for example ALIAS lava_lamp A13, or ALIAS exterior_lights C1,3,5.

Assigning aliases to devices allows you to use the human-readable names in direct commands like those discussed above, so heyu on lava_lamp and heyu on A13 are equivalent. Note that in the exterior_lights example, an ALIAS is used to specify multiple modules — in this case C1, C3, and C5. Should you add another exterior light using module C7, you need only alter the ALIAS directive in your x10config without worrying about changing it in every script and macro in which exterior_lights appears.

Scheduling

Aliases are also valuable when you’re scheduling X10 commands to upload to the CM11A’s onboard memory. You compose your schedule of recurring events in a separate file. Inside your x10config file you specify that file with the SCHEDULE_FILE directive. Then, when you execute heyu upload, Heyu reads in the schedule file, parses the aliases and macros, and uploads the raw X10 commands to the CM11A. Heyu’s example x10config includes the default SCHEDULE_FILE x10.sched, and the package includes a well-commented example x10.sched.

The basic unit of scheduling is a timer. Each timer definition has six arguments: the day-of-week mask, starting date and ending date, start time, stop time, start macro, and stop macro. The syntax is a little bit like cron syntax, but distinct enough that it requires an explanation.

The day-of-week mask is a seven-character string specifying the days of the week when the timer should be activated. Days the timer is active are filled with the first letter of the day name (i.e., smtwtfs), and days the timer is inactive are filled with a period. For example, .m.w.f.. represents Monday, Wednesday, and Friday, and s.twtfs represents every day except Monday.

The start and end dates are in MM/DD format; for a daily event 01/01-12/31 will execute the timer year-round.

At the specified start time, the CM11A will execute the specified start macro, and at the specified stop time it will execute the specified stop macro. That means each timer definition actually defines two events. Although most timers will define two related events, like turning a light on at one time and turning it off at another, the two macros could just as easily be unrelated.

A macro definition has three arguments: the macro name, a number specifying a delay in minutes, and a semicolon-separated list of X10 commands.

For example, the macro definition macro lava_on 0 on lava_lamp turns on the device aliased as lava_lamp with no delay, while the macro definition macro lava_off 15 off lava_lamp turns off the same device after waiting 15 minutes.

You can call both macros with a timer definition. timer smtwtf. 01/01-12/31 18:00 01:00 lava_on lava_off will execute the lava_on macro at 6:00 p.m. and the lava_off macro at 1:00 a.m. every Sunday, Monday, Tuesday, Wednesday, Thursday, and Friday, all year.

You can substitute the strings DAWN and DUSK for any start or end times you wish, or even simple formulae like DAWN-5 and DUSK+60. To implement this magic, Heyu calculates the sunrise and sunset times for your location, then substitutes the appropriate times when it uploads the actual commands to the CM11A. In order for this to work, you must specify your latitude and longitude in x10config. You can also append the letter s to any start or end time in order to activate security randomization, varying the actual execution time by plus or minus 30 minutes.

More options are documented inside Heyu’s example x10.sched.

Advanced usage

Heyu can do considerably more than we have room to discuss here. Recent builds have added a state engine daemon called heyu_engine that can run in the background and maintain a table of the on/off status of every X10 module on the network. If you have two-way X10 modules, they can respond to status queries from the CM11A, but heyu_engine can keep track of simpler modules (though without the guaranteed accuracy of two-way modules) based on the on and off commands it sends out to them.

This opens the door to using Heyu with all sorts of non-appliance X10 modules, such as cameras, motion detectors, and security devices that have their own status codes. You can write scripts for Heyu to execute when it receives certain codes or combinations of codes — scripts that include the execution of external commands (so you can not only tell Heyu to blink the lights in alarm when the motion detector is triggered behind the barn, but have it email you as well).

There is an active Heyu user group where Sullivan himself often answers questions. The Heyu Web site maintains a list of third-party utilities to interface Heyu with additional hardware, and the Linux Home Automation site keeps track of still others.

Although Sullivan continues to add support for new and changing X10 modules as they are released, he does not foresee any major new features coming to Heyu in the future. Users have built their own tools to make Heyu network-aware through CGI, for example, but Sullivan does not intend to make the core app networkable. Likewise, there are some third-party GUI tools, but Sullivan intends to keep Heyu command-line driven.

If you need to get control of your X10-outfitted home from your Linux desktop, Heyu provides the right balance of flexibility and simplicity.