Desc: Using the generic UPS driver
File: generic-ups.txt
Date: 5 September 1999

If you have a UPS that does "contact closure" reporting, you probably need
to use this driver.  For APC Back-UPS models, this is the only method
of monitoring that's available.  This is also used on other APC units when
only their grey "dumb" cables are available.

The basic idea is for the UPS to send high/low signals back to the serial
port's various lines to indicate status.  These signals usually are the
following:

1. "On line" or "On battery"
2. "Battery OK" or "Low battery"

What's more, there is usually an outgoing signal from the PC that is used
to shut down the load side of the UPS.  This is necessary to ensure that
all connected systems are reset, even if it means powering them off.
Otherwise, a system may halt and remain halted as power returns at the
worst possible time.

To know if this driver will work with your UPS, compare the table below
with the information you have regarding its monitoring capabilities.
If you have an unlisted model that just happens to put the signals in
the same place as a listed model, it might just work.

Abbreviations:
  PF - Power failure line
  LB - Low battery line
  SD - Shutdown line
  CP - Cable power (must be present for cable to have valid reading)
 CTS - Clear to send signal (from UPS)
 RTS - Ready to send signal (from PC)
 DCD - Data carrier detect (from UPS)
 RNG - Ring indicate (from UPS)
 DTR - Data terminal ready (from PC)

"num" below is the type number you'd use with -t for this driver.

A - in front of the signal name (like -RNG) means that the indicated
condition is signaled with an active low signal.  -RNG in the BL column
means that the battery is low when that line goes low, and the battery
is OK when that line is held high.

num | Model name/info                          |  PF  |  LB  |  SD  |  CP  |
----+------------------------------------------+------+------+------+------+
 1  | APC Back-UPS with 940-0095A/B/C cable    | -RNG |  DCD |  RTS |  DTR |
----+------------------------------------------+------+------+------+------+
 2  | APC Back-UPS with 940-0020B cable        | -CTS | -DCD |  DTR | none |
    |                                          |      |      |  RTS |      |
----+------------------------------------------+------+------+------+------+
 3  | PowerTech Comp1000 with DTR cable power  | -CTS | -DCD |  DTR |  DTR |
    |                                          |      |      |  RTS |      |
----+------------------------------------------+------+------+------+------+

There are a few drivers that do this kind of contact closure measurement
which are not currently part of the genericups code.  They will be rolled
into the genericups driver eventually, like the old backups driver.  So,
if you find that your normal driver is missing some day, come back here
and check the table.  It'll probably be up there.

Adding new support - mere mortals
---------------------------------

If you just want your currently unsupported UPS to work without ripping
into the code, post a request to the mailing list with the details of
which lines indicate which value.  Unless it's truly bizarre, a solution
should be found rather quickly.  There are only so many combinations that
you can make with 4 incoming and 2 outgoing lines.  

For those of you keeping track, those are the 6 "high/low" lines on your
standard 9 pin serial port.  The other 3 are TxD, RxD, and GND.  If you
try to run a high/low signal on any of those, the results will be
unpredictable.  Any UPS hooked to the transmit or receive lines on the PC
is likely a "smart" variant and needs a special driver.  Consult a guru.

Oh yes, you can get on the mailing list by sending "subscribe ups" to
majordomo@lists.exploits.org.

Adding new support - hack time
------------------------------

If you're the brave type that likes hacking code, then it is possible to
add support for your favorite UPS by adding a new entry.  The most important
part is to figure out which line does what relative to the PC's serial
port.  Then, edit the settype() function and add a new entry to the
switch.  The general form for the line_* variables is as follows:

Outgoing lines:

line_NORM = what to set to make the line "normal" - i.e. cable power
line_SD   = what to set to make the UPS shut down the load

Incoming lines:

line_OL   = flag that appears for on line / on battery
val_OL    = value of that flag when the UPS is on battery
line_BL   = flag that appears for low battery / battery OK
val_BL    = value of that flag when the battery is low

This may seem a bit confusing to have two variables per value that
we want to read, but here's how it works.  If you set line_OL to TIOCM_RNG,
then the value of TIOCM_RNG (0x080 on my box) will be anded with the
value of the serial port whenever a poll occurs.  If that flag exists,
then the result of the and will be 0x80.  If it does not exist, the result
will be 0.

So, if line_OL = foo, then val_OL can only be foo or 0.  

As a general case, if line_OL == val_OL, then the value you're reading is
active high.  Otherwise, it's active low.  Check out the guts of
updateinfo() to see how it really works.
