gold: Fix hardcoded library search path
[dragonfly.git] / share / man / man4 / man4.i386 / tw.4
CommitLineData
984263bc
MD
1.\" Copyright (c) 1992, 1993 Eugene W. Stark
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\" 3. All advertising materials mentioning features or use of this software
13.\" must display the following acknowledgement:
14.\" This product includes software developed by Eugene W. Stark.
15.\" 4. The name of the author may not be used to endorse or promote products
16.\" derived from this software without specific prior written permission.
17.\"
18.\" THIS SOFTWARE IS PROVIDED BY EUGENE W. STARK (THE AUTHOR) ``AS IS'' AND
19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT,
22.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
23.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
24.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28.\" SUCH DAMAGE.
29.\"
30.\" $FreeBSD: src/share/man/man4/man4.i386/tw.4,v 1.9.2.3 2001/08/17 13:08:46 ru Exp $
de023c90 31.\" $DragonFly: src/share/man/man4/man4.i386/tw.4,v 1.3 2006/08/18 01:42:58 swildner Exp $
984263bc
MD
32.\"
33.Dd October 30, 1993
34.Dt TW 4 i386
35.Os
36.Sh NAME
37.Nm tw
38.Nd TW-523 X-10 device driver
39.Sh DESCRIPTION
40.Nm Tw
41is the driver for the TW-523 power line interface, for use with X-10 home
42control products. The X-10 protocol is compatible with a number of home
43control systems, including Radio Shack ``Plug 'n Power(tm)'' and
44Stanley ``Lightmaker(tm).''
45.Pp
46The driver supports
47.Fn read
48.Fn write
49and
50.Fn select
51system calls.
52The driver allows multiple processes to read and write simultaneously,
53but there is probably not much sense in having more than one reader or more
54than one writer at a time, and in fact there may currently be a race
55condition in the driver if two processes try to transmit simultaneously
56(due to unsynchronized access to the sc_pkt structure in tw_sc).
57.Pp
58Transmission is done by calling
59.Fn write
60to send three byte packets of data.
61The first byte contains a four bit house code (0=A to 15=P). The second byte
62contains a five bit unit/key code (0=unit 1 to 15=unit 16, 16=All Units Off
63to 31 = Status Request). The third byte specifies the number of times the
64packet is to be transmitted without any gaps between successive transmissions.
65Normally this is 2, as per the X-10 documentation, but sometimes (e.g. for
66bright and dim codes) it can be another value. Each call to
67.Fn write
68can specify
69an arbitrary number of data bytes, but at most one packet will actually be
70processed in any call. Any incomplete packet is buffered until a subsequent
71call to
72.Fn write
73provides data to complete it. Successive calls to
74.Fn write
75leave a three-cycle gap between transmissions, per the X-10 documentation.
76The driver transmits each bit only once per half cycle, not three times as
77the X-10 documentation states, because the TW523 only provides sync on
78each power line zero crossing. So, the driver will probably not work
79properly if you have three-phase service. Most residences use a two-wire
80system, for which the driver does work.
81.Pp
82Reception is done using
83.Fn read
84The driver produces a series of three
85character packets. In each packet, the first character consists of flags,
86the second character is a four bit house code (0-15), and the third character
87is a five bit key/function code (0-31). The flags are the following:
88.Bd -literal
89#define TW_RCV_LOCAL 1 /* The packet arrived during a local transmission */
90#define TW_RCV_ERROR 2 /* An invalid/corrupted packet was received */
91.Ed
92.Pp
93The
94.Fn select
95system call can be used in the usual way to determine if there
96is data ready for reading.
984263bc
MD
97.Sh FILES
98.Bl -tag -width /dev/tw
99.It Pa /dev/tw?
100the TW523 special file
101.El
de023c90
SW
102.Sh SEE ALSO
103.Xr xten 1 ,
104.Xr xtend 8
105.Pp
106TW-523 documentation from X-10 Inc.
984263bc
MD
107.Sh AUTHORS
108.An Eugene W. Stark Aq stark@cs.sunysb.edu