Merge from vendor branch LIBARCHIVE:

[dragonfly.git] / usr.sbin / xten / README

Installation Notes for X-10 software
Eugene W. Stark (stark@cs.sunysb.edu)
October 30, 1993
(latest update May 29, 1997)

The TW523 is a carrier-current modem for home control/automation purposes.
It is made by:

        X-10 Inc.
        185A LeGrand Ave.
        Northvale, NJ 07647
        USA
        (201) 784-9700 or 1-800-526-0027

        X-10 Home Controls Inc.
        1200 Aerowood Drive, Unit 20
        Mississauga, Ontario
        (416) 624-4446 or 1-800-387-3346

The TW523 is designed for communications using the X-10 protocol,
which is compatible with a number of home control systems, including
Radio Shack "Plug 'n Power(tm)" and Stanley "Lightmaker(tm)."
I bought my TW523 from:

        Home Control Concepts
        9353-C Activity Road
        San Diego, CA 92126
        (619) 693-8887

They supplied me with the TW523 (which has an RJ-11 four-wire modular
telephone connector), a modular cable, an RJ-11 to DB-25 connector with
internal wiring, documentation from X-10 on the TW523 (very good),
an instruction manual by Home Control Concepts (not very informative),
and a floppy disk containing binary object code of some demonstration/test
programs and of a C function library suitable for controlling the TW523
by an IBM PC under MS-DOS (not useful to me other than to verify that
the unit worked).   I suggest saving money and buying the bare TW523
rather than the TW523 development kit (what I bought), because if you
are running FreeBSD you don't really care about the DOS binaries.
For details on the X-10 protocol itself, refer to the documentation from
X-10 Inc.

The interface to the TW-523 consists of four wires on the RJ-11 connector,
which are jumpered to somewhat more wires on the DB-25 connector, which
in turn is intended to plug into the PC parallel printer port.  I dismantled
the DB-25 connector to find out what they had done:

        Signal          RJ-11 pin       DB-25 pin(s)    Parallel Port
        Transmit TX       4 (Y)         2, 4, 6, 8      Data out
        Receive RX        3 (G)         10, 14          -ACK, -AutoFeed
        Common            2 (R)         25              Common
        Zero crossing     1 (B)         17 or 12        -Select or +PaperEnd

NOTE: In the original cable I have (which I am still using, May, 1997)
the Zero crossing signal goes to pin 17 (-Select) on the parallel port.
In retrospect, this doesn't make a whole lot of sense, given that the
-Select signal propagates the other direction.  Indeed, some people have
reported problems with this, and have had success using pin 12 (+PaperEnd)
instead.  This driver searches for the zero crossing signal on either
pin 17 or pin 12, so it should work with either cable configuration.
My suggestion would be to start by making the cable so that the zero
crossing signal goes to pin 12 on the parallel port.

I use the TW-523 and this software in the USA with 120V/60Hz power.
Phil Sampson (vk2jnt@gw.vk2jnt.ampr.org OR sampson@gidday.enet.dec.com)
in Australia has reported success in using a TW-7223 (a local version
of the TW-523) and Tandy modules with this software under 240V/50Hz power.
For reasons explained in the comments in the driver, it will probably not
work if you have three-phase power, but this is usually not the case for
normal residences and offices.


1.  Installing the TW523 Device Driver

I assume that you are running FreeBSD.  If you are running some other
system, you are more or less on your own, though I can try to help if you
have problems.

Check the configuration parameters at the beginning of the file

        /sys/i386/isa/tw.c

Probably the only thing you might need to change is to change the
definition of HALFCYCLE from 8333 to 10000 if you are using 50Hz power.
The driver assumes that the TW523 device is connected to a parallel port.
See the comments near the beginning of the file to find out where to
get a TW523 if you don't have one, and how to make a cable for it to
connect to your parallel port.

Add a line like the following

        device          tw0     at isa? port 0x278 tty irq 5

to /sys/i386/conf/YOURSYSTEM, but make sure to change the I/O port and
interrupt to match your hardware configuration.

Cd to /sys/i386/conf and do "config YOURSYSTEM".
Cd to /sys/compile/YOURSYSTEM and do "make depend", then "make".
(If you have any troubles, I suggest starting fresh by doing a full
"make clean; make depend; make".)  Assuming the make works correctly, do

        make install

(Take the usual precautions by saving a known working kernel until you
verify that the new kernel actually boots.)

Reboot the system.  You should see a line indicating that the TW523 has
been configured as the system comes up.  If you see this line, then probably
everything is going to work OK, because the TW523 will only get configured
if the driver is able to sync to the power line.  If the TW523 is not plugged
in, or the driver is not getting sync for some reason, then you won't see
any message on bootup.

