HEYU (version 1) Program overview

                   Installing Heyu on a Unix-like system.

This program operates an X10 module via a CM11A computer interface. It is

based on the program X10 by Larry Cambell as modified by Paul Fox. All but a

Heyu requires a reasonable compiler (GCC works well), the 'make' program,

few functions have been changed enough that they no longer interwork with

and the development header (.h) files.  Many OS distributions will either

the original. I think this justifies issuing the program as 'heyu' instead

install these by default or provide a visible option to include the

of 'x10'.

"development package" during OS installation.  But some of the newer OS's

do not, e.g., with Ubuntu Linux it's necessary to afterward execute the

The program name comes from the old joke about having a 3rd person in the

command 'apt-get install build-essential'. 

house. Ida No was the one frequently blamed when things went wrong. In my

house it was the frequently heard yells of "Heyu! Turn off the lights!"

Note: If you're upgrading from a previous version of Heyu, run 'heyu stop'

A poor joke, but I like it.

under that version before proceeding.

The program is strictly command line driven, and works well with crontab.

Quickstart:

Crontab can be used to schedule events. You can also upload timers and

    sh ./Configure.sh [option] (As a normal user)

macros to the CM11's memory.

    make                       (As a normal user)

    su                         (Become superuser)

The program comes complete with source code, sample config files, MAN pages

    make install            (As superuser)

an executable binary. The program has options to allow you to:

    exit                       (Revert to normal user)

    heyu info               (As a normal user, to test installation)

   * Get the date and time from the interface

   * Get information about current settings and module states

(The 'make install' requires that you have write permissions to

   * Turn an X10 module on or off

/usr/local/bin, man page, and other directories.)

   * Dim or brighten an X10 module

   * Monitor all data sent to or from the CM11A

Ubuntu Linux users should execute 'sudo make install' rather than

   * Get the status of intelligent X10 modules (rr501 for instance)

the three commands 'su', 'make install', and 'exit'.

   * Set the X10 clock from the computer's clock (time and date)

   * Zero out the macro and event memory of the X10

*** Kindly report any compile errors or warnings to the author.***

   * Upload macros and timers

   * preset the dim level of advanced two way devices

It can take 5-8 seconds to set up the heyu_relay daemon and initialize

the CM11A interface the first time Heyu is run, e.g., with 'heyu info'.

As of version 1.27, Heyu has the ability to send a schedule of events to the

CM11A. This enables timers and macros.

Running 'heyu help' will display the long list of Heyu commands.

These are further explained in the man page heyu(1).

The people at X10 have informed me that there is no way to download (to the

computer) the events stored in the CM11A. That being the case, I wrote

CUSTOMIZING

programs that will load the events and macros from local data files. This

-----------

will erase whatever has been stored there, but I guess that's the way it has

The Configure.sh script creates a Makefile by running 'uname -s' and then

to be.

passing known good options to Autoconf configure script.  The contents

of Makefile.in is then expanded to the Makefile.  Changes to the makefile

This should compile on any Linux system. It should also compile on any other

should be made in Configure.sh or Makefile.in.

BSDish or SYSV system. Just edit the #define in the make file. Make install

will try to install the man page and the program. The makefile has defines

If Configure.sh can not figure out what your system is, you can try

for these locations.

sh ./Configure.sh generic

    or

See the original README in Larry Campbell's program for some nice info on

sh ./Configure.sh sysv

the cp290 and the history of the program. See the original for some really

niffty uses using scheduling and macros.

If those don't work, we'll have to figure it out by hand. Please contact

the author so your discoveries can be integrated into the next release.

There are two demo programs included with heyu, monit and x10biff.

SERIAL PORTS

   * The monit program will turn off your monitor based on idle time. It's

------------

     the ultimate screen saver.

Many newer computers don't have built-in RS232 serial ports, only USB

   * The x10biff program will flash a light to let you know that you have

ports.  For these computers a USB-Serial adapter is required to connect

     E-mail.

the CM11A.  Before purchasing a USB-Serial adapter, verify that the driver

for your OS is available, either built-in to the OS, provided with the

Daniel B. Suthers, CCP, CSP

adapter on a companion disc, or downloadable from the adapter

12-31-1996

manufacturer's website.

Updated 12-12-1999

E-mail: dbs@tanj.com

If you have a choice, select an adapter with an FTDI chipset over one

uucp: pacbell!daver!dansst!dbs

with a Prolific chipset.  One dealer who specifies the chipset

and supported operating systems for each adapter model for sale is

