SPX10S1(1) SPX10S1(1) NAME spx10S1 - serial port ttyS1 X10 communication SYNOPSIS spx10S1 [-d device] [-f dbfilename] [-i infilename] [-l lockfile] [-o outfilename] [-q queryfilename] [-V] [-v] DESCRIPTION Spx10S1 is for asynchronous raw serial port communication with the X10 CM17A Computer Interface and MR26A RF Receiver used in many home automation systems. The program is intended to provide simple and reliable serial port communication between a computer running Linux and the X10 CM17A, (e.g., "Firecracker,") Computer Interface and MR26A RF Receiver, (both on the same port, /dev/ttyS1,) and allows X10 devices to be controlled, and monitored, via RF transmission by the computer, (the X10 UR81A Universal Remote, often distributed with the MR26A is supported, also.) The default port is /dev/ttyS1 at 9600 baud. The default semaphore lock file is /var/lock/LCK..ttyS1, which has an fcntl(2) advisory lock applied. The serial port is controlled through termios(3), and is restored to original values on exit. The serial port child read process is created by fork(2) from the parent write process, and both processes respond to SIGINT = ^C and SIGTERM signals. Asynchronous serial port control is implemented with select(2). The input file, (usually stdin for commands,) uses canonical input for flow control. The X10 device and transmission codes are cross indexed in a binary search database using mmap(2), which also contains a command sequence field, (including shell calls,) that are executed in response to a specific transmission code. Variable names and states are supported via a hash lookup table. The database file is a Unix tab delimited field file, in lexical order, (i.e., constructed with sort(1),) consisting of four fields: 1) The X10 transmission code. 2) The device code and command. 3) A user defined alias. 4) A command sequence to execute in response to the transmission code. For example: d5 aa 64 00 ad a9 on porch motion a11 on; isset ix exec echo "motion detected" | mailx -s "motion detected" 5551234@myphone.com would turn on device A11, and then, send a message to my cell phone if motion was detected on my front porch, but only if the variable "ix" was set, (e.g., the variable "ix" enables transmission to my cell phone.) The motion detector is on house code A, device code 9, which has the transmission sequence, "d5 aa 64 00 ad." (The reason for including the transmission sequence in the database was for extensibil- ity with other devices and products-the program will print unknown transmission sequences received for future inclusion in the database-or take evasive action in jamming or collision situations, etc.) The language in field 4: [a-p][1-9][0-6]?: house code and unit code, i.e., "b12" on: turn a device on, i.e., "b12 on" off: turn a device off, i.e., "b12 off" dim ([0-9][0-2]?)?: dim a device, i.e., "b12 dim" or "b12 dim 5" bright ([0-9][0-2]?)?: brighten a device, i.e., "b12 bright" or "b12 bright 5" all_off: all devices off in a house, i.e., "b all_off" all_on: all devices on in a house, i.e., "b all_on" all_lamps_off: all lamps off in a house, i.e., "b all_lamps_off", (actually an alias for all_off) all_lamps_on: all lamps on in a house, i.e., "b all_lamps_on", (actually an alias for all_on) quit: stop the program exit: alias for "quit" set : set a variable, i.e., "set x123", (a variable is either set, or it isn't) reset : reset a variable, i.e., "reset x123", (a variable is either set, or it isn't) unset, alias for "reset" isset : test if a variable is set, i.e., "isset x123 b12 on", (a variable is either set, or it isn't) isnotset : test if a variable is not set, i.e., "isnotset x123 b12 on", (a variable is either set, or it isn't) timeset : the last time a variable was set, in ctime(3) istimeset seconds action: if a variable has been set at least seconds many seconds, (or has been set less than seconds many seconds if seconds is negative,) do action exec : execute a command system, alias for "exec" variable, any alphanumeric string not one of the above keywords ';': command delimiter, i.e., "isset x123 b12 on; isset abc b11 off" Note that the isset and isnotset commands allow simple constructs-the main function is to inhibit spawning a shell for every instance of a state change, (like a motion detector in a room,) for example: isset x123 exec myfile; isset abc exec myprogram would invoke a shell process only if x123, (or abc,) is set; any more complicated constructs should be handled by the shell interpreter in a batch file. The isset and isnotset commands can be chained to provide "and" boolean functionality, for example: isset x123 isnotset y456 exec myfile would invoke a shell process only if x123 is set, and y456 is not set. The program is not intended to be interactive, (although it does accept commands from stdin,) and is a network centric automaton, (daemon, 'bot., etc.,) launched in the computer's init scripts. An example invocation is: mknod myfile p spx10S1 -f spx10S1db -i myfile Commands, to be sent to X10 devices are written to the named pipe, myfile, (the named pipe is also used by the program to send commands in response to transmission sequences-fcntl(2) advisory locking is pro- vided for concurrency control,) and received transmissions, and database lookups, are printed to stdout for logging considerations. The program is intended for inclusion in a network centric embedded home automation system, (based on a "live CD" version of Knoppix, with no hard disk for security considerations.) The CM17A section of the code is based on code from the BottleRocket program, (http://www.linuxha.com/bottlerocket/,) by Tymm Twillman, Ash- ley Clark, David Anderson, Warner Losh, and, Christian Gafton. (c) 1999 Ashley Clark (aclark@ghoti.org) and Tymm Twillman (tymm@acm.org) Free Software. LGPL applies. No warranties expressed or implied. The serial port code is based on the spcid program, (http://www.john- con.com/john/cid/,) the database code is based on the NdeX program, (http://www.johncon.com/ndex/,) and the hash table code on hash.shar.gz, (http://www.johncon.com/.) OPTIONS -d device Device name, (/dev/ttyS1). -f dbfilename Database file name, (spx10S1db). -i infilename Input filename, (stdin). -l lockfile Lock file name, (/var/lock/LCK..ttyS1). -o outfilename Output filename, (stdout). -q queryfilename Query filename, (stderr). -V Verbose diagnostics. -v Print the program's version information WARNINGS The termios(3) and fopen(2) settings tested only on Linux 2.4. Porta- bility to systems other than Linux may be problematical. The semaphore locking mechanism uses fcntl(2), and may not be compatible with other serial programs. SEE ALSO spx10S0(1), spx10S1(1), spx10lock(1), spx10delay(1). DIAGNOSTICS Error messages for incompatible arguments, inaccessible files, and opening and closing files. AUTHORS ---------------------------------------------------------------------- A license is hereby granted to reproduce this software source code and to create executable versions from this source code. The copyright notice included with the software must be maintained in all copies produced. THIS PROGRAM IS PROVIDED "AS IS". THE AUTHOR PROVIDES NO WARRANTIES WHATSOEVER, EXPRESSED OR IMPLIED, INCLUDING WARRANTIES OF MERCHANTABILITY, TITLE, OR FITNESS FOR ANY PARTICULAR PURPOSE. THE AUTHOR DOES NOT WARRANT THAT USE OF THIS PROGRAM DOES NOT INFRINGE THE INTELLECTUAL PROPERTY RIGHTS OF ANY THIRD PARTY IN ANY COUNTRY. Copyright (c) 1994-2008, John Conover, All Rights Reserved. The CM17A section of the code is based on code from the BottleRocket program, (http://www.linuxha.com/bottlerocket/,) by Tymm Twillman, Ashley Clark, David Anderson, Warner Losh, and, Christian Gafton. (c) 1999 Ashley Clark (aclark@ghoti.org) and Tymm Twillman (tymm@acm.org) Free Software. LGPL applies. No warranties expressed or implied. Comments and/or bug reports should be addressed to: john@email.johncon.com (John Conover) http://www.johncon.com/ ---------------------------------------------------------------------- January 10, 2008 SPX10S1(1)