share/man/man4/man4.i386/tw.4

   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 $
  31 .\"
  32 .Dd October 30, 1993
  33 .Dt TW 4 i386
  34 .Os
  35 .Sh NAME
  36 .Nm tw
  37 .Nd TW-523 X-10 device driver
  38 .Sh DESCRIPTION
  39 .Nm Tw
  40 is the driver for the TW-523 power line interface, for use with X-10 home
  41 control products.  The X-10 protocol is compatible with a number of home
  42 control systems, including Radio Shack ``Plug 'n Power(tm)'' and
  43 Stanley ``Lightmaker(tm).''
  44 .Pp
  45 The driver supports
  46 .Fn read
  47 .Fn write
  48 and
  49 .Fn select
  50 system calls.
  51 The driver allows multiple processes to read and write simultaneously,
  52 but there is probably not much sense in having more than one reader or more
  53 than one writer at a time, and in fact there may currently be a race
  54 condition in the driver if two processes try to transmit simultaneously
  55 (due to unsynchronized access to the sc_pkt structure in tw_sc).
  56 .Pp
  57 Transmission is done by calling
  58 .Fn write
  59 to send three byte packets of data.
  60 The first byte contains a four bit house code (0=A to 15=P).  The second byte
  61 contains a five bit unit/key code (0=unit 1 to 15=unit 16, 16=All Units Off
  62 to 31 = Status Request).  The third byte specifies the number of times the
  63 packet is to be transmitted without any gaps between successive transmissions.
  64 Normally this is 2, as per the X-10 documentation, but sometimes (e.g. for
  65 bright and dim codes) it can be another value.  Each call to
  66 .Fn write
  67 can specify
  68 an arbitrary number of data bytes, but at most one packet will actually be
  69 processed in any call.  Any incomplete packet is buffered until a subsequent
  70 call to
  71 .Fn write
  72 provides data to complete it.  Successive calls to
  73 .Fn write
  74 leave a three-cycle gap between transmissions, per the X-10 documentation.
  75 The driver transmits each bit only once per half cycle, not three times as
  76 the X-10 documentation states, because the TW523 only provides sync on
  77 each power line zero crossing.  So, the driver will probably not work
  78 properly if you have three-phase service.  Most residences use a two-wire
  79 system, for which the driver does work.
  80 .Pp
  81 Reception is done using
  82 .Fn read
  83 The driver produces a series of three
  84 character packets.  In each packet, the first character consists of flags,
  85 the second character is a four bit house code (0-15), and the third character
  86 is a five bit key/function code (0-31).  The flags are the following:
  87 .Bd -literal
  88 #define TW_RCV_LOCAL    1  /* The packet arrived during a local transmission */
  89 #define TW_RCV_ERROR    2  /* An invalid/corrupted packet was received */
  90 .Ed
  91 .Pp
  92 The
  93 .Fn select
  94 system call can be used in the usual way to determine if there
  95 is data ready for reading.
  96 .Sh SEE ALSO
  97 .Xr xten 1 ,
  98 .Xr xtend 8
  99 .Pp
 100 TW-523 documentation from X-10 Inc.
 101 .Sh FILES
 102 .Bl -tag -width /dev/tw
 103 .It Pa /dev/tw?
 104 the TW523 special file
 105 .El
 106 .Sh AUTHORS
 107 .An Eugene W. Stark Aq stark@cs.sunysb.edu