NOTE
This man page only documents the specific features of the genericups
driver. For information about the core driver, see nutupsdrv(8).
SUPPORTED HARDWARE
This driver supports hardware from many different manufacturers as it
only uses the very simplest of signaling schemes. Contact closure
refers to a kind of interface where basic high/low signals are provided
to indicate status. This kind of UPS can only report line power and
battery status.
This means that you will only get the essentials in ups.status: OL, OB,
and LB. Anything else requires a smarter UPS.
CABLING
Cabling is different for every kind of UPS. See the table below for
information on what is known to work with a given UPS type.
EXTRA ARGUMENTS
This driver supports the following settings in the ups.conf(5):
upstype=type
Required. Configures the driver for a specific kind of UPS.
See the UPS Types section below for more information on which
entries are available.
mfr=string
Optional. The very nature of a generic UPS driver sometimes
means that the stock manufacturer data has no relation to the
actual hardware that is attached. With the mfr setting, you can
change the value that is seen by clients that monitor this UPS.
model=string
Optional. This is like mfr above, but it overrides the model
string instead.
serial=string
Optional. This is like mfr above and intended to record the
identification string of the UPS. It is titled serial because
usually this string is referred to as the serial number.
drvctl if it gets tired of waiting for the driver to return.
CUSTOM CONFIGURATIONS
You may override the values for CP, OL, LB, and SD by defining them in
the ups.conf after the upstype setting.
For example, to set the cable power to DTR and the low battery value to
DCD, it would look like this:
CP = DTR
LB = DCD
Recognized values for input lines are CTS, DCD, and RNG. Recognized
values for output lines are DTR, RTS, and ST. See below for more about
what these signals mean.
These values may be negated for active low signals. That is, "LB=-DCD"
recognizes a low battery condition when DCD is not held high.
TYPE INFORMATION
The essence of a UPS definition in this driver is how it uses the
serial lines that are available. These are the abbreviations you will
see below:
OL - On line (no power failure) (opposite of OB - on battery)
LB - Low battery
SD - Shutdown load
CP - Cable power (must be present for cable to have valid reading)
CTS - Clear to Send. Received from the UPS.
RTS - Ready to Send. Sent by the PC.
DCD - Data Carrier Detect. Received from the UPS.
RNG - Ring indicate. Received from the UPS.
DTR - Data Terminal Ready. Sent by the PC.
ST - Send a BREAK on the transmit data line
A - in front of a signal name (like -RNG) means that the indicated con-
dition is signaled with an active low signal. For example, [LB=-RNG]
means the battery is low when the ring indicate line goes low, and that
the battery is OK when that line is held high.
[CP=DTR] [OL=CTS] [LB=DCD] [SD=DTR+RTS]
4 = Generic RUPS Model
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=-RTS]
5 = Tripp Lite UPS with Lan2.2 interface (black 73-0844 cable)
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=DTR+RTS]
6 = Best Patriot with INT51 cable
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]
7 = CyberPower Power99
also Upsonic Power Guardian PG-500
Also Belkin Belkin Home Office
F6H350-SER, F6H500-SER, F6H650-SER
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
8 = Nitram Elite 500
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]
9 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0023A cable
[CP=none] [OL=-DCD] [LB=CTS] [SD=RTS]
10 = Victron Lite with crack cable
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
11 = Powerware 3115
[CP=DTR] [OL=-CTS] [LB=-DCD] [SD=ST]
12 = APC Back-UPS Office with 940-0119A cable
[CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR]
13 = RPT Repoteck RPT-800A/RPT-162A
[CP=DTR+RTS] [OL=DCD] [LB=-CTS] [SD=ST]
14 = Online P-series
[CP=DTR] [OL=DCD] [LB=-CTS] [SD=RTS]
15 = Powerware 5119, 5125
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=ST]
16 = Nitram Elite 2002
[CP=DTR+RTS] [OL=CTS] [LB=-DCD] [SD=???]
17 = PowerKinetics 9001
[CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]
18 = TrippLite Omni 450LAN with Martin's cabling
[CP=DTR] [OL=CTS] [LB=DCD] [SD=none]
22 = Gamatronic All models with alarm interface
also CyberPower SL series
[CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
SIMILAR MODELS
Many different UPS companies make 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 despair. You can fix that easily by using the mfr and
model variables documented above in your ups.conf(5).
TESTING COMPATIBILITY
If your UPS isn't listed above, you can try going through the list
until you find one that works. There is a lot of cable and interface
reuse in the UPS world, and you may find a match.
To do this, first make sure nothing important is plugged into the out-
lets on the UPS, as you may inadvertently switch it off. Definitely
make sure that the computer you're using is not plugged into that UPS.
Plug in something small like a lamp so you know when power is being
supplied to the outlets.
Now, you can either attempt to make an educated guess based on the doc-
umentation your manufacturer has provided (if any), or just start going
down the list.
Step 1
Pick a driver to try from the list (genericups -h) and go to step 2.
Step 2
Start the driver with the type you want to try -
genericups -x upstype=n /dev/port
Let upsd sync up (watch the syslog), and then run upsc to see what it
found. If the STATUS is right (should be OL for on line), go to step
3, otherwise go back to step 1.
Alternatively, you can run genericups in debug mode -
genericups -DDDDD -x upstype=n /dev/port
In this mode it will be running in the foreground and continuously dis-
play the line and battery status of the UPS.
Wait for the UPS to start complaining about a low battery. Depending
on the size of your UPS battery and the lamp's bulb, this could take
awhile. It should start complaining audibly at some point. When this
happens, STATUS should show "OB LB" within 15 seconds. If not, go to
step 1, otherwise continue to step 5.
Step 5
So far: OL works, OB works, and LB works.
With the UPS running on battery, run the genericups driver with the -k
switch to shut it down.
genericups -x upstype=n -k /dev/port
If the UPS turns off the lamp, you're done. At this point, you have
verified that the shutdown sequence actually does what you want. You
can start using the genericups driver with this type number for normal
operations.
You should use your findings to add a section to your ups.conf. Here
is a quick example:
[myups]
driver = genericups
port = /dev/ttyS0
upstype = 1
Change the port and upstype values to match your system.
NEW SUPPORT
If the above testing sequence fails, you will probably need to create a
new entry to support your hardware. All UPS types are determined from
the table in the genericups.h file in the source tree.
On a standard 9 pin serial port, there are 6 lines that are used as the
standard "high/low" signal levels. 4 of them are incoming (to the PC,
from the UPS), and the other 2 are outgoing (to the UPS, from the PC).
The other 3 are the receive/transmit lines and the ground.
Be aware that many manufacturers remap pins within the cable. If you
have any doubts, a quick check with a multimeter should confirm whether
the cable is straight-through or not. Another thing to keep in mind is
that some cables have electronics in them to do special things. Some
have resistors and transistors on board to change behavior depending on
what's being supplied by the PC.
SPECIFIC MODEL NOTES
These have been contributed by users of this driver.
BUGS
There is no way to reliably detect a contact-closure UPS. This means
the driver will start up happily even if no UPS is detected. It also
means that if the connection between the UPS and computer is inter-
rupted, you may not be able to sense this in software.
Most contact-closure UPSes will not power down the load if the line
power is present. This can create a race when using slave upsmon(8)
systems. See the upsmon(8) man page for more information.
The solution to both of these problems is to upgrade to a smart proto-
col UPS of some kind that allows detection and proper load cycling on
command.
SEE ALSO
The core driver:
nutupsdrv(8)
Internet resources:
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
Thu Aug 11 2005 GENERICUPS(8)
Man(1) output converted with
man2html