'\" t .\" Title: genericups .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 04/26/2022 .\" Manual: NUT Manual .\" Source: Network UPS Tools 2.8.0 .\" Language: English .\" .TH "GENERICUPS" "8" "04/26/2022" "Network UPS Tools 2\&.8\&.0" "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 (some UPSes may also support RB and BYPASS)\&. 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 RB .RS 4 Replace battery .RE .PP BYPASS .RS 4 Battery bypass active or no battery installed .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 DSR .RS 4 Data Set Ready\&. Received from the UPS\&. .RE .PP ST .RS 4 Send a BREAK on the transmit data line .RE .PP NULL .RS 4 Disable this signal\&. Disabled signal will always be low except for OL which will always be high\&. .RE .PP none .RS 4 Alias to NULL which matches some other documentation\&. .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 .\} .sp 23 = Generic FTTx (Fiber to the x) battery backup with 4\-wire telemetry interface .sp .if n \{\ .RS 4 .\} .nf [CP=RTS] [OL=CTS] [LB=\-DCD] [RB=\-RNG] [BYPASS=\-DSR] [SD=none] .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 secondary \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/