nut-debian/docs/man/genericups.8

'\" t
.\"     Title: genericups
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 02/15/2014
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.7.1.5
.\"  Language: English
.\"
.TH "GENERICUPS" "8" "02/15/2014" "Network UPS Tools 2\&.7\&.1\&." "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, Eaton Management Card Contact \- Config3 with cable 66033 (shutdown does not work)
.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/