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