HEYU(1)

NAME
heyu - control program for the X10 CM11A serial interface

SYNOPSIS
heyu [-v] address unit-specifier
heyu [-v] date
heyu [-v] erase
heyu [-v] function unit-specifier state
heyu [-v] info
heyu help
heyu [-v] monitor
heyu [-v] preset unit-specifier preset-dim
heyu [-v] reset [housecode]
heyu [-v] setclock
heyu [-v] status [unit-specifier]
heyu [-v] stop
heyu [-v] turn unit-specifier state [amount]
heyu [-v] upload [check]
heyu [-v] version

DESCRIPTION
heyu is a little program for controlling a X10 "CM11A" home control device. This is the control device found in the "Activehome" package from X10. The CM11A can remotely control lights and appliances in your house by signaling over the house wiring. It can respond to some X10 signals by sending out other X10 signals.

The -v option puts the program into a very verbose mode, mainly used for debugging.

Heyu depends on a config file to tell it where your CM11A is connected and what aliases you are using. It will not run without the config file. See x10config(5) for more information.

The X10 CM11A connects to a computer with an RS232 interface. It can store about 128 events; each event can turn on, turn off, or dim up to sixteen X10 modules . The CM11A box has a battery backed clock which the computer can read. The data is also battery backed.

X10 modules are identified by a one-letter housecode ranging from A to P (for 16 different codes) and a number from 1 to 16, for a total of 256 possible unit codes.

You could just put a bunch of "x10 turn" commands in your crontab, but this doesn't work if your system is down for backups, or has crashed, or if someone's tripped over the RS232 cable and unplugged it, and it clutters up your crontab something awful. For most uses, it's much easier to just load the events into the X10.

As of version 1.28, heyu will load events into the CM11A. I have established that there is no command that will dump the contents of the CM11A to the serial port. This makes it impossible to alter discrete events or macros unless the entire table is known. This means that we can't set the macros using another program (Activehome, for instance) and then add a new macro from heyu.

The timers and macros are stored in a file. The default is $HOME/.x10sched.conf. See x10sched(5) for the layout of the file.

As of version 1.6, a relay daemon is spawned that gathers the CM11A output for any process that wants it. This allows you to run monitor while sending on/off commands. Just as important is that it also catches the power fail messages and responds to it immediately.

As of version 1.34, you can use more than one CM11. Use different x10config files for each one and set the X10CONFIG environmental variable to access the second one. Version 1.34 also added the ability to send just an address or just a function. Version 1.35 added the ability to execute an external program (heyuhelper)each time an event was received or triggered. See the heyuhelper man page for more information about that.

COMMANDS

address
    Sends the specified address without a functon. This may be useful to people who have scene setting switches.

date
    Gets current date and time from CM11 and displays it in a form suitable for feeding to date(1) as input. Thus, you can set your system clock by saying "date `heyu date`". It gets the year from your local computer time. I'd not recommend using this feature.

erase
    Erases the CM11A's eeprom. All events, macro, etc are permanently gone.

function
    Sends just an on/off functon for the specified housecode. A dummy unit code is required to simplify the coding. For example, use "n1" for housecode n.

info
    Displays current setting of CM11A's clock and housecode.

help
    Displays a list of the commands that are available.

upload
    The upload command reads timers and macros from the .x10sched.conf file. If there are no errors, it will load the data into the CM11A for you. If there are errors the load will abort without changing anything. Heyu will report the macro names and memory locations as it loads. These memory locations can be used when the monitor command output shows something like: "macro executed at eeprom address 996". The upload command with the check option (heyu upload check) will check the config file and report out the macro locations. It will also print a map of what it will write to the eeprom if the environmental variable "X10DEBUG" is set, as in "X10DEBUG=1 heyu upload check".

monitor
    Monitors all events reported by the CM11A module. The output goes to stdout, so you may redirect it to a file. The events are time-stamped.

preset
    Preset dim works with 2way lamp modules like the PLM24. It allows you to specify exactly what level the light will come on to if you send a dim command.

reset
    The default action for reset is to reset the counters in the the CM11A and to set it to the default housecode. If a housecode is specified as an argument, the CM11A will be set to track state changes on that house code.

