From 9a6f00fd3980c97d7b1351b46cbad4fd08e557f8 Mon Sep 17 00:00:00 2001 From: "Jordan K. Hubbard" Date: Tue, 18 Apr 1995 01:57:50 +0000 Subject: [PATCH] Extensive updates to this package. Moved Install.notes -> README, as ratified at the core meeting of April 13th. Submitted by: Gene Stark --- usr.sbin/xten/Makefile | 2 +- usr.sbin/xten/README | 222 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 223 insertions(+), 1 deletion(-) create mode 100644 usr.sbin/xten/README diff --git a/usr.sbin/xten/Makefile b/usr.sbin/xten/Makefile index cc7baeae3e41..6300ec9effed 100644 --- a/usr.sbin/xten/Makefile +++ b/usr.sbin/xten/Makefile @@ -2,7 +2,7 @@ PROG= xten SRCS= xten.c -CFLAGS+=-I. -I${.CURDIR}/../../libexec/xtend +CFLAGS+=-I. -I/usr/src/libexec/xtend MAN1= xten.1 diff --git a/usr.sbin/xten/README b/usr.sbin/xten/README new file mode 100644 index 000000000000..9725ba402b58 --- /dev/null +++ b/usr.sbin/xten/README @@ -0,0 +1,222 @@ +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