NOTE:  I have received a report that some multi IDE/SIO/PARALLEL cards
"cheat" and use TTL outputs rather than pullup open collector outputs,
and this can mess up the scheme by which sync gets to the driver.
If you are having trouble getting the driver to work, you might want to
look into this possibility.

In directory /dev, execute the command

        MAKEDEV tw0


2.  Installing the X-10 Daemon

The X-10 daemon "xtend" is integrated in to the FreeBSD "/etc/sysconfig"
system configuration file.  To enable the daemon, simply edit that file,
find the "xtend" line, change it to read as below.

        # Set to YES if you want to run the X-10 power controller daemon
        xtend=YES

This will cause the X-10 daemon to be invoked automatically when you boot
the system.  To test the installation, you can either reboot now, or
you can just run "xtend" by hand.  The daemon should start up, and it should
create files in /var/spool/xten.  Check the file /var/spool/xten/Log to
make sure that the daemon started up without any errors.

Now you are ready to start trying X-10 commands.  Try doing

        xten A 1 Off
        xten A 1 On 1 Dim:10

etc.  The "xten" program expects a house code as its first argument, then
a series of key codes, which are either unit names ("1" through "16") or
else are command names.  You can find the list of command names by looking
at the table in the file "xten.c".  Each key code can optionally be followed
by a colon : then a number specifying the number of times that command is
to be transmitted without gaps between packets.  The default is 2, and this
is the normal case, but some commands like Bright and Dim are designed to
be transmitted with counts other than 2.  See the X-10 documentation for
more detail.

The "xten" program works by connecting to "xtend" through a socket, and
asking that the X-10 codes be transmitted over the TW523.  All activity
on the TW523 is logged by the daemon in /var/spool/xten/Log.  The daemon
also attempts to track the state of all devices.  (Of course, most X-10
devices do not transmit when they are operated manually, so if somebody
operates a device manually there is no way the X-10 daemon will know
about it.) 

3. Low-level Programming of the TW523 Driver

Normally, you would never operate the TW523 directly, rather you would
use the shell command "xten" or you would connect to "xtend" through its
socket.  However, if you don't want to run "xtend", you can manipulate
the TW523 directly through the device /dev/tw0.  Have a look at the
xtend code for a programming example.

The driver supports read(), write(), and select() system calls.
The driver allows multiple processes to read and write simultaneously,
but there is probably not much sense in having more than one reader or more
than one writer at a time, and in fact there may currently be a race
condition in the driver if two processes try to transmit simultaneously
(due to unsynchronized access to the sc_pkt structure in tw_sc).

Transmission is done by calling write() to send three byte packets of data.
The first byte contains a four bit house code (0=A to 15=P).  The second byte
contains five bit unit/key code (0=unit 1 to 15=unit 16, 16=All Units Off
to 31 = Status Request).  The third byte specifies the number of times the
packet is to be transmitted without any gaps between successive transmissions.
Normally this is 2, as per the X-10 documentation, but sometimes (e.g. for
bright and dim codes) it can be another value.  Each call to write can specify
an arbitrary number of data bytes, but at most one packet will actually be
processed in any call.  Any incomplete packet is buffered until a subsequent
call to write() provides data to complete it.  Successive calls to write()
leave a three-cycle gap between transmissions, per the X-10 documentation.
The driver transmits each bit only once per half cycle, not three times as
the X-10 documentation states, because the TW523 only provides sync on
each power line zero crossing.  So, the driver will probably not work
properly if you have three-phase service.  Most residences use a two-wire
system, for which the driver does work.

Reception is done using read().  The driver produces a series of three
character packets.  In each packet, the first character consists of flags,
the second character is a four bit house code (0-15), and the third character
is a five bit key/function code (0-31).  The flags are the following:

#define TW_RCV_LOCAL    1  /* The packet arrived during a local transmission */
#define TW_RCV_ERROR    2  /* An invalid/corrupted packet was received */

The select() system call can be used in the usual way to determine if there
is data ready for reading.


                                                Happy Controlling!
                                                Gene Stark
                                                stark@cs.sunysb.edu


Appendix.  Miscellaneous Additional Information

The following excerpts from my E-mail correspondence may be relevant
to some situations:


From: Steve Passe
Subject: Re: tw woes 
Date: Sat, 09 Dec 1995 20:57:15 -0700

Hi,

I have just verified that /dev/tw works on 2.1.0-RELEASE.  I can
send and receive x10 commands via my x10 daemon and X11 based tools.