status
    Queries the module specified and reports on it's current state. This only works with certain modules, like the LM14a and RR501.

stop
    Kills the relay daemon that gathers input from the tty port. This will also cause any monitors to stop. It can only kill the processes that you have permissions to stop.

setclock
    Reads the system clock and loads it into the CM11A. This is adjusted for local daylight savings time.

turn
    Sets the specified unit to the specified state. It turns them on, off, dims or brightens them. The special names lightson, lightsoff, allon and alloff also work.

version
    Prints the version number and then exits.

-v  This option can be used before any others (heyu -v info) to print a verbose listing of what is happening.

ARGUMENTS
Most heyu commands require arguments. They are as follows:

binary-state
    binary-state is either on or off.

change-state
    change-state is either up or down followed by number of steps. You can use dim instead of down or bright instead of up.

housecode
    housecode is a letter from a-p.

preset-dim
    A preset dim falls into the range of 1 to 32. The next dim or bright command will jump to that level.

state
    state is in the form: (function) ([value])
    on
    off
    up (value)
        value is a number from 1-22
    down (value)
        value is a number from 1-22

unit-specifier
    A specifier for one or more X10 modules, in the form (housecode)(unit-number[,unit-number...]). If the x10config file is present, and contains aliases, the unit-specifier may be one of those aliases instead of (housecode)(unit-number).
    There are special aliases lightson, lightsoff, allon and alloff. These allow you to execute 'heyu turn lightson' to turn on all lights assigned to the default housecode in your x10config file.
    If you want to use a special alias with a different housecode, you would specifiy a dummy unit as in 'heyu turn d1 allon'.

unit-number
    A unit number is within the range of 1 to 16. The character '*' can be used to mean all unit numbers. One or more X10 modules is usually assigned a unit number.

EXAMPLES

heyu turn a5 on
    Turns X10 module A5 on.

heyu turn b7 down 8
    Dims X10 module B7 by 8/22 of it's total range.

heyu info
    Displays CM11A clock time, base housecode and unit status. It also has a bitmap that shows what it thinks is the state of the X10modules on the same housecode.

heyu status B1
    Returns the status of the X10 module B1 if the unit replies.

heyu stop
    Stops the relay daemon that monitors the tty port. The monitor program will also stop if you are running it. I need to stop the program before I install a new version to avoid 'text busy' messages.

heyu setclock
    Sets CM11A's clock to current (system) time of day. This is adjusted for daylight savings time.

heyu reset
    Sets the CM11A to the default housecode specified in the x10config file.
    (This does not clobber the X10 clock)

heyu reset c
    Sets the CM11A to track events on housecode C
    (This does not clobber clock)

heyu date
    Displays date in date(1) input format. The year is taken from your system clock. Please don't use this to set your computer's clock.

ENVIRONMENT
X10CONFIG - Points to a fully qualified file name of your configuration file. See x10config(5) for more information on it's makeup.
X10SCHED - Points to a fully qualified file name of your schedule file (timers, and macros). See x10sched(5) for more information on it's layout.

FILES
 .x10config - X10 unit description file
 .x10sched.conf - CM11A schedule information for timers and macros.
 /var/spool/lock/LCK..heyu.mon - lock file for monitor process
 /var/tmp/heyu.out - fifo file for relay process
 /var/tmp/heyu.write - lock file for processes that write to the CM11A

BUGS
Occasionally the interface will not accept the first command after a reboot of the CM11A or the computer. This is due to a controller in a strange state.

AUTHORS
Re-written to use the CM11A interface by Daniel B. Suthers (dbs@tanj.com). Originally written (Known as X10) by Larry Campbell (maynard!campbell). System V port, ID file, improved display formats, and other cleanup by John Chmielewski (rogue!jlc). Module aliasing additions by Paul Fox (pgf@foxharp.boston.ma.us)

SEE ALSO
ftp://www.x10-beta.com/ftp
http://heyu.tanj.com/heyu/ (faq)
http://heyu.tanj.com/heyu/protocol.txt
date(1), x10config(5), x10sched(5), heyuhelper(1)