libexec/xtend/xtend.8

   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/libexec/xtend/xtend.8,v 1.11.2.4 2001/08/16 10:44:22 ru Exp $
  31 .\"
  32 .Dd October 30, 1993
  33 .Dt XTEND 8
  34 .Os
  35 .Sh NAME
  36 .Nm xtend
  37 .Nd X-10 daemon
  38 .Sh SYNOPSIS
  39 .Nm /usr/libexec/xtend
  40 .Sh DESCRIPTION
  41 .Nm Xtend
  42 interfaces between user-level programs and the TW523 X-10 controller.
  43 It logs all packets received from the TW523, attempts to track the
  44 status of all X-10 devices, and accepts socket connections from user-level
  45 client programs that need to manipulate X-10 devices.
  46 .Pp
  47 When
  48 .Nm
  49 is started, it forks, releases the controlling terminal, then opens
  50 its log file, where it subsequently records all X-10 activity and
  51 diagnostic messages.  It then begins processing packets received from
  52 the TW523 and accepting connections one at a time from clients
  53 wishing to issue X-10 commands.
  54 .Nm Xtend
  55 is started from
  56 .Pa /etc/rc.i386
  57 startup script if enabled in
  58 .Pa /etc/rc.conf
  59 script.
  60 .Pp
  61 Sending
  62 .Nm
  63 a
  64 .Dv SIGHUP
  65 causes it to close and reopen its log file.  This is useful
  66 in shell scripts that rotate the log files to keep them from growing
  67 indefinitely.
  68 If
  69 .Nm
  70 receives a
  71 .Dv SIGTERM ,
  72 it shuts down gracefully and exits.
  73 A
  74 .Dv SIGPIPE
  75 causes
  76 .Nm
  77 to abort the current client connection.
  78 .Pp
  79 .Nm Xtend
  80 communicates with client processes by a simple protocol in which a one-line
  81 command is sent by the client, and is acknowledged by a one-line response
  82 from the daemon.
  83 .Pp
  84 .Nm Xtend
  85 understands four types of commands:
  86 .Bl -tag -width "monitor H U
  87 .It Ic status Ar H U
  88 where
  89 .Ar H
  90 is a single letter house code, and
  91 .Ar U
  92 is a numeric unit code,
  93 causes
  94 .Nm
  95 to respond with one line of status information about the specified device.
  96 .It Ic send Ar H U N
  97 where
  98 .Ar H
  99 is a single-letter house code,
 100 .Ar U
 101 is either a numeric unit code
 102 or a function code (see source file
 103 .Pa xtend/packet.c )
 104 for a list, and
 105 .Ar N
 106 is a number indicating the number of times (usually 2)
 107 the packet is to be transmitted without gaps,
 108 causes
 109 .Nm
 110 to perform the specified X-10 transmission.  If the transmission was apparently
 111 successful, a single-line response containing
 112 .Sy OK
 113 is issued, otherwise a single-line response containing
 114 .Sy ERROR
 115 is produced.
 116 .It Ic dump
 117 causes
 118 .Nm
 119 to dump the current status of all devices to an
 120 .Tn ASCII
 121 file in the spool
 122 directory.  The response
 123 .Sy OK
 124 is issued, regardless of whether the status dump was successful.
 125 .It Ic monitor Ar H U
 126 causes
 127 .Nm
 128 to add the current client socket connection to a list of clients that are to
 129 be notified about activity concerning the specified X-10 device.
 130 The single-line acknowledgement
 131 .Sy OK
 132 is returned if the maximum (currently 5) number of such clients was not
 133 exceeded, otherwise
 134 .Sy ERROR
 135 is returned.
 136 .Nm Xtend
 137 then returns to its normal mode of accepting connections from clients.
 138 However, each subsequent change in the status of the specified device will
 139 cause
 140 .Nm
 141 to write one line of status information for the device (in the same
 142 format as produced by the
 143 .Ic status
 144 command) to the saved socket.  This feature is useful for writing programs
 145 that need to monitor the activity of devices, like motion detectors, that can
 146 perform X-10 transmissions.
 147 .El
 148 .Sh OPTIONS
 149 None.
 150 .Sh SEE ALSO
 151 .Xr xten 1 ,
 152 .Xr tw 4
 153 .Sh FILES
 154 .Bl -tag -width /var/spool/xten/status.out -compact
 155 .It Pa /dev/tw0
 156 the TW523 special file
 157 .It Pa /var/run/tw523
 158 socket for client connections
 159 .It Pa /var/run/xtend.pid
 160 pid file
 161 .It Pa /var/spool/xten/Log
 162 log file
 163 .It Pa /var/spool/xten/Status
 164 device status file (binary)
 165 .It Pa /var/spool/xten/status.out
 166 .Tn ASCII
 167 dump of device status
 168 .El
 169 .Sh BUGS
 170 There is currently no timeout on client socket connections, so a hung
 171 client program can prevent other clients from accessing the daemon.
 172 .Pp
 173 .Nm Xtend
 174 does the best it can at trying to track device status, but there is
 175 usually no way it can tell when a device has been operated manually.
 176 This is due to the fact that most X-10 devices are not able to
 177 respond to queries about their status.
 178 .Sh AUTHORS
 179 .An Eugene W. Stark Aq stark@cs.sunysb.edu