DESCRIPTION
-----------

BottleRocket is an interface to the X10 FireCracker home automation
kit.  The FireCracker kit consists of a dongle-like RF transmitter
that connects to the serial port of a PC, and a receiver that plugs
into a wall socket and intercepts the signals, passing them on
through house wiring to other units that turn appliances on/off or
dim/brighten lamps.  It doesn't support any kind of 2-way
communication, unlike some of the other X10 products.

This is version 0.04c; it includes changes for better timing (ideas
taken from "firecracker" by Chris Yokum) and support for machines with
no proper DTR, as well as restoring the states of the lines mucked
with (apparently this caused havoc with some UPSes).  Also support
for Solaris was added.

Need to tweak timing parameters in older versions should be fixed now.
However, still, if you have problems, increase the delay values (they're
different from the older ones, but same idea) in br_cmd.c.

Starting with 0.04, BottleRocket incorporates a bunch of code by Ashley Clark
(aclark@ghoti.org) for better x10-amh compatability, somewhat cleaner code,
multiple device selection and getopt_long support (at least for Linux).
Auto configuration support added by David Anderson to make it easier to set
things up on different systems.  Also added support for a slower but more
reliable delay between outgoing bits; should work better for non-x86
based machines (there's a line to uncomment in the Makefile for this).
If you do get this working on something that's not Intel, please drop me
a note and let me know.

A problem has also been fixed whereby any user with serial port access through
br could have error/info from bottlerocket output to any device plugged in
through the transmitter.  However, there's still no way to guarantee a user
can't cause a modem plugged in through the transmitter to drop carrier.

Thanks to Warner Losh for portability/security info.

Also thanks to Christian Gafton for bug fixes and cleanup in 0.04a.

Version 0.03 started the x10-amh compatability and nicer serial port usage
as well as the ability to repeat commands, and environment/command line
selectable port (for root, at least). 0.03a was a bugfix release.

Version 0.02 moved command handling into its own file so it can be linked
into other things.  0.02a and 0.02b were bug fixes.

This version has accidentally been tested while my modem was online, and
everything worked just fine.  I still wouldn't suggest it though.


FILES
-----

README   - you're looking at it.

Makefile - decided to add one of these to make things easier now that
           there is more than one file in the collection

br.c     - The command line interface; uses the br_cmd stuff (below)
           to carry out commands.

br_cmd.c - Functions for executing X10 comands using the FireCracker
           home automation system.  Basically only one function you
           need in this: x10_br_out which takes the file descriptor
           of the serial port to which the Dynamite interface is
           connected, an address (high 4 bits correspond to the letter
           of the device address, lower 4 correspond to the numeric
           part) and a command (these are defined in br_cmd.h; valid
           commands are ON, OFF, DIM and BRIGHT).  Note that you should
           set the address to 0 if you're using DIM and BRIGHT.

br_cmd.h - The file you should include to make use of br_cmd.c.  It
           holds the numeric IDs of the commands.

br_translate.h - Translation tables used by br_cmd to build commands.
                 You shouldn't have to mess with this unless you're
                 messing around with innards.  Doesn't need to be
                 #included by other programs to use br_cmd stuff.


COMPILING
---------
Change to the bottlerocket directory and type "make".  That's it.


RUNNING
-------

Use is simple.  Just run BottleRocket with the address of the unit
you want to control and the command you want it to execute.  Note
that dim/brighten are only able to address a whole letter group
of units at a time, so only the letter portion should be specified
on the command line for these commands.

e.g.

br A6 on      -- turns on appliance set to be unit "A6"
br P dim      -- dims last selected lamp set to housecode "P"

Also, Ashley Clark has given me code for x10-amh compatability so you can
do things like:

br -c A -f 1,2,3,4,5,6 -n 7

to turn off units 1-6 and unit 7 on.  All 'on' commands will be executed
before 'off', and 'dim' comes last, so br -c A -f 1 -n 1 will turn
A1 on then off.

Note:  You generally have to be root to run this, as it requires
       serial port access.

THE INTERFACE
-------------
The interface is really pretty simple; just wiggle the RTS and DTR lines
on a serial port and the little box hooked up to your machine will
transmit signals to another little box that routes the signal to where
it should go (if everything works).  The module is made as a pass-thru
kind of thing, and X10 claims that you can hook up other serial devices to
the same port without a problem, but I wouldn't suggest it (at least if
you're using any kind of hardware handshaking, or have a modem that will
drop carrier if it loses DTR... those lines are actually generally pretty
nice to have working without someone jittering bits down them)...

CONTACTING ME
-------------

If you have ideas/comments/code/bug reports, email me at tymm@acm.org.