HEYU (version 1) Program overview

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
few functions have been changed enough that they no longer interwork with
the original. I think this justifies issuing the program as 'heyu' instead
of 'x10'.

The program name comes from the old joke about having a 3rd person in the
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!"
A poor joke, but I like it.

The program is strictly command line driven, and works well with crontab.
Crontab can be used to schedule events. You can also upload timers and
macros to the CM11's memory.

The program comes complete with source code, sample config files, MAN pages
an executable binary. The program has options to allow you to:

   * Get the date and time from the interface
   * Get information about current settings and module states
   * Turn an X10 module on or off
   * Dim or brighten an X10 module
   * Monitor all data sent to or from the CM11A
   * Get the status of intelligent X10 modules (rr501 for instance)
   * Set the X10 clock from the computer's clock (time and date)
   * Zero out the macro and event memory of the X10
   * Upload macros and timers
   * preset the dim level of advanced two way devices

As of version 1.27, Heyu has the ability to send a schedule of events to the
CM11A. This enables timers and macros.

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
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
to be.

This should compile on any Linux system. It should also compile on any other
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
for these locations.

See the original README in Larry Campbell's program for some nice info on
the cp290 and the history of the program. See the original for some really
niffty uses using scheduling and macros.

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

   * The monit program will turn off your monitor based on idle time. It's
     the ultimate screen saver.
   * The x10biff program will flash a light to let you know that you have
     E-mail.

Daniel B. Suthers, CCP, CSP
12-31-1996
Updated 12-12-1999
E-mail: dbs@tanj.com
uucp: pacbell!daver!dansst!dbs

                   Installing Heyu on a Unix-like system.

(This file is duplicated as both INSTALL and README.INSTALL, in the
event your case-insensitive file system overwrites INSTALL with the
install script.)

Heyu requires a reasonable compiler (GCC works well), the 'make' program,
and the development header (.h) files.  Many OS distributions will either
install these by default or provide a visible option to include the
"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
command 'apt-get install build-essential'.

Note: If you're upgrading from a previous version of Heyu, run 'heyu stop'
under that version before proceeding.

Quickstart:
    sh ./Configure  [option]   (As a normal user)
    make                       (As a normal user)
    su                         (Become superuser)
    make install 	       (As superuser)
    exit                       (Revert to normal user)
    heyu info		       (As a normal user, to test installation)

(The 'make install' requires that you have write permissions to
/usr/local/bin, man page, and other directories.)

Ubuntu Linux users should execute 'sudo make install' rather than
the three commands 'su', 'make install', and 'exit'.

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

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'.

Running 'heyu help' will display the long list of Heyu commands.
These are further explained in the man page heyu(1).

CUSTOMIZING
-----------
The Configure script creates a Makefile by running 'uname -s' and then
adding known good configuration options to the Makefile.  The contents
of Makefile.in is then appended to the Makefile.  Changes to the makefile
should be made in Configure or Makefile.in.

If Configure can not figure out what your system is, you can try
sh ./Configure generic
    or
sh ./Configure sysv

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.

SERIAL PORTS
------------
Many newer computers don't have built-in RS232 serial ports, only USB
ports.  For these computers a USB-Serial adapter is required to connect
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
adapter on a companion disc, or downloadable from the adapter
manufacturer's website.

If you have a choice, select an adapter with an FTDI chipset over one
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 -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 step mentioned above with the '-nocm17a'
switch, i.e.,

    sh ./Configure -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 with
the '-noext0' switch, i.e.,

   sh ./Configure -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, i.e.,

   sh ./Configure -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, i.e.,

   sh ./Configure -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, i.e.,

   sh ./Configure -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, i.e.,

   sh ./Configure -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, i.e.,

   sh ./Configure -nokaku


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 does not distinguish this OS from other sysv systems.
Supply the system type parameter "attsvr4" to Configure, i.e.,
run 'sh ./Configure 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 for "OpenSolaris_BSD", i.e.,
  sh ./Configure 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".