I used a "cross-over" cable between tw523 and db-25 connector:

  |||||-----------|||||
   \                 /

NOTE: I am NOT using the RadioShack brand of hood:

looking at INSIDE of hood:

----------
|        |
|        |
|  B G B |  < Black, Green, Blue
| W R Y  |  < White, Red, Yellow
| |||||| |
| |||||| |
| |||||| |
|        |
|        |
|        |
----------

OUTSIDE:

 Hood                   TW523
----------             ------------------
|        |             |                |
|        |             |                |
| ------ |             |    +------+    |
| |||||| |             |    | |||| |    |
| |||||| |             |    | |||| |    |
| --  -- |             |    +--  --+    |
|  |  |  |             |      |  |      |
|   --   |             |       --       |
|        |             |                |
|        |             |    1 2 3 4     |
----------             ------------------
 Y G R B                    B R G Y
 | | | |                    | | | |
 | | | |--------------------| | | |
 | | |------------------------| | |
 | |----------------------------| |
 |--------------------------------|

Be sure that the tw523 is NOWHERE NEAR a surge protector.  I have seen
x-10 devices fail to work when plugged in NEXT to a surge protector!


I placed the tw option before the lpt entries in my config file: 

device          tw0     at isa? port 0x378 tty irq 7
device          lpt0    at isa? port? tty irq 7

from dmesg I get:

Dec  9 19:11:59 ilsa /kernel: tw0 at 0x378-0x37f irq 7 on isa
Dec  9 19:11:59 ilsa /kernel: lpt0 not probed due to I/O address conflict with 
tw0 at 0x378

Once I have opened /dev/tw with my daemon I get messages 
 (pressing UNIT J, key 16):

Dec  9 20:18:26 ilsa /kernel: TWRCV: valid packet: (22, 1f8) J 16
Dec  9 20:18:26 ilsa /kernel: TWRCV: valid packet: (22, 1f8) J 16

These messages from the driver should be dis-abled once you get it working,
you'll fill up the var partition with a lot of useless garbage otherwise!



From: Steve Passe
Subject: Re: tw woes 
Date: Sat, 16 Dec 1995 11:56:59 -0700

Hi,

I now more or less understand the set of problems concerning cabling
for using /dev/tw and a tw523.  Summary:


 1: modular cables come in 2 flavors:

|||||----------|||||            <- "phone" cable
 \                /

                  \
|||||----------|||||            <- "data" cable
 \

 we need to be able to clearly differentiate the two.  I suggest we
 standardize on using "phone" cables only.


 2: modular db25 connectors ARE NOT CONSISTANT in their color code
    scheme, EVEN within the same BRAND!

 we can't describe the connection in terms of cable/connector wire color.
 we must clearly explain the consequences of mis-connection: 
 POSSIBLE damage to (but NOT limited to) the parallel port and/or tw523.


 3: not all parallel ports have pullups on their status inputs.  I found
    2 different port boards in my junk box without pullups on paper-out.
    As is, these boards failed to work, ie the probe routine failed.
    By adding 10K pullup resistors (to +5v) to both ACK and paper-out
    (pins 10 & 12) I was able to make these boards work: probe succeeds,
    transmit and receive work reliably.

 we must describe a test to determine if a parallel port will work as is.
 perhaps something like:

--------------------------------------------------------------------------
Not a parallel ports will work with the connector described in this paper.
To test your port for usability you should take the following measurements
with a voltmeter.  The computer must be powered-up, and preferably in
a safe state for tinkering, such as halted in a startup menu. Nothing
should be attached to the parallel ports, except perhaps an extension
cable for testing convenience.

 1: measure the voltage between pins 10 & 25 (GND) of the parallel port.

 2: measure the voltage between pins 12 & 25 (GND) of the parallel port.

If both of these measurements have a value of >= 4.0 volts your port
should work as is.  If either is below 4.0 volts (typically less than
1.0 volt) your port will NOT WORK RELIABLY as is.  It can be made to 
work by adding 10k ohm pull-up resistors to either line that is below
the minimum 4.0 volts.  This is an ADVANCED TECHNIQUE that should NOT
be attempted by anyone without some hardware construction experience.

Assuming that you do feel competant to make these modifications it is
easiest to tack 10k resistors on the bottom side of the port board
from each of pins 10 & 12 of the parallel port connector to a source
of +5 volts.  This will probably be the power pin of one of the ICs.
CAUTION: there may also be +-12 volts on a port board supplying some
of the ICs.  If your port is on your motherboard it would probably be
best to obtain an external port card, and disable/re-address the 1st
parallel port.
--------------------------------------------------------------------------