593 lines
14 KiB
Groff
593 lines
14 KiB
Groff
'\" t
|
|
.\" Title: genericups
|
|
.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
|
|
.\" Generator: DocBook XSL Stylesheets v1.75.2 <http://docbook.sf.net/>
|
|
.\" Date: 09/15/2011
|
|
.\" Manual: NUT Manual
|
|
.\" Source: Network UPS Tools
|
|
.\" Language: English
|
|
.\"
|
|
.TH "GENERICUPS" "8" "09/15/2011" "Network UPS Tools" "NUT Manual"
|
|
.\" -----------------------------------------------------------------
|
|
.\" * Define some portability stuff
|
|
.\" -----------------------------------------------------------------
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.\" http://bugs.debian.org/507673
|
|
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
|
|
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\" -----------------------------------------------------------------
|
|
.\" * set default formatting
|
|
.\" -----------------------------------------------------------------
|
|
.\" disable hyphenation
|
|
.nh
|
|
.\" disable justification (adjust text to left margin only)
|
|
.ad l
|
|
.\" -----------------------------------------------------------------
|
|
.\" * MAIN CONTENT STARTS HERE *
|
|
.\" -----------------------------------------------------------------
|
|
.SH "NAME"
|
|
genericups \- Driver for contact\-closure UPS equipment
|
|
.SH "NOTE"
|
|
.sp
|
|
This man page only documents the specific features of the genericups driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
|
|
.SH "SUPPORTED HARDWARE"
|
|
.sp
|
|
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\&.
|
|
.sp
|
|
This means that you will only get the essentials in ups\&.status: OL, OB, and LB\&. Anything else requires a smarter UPS\&.
|
|
.SH "CABLING"
|
|
.sp
|
|
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\&.
|
|
.SH "EXTRA ARGUMENTS"
|
|
.sp
|
|
This driver supports the following settings in the \fBups.conf\fR(5):
|
|
.PP
|
|
upstype=\fItype\fR
|
|
.RS 4
|
|
Required\&. Configures the driver for a specific kind of UPS\&. See the
|
|
UPS Types
|
|
section below for more information on which entries are available\&.
|
|
.RE
|
|
.PP
|
|
mfr=\fIstring\fR
|
|
.RS 4
|
|
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\&.
|
|
.RE
|
|
.PP
|
|
model=\fIstring\fR
|
|
.RS 4
|
|
Optional\&. This is like
|
|
mfr
|
|
above, but it overrides the model string instead\&.
|
|
.RE
|
|
.PP
|
|
serial=\fIstring\fR
|
|
.RS 4
|
|
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\&.
|
|
.RE
|
|
.PP
|
|
sdtime=\fIvalue\fR
|
|
.RS 4
|
|
Optional\&. The driver will sleep for this many seconds after setting the shutdown signal\&. This is necessary for some hardware which requires a sustained level to activate the shutdown sequence\&.
|
|
.sp
|
|
The default behavior of the driver is to exit immediately\&. If this doesn\(cqt reliably trigger a shutdown in your UPS hardware, use this setting to give it more time to react\&.
|
|
.RE
|
|
.if n \{\
|
|
.sp
|
|
.\}
|
|
.RS 4
|
|
.it 1 an-trap
|
|
.nr an-no-space-flag 1
|
|
.nr an-break-flag 1
|
|
.br
|
|
.ps +1
|
|
\fBNote\fR
|
|
.ps -1
|
|
.br
|
|
.sp
|
|
very large values for sdtime may create warnings from upsdrvctl if it gets tired of waiting for the driver to return\&.
|
|
.sp .5v
|
|
.RE
|
|
.SH "CUSTOM CONFIGURATIONS"
|
|
.sp
|
|
You may override the values for CP, OL, LB, and SD by defining them in the \fBups.conf\fR(5) after the upstype setting\&.
|
|
.sp
|
|
For example, to set the cable power to DTR and the low battery value to DCD, it would look like this:
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
CP = DTR
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
LB = DCD
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
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\&.
|
|
.sp
|
|
These values may be negated for active low signals\&. That is, "LB=\-DCD" recognizes a low battery condition when DCD is not held high\&.
|
|
.SH "TYPE INFORMATION"
|
|
.sp
|
|
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:
|
|
.PP
|
|
OL
|
|
.RS 4
|
|
On line (no power failure) (opposite of OB \- on battery)
|
|
.RE
|
|
.PP
|
|
LB
|
|
.RS 4
|
|
Low battery
|
|
.RE
|
|
.PP
|
|
SD
|
|
.RS 4
|
|
Shutdown load
|
|
.RE
|
|
.PP
|
|
CP
|
|
.RS 4
|
|
Cable power (must be present for cable to have valid reading)
|
|
.RE
|
|
.PP
|
|
CTS
|
|
.RS 4
|
|
Clear to Send\&. Received from the UPS\&.
|
|
.RE
|
|
.PP
|
|
RTS
|
|
.RS 4
|
|
Ready to Send\&. Sent by the PC\&.
|
|
.RE
|
|
.PP
|
|
DCD
|
|
.RS 4
|
|
Data Carrier Detect\&. Received from the UPS\&.
|
|
.RE
|
|
.PP
|
|
RNG
|
|
.RS 4
|
|
Ring indicate\&. Received from the UPS\&.
|
|
.RE
|
|
.PP
|
|
DTR
|
|
.RS 4
|
|
Data Terminal Ready\&. Sent by the PC\&.
|
|
.RE
|
|
.PP
|
|
ST
|
|
.RS 4
|
|
Send a BREAK on the transmit data line
|
|
.RE
|
|
.sp
|
|
A "\-" in front of a signal name (like \-RNG) means that the indicated condition 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\&.
|
|
.SH "UPS TYPES"
|
|
.sp
|
|
0 = UPSonic LAN Saver 600
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR+RTS] [OL=\-CTS] [LB=DCD] [SD=DTR]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
1 = APC Back\-UPS/Back\-UPS Pro/Smart\-UPS with 940\-0095A/C cable
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=\-RNG] [LB=DCD] [SD=RTS]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
2 = APC Back\-UPS/Back\-UPS Pro/Smart\-UPS with 940\-0020B cable
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=RTS] [OL=\-CTS] [LB=DCD] [SD=DTR+RTS]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
Type 2 has also been reported to work with the 940\-0020C cable\&.
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
3 = PowerTech Comp1000 with DTR cable power
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=CTS] [LB=DCD] [SD=DTR+RTS]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
4 = Generic RUPS Model
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=\-RTS]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
5 = Tripp Lite UPS with Lan2\&.2 interface (black 73\-0844 cable)
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=DTR+RTS]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
6 = Best Patriot with INT51 cable
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=RTS]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
7 = CyberPower Power99 Also Upsonic Power Guardian PG\-500, Belkin Belkin Home Office, F6H350\-SER, F6H500\-SER, F6H650\-SER
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=DTR]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
8 = Nitram Elite 500
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=???]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
9 = APC Back\-UPS/Back\-UPS Pro/Smart\-UPS with 940\-0023A cable
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=none] [OL=\-DCD] [LB=CTS] [SD=RTS]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
10 = Victron Lite with crack cable
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=DTR]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
11 = Powerware 3115
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=\-CTS] [LB=\-DCD] [SD=ST]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
12 = APC Back\-UPS Office with 940\-0119A cable
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=RTS] [OL=\-CTS] [LB=DCD] [SD=DTR]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
13 = RPT Repoteck RPT\-800A/RPT\-162A
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR+RTS] [OL=DCD] [LB=\-CTS] [SD=ST]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
14 = Online P\-series
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=DCD] [LB=\-CTS] [SD=RTS]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
15 = Powerware 5119, 5125
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=ST]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
16 = Nitram Elite 2002
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR+RTS] [OL=CTS] [LB=\-DCD] [SD=???]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
17 = PowerKinetics 9001
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=???]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
18 = TrippLite Omni 450LAN with Martin\(cqs cabling
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=CTS] [LB=DCD] [SD=none]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
19 = Fideltronic Ares Series
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=CTS] [LB=\-DCD] [SD=RTS]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
20 = Powerware 5119 RM
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=DTR] [OL=\-CTS] [LB=DCD] [SD=ST]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
Check docs/cables/powerware\&.txt
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
21 = Generic RUPS 2000 (Megatec M2501 cable)
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=RTS+DTR]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
22 = Gamatronic All models with alarm interface (also CyberPower SL series)
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=DTR]
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.SH "SIMILAR MODELS"
|
|
.sp
|
|
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\(cqt match, don\(cqt despair\&. You can fix that easily by using the mfr and model variables documented above in your \fBups.conf\fR(5)\&.
|
|
.SH "TESTING COMPATIBILITY"
|
|
.sp
|
|
If your UPS isn\(cqt 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\&.
|
|
.sp
|
|
To do this, first make sure nothing important is plugged into the outlets on the UPS, as you may inadvertently switch it off\&. Definitely make sure that the computer you\(cqre 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\&.
|
|
.sp
|
|
Now, you can either attempt to make an educated guess based on the documentation your manufacturer has provided (if any), or just start going down the list\&.
|
|
.SS "Step 1"
|
|
.sp
|
|
Pick a driver to try from the list (genericups \-h) and go to step 2\&.
|
|
.SS "Step 2"
|
|
.sp
|
|
Start the driver with the type you want to try \-
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
genericups \-x upstype=n /dev/port
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
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), continue to Step 3, otherwise go back to step 1\&.
|
|
.sp
|
|
Alternatively, you can run genericups in debug mode \-
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
genericups \-DDDDD \-x upstype=n /dev/port
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
In this mode it will be running in the foreground and continuously display the line and battery status of the UPS\&.
|
|
.SS "Step 3"
|
|
.sp
|
|
Disconnect the UPS from the wall/mains power\&. This is easiest if you have a switched outlet in between it and the wall, but you can also just pull the plug to test\&. The lamp should stay lit, and the status should switch to "OB"\&. If the lamp went out or the status didn\(cqt go to "OB" within about 15 seconds, go to Step 1\&. Otherwise, continue to Step 4\&.
|
|
.SS "Step 4"
|
|
.sp
|
|
At this point, we know that OL and OB work\&. If nothing else beyond this point works, you at least know what your OL/OB value should be\&.
|
|
.sp
|
|
Wait for the UPS to start complaining about a low battery\&. Depending on the size of your UPS battery and the lamp\(cqs 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\&.
|
|
.SS "Step 5"
|
|
.sp
|
|
So far: OL works, OB works, and LB works\&.
|
|
.sp
|
|
With the UPS running on battery, run the genericups driver with the \-k switch to shut it down\&.
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
genericups \-x upstype=n \-k /dev/port
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
If the UPS turns off the lamp, you\(cqre 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\&.
|
|
.sp
|
|
You should use your findings to add a section to your ups\&.conf\&. Here is a quick example:
|
|
.sp
|
|
.if n \{\
|
|
.RS 4
|
|
.\}
|
|
.nf
|
|
[myups]
|
|
driver = genericups
|
|
port = /dev/ttyS0
|
|
upstype = 1
|
|
.fi
|
|
.if n \{\
|
|
.RE
|
|
.\}
|
|
.sp
|
|
Change the port and upstype values to match your system\&.
|
|
.SH "NEW SUPPORT"
|
|
.sp
|
|
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\&.
|
|
.sp
|
|
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\&.
|
|
.sp
|
|
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\(cqs being supplied by the PC\&.
|
|
.SH "SPECIFIC MODEL NOTES"
|
|
.sp
|
|
These have been contributed by users of this driver\&.
|
|
.sp
|
|
The Centralion CL series may power down the load if the driver starts up with the UPS running on battery as the default line settings contain the shutdown sequence\&. \- Neil Muller
|
|
.sp
|
|
The Tripp\-Lite Internet Office 700 must be used with the black 73\-0844 cable instead of the gray 73\-0743 cable\&. This entry should work with any of their models with the Lan 2\&.2 interface \- see the sticker by the DB9 connector on the UPS\&. \- Stephen Brown
|
|
.sp
|
|
Type 5 should work with the Tripp\-Lite Lan 2\&.1 interface and the 73\-0724 cable\&. This was tested with the OmniSmart 675 PNP on Red Hat 7\&.2\&. \- Q Giese
|
|
.sp
|
|
Types 7 and 10 should both work with the PhoenixTec A1000\&.
|
|
.SH "BUGS"
|
|
.sp
|
|
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 interrupted, you may not be able to sense this in software\&.
|
|
.sp
|
|
Most contact\-closure UPSes will not power down the load if the line power is present\&. This can create a race when using slave \fBupsmon\fR(8) systems\&. See the \fBupsmon\fR(8) man page for more information\&.
|
|
.sp
|
|
The solution to both of these problems is to upgrade to a smart protocol UPS of some kind that allows detection and proper load cycling on command\&.
|
|
.SH "SEE ALSO"
|
|
.SS "The core driver"
|
|
.sp
|
|
\fBnutupsdrv\fR(8)
|
|
.SS "Internet resources"
|
|
.sp
|
|
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/
|