.\" Copyright (c) 1992, 1993 Eugene W. Stark
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by Eugene W. Stark.
.\" 4. The name of the author may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY EUGENE W. STARK (THE AUTHOR) ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/share/man/man4/man4.i386/tw.4,v 1.9.2.3 2001/08/17 13:08:46 ru Exp $
.\" $DragonFly: src/share/man/man4/man4.i386/tw.4,v 1.3 2006/08/18 01:42:58 swildner Exp $
.\"
.Dd October 30, 1993
.Dt TW 4 i386
.Os
.Sh NAME
.Nm tw
.Nd TW-523 X-10 device driver
.Sh DESCRIPTION
.Nm 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).''
.Pp
The driver supports
.Fn read
.Fn write
and
.Fn 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).
.Pp
Transmission is done by calling
.Fn 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
.Fn 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
.Fn write
provides data to complete it.  Successive calls to
.Fn 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.
.Pp
Reception is done using
.Fn 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:
.Bd -literal
#define TW_RCV_LOCAL	1  /* The packet arrived during a local transmission */
#define TW_RCV_ERROR	2  /* An invalid/corrupted packet was received */
.Ed
.Pp
The
.Fn select
system call can be used in the usual way to determine if there
is data ready for reading.
.Sh FILES
.Bl -tag -width /dev/tw
.It Pa /dev/tw?
the TW523 special file
.El
.Sh SEE ALSO
.Xr xten 1 ,
.Xr xtend 8
.Pp
TW-523 documentation from X-10 Inc.
.Sh AUTHORS
.An Eugene W. Stark Aq stark@cs.sunysb.edu