The functionality of this package is based on the freely available
X10 shar archive that is often talked about on comp.home.automation newsgroup
This package requires that you have at least one CP290 interface module
and at least one X10 appliance module.
Both are available relatively cheaply from Advanced Services Inc.
	32 Court Street
	Box 3871
	Plymouth, MA 02361
	800-263-8608

	CP290 - $39.50
	AM466 - $10.95 ea


There are several programs incorporated into this archive

1) a standalone C program that you can use to turn on and off x10 devices (x10)
2) a shared object library that one can use to link into Tcl for easy
   access to a GUI (libx10.so)
3) a sample Tcl GUI application (powergui) using #2
4) a sample Tcl command line application using #2


The simplest of these is the C program

usage:
	x10 [-d device] -z <zone> -c <code#> -a <on|off>

	by default it looks for a /dev/x10 device. You can either set it up
	and link it to the serial port where you cp290 is attached, or you
	can use the -d to specify the serial port directly

	zone is one of 16 zones (a-p)
	code is one of 16 codes (1-16)

	each appliance module can have any code an zone you select. There
	are two dials on the front that can be turned with a flat-head
	screwdriver.


I put a lot of time and functionality into the Tcl interface, so that's
where I'm going to concentrate here.  I believe usage by example is the
best way to explain this, so let's get started.

	#INSTALLING#

First, you must make and install. Edit the Makefile and modify it
to suit your configuration.  The code itself should be portable. The
flags for building position independent code and linking shared object
libraries may vary from machine to machine. For those machines that do
not have any shared object library mechanism, you will have to link in
the x10.o and tclx10.o files directly into your tclsh executable.
(e.g. some NetBSD versions).  For instructions on how to do this, I
refer you to the Tcl books. Brent Welch and John Ousterhout explain
this in detail.

After you build the share object library, do a make install to update
your package index and copy the library into place. You may need root
access to do this.

	#USAGE#

% package require X10		
# This command loads the shared object library and sets up the aliases.
# If you have an .x10rc file, it sources it

% set cp290 [x10 init]
% $cp290 configure -device /dev/ttyb
# This configures a new x10 handle - not bound to a device
# The second command takes care of the binding the handle to a device

% set cp290 [x10 init /dev/ttyb]
# This command takes care of opening the handle and binding it to
# a device in one swell foop

% $cp290 configure -device /dev/ttyc
# This will close any opened device and bind the handle to a new
# x10 interface on /dev/ttyc. It will initialize the handle if no
# previous interface was bound.

% $cp290 configure -basezone b
# The cp290 has 8 rocker switches on the front. The basezone command
# controls which zone these rocker switches send signals to. You can
# set the basezone to anything from a to p. The rocker switches then
# can be used to control devices in that zone

% x10 alias light {a 4}
# Setup an alias so that the host 'light' corresponds to zone a, device 4
% x10 alias light
a 4
# This shows the alias corresponding to light
% x10 alias
light dark midnight twilight
# This shows all of the aliases currently setup

% x10 list
{xten0 /dev/ttyb}
{xten1 /dev/ttyc}
# This command shows all of the currently setup x10 session and what
# serial ports they are bound to

% xten0 light off
# Turn off the light device on handle xten0
% xten1 dark on
# Turn on the dark device on handle xten1
% xten0 a 3 on
# Turn on the module associated with zone a, code 3


# This covers the basics. You should now be able to mostly understand the
# Tcl 'power' and the 'powergui' programs included here. 
 
	#USING .x10rc#

The .x10rc file is automatically sourced (from your home directory) when
you load the X10 package. This makes it possible to simplify your alias
and device setup and provides good separation of your code from your
data.

Take a look at the .x10rc file provided here. It is used by us for
powergui. The gui program has no clue how many devices there are when
it starts. It just does an x10 alias to list all the aliases and
dynamically builds a GUI based upon that.

	#Callbacks#

It is also possible to use the rocker switches and have them update
the GUI dynamically.

% xten0 configure -command <cmdproc> <args>

cmdproc is then called (a Tcl procedure that you device) with 4 arguments.
zone, device, action, and optional arguments (args from above)
action is either on or off, and all arguments you specify when creating
the command are passed as one argument to the procedure which you can
then use the standard Tcl list utilities to process. See the 'callme'
procedure in powergui for an example of how this works.