Xtend Documentation

xtend(1)						 xtend(1)


NAME
       xtend  -	daemon	to  execute  command  lines based on X10
       requests

SYNOPSIS
       xtend [-v] [-f command_file] [-d debug_level] [-g] [-h]

DESCRIPTION
       xtend is a daemon that is used in combination with a CM11a
       X10  interface that hooks to one of your serial ports.  It
       executes arbitrary shell commands depending  on	what  X10
       commands it sees.

OPTIONS
       -f  command_file
	      Specifies	a  command_file  which contains the com
	      mands to execute for each X10 event.  See below for
	      the  file format.	If this option is not specified,
	      command_file defaults to ``$HOME/.xtendrc''

       -d  debug_level
	      Specifies a debug_level for program execution.  The
	      higher  this  value, the more information about the
	      program execution is sent to the	standard  output.
	      ``-d  2''	is great if you want to watch X10 events
	      as they happen.

       -v     A shortcut for ``-d 1'', the most generally  useful
	      debug level.

       -g     Prints the GNU ``copyleft'' information.

       -h     Prints a brief help message.

FILE FORMAT
       The  command_file format is made up of any number of lines
       of the form

       Note that everything except the shell  commands	are  case
       insensitive (PORT == Port == PoRt).

       A  #  character introduces a comment.  Use \# to specify a
       literal #, and \\ to specify a literal \.

       Xtend rereads its configuration file when  it  receives	a
       hangup  signal, SIGHUP.	Any line may be added, deleted or
       modified when the configuration file is reread.

       Shell  This specifies what shell will be used to run  your
	      commands.	If you don't specify one, it defaults to
	      the environment variable SHELL, or if that's  unde
	      fined, /bin/sh.

       Port   Which  serial port the CM11a is connected to.  This
	      should be something like /dev/ttyS0.  Only  one  of
	      Port and File may be defined.

       File   Which  spool  file  the CM11a data will be arriving
	      in.  This is in case more than one program wants to
	      use the CM11a and spools incoming data to a file to
	      get around the problems  with  sharing  the  serial
	      port.  (heyu(1) in particular does this.)	Only one
	      of Port and File may be defined.

       Lockdir
	      Where the normal UUCP-style lock file is generated.
	      This  defaults  to  whatever  was compiled into the
	      program  (probably  something  like  /var/lock,  or
	      /var/uucp/locks)	and should probably be left alone
	      as the default.

	      Note that if a lock file is  already  found,  Xtend
	      will not start.  However, if the existing lock file
	      is held by a non-existent (eg, dead)  process,  the
	      lock  can	be  replaced by Xtend.	This should only
	      happen if a process gets a lock but does not  clean
	      up properly after itself when it terminates.

	      If File (see above) is used, Lockdir is ignored.

       Statusfile
	      This  specifies  a  file where the current state of
	      all 256 X10 devices is to be stored.  The file will
	      always  be 512 bytes long and will never grow.  The
	      format for the file starts with A1 and goes through
	      P16,  with  each	device	taking up two bytes.  The
	      first byte can be interpreted in the  same  way  as
	      the  ENVIRONMENT	VARIABLES below.  The second byte
	      is currently reserved (and will be set to	zero  in
	      this version).

	      Be  aware of possible security implications of this
	      file - if you don't want all processes to	be  able
	      to know the status of the X10 system, make sure the
	      file is not world readable!

       Appliance
	      This marks the specified addresses as belonging  to
	      appliances  and thus when Xtend keeps track of what
	      is on and off, these addresses will ignore the "All
	      Lights On" command.  You also can't dim or brighten
	      them.

	      This is solely for the purpose of the informational
	      environment  variables  (see  ENVIRONMENT VARIABLES
	      below), and does not alter the behavior of how com
	      mands are executed.

	      It  is  permitted to repeat this line as many times
	      as necessary.

	      e.g.:

	      Appliance A1 B1

	      is the same thing as:

	      Appliance A1

	      Appliance B1

       All other lines in the file are of the form:
	      <address> <X10 command> <shell command>

	      Where:

	      <address> is the X10 address, A1 through P16.

	      <X10 command> is one  of	all-off,  lights-on,  on,
	      off, dim, bright

	      <shell  command>	is  any	command line that can be
	      passed to a shell.


ENVIRONMENT VARIABLES
       All command lines executed by Xtend have certain variables
       placed  in  their  environment.	The variables are of the
       form X10_<HOUSE><UNIT>. For example, a variable referring
       to unit B7 would be X10_B7.

       Bit 7 - On (1)/Off (0): Is the unit currently on or off?

       Bit  6 - Addressed (1) / Not Addressed (0): When X10 turns
       a group of units on at once, it "addresses"  all	of  them
       and  then  sends a command.  These are units that are cur
       rently addressed.  If an X10  command  is  sent	to  their
       house code, they will respond to it.

       Bit  5  - Appliance (1) / Light (0): Is the unit an appli
       ance or a light?	This is settable  with	the  "Appliance"
       keyword. (see above)

       A  quick way to check if a unit is "on" is to do something
       like $X10_B4>=128.  If that is true, then unit B4 is on.

       Note that if a particular variable is undefined, it should
       be treated as if it was equal to zero.

EXAMPLES
       A simple file could be:

       Shell /bin/bash

       Port /dev/ttyS0

       a1 off cat /var/tmp/hello.au > /dev/audio

       b9  off	echo  "Someone tripped the motion sensor!" | mail
       root

       a9 on ifup ppp0

       a all-off cat /var/tmp/alloff.au > /dev/audio

       a lights-on cat /var/tmp/allon.au > /dev/audio

SAFETY
       X10 is not necessarily  the  most  secure  protocol.   For
       example,	depending on the wiring in your neighborhood, if
       your next door neighbor has X10, you could end up control
       ling  each other's lights by accident.  This can be useful
       if you want this ability, but annoying if you don't.   One
       solution	is  to	use a different ``house code'' than your
       neighbor.

       Smarthome and other companies sell a signal  blocker  that
       will  prevent  X10 signals from leaking out, or other peo
       ple's signals from leaking in.

       This said, if you run Xtend as root, or	have  it  control
       something really really icky and dangerous, be careful.

       A  good	way to help prevent abuse is to put a lock around
       dangerous commands.  For example:

       d1 on touch $HOME/.lock ; sleep 10; rm $HOME/.lock

       d2 on if [ -f $HOME/.lock ]; then dangerous_command ; fi

       Once d1 is executed, you have 10 seconds	to  execute  d2.
       After the 10 seconds, d2 will not run.

SEE ALSO
       heyu(1)

AUTHOR
       David Shaw <dshaw@jabberwocky.com>

       Send  bug reports, porting experiences, and whatnot to me.
       This program is released under the GNU ``copyleft''.   Run
       xtend -g for a complete explanation.