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\&.
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\&.
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
.RS4
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
.RS4
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
.RS4
Optional\&. This is like
mfr
above, but it overrides the model string instead\&.
.RE
.PP
serial=\fIstring\fR
.RS4
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
.RS4
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
.ifn\{\
.sp
.\}
.RS4
.it1an-trap
.nran-no-space-flag1
.nran-break-flag1
.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
.ifn\{\
.RS4
.\}
.nf
CP = DTR
.fi
.ifn\{\
.RE
.\}
.sp
.ifn\{\
.RS4
.\}
.nf
LB = DCD
.fi
.ifn\{\
.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
.RS4
On line (no power failure) (opposite of OB \- on battery)
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
.ifn\{\
.RS4
.\}
.nf
[CP=DTR+RTS] [OL=\-CTS] [LB=DCD] [SD=DTR]
.fi
.ifn\{\
.RE
.\}
.sp
1 = APC Back\-UPS/Back\-UPS Pro/Smart\-UPS with 940\-0095A/C cable
.sp
.ifn\{\
.RS4
.\}
.nf
[CP=DTR] [OL=\-RNG] [LB=DCD] [SD=RTS]
.fi
.ifn\{\
.RE
.\}
.sp
2 = APC Back\-UPS/Back\-UPS Pro/Smart\-UPS with 940\-0020B cable
.sp
.ifn\{\
.RS4
.\}
.nf
[CP=RTS] [OL=\-CTS] [LB=DCD] [SD=DTR+RTS]
.fi
.ifn\{\
.RE
.\}
.sp
.ifn\{\
.RS4
.\}
.nf
Type 2 has also been reported to work with the 940\-0020C cable\&.
.fi
.ifn\{\
.RE
.\}
.sp
3 = PowerTech Comp1000 with DTR cable power
.sp
.ifn\{\
.RS4
.\}
.nf
[CP=DTR] [OL=CTS] [LB=DCD] [SD=DTR+RTS]
.fi
.ifn\{\
.RE
.\}
.sp
4 = Generic RUPS Model
.sp
.ifn\{\
.RS4
.\}
.nf
[CP=RTS] [OL=CTS] [LB=\-DCD] [SD=\-RTS]
.fi
.ifn\{\
.RE
.\}
.sp
5 = Tripp Lite UPS with Lan2\&.2 interface (black 73\-0844 cable)
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)
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
.ifn\{\
.RS4
.\}
.nf
genericups \-x upstype=n /dev/port
.fi
.ifn\{\
.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
.ifn\{\
.RS4
.\}
.nf
genericups \-DDDDD \-x upstype=n /dev/port
.fi
.ifn\{\
.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
.ifn\{\
.RS4
.\}
.nf
genericups \-x upstype=n \-k /dev/port
.fi
.ifn\{\
.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
.ifn\{\
.RS4
.\}
.nf
[myups]
driver = genericups
port = /dev/ttyS0
upstype = 1
.fi
.ifn\{\
.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\&.
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\&.
