Desc: Using the generic UPS driver
File: generic-ups.txt
Date: 22 December 2000
Auth: Russell Kroll <rkroll@exploits.org>

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 LB 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  |
----+------------------------------------------+------+------+------+------+
 0  | UPSONIC LAN Server 600                   | -CTS |  DCD | -DTR |  DTR |
    |                                          |      |      |  RTS |  RTS |
----+------------------------------------------+------+------+------+------+
 1  | APC Back-UPS with 940-0095A/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 |      |
----+------------------------------------------+------+------+------+------+
 4  | Centralion CL Series UPS (RUPS cable)    |  CTS |  DCD | -RTS |  RTS |
----+------------------------------------------+------+------+------+------+
 5  | Tripp Lite Internet Office 700 (73-0844) | -CTS | -DCD |  DTR |  DTR |
    |                                          |      |      |  RTS |      |
----+------------------------------------------+------+------+------+------+
 6  | Best Patriot (INT51 cable)               | -CTS | -DCD |  RTS |  DTR |
----+------------------------------------------+------+------+------+------+
 7  | CyberPower Power99                       | -CTS | -DCD |  DTR |  RTS |
----+------------------------------------------+------+------+------+------+
 8  | Nitram Elite UPS                         | -CTS | -DCD | none |  DTR |
----+------------------------------------------+------+------+------+------+
 9  | APC Back-UPS with 940-0023A cable        |  DCD |  CTS |  RTS | none |
----+------------------------------------------+------+------+------+------+
 10 | Victron Lite (crack cable)               | -CTS | -DCD |  DTR |  RTS |
----+------------------------------------------+------+------+------+------+
 11 | Powerware 3115                           |  CTS |  DCD |   ST |  DTR |
----+------------------------------------------+------+------+------+------+

Similar models
==============

Many UPS companies put out models with similar interfaces.  The RUPS cable
seems to be especially popular in the "power strip" variety of UPS found
in office supply stores.  If your UPS works with an entry in the table above,
but the model or manufacturer information don't match, don't dispair.  You
can fix that easily with the -m and -M options.

	/usr/local/ups/bin/genericups -t 4 -M Belkin -m Resource

-M overrides the manufacturer and -m overrides the model.  Now everything
will look proper in your displays.

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 upstab[] in genericups.h and add a new grouping of
information for that model.  Just insert it *before* the one with all NULLs.

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.

Model-specific notes
====================

Centralion CL Series
--------------------

Neil Muller wrote in with the Centralion CL Series support information, and
provided some details on how the shutdown works.  Specifically, if the
driver starts up while the UPS is on battery power, the short interval
with the default line settings will power down the load.

Tripp Lite Internet Office 700
------------------------------

Stephen Brown provided the specs for this model's support.  He notes that
you must use the black 73-0844 cable instead of the gray 73-0743 cable.
This code should work with any of their models that uses the Lan 2.2
interface - look for the sticker by the DB9 connector on the UPS.

Back-UPS Office
---------------

The Back-UPS Office has a connector that looks something like a modular
phone cord, and should work with type 0.  Right now, shutdowns are not
supported, though.  If you find out how to make this model shut down
through the -k feature, please let us know.
