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