xtend(1)

NAME

xtend - daemon to execute command lines based on X10 requests

SYNOPSIS

xtend [-v] [-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 commands 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. This option implies ``-b''.

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

-b: Do not put Xtend into the background (to run as a daemon).

-V: Prints version and default configuration information.

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

-h: Prints a brief help message.

COMMAND FILE FORMAT

Note that everything except the shell commands (see below) 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.

Commands are of the form <command> <argument>

Valid commands:

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 undefined, /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, as it is unnecessary.

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 commands 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:

Where:

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

<X10 command> is one of all-off, lights-on, on, off, dim, bright, statuson, statusoff, or statusrequest

<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 currently 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 appliance 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 controlling 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 people'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.

AUTHOR

David Shaw <[email protected]>

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