gold: Fix hardcoded library search path
[dragonfly.git] / usr.sbin / xten / README
1 Installation Notes for X-10 software
2 Eugene W. Stark (stark@cs.sunysb.edu)
3 October 30, 1993
4 (latest update May 29, 1997)
5
6 The TW523 is a carrier-current modem for home control/automation purposes.
7 It is made by:
8
9         X-10 Inc.
10         185A LeGrand Ave.
11         Northvale, NJ 07647
12         USA
13         (201) 784-9700 or 1-800-526-0027
14
15         X-10 Home Controls Inc.
16         1200 Aerowood Drive, Unit 20
17         Mississauga, Ontario
18         (416) 624-4446 or 1-800-387-3346
19
20 The TW523 is designed for communications using the X-10 protocol,
21 which is compatible with a number of home control systems, including
22 Radio Shack "Plug 'n Power(tm)" and Stanley "Lightmaker(tm)."
23 I bought my TW523 from:
24
25         Home Control Concepts
26         9353-C Activity Road
27         San Diego, CA 92126
28         (619) 693-8887
29
30 They supplied me with the TW523 (which has an RJ-11 four-wire modular
31 telephone connector), a modular cable, an RJ-11 to DB-25 connector with
32 internal wiring, documentation from X-10 on the TW523 (very good),
33 an instruction manual by Home Control Concepts (not very informative),
34 and a floppy disk containing binary object code of some demonstration/test
35 programs and of a C function library suitable for controlling the TW523
36 by an IBM PC under MS-DOS (not useful to me other than to verify that
37 the unit worked).   I suggest saving money and buying the bare TW523
38 rather than the TW523 development kit (what I bought), because if you
39 are running FreeBSD you don't really care about the DOS binaries.
40 For details on the X-10 protocol itself, refer to the documentation from
41 X-10 Inc.
42
43 The interface to the TW-523 consists of four wires on the RJ-11 connector,
44 which are jumpered to somewhat more wires on the DB-25 connector, which
45 in turn is intended to plug into the PC parallel printer port.  I dismantled
46 the DB-25 connector to find out what they had done:
47
48         Signal          RJ-11 pin       DB-25 pin(s)    Parallel Port
49         Transmit TX       4 (Y)         2, 4, 6, 8      Data out
50         Receive RX        3 (G)         10, 14          -ACK, -AutoFeed
51         Common            2 (R)         25              Common
52         Zero crossing     1 (B)         17 or 12        -Select or +PaperEnd
53
54 NOTE: In the original cable I have (which I am still using, May, 1997)
55 the Zero crossing signal goes to pin 17 (-Select) on the parallel port.
56 In retrospect, this doesn't make a whole lot of sense, given that the
57 -Select signal propagates the other direction.  Indeed, some people have
58 reported problems with this, and have had success using pin 12 (+PaperEnd)
59 instead.  This driver searches for the zero crossing signal on either
60 pin 17 or pin 12, so it should work with either cable configuration.
61 My suggestion would be to start by making the cable so that the zero
62 crossing signal goes to pin 12 on the parallel port.
63
64 I use the TW-523 and this software in the USA with 120V/60Hz power.
65 Phil Sampson (vk2jnt@gw.vk2jnt.ampr.org OR sampson@gidday.enet.dec.com)
66 in Australia has reported success in using a TW-7223 (a local version
67 of the TW-523) and Tandy modules with this software under 240V/50Hz power.
68 For reasons explained in the comments in the driver, it will probably not
69 work if you have three-phase power, but this is usually not the case for
70 normal residences and offices.
71
72
73 1.  Installing the TW523 Device Driver
74
75 I assume that you are running FreeBSD.  If you are running some other
76 system, you are more or less on your own, though I can try to help if you
77 have problems.
78
79 Check the configuration parameters at the beginning of the file
80
81         /sys/i386/isa/tw.c
82
83 Probably the only thing you might need to change is to change the
84 definition of HALFCYCLE from 8333 to 10000 if you are using 50Hz power.
85 The driver assumes that the TW523 device is connected to a parallel port.
86 See the comments near the beginning of the file to find out where to
87 get a TW523 if you don't have one, and how to make a cable for it to
88 connect to your parallel port.
89
90 Add a line like the following
91
92         device          tw0     at isa? port 0x278 tty irq 5
93
94 to /sys/i386/conf/YOURSYSTEM, but make sure to change the I/O port and
95 interrupt to match your hardware configuration.
96
97 Cd to /sys/i386/conf and do "config YOURSYSTEM".
98 Cd to /sys/compile/YOURSYSTEM and do "make depend", then "make".
99 (If you have any troubles, I suggest starting fresh by doing a full
100 "make clean; make depend; make".)  Assuming the make works correctly, do
101
102         make install
103
104 (Take the usual precautions by saving a known working kernel until you
105 verify that the new kernel actually boots.)
106
107 Reboot the system.  You should see a line indicating that the TW523 has
108 been configured as the system comes up.  If you see this line, then probably
109 everything is going to work OK, because the TW523 will only get configured
110 if the driver is able to sync to the power line.  If the TW523 is not plugged
111 in, or the driver is not getting sync for some reason, then you won't see
112 any message on bootup.
113
114 NOTE:  I have received a report that some multi IDE/SIO/PARALLEL cards
115 "cheat" and use TTL outputs rather than pullup open collector outputs,
116 and this can mess up the scheme by which sync gets to the driver.
117 If you are having trouble getting the driver to work, you might want to
118 look into this possibility.
119
120
121 2.  Installing the X-10 Daemon
122
123 The X-10 daemon "xtend" is integrated in to the FreeBSD "/etc/sysconfig"
124 system configuration file.  To enable the daemon, simply edit that file,
125 find the "xtend" line, change it to read as below.
126
127         # Set to YES if you want to run the X-10 power controller daemon
128         xtend=YES
129
130 This will cause the X-10 daemon to be invoked automatically when you boot
131 the system.  To test the installation, you can either reboot now, or
132 you can just run "xtend" by hand.  The daemon should start up, and it should
133 create files in /var/spool/xten.  Check the file /var/spool/xten/Log to
134 make sure that the daemon started up without any errors.
135
136 Now you are ready to start trying X-10 commands.  Try doing
137
138         xten A 1 Off
139         xten A 1 On 1 Dim:10
140
141 etc.  The "xten" program expects a house code as its first argument, then
142 a series of key codes, which are either unit names ("1" through "16") or
143 else are command names.  You can find the list of command names by looking
144 at the table in the file "xten.c".  Each key code can optionally be followed
145 by a colon : then a number specifying the number of times that command is
146 to be transmitted without gaps between packets.  The default is 2, and this
147 is the normal case, but some commands like Bright and Dim are designed to
148 be transmitted with counts other than 2.  See the X-10 documentation for
149 more detail.
150
151 The "xten" program works by connecting to "xtend" through a socket, and
152 asking that the X-10 codes be transmitted over the TW523.  All activity
153 on the TW523 is logged by the daemon in /var/spool/xten/Log.  The daemon
154 also attempts to track the state of all devices.  (Of course, most X-10
155 devices do not transmit when they are operated manually, so if somebody
156 operates a device manually there is no way the X-10 daemon will know
157 about it.) 
158
159 3. Low-level Programming of the TW523 Driver
160
161 Normally, you would never operate the TW523 directly, rather you would
162 use the shell command "xten" or you would connect to "xtend" through its
163 socket.  However, if you don't want to run "xtend", you can manipulate
164 the TW523 directly through the device /dev/tw0.  Have a look at the
165 xtend code for a programming example.
166
167 The driver supports read(), write(), and select() system calls.
168 The driver allows multiple processes to read and write simultaneously,
169 but there is probably not much sense in having more than one reader or more
170 than one writer at a time, and in fact there may currently be a race
171 condition in the driver if two processes try to transmit simultaneously
172 (due to unsynchronized access to the sc_pkt structure in tw_sc).
173
174 Transmission is done by calling write() to send three byte packets of data.
175 The first byte contains a four bit house code (0=A to 15=P).  The second byte
176 contains five bit unit/key code (0=unit 1 to 15=unit 16, 16=All Units Off
177 to 31 = Status Request).  The third byte specifies the number of times the
178 packet is to be transmitted without any gaps between successive transmissions.
179 Normally this is 2, as per the X-10 documentation, but sometimes (e.g. for
180 bright and dim codes) it can be another value.  Each call to write can specify
181 an arbitrary number of data bytes, but at most one packet will actually be
182 processed in any call.  Any incomplete packet is buffered until a subsequent
183 call to write() provides data to complete it.  Successive calls to write()
184 leave a three-cycle gap between transmissions, per the X-10 documentation.
185 The driver transmits each bit only once per half cycle, not three times as
186 the X-10 documentation states, because the TW523 only provides sync on
187 each power line zero crossing.  So, the driver will probably not work
188 properly if you have three-phase service.  Most residences use a two-wire
189 system, for which the driver does work.
190
191 Reception is done using read().  The driver produces a series of three
192 character packets.  In each packet, the first character consists of flags,
193 the second character is a four bit house code (0-15), and the third character
194 is a five bit key/function code (0-31).  The flags are the following:
195
196 #define TW_RCV_LOCAL    1  /* The packet arrived during a local transmission */
197 #define TW_RCV_ERROR    2  /* An invalid/corrupted packet was received */
198
199 The select() system call can be used in the usual way to determine if there
200 is data ready for reading.
201
202
203                                                 Happy Controlling!
204                                                 Gene Stark
205                                                 stark@cs.sunysb.edu
206
207
208 Appendix.  Miscellaneous Additional Information
209
210 The following excerpts from my E-mail correspondence may be relevant
211 to some situations:
212
213
214 From: Steve Passe
215 Subject: Re: tw woes 
216 Date: Sat, 09 Dec 1995 20:57:15 -0700
217
218 Hi,
219
220 I have just verified that /dev/tw works on 2.1.0-RELEASE.  I can
221 send and receive x10 commands via my x10 daemon and X11 based tools.
222
223 I used a "cross-over" cable between tw523 and db-25 connector:
224
225   |||||-----------|||||
226    \                 /
227
228 NOTE: I am NOT using the RadioShack brand of hood:
229
230 looking at INSIDE of hood:
231
232 ----------
233 |        |
234 |        |
235 |  B G B |  < Black, Green, Blue
236 | W R Y  |  < White, Red, Yellow
237 | |||||| |
238 | |||||| |
239 | |||||| |
240 |        |
241 |        |
242 |        |
243 ----------
244
245 OUTSIDE:
246
247  Hood                   TW523
248 ----------             ------------------
249 |        |             |                |
250 |        |             |                |
251 | ------ |             |    +------+    |
252 | |||||| |             |    | |||| |    |
253 | |||||| |             |    | |||| |    |
254 | --  -- |             |    +--  --+    |
255 |  |  |  |             |      |  |      |
256 |   --   |             |       --       |
257 |        |             |                |
258 |        |             |    1 2 3 4     |
259 ----------             ------------------
260  Y G R B                    B R G Y
261  | | | |                    | | | |
262  | | | |--------------------| | | |
263  | | |------------------------| | |
264  | |----------------------------| |
265  |--------------------------------|
266
267 Be sure that the tw523 is NOWHERE NEAR a surge protector.  I have seen
268 x-10 devices fail to work when plugged in NEXT to a surge protector!
269
270
271 I placed the tw option before the lpt entries in my config file: 
272
273 device          tw0     at isa? port 0x378 tty irq 7
274 device          lpt0    at isa? port? tty irq 7
275
276 from dmesg I get:
277
278 Dec  9 19:11:59 ilsa /kernel: tw0 at 0x378-0x37f irq 7 on isa
279 Dec  9 19:11:59 ilsa /kernel: lpt0 not probed due to I/O address conflict with 
280 tw0 at 0x378
281
282 Once I have opened /dev/tw with my daemon I get messages 
283  (pressing UNIT J, key 16):
284
285 Dec  9 20:18:26 ilsa /kernel: TWRCV: valid packet: (22, 1f8) J 16
286 Dec  9 20:18:26 ilsa /kernel: TWRCV: valid packet: (22, 1f8) J 16
287
288 These messages from the driver should be dis-abled once you get it working,
289 you'll fill up the var partition with a lot of useless garbage otherwise!
290
291
292
293 From: Steve Passe
294 Subject: Re: tw woes 
295 Date: Sat, 16 Dec 1995 11:56:59 -0700
296
297 Hi,
298
299 I now more or less understand the set of problems concerning cabling
300 for using /dev/tw and a tw523.  Summary:
301
302
303  1: modular cables come in 2 flavors:
304
305 |||||----------|||||            <- "phone" cable
306  \                /
307
308                   \
309 |||||----------|||||            <- "data" cable
310  \
311
312  we need to be able to clearly differentiate the two.  I suggest we
313  standardize on using "phone" cables only.
314
315
316  2: modular db25 connectors ARE NOT CONSISTANT in their color code
317     scheme, EVEN within the same BRAND!
318
319  we can't describe the connection in terms of cable/connector wire color.
320  we must clearly explain the consequences of mis-connection: 
321  POSSIBLE damage to (but NOT limited to) the parallel port and/or tw523.
322
323
324  3: not all parallel ports have pullups on their status inputs.  I found
325     2 different port boards in my junk box without pullups on paper-out.
326     As is, these boards failed to work, ie the probe routine failed.
327     By adding 10K pullup resistors (to +5v) to both ACK and paper-out
328     (pins 10 & 12) I was able to make these boards work: probe succeeds,
329     transmit and receive work reliably.
330
331  we must describe a test to determine if a parallel port will work as is.
332  perhaps something like:
333
334 --------------------------------------------------------------------------
335 Not a parallel ports will work with the connector described in this paper.
336 To test your port for usability you should take the following measurements
337 with a voltmeter.  The computer must be powered-up, and preferably in
338 a safe state for tinkering, such as halted in a startup menu. Nothing
339 should be attached to the parallel ports, except perhaps an extension
340 cable for testing convenience.
341
342  1: measure the voltage between pins 10 & 25 (GND) of the parallel port.
343
344  2: measure the voltage between pins 12 & 25 (GND) of the parallel port.
345
346 If both of these measurements have a value of >= 4.0 volts your port
347 should work as is.  If either is below 4.0 volts (typically less than
348 1.0 volt) your port will NOT WORK RELIABLY as is.  It can be made to 
349 work by adding 10k ohm pull-up resistors to either line that is below
350 the minimum 4.0 volts.  This is an ADVANCED TECHNIQUE that should NOT
351 be attempted by anyone without some hardware construction experience.
352
353 Assuming that you do feel competant to make these modifications it is
354 easiest to tack 10k resistors on the bottom side of the port board
355 from each of pins 10 & 12 of the parallel port connector to a source
356 of +5 volts.  This will probably be the power pin of one of the ICs.
357 CAUTION: there may also be +-12 volts on a port board supplying some
358 of the ICs.  If your port is on your motherboard it would probably be
359 best to obtain an external port card, and disable/re-address the 1st
360 parallel port.
361 --------------------------------------------------------------------------
362
363