Note for CM10A (IBM HD16) owners:

For Heyu to support the CM10A, you must append
the keyword CM10A to the TTY directive in your
Heyu configuration file, e.g.,
  TTY  /dev/ttyS0  CM10A

For this change to become fully effective it must
be incorporated in the heyu_relay process running in
the background.  If the heyu_relay is currently running
(almost any Heyu command will have started it running),
this requires stopping and restarting Heyu, e.g.,
  heyu stop
  heyu cm10a_init

Heyu Webhook Information
-------------------------
Heyu's webhook command allows information about Heyu's configuration to be
displayed in a variety of user-defined formats which will hopefully
be useful for writers of web interfaces and other front end software for
Heyu.

Usage: heyu webhook <option> -L[fmt] -d|D[fmt] -m|M[fmt] -b[fmt] -ce[list] -nb<path> [category]

Options:
  pathinfo      Display pathspecs for Heyu config and log files.
  helpinfo      Display available help menu commands
  config_dump   Display display configuration file directives.
  flaginfo      Display flags, czflags, or tzflags as long ASCII bitmap.
  flagbankinfo  Display flags, czflags, or tzflags as multiple banks of 32.
  maskinfo      Display masks for environment variable X10_Hu
  flagmaskinfo  Display masks for environment variable X10_Hu_vFlags
  fileinfo      Deprecated - use pathinfo
  menuinfo      Deprecated - use helpinfo

Switches:
  -L         Prefix with formatted line number in configuration file.
  -d |-D     Display formatted directive label in lower | upper case.
  -m |-M     Format multiple directive label numbering beginning with 0 | 1
  -b         Format body of directive.
  -ce<list>  Characters in <list> are escaped in SCRIPT command lines.
  -nb<path>  Substitute <path> for logfile path if none defined.

The format specification %V must appear once in each format string ([fmt]),
where it will be replaced as appropriate by the line number, directive label,
label number, or directive body.

Categories for config_dump:
  alias
  usersyn
  scene
  script
  other    (Everything other than the above directives.)
  <blank>  (Everything).

Categories for pathinfo:
  conf     Pathspec for Heyu configuration file
  log      Pathspec for Heyu log file.
  <blank>  Both of the above;

Categories for flaginfo and flagbankinfo:
  flags    Common flags.
  czflags  Counter-zero flags
  tzflags  Timer-zero flags

The "helpinfo" option displays the individual help menus available,
which will vary according to the Configure options selected when
Heyu is compiled.  The help menues will only be of interest for an
interface which provides a Heyu command line.

The switches can define a format for each of the parts of a directive
in the configuration file.  Without a format suffix, the switches have
a default format.  Each defined switch format must contain the symbol
%V which is replaced at output by the particular part of the directive.
Note: Format characters which have special meaning to the shell have to
be escaped, e.g., '"', '$', '(', ')', and probably others.

If no switches are specified, the directive is displayed as the directive
label in lower case followed by a single-blank separated list of the
other tokens in the directive as they appear in the configuration file,
e.g.,
  heyu webhook config_dump alias
yields:
  alias porch_light A7 StdWS

The -L switch prefixes the line with the line number in the configuration
file, e.g.,
  heyu webhook config_dump -L alias

yields with the default format "%V: ":
  26: alias porch_light A7 StdWS

whereas switch -L%V# would yield:
  26#alias porch_light A7 StdWS

The -d or -D switch determines the case of the directive label, lower or
upper respectively.  A format suffix allows the displayed label to be
expanded, e.g.,
  heyu webhook config_dump -DHEYU_%V alias

yields:
  HEYU_ALIAS porch_light A7 StdWS

The -m or -M switch appends a sequential number to the directive label
for those directives which can appear multiple times in the configuration
file.  The numbering starts with 0 for -m or with 1 for -M.  These switches
are ignored for directives which can only appear once, e.g., TTY, in the
config file. The default format is "[%V]", which for:
  heyu webhook config_dump -m alias

