mirror of
https://git.FreeBSD.org/src.git
synced 2024-12-25 11:37:56 +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>
223 lines
9.6 KiB
Plaintext
223 lines
9.6 KiB
Plaintext
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
|