# 
# Copyright 2008 Maurice Castro. All rights reserved.
# 
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions
# are met:
# 
#    1. Redistributions of source code must retain the above copyright
#        notice, this list of conditions and the following disclaimer.
#    2. Redistributions in binary form must reproduce the above
#        copyright notice, this list of conditions and the following
#        disclaimer in the documentation and/or other materials provided
#        with the distribution.
# 
# THIS SOFTWARE IS PROVIDED BY Maurice Castro ``AS IS'' AND ANY EXPRESS
# OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL Maurice Castro OR OTHER CONTRIBUTORS
# BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
# OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
# OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
# WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
# OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
# EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#

* Overview

The Jam Panic Button is based on a Tenx USB chip, probably a TMU3102. These 
chips are also used in missile launcher toys. The code presented will read 
a button press from the panic button provided the device is detected as a 
ugen device by the FreeBSD kernel. 

To use the program issue the command 

	panicbutton PROGNAME

where PROGNAME is the program to execute when the panicbutton is depressed.

An example of the use of the program is to display a web site when the 
button is depressed:

	panicbutton "firefox www.castro.aus.net"

or more usefully reboot a machine which has lost video while changing 
a driver:

	panicbutton "sudo reboot"

Please note that there have been occasions when it has been necessary
to disconnect the panic button from the usb host to reset the device
and allow the button to be detected.

The program requires access to the device files /dev/usb and
/dev/ugen[0-9]+ for the device which has the panic button attached.
This is safely achieved by creating a setuid root program which
drops priveleges to run as the user which started the program when
it runs the program specified on the command line of the panicbutton
program. To ensure that this security mechanism is enforced the
program will not run if it is started by root directly.