yields:
  alias[0] porch_light A7 StdWS

whereas:
  heyu webhook config_dump -M%V alias

would yield:
  alias1 porch_light A7 StdWS

The -b switch specifies the format for the body of the directive, i.e., all
that follows the directive label.  The default is just " %V" (which is the
same as omitting the switch).  However:
  heyu webhook config_dump -b" = \"%V\"" alias

yields:
  alias = "porch_light A7 StdWS"

An exception to the single-blank spacing of tokens is the command line
tail of a SCRIPT directive.  The command line tail is displayed as-is
since the spaces may be significant.  But certain characters in the
command line may need to be escaped to avoid conflict with the body
format.

The -ce<list> switch ("command-line escape") will result in each
command line character in the <list> suffix to be escaped.  E.g.,
for the directive:
  script a7 on :: echo "Porch Light has been turned ON"

Executing:
  heyu webhook config_dump -b" = \"%V\"" -ce"\""

yields
  script = "a7 on :: echo \"Porch Light has been turned ON\""

Example:
  heyu webhook config_dump -L"%V: " -dheyu_%V -m\(%V\) -b=\"%V\" alias

yields:
 13: heyu_alias(2)="porch_light A7 StdWS"

The -nb<path> switch ("null body") substitutes <path> for the logfile
path when directive LOG_DIR is omitted from the configuration file and
the default logfile path "/dev/null" may be difficult to deal with.

The options fileinfo and menuinfo were provided for a specific PHP
script.  They exist for backward compatibility but are deprecated.
They can be replaced by pathinfo and helpinfo as follows:
For fileinfo, use:
  heyu webhook pathinfo -d\$heyu_%V -b"=\"%V\";" -nb/tmp/
For menuinfo, use:
  heyu webhook helpinfo -d\$%V_menu -m[%V] -b"=\"/heyu/help %V\";"

Notes:
Obsolete configuration directives are omitted from config_dump.
(Heyu displays a warning message when they are encountered in the
configuration file.)

The syntax for aliases in Heyu version 1 used no ALIAS directive,
merely a line with the alias label, housecode, and unit.  While this
syntax is still supported in Heyu version 2, config_dump will not
include these aliases in the alias category.

BACKWARD COMPATIBILITY ISSUES FOR HEYU VERSION 2

Configuration file
------------------
Heyu version 2 can use an existing Heyu configuration file
from version 1 (~/.x10config or /etc/x10.conf) provided
it is renamed and moved to the new location where Heyu
version 2 expects to find it - either "~/.heyu/x10config"
or "/etc/heyu/x10.conf" (notice the 'dot' changes).
There are a number of new configuration options for
version 2 that the user may then want to add, which are
explained in both the x10config.5 man page and in the
example file "x10config.sample" provided.  Of course
for some users it may be more convenient to simply rename
and modify the "x10config.sample" file.

In operation, Heyu version 2 must write some files in
the same directory as the configuration file, so this
directory must be writeable.

Schedule file
-------------
In most cases an existing schedule file used for Heyu
version 1 will work in version 2, however dawn/dusk
related events are now handled directly by the Heyu
program and the old 'makesched' utility is no longer
used.  The default name for the schedule file is now
x10.sched and Heyu version 2 will expect to find it
in the same directory as the configuration file.
(Its name can be changed via the configuration file.)

Under Heyu version 2, the CM11A clock is maintained
on Local Standard Time throughout the year.  Events
in the schedule file are assumed to be Local Civil
Time (i.e., Wall Clock Time) and Heyu automatically
adjusts them during periods of Daylight Saving Time.
Heyu version 2 automatically sets the CM11A clock
to the correct time (derived from the system clock)
when a schedule is uploaded or when the 'heyu setclock'
command is executed.


Warning
-------
Users running a dual-boot system with MS-Windows
should read the warning in the x10config.5 man page
about running X10's ActiveHome software while booted
into Windows if the CM11A has been programmed under
Unix/Linux by Heyu with certain configuration options.