TW(4)

NAME
tw - TW-523 X-10 device driver

DESCRIPTION
Tw is the driver for the TW-523 power line interface, for use with X-10 home control products. The X-10 protocol is compatible with a number of home control systems, including Radio Shack ``Plug 'n Power(tm)'' and Stanley ``Lightmaker(tm).''

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

SEE ALSO
xten(1), xtend(8)

TW-523 documentation from X-10 Inc.

FILES

/dev/tw?
    the TW523 special file

AUTHOR
Eugene W. Stark (stark@cs.sunysb.edu)