dd5527c607
Use the .Tn macro for generic FreeBSD references. Cleanup other formatting problems noticed while making the above changes.
112 lines
4.4 KiB
Groff
112 lines
4.4 KiB
Groff
.\" 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.
|
|
.\"
|
|
.\" $Id: tw.4,v 1.6 1997/02/22 13:25:43 peter Exp $
|
|
.\"
|
|
.Dd Oct 30, 1993
|
|
.Dt TW 4 i386
|
|
.Os FreeBSD
|
|
.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:
|
|
.Bl -diag
|
|
.It
|
|
#define TW_RCV_LOCAL 1 /* The packet arrived during a local transmission */
|
|
.It
|
|
#define TW_RCV_ERROR 2 /* An invalid/corrupted packet was received */
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fn select
|
|
system call can be used in the usual way to determine if there
|
|
is data ready for reading.
|
|
.Sh SEE ALSO
|
|
.Xr xten 1 ,
|
|
.Xr xtend 8
|
|
.Bl -diag
|
|
.It
|
|
TW-523 documentation from X-10 Inc.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /dev/tw
|
|
.It Pa /dev/tw?
|
|
the TW523 special file
|
|
.El
|
|
.Sh AUTHOR
|
|
Eugene W. Stark (stark@cs.sunysb.edu)
|