1 .\" Copyright (c) 1992, 1993 Eugene W. Stark
2 .\" All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
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.3 2006/02/17 19:33:32 swildner Exp $
40 .Nm /usr/libexec/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.
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.
58 startup script if enabled in
66 causes it to close and reopen its log file. This is useful
67 in shell scripts that rotate the log files to keep them from growing
73 it shuts down gracefully and exits.
78 to abort the current client connection.
81 communicates with client processes by a simple protocol in which a one-line
82 command is sent by the client, and is acknowledged by a one-line response
86 understands four types of commands:
87 .Bl -tag -width "monitor H U
91 is a single letter house code, and
93 is a numeric unit code,
96 to respond with one line of status information about the specified device.
100 is a single-letter house code,
102 is either a numeric unit code
103 or a function code (see source file
107 is a number indicating the number of times (usually 2)
108 the packet is to be transmitted without gaps,
111 to perform the specified X-10 transmission. If the transmission was apparently
112 successful, a single-line response containing
114 is issued, otherwise a single-line response containing
120 to dump the current status of all devices to an
123 directory. The response
125 is issued, regardless of whether the status dump was successful.
126 .It Ic monitor Ar H U
129 to add the current client socket connection to a list of clients that are to
130 be notified about activity concerning the specified X-10 device.
131 The single-line acknowledgement
133 is returned if the maximum (currently 5) number of such clients was not
138 then returns to its normal mode of accepting connections from clients.
139 However, each subsequent change in the status of the specified device will
142 to write one line of status information for the device (in the same
143 format as produced by the
145 command) to the saved socket. This feature is useful for writing programs
146 that need to monitor the activity of devices, like motion detectors, that can
147 perform X-10 transmissions.
152 .Bl -tag -width /var/spool/xten/status.out -compact
154 the TW523 special file
155 .It Pa /var/run/tw523
156 socket for client connections
157 .It Pa /var/run/xtend.pid
159 .It Pa /var/spool/xten/Log
161 .It Pa /var/spool/xten/Status
162 device status file (binary)
163 .It Pa /var/spool/xten/status.out
165 dump of device status
171 .An Eugene W. Stark Aq stark@cs.sunysb.edu
173 There is currently no timeout on client socket connections, so a hung
174 client program can prevent other clients from accessing the daemon.
177 does the best it can at trying to track device status, but there is
178 usually no way it can tell when a device has been operated manually.
179 This is due to the fact that most X-10 devices are not able to
180 respond to queries about their status.