ByteRunner (http://ww.byterunner.com).

Drivers for adapters with a Prolific PL2303 chipset can often be found

at http://www.prolific.com.tw/eng/downloads.asp?ID=31

For Linux, the serial device name for a USB-Serial adapter will normally

be /dev/ttyUSBx, where x = 0 for the first adapter plugged into the

USB port and higher numbers for subsequent adapters.

Note: The International 230V version of the CM11 sold in Europe and

elsewhere is now usually provided with a USB cable in addition to the

standard RS232 cable.  Many Linux users have experienced lockups and

other problem with this USB cable (based on a Prolific chipset) which

disappeared when they switched to a regular USB-Serial adapter.

OPTIONS

------- 

By default, Heyu allocates space for 32 common flags, 32 counters, and

32 user countdown timers.  The number of each of these can be increased

at compile time with switches -flags=NN, -counters=NN, and -timers=NN.

The specified NN must be in the range 1-1024 and will be rounded up to

the nearest multiple of 32, e.g.,

   sh ./Configure.sh -flags=64  -timers=75

will allocate space for 64 flags and 96 timers, the latter because

the specified 75 is rounded up to 96.  The number of counters will

remain 32.

By default, support for the X10 CM17A "Firecracker" device is compiled

into Heyu.  As there is no known version of this device available which

transmits at frequencies other than the 310 MHz used for transceivers

in North America, users outside this region may wish to compile without

CM17A support. Since the CM17A is both powered and actuated by the DTR

and RTS serial lines, support for this device might as well also be

omitted if your serial port hardware does not support these lines.

To do so, run the Configure.sh step mentioned above with the '-nocm17a'

switch, i.e.,

    sh ./Configure.sh -nocm17a

By default, support for Extended Type 0 (Shutter and Shade) commands

is compiled into Heyu.  As there is only one module known to support

these commands (the 230V, 50Hz Marmitek SW10 Shutter Motor Controller

sold in Europe), this support may be omitted by using Configure.sh with

the '-noext0' switch, i.e., 

   sh ./Configure.sh -noext0

By default, support for RFXSensors is compiled into Heyu. RFXSensors

require a WGL W800RF32 or RFXCOM X10 RF receiver as well as a RFXSensor

transmitter.  This support may be omitted by including the '-norfxs'

switch with Configure.sh, i.e.,

   sh ./Configure.sh -norfxs

By default, support for RFXMeters is compiled into Heyu. RFXMeters

requires a 433.92 MHz RFXCOM X10 RF receiver as well as the RFXMeter

transmitter.  This support may be omitted by including the '-norfxm' switch

with Configure.sh, i.e.,

   sh ./Configure.sh -norfxm

By default, support for the Digimax 210 remote thermostat is compiled

into Heyu. The Digimax requires a 433.92 MHz RFXCOM X10 RF receiver as

well as the Digimax transmitter.  This support may be omitted by

including the '-nodmx' switch with Configure.sh, i.e.,

   sh ./Configure.sh -nodmx

By default, support for Oregon RF sensors is compilied into Heyu.

Oregon sensor support requires a 433.92 MHz RFXCOM X10 RF receiver

as well as a supported model of Oregon sensor.  This support may be

omitted by including the '-noore' switch with Configure.sh, i.e.,

   sh ./Configure.sh -noore

By default, support for signals received from KaKu and HomeEasy

transmitters is compiled into Heyu.  KaKu/HomeEasy support requires a

433.92 MHz RFXCOM X10 RF receiver.  This support may be omitted

by including the '-nokaku' switch with Configure.sh, i.e.,

   sh ./Configure.sh -nokaku

By default, support for RFXLAN RF receiver (network version of RFXCOM)

is compiled into Heyu.  This support may be omitted by including the

'-norfxlan' switch with Configure.sh, i.e.,

   sh ./Configur.sh -norfxlan

Notes for Mac OS X:

-------------------

The heyu executable is installed in directory /usr/local/bin, which

is not on the Mac's default PATH.  You will have to add this directory

to your $PATH.  Similarly you may have to add the man page directory

/usr/local/man to your $MANPATH (or the /usr/share/misc/man.conf file

for newer versions of OS X which have deprecated $MANPATH).

Newer Macs don't have an actual RS232 serial port, only a USB port,

and a USB/Serial adapter is required.  The manufacturer's adapter

driver will usually add two or more different devices in /dev

(and often with "usbserial" as part of the name).  You'll have

to experiment to see which one works with Heyu by trying the

different names in the TTY directive in the heyu configuration

file.  The device name which also includes "cu" rather than "tty"

has been found to work on the (few) Macs tested thusfar.

Notes for AT&T SysV r4:

----------------------

The function uname(1) used to determine the system type for

Configure.sh does not distinguish this OS from other sysv systems.

Supply the system type parameter "attsvr4" to Configure.sh, i.e.,

run 'sh ./Configure.sh attsvr4'.

Notes for OpenSolaris:

---------------------

The directories in which the Heyu binary executable and man pages

are installed are set per the OpenSolaris system conventions to:

  BIN = /opt/heyu/bin

  MAN = /opt/heyu/man/man1

  MAN5 = /opt/heyu/man/man5

However for a virgin OS installation, none of these directories

are on the system's PATH/MANPATH and the user is responsible

for adding them to the PATH/MANPATH in order to have full use of

Heyu.

The user may alternatively rerun Configure.sh for "OpenSolaris_BSD",

i.e., 'sh ./Configure.sh opensolaris_bsd',

which will set the directories using the BSD convention under

the /usr/local tree, which however may be deleted when OpenSolaris

is upgraded.

Some older versions of OpenSolaris, in particular SXCE (Solaris

Express Community Edition), may encounter an error when running

'make install' like "test: argument expected".  If this occurs,

change the first line of file install.sh to read "#!/bin/ksh".