bpowerd v3.0b1
Author: Christopher Craig <ccraig@cc.gatech.edu>

Copyright: This program is released under the GNU Public License

================
What is it?    |
================

bpowerd is a program to monitor Best Power Patriot and Patriot Plus UPSs under
Linux.  It uses init to inform the system of a power outage and is capable of
detecting power fail and low battery conditions.  It is also capable of
killing the inverter on shutdown.

There are two ways this can happen, which one you use depends on which init
was detected by the configure program:

=================
How does it work|
=================

----------------+
The BSD init way|
----------------+

The following is the steps taken in the event of a powerfail

1) bpowerd detects failure and writes FAIL to /etc/powerstatus and either
FAIL or SCRAM to /etc/upsstatus for a power failure or low battery condition
respectively. 
2) bpowerd signals init with SIGPWR
3) init executes the command in the line starting with "pf", this should be 
a call to bpowerfail with the "start" argument
4) bpowerfail executes the command associated with the state in /etc/upsstatus

If the power comes back on "OK" is written to both /etc/upsstatus and
/etc/powerstatus and init is signaled.  init then runs the command on the line
starting with "pg" which should be a call to bpowerfail with the "stop"
option.  bpowerfail then halts all running shutdowns.

-------------------+
The Sys V init way |
-------------------+

1) bpowerd detects a state change and sends a struct with the power status 
   to /dev/initctl
2) init executes the appropriate line from the /etc/inittab
3) bpowerfail executes the command associated with the argument passed it
   by init

===============
Shutting Down |
===============
There are three ways to shut down.  
1) Kill bpowerd with SIGTERM: this will cleanly kill bpowerd and remove it
from memory.  
2) Kill bpowerd with SIGINT: this will kill bpowerd and kill the inverter if
there is a powerfail.  This is normally used in system shutdown scripts
3) Kill bpowerd with SIGKILL: This is a Very Bad Thing.  This will immediately
remove bpowerd from memory with out first closing the ups port.  Consequently
you will have to reboot before you can restart bpowerd

Furthermore there are two ways to shutdown the system and kill the inverter if 
appropriate.
1) Kill bpowerd with SIGTERM and then run 'bpowerd -k' if the inverter should
be killed (this is rather easy on BSD systems since you have yucky state
files, but it is quite difficult on SysV systems)
2) Kill bpowerd with SIGINT and let it kill the inverter if appropriate (This
is what I do and I use the function

	kill -INT `/sbin/pidof bpowerd`
	while [ "`/sbin/pidof bpowerd`" != "" ]; do
	   sleep 1;
	done

to make sure it waits for the daemon to shutdown.



=========
Cables  |
=========

Best has two cables available for their UPS: INT-0027 and INT-0051.
Best has stopped shipping INT-0027, but you may have it if you have
an older Patriot.  The newer INT-0051 will also work with the Best
supplied software (CheckUPS) for both Linux and Windows.
If you want to make your own cable, the schematics are provided below:

The pinout of the UPS is given below:
        UPS pin 1 Shutdown
        UPS pin 3 Inverter
        UPS pin 4 common
        UPS pin 5 Low Runtime

INT-0027
========
All:  \/\/\/ = Resistor (3.3K)

DB-9 (UPS)                                    DB-9 (Computer)  DB-25 (Computer)
1 ------------------------------------------------- 4 ---------- 20
                               +--\/\/\/----------- 2 ---------- 3
                               |
3 -----------------------------+--\/\/\/----------- 3 ---------- 2

4 ------------------------------------------------- 5 ---------- 7
5 -----------------------------+--\/\/\/---+------- 1 ---------- 8
                               |           |
                               |           +------- 6 ---------- 6
                               +--\/\/\/----------- 7 ---------- 4


INT-0051
========
All: \/\/\/ = Resistor (10K)

DB-9 (UPS)                               DB-9 (Computer)
3 --------------------+------------------------ 8
                      |
                      +---\/\/\/---+
                                   |
                                   +----------- 4
                                   |
                      +---\/\/\/---+
                      |
5 --------------------+------------------------ 1
1 --------------------------------------------- 7
4 --------------------------------------------- 3
9 --------------------------------------------- 5

==========
Credits  |
==========

Thanks to 
Best Power for their cooperation in giving me the schematics for thier control
line so that I didn't have to wait for it to get here.

Tom Webster, for writing genpowerd which I pulled heavily from
Mitch Blevins for work on the initctl interface and the INT-0051 cable.

and 

Jesus Christ for allowing me to live.