mirror of
https://github.com/freebsd/freebsd-src.git
synced 2024-12-05 16:39:31 +00:00
9a6f00fd39
Moved Install.notes -> README, as ratified at the core meeting of April 13th. Submitted by: Gene Stark <gene@starkhome.cs.sunysb.edu> |
||
---|---|---|
.. | ||
Install.notes | ||
Makefile | ||
README | ||
xten.1 | ||
xten.c |
Installation Notes for X-10 software Eugene W. Stark (stark@cs.sunysb.edu) October 30, 1993 The TW523 is a carrier-current modem for home control/automation purposes. It is made by: X-10 Inc. 185A LeGrand Ave. Northvale, NJ 07647 USA (201) 784-9700 or 1-800-526-0027 X-10 Home Controls Inc. 1200 Aerowood Drive, Unit 20 Mississauga, Ontario (416) 624-4446 or 1-800-387-3346 The TW523 is designed for communications using the X-10 protocol, which is compatible with a number of home control systems, including Radio Shack "Plug 'n Power(tm)" and Stanley "Lightmaker(tm)." I bought my TW523 from: Home Control Concepts 9353-C Activity Road San Diego, CA 92126 (619) 693-8887 They supplied me with the TW523 (which has an RJ-11 four-wire modular telephone connector), a modular cable, an RJ-11 to DB-25 connector with internal wiring, documentation from X-10 on the TW523 (very good), an instruction manual by Home Control Concepts (not very informative), and a floppy disk containing binary object code of some demonstration/test programs and of a C function library suitable for controlling the TW523 by an IBM PC under MS-DOS (not useful to me other than to verify that the unit worked). I suggest saving money and buying the bare TW523 rather than the TW523 development kit (what I bought), because if you are running 386BSD you don't really care about the DOS binaries. For details on the X-10 protocol itself, refer to the documentation from X-10 Inc. The interface to the TW-523 consists of four wires on the RJ-11 connector, which are jumpered to somewhat more wires on the DB-25 connector, which in turn is intended to plug into the PC parallel printer port. I dismantled the DB-25 connector to find out what they had done: Signal RJ-11 pin DB-25 pin(s) Parallel Port Transmit TX 4 (Y) 2, 4, 6, 8 Data out Receive RX 3 (G) 10, 14 -ACK, -AutoFeed Common 2 (R) 25 Common Zero crossing 1 (B) 17 -Select Input I use the TW-523 and this software in the USA with 120V/60Hz power. Phil Sampson (vk2jnt@gw.vk2jnt.ampr.org OR sampson@gidday.enet.dec.com) in Australia has reported success in using a TW-7223 (a local version of the TW-523) and Tandy modules with this software under 240V/50Hz power. For reasons explained in the comments in the driver, it will probably not work if you have three-phase power, but this is usually not the case for normal residences and offices. 1. Installing the TW523 Device Driver I assume that you are running FreeBSD. If you are running some other system, you are more or less on your own, though I can try to help if you have problems. Check the configuration parameters at the beginning of the file /sys/i386/isa/tw.c Probably the only thing you might need to change is to change the definition of HALFCYCLE from 8333 to 10000 if you are using 50Hz power. The driver assumes that the TW523 device is connected to a parallel port. See the comments near the beginning of the file to find out where to get a TW523 if you don't have one, and how to make a cable for it to connect to your parallel port. Add a line like the following device tw0 at isa? port 0x278 tty irq 5 vector twintr to /sys/i386/conf/YOURSYSTEM, but make sure to change the I/O port and interrupt to match your hardware configuration. Cd to /sys/i386/conf and do "config YOURSYSTEM". Cd to /sys/compile/YOURSYSTEM and do "make depend", then "make". (If you have any troubles, I suggest starting fresh by doing a full "make clean; make depend; make".) Assuming the make works correctly, do mv /386bsd /386bsd.old mv 386bsd /386bsd (If you are not a trusting person, or you don't have any spare fixit floppies with working kernels lying around, don't do this without testing the kernel first by copying it to a fixit floppy and booting from that.) Reboot the system. You should see a line indicating that the TW523 has been configured as the system comes up. If you see this line, then probably everything is going to work OK, because the TW523 will only get configured if the driver is able to sync to the power line. If the TW523 is not plugged in, or the driver is not getting sync for some reason, then you won't see any message on bootup. NOTE: I have received a report that some multi IDE/SIO/PARALLEL cards "cheat" and use TTL outputs rather than pullup open collector outputs, and this can mess up the scheme by which sync gets to the driver. If you are having trouble getting the driver to work, you might want to look into this possibility. In directory /dev, execute the command MAKEDEV tw0 2. Installing the X-10 Daemon Go to the xten source directory (probably /usr/src/contrib/xten). Check over the file "paths.h", if desired, to make sure that the entries are reasonable for your system. On my system, I have a special UID "xten" for the daemon. If you want to do this, too, you will have to add this UID to your /etc/master.passwd in the usual way. Otherwise, use "root" or "daemon" or something. You should change the ownership of /dev/tw0 to match this UID, so that the daemon will be able to access the TW-523. Edit the file Makefile.inc in the source directory to specify this UID: xtenuser= xten Then run "make". If everything is OK, run make install This should install the daemon "xtend" and the command "xten". Make sure the directory /var/spool/xten exists and is owned by the UID you selected above. This directory is used by the daemon for its log and device status files. When it is run, the daemon will also create a socket /var/run/tw523 and it will put its pid in /var/run/xtend.pid so that it can be signalled from shell scripts. Add the following lines to your /etc/rc.local file: if [ -x /usr/libexec/xtend ]; then echo -n ' xtend'; /usr/libexec/xtend fi This will cause the X-10 daemon to be invoked automatically when you boot the system. To test the installation, you can either reboot now, or you can just run "xtend" by hand. The daemon should start up, and it should create files in /var/spool/xten. Check the file /var/spool/xten/Log to make sure that the daemon started up without any errors. Now you are ready to start trying X-10 commands. Try doing xten A 1 Off xten A 1 On 1 Dim:10 etc. The "xten" program expects a house code as its first argument, then a series of key codes, which are either unit names ("1" through "16") or else are command names. You can find the list of command names by looking at the table in the file "xten.c". Each key code can optionally be followed by a colon : then a number specifying the number of times that command is to be transmitted without gaps between packets. The default is 2, and this is the normal case, but some commands like Bright and Dim are designed to be transmitted with counts other than 2. See the X-10 documentation for more detail. The "xten" program works by connecting to "xtend" through a socket, and asking that the X-10 codes be transmitted over the TW523. All activity on the TW523 is logged by the daemon in /var/spool/xten/Log. The daemon also attempts to track the state of all devices. (Of course, most X-10 devices do not transmit when they are operated manually, so if somebody operates a device manually there is no way the X-10 daemon will know about it.) 3. Low-level Programming of the TW523 Driver Normally, you would never operate the TW523 directly, rather you would use the shell command "xten" or you would connect to "xtend" through its socket. However, if you don't want to run "xtend", you can manipulate the TW523 directly through the device /dev/tw0. Have a look at the xtend code for a programming example. The driver supports read(), write(), and select() system calls. The driver allows multiple processes to read and write simultaneously, but there is probably not much sense in having more than one reader or more than one writer at a time, and in fact there may currently be a race condition in the driver if two processes try to transmit simultaneously (due to unsynchronized access to the sc_pkt structure in tw_sc). Transmission is done by calling write() to send three byte packets of data. The first byte contains a four bit house code (0=A to 15=P). The second byte contains five bit unit/key code (0=unit 1 to 15=unit 16, 16=All Units Off to 31 = Status Request). The third byte specifies the number of times the packet is to be transmitted without any gaps between successive transmissions. Normally this is 2, as per the X-10 documentation, but sometimes (e.g. for bright and dim codes) it can be another value. Each call to write can specify an arbitrary number of data bytes, but at most one packet will actually be processed in any call. Any incomplete packet is buffered until a subsequent call to write() provides data to complete it. Successive calls to write() leave a three-cycle gap between transmissions, per the X-10 documentation. The driver transmits each bit only once per half cycle, not three times as the X-10 documentation states, because the TW523 only provides sync on each power line zero crossing. So, the driver will probably not work properly if you have three-phase service. Most residences use a two-wire system, for which the driver does work. Reception is done using read(). The driver produces a series of three character packets. In each packet, the first character consists of flags, the second character is a four bit house code (0-15), and the third character is a five bit key/function code (0-31). The flags are the following: #define TW_RCV_LOCAL 1 /* The packet arrived during a local transmission */ #define TW_RCV_ERROR 2 /* An invalid/corrupted packet was received */ The select() system call can be used in the usual way to determine if there is data ready for reading. Happy Controlling! Gene Stark stark@cs.sunysb.edu