docs/man/genericups.txt

   1 GENERICUPS(8)
   2 =============
   3
   4 NAME
   5 ----
   6 genericups - Driver for contact-closure UPS equipment
   7
   8 NOTE
   9 ----
  10 This man page only documents the specific features of the genericups
  11 driver.  For information about the core driver, see linkman:nutupsdrv[8].
  12
  13 SUPPORTED HARDWARE
  14 ------------------
  15 This driver supports hardware from many different manufacturers as it only
  16 uses the very simplest of signaling schemes.  Contact closure refers to a
  17 kind of interface where basic high/low signals are provided to indicate
  18 status.  This kind of UPS can only report line power and battery status.
  19
  20 This means that you will only get the essentials in ups.status: OL, OB,
  21 and LB.  Anything else requires a smarter UPS.
  22
  23 CABLING
  24 -------
  25 Cabling is different for every kind of UPS.  See the table below for
  26 information on what is known to work with a given UPS type.
  27
  28 EXTRA ARGUMENTS
  29 ---------------
  30 This driver supports the following settings in the linkman:ups.conf[5]:
  31
  32 upstype='type'::
  33
  34 Required.  Configures the driver for a specific kind of UPS.  See the
  35 <<_ups_types,UPS Types>> section below for more information on which entries
  36 are available.
  37
  38 mfr='string'::
  39
  40 Optional.  The very nature of a generic UPS driver sometimes means that
  41 the stock manufacturer data has no relation to the actual hardware that is
  42 attached.  With the `mfr` setting, you can change the value that is seen by
  43 clients that monitor this UPS.
  44
  45 model='string'::
  46
  47 Optional.  This is like `mfr` above, but it overrides the model string
  48 instead.
  49
  50 serial='string'::
  51
  52 Optional.  This is like `mfr` above and intended to record the identification
  53 string of the UPS. It is titled "serial" because usually this string is
  54 referred to as the serial number.
  55
  56 sdtime='value'::
  57
  58 Optional.  The driver will sleep for this many seconds after setting the
  59 shutdown signal.  This is necessary for some hardware which requires a
  60 sustained level to activate the shutdown sequence.
  61 +
  62 The default behavior of the driver is to exit immediately.  If this
  63 doesn't reliably trigger a shutdown in your UPS hardware, use this
  64 setting to give it more time to react.
  65
  66 NOTE: very large values for +sdtime+ may create warnings from upsdrvctl if
  67 it gets tired of waiting for the driver to return.
  68
  69 CUSTOM CONFIGURATIONS
  70 ---------------------
  71
  72 You may override the values for CP, OL, LB, and SD by defining them in
  73 the linkman:ups.conf[5] after the upstype setting.
  74
  75 For example, to set the cable power to DTR and the low battery value to
  76 DCD, it would look like this:
  77
  78         CP = DTR
  79
  80         LB = DCD
  81
  82 Recognized values for input lines are CTS, DCD, and RNG.  Recognized
  83 values for output lines are DTR, RTS, and ST.  See below for more about
  84 what these signals mean.
  85
  86 These values may be negated for active low signals.  That is, "LB=-DCD"
  87 recognizes a low battery condition when DCD is not held high.
  88
  89 TYPE INFORMATION
  90 ----------------
  91 The essence of a UPS definition in this driver is how it uses the serial
  92 lines that are available.  These are the abbreviations you will see below:
  93
  94 OL:: On line (no power failure) (opposite of OB - on battery)
  95
  96 LB:: Low battery
  97
  98 SD:: Shutdown load
  99
 100 CP:: Cable power (must be present for cable to have valid reading)
 101
 102 CTS:: Clear to Send.  Received from the UPS.
 103
 104 RTS:: Ready to Send.  Sent by the PC.
 105
 106 DCD:: Data Carrier Detect.  Received from the UPS.
 107
 108 RNG:: Ring indicate.  Received from the UPS.
 109
 110 DTR:: Data Terminal Ready.  Sent by the PC.
 111
 112 ST:: Send a BREAK on the transmit data line
 113
 114 A "-" in front of a signal name (like -RNG) means that the indicated
 115 condition is signaled with an active low signal.  For example, [LB=-RNG]
 116 means the battery is low when the ring indicate line goes low, and that
 117 the battery is OK when that line is held high.
 118
 119 UPS TYPES
 120 ---------
 121
 122 0 = UPSonic LAN Saver 600
 123
 124     [CP=DTR+RTS] [OL=-CTS] [LB=DCD] [SD=DTR]
 125
 126 1 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0095A/C cable
 127
 128     [CP=DTR] [OL=-RNG] [LB=DCD] [SD=RTS]
 129
 130 2 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0020B cable
 131
 132     [CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR+RTS]
 133
 134     Type 2 has also been reported to work with the 940-0020C cable.
 135
 136 3 = PowerTech Comp1000 with DTR cable power
 137
 138     [CP=DTR] [OL=CTS] [LB=DCD] [SD=DTR+RTS]
 139
 140 4 = Generic RUPS Model
 141
 142     [CP=RTS] [OL=CTS] [LB=-DCD] [SD=-RTS]
 143
 144 5 = Tripp Lite UPS with Lan2.2 interface (black 73-0844 cable)
 145
 146     [CP=DTR] [OL=CTS] [LB=-DCD] [SD=DTR+RTS]
 147
 148 6 = Best Patriot with INT51 cable
 149
 150     [CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]
 151
 152 7 = CyberPower Power99
 153     Also Upsonic Power Guardian PG-500, Belkin Belkin Home Office,
 154     F6H350-SER, F6H500-SER, F6H650-SER, Eaton Management Card Contact - Config3
 155     with cable 66033 (shutdown does not work)
 156
 157     [CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
 158
 159 8 = Nitram Elite 500
 160
 161     [CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]
 162
 163 9 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0023A cable
 164
 165     [CP=none] [OL=-DCD] [LB=CTS] [SD=RTS]
 166
 167 10 = Victron Lite with crack cable
 168
 169      [CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
 170
 171 11 = Powerware 3115
 172
 173      [CP=DTR] [OL=-CTS] [LB=-DCD] [SD=ST]
 174
 175 12 = APC Back-UPS Office with 940-0119A cable
 176
 177      [CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR]
 178
 179 13 = RPT Repoteck RPT-800A/RPT-162A
 180
 181      [CP=DTR+RTS] [OL=DCD] [LB=-CTS] [SD=ST]
 182
 183 14 = Online P-series
 184
 185      [CP=DTR] [OL=DCD] [LB=-CTS] [SD=RTS]
 186
 187 15 = Powerware 5119, 5125
 188
 189      [CP=DTR] [OL=CTS] [LB=-DCD] [SD=ST]
 190
 191 16 = Nitram Elite 2002
 192
 193      [CP=DTR+RTS] [OL=CTS] [LB=-DCD] [SD=???]
 194
 195 17 = PowerKinetics 9001
 196
 197      [CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]
 198
 199 18 = TrippLite Omni 450LAN with Martin's cabling
 200
 201      [CP=DTR] [OL=CTS] [LB=DCD] [SD=none]
 202
 203 19 = Fideltronic Ares Series
 204
 205      [CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]
 206
 207 20 = Powerware 5119 RM
 208
 209      [CP=DTR] [OL=-CTS] [LB=DCD] [SD=ST]
 210
 211      Check docs/cables/powerware.txt
 212
 213 21 = Generic RUPS 2000 (Megatec M2501 cable)
 214
 215      [CP=RTS] [OL=CTS] [LB=-DCD] [SD=RTS+DTR]
 216
 217 22 = Gamatronic All models with alarm interface
 218      (also CyberPower SL series)
 219
 220      [CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
 221
 222 SIMILAR MODELS
 223 --------------
 224
 225 Many different UPS companies make models with similar interfaces.  The
 226 RUPS cable seems to be especially popular in the "power strip" variety of
 227 UPS found in office supply stores.  If your UPS works with an entry in the
 228 table above, but the model or manufacturer information don't match,
 229 don't despair.  You can fix that easily by using the mfr and model
 230 variables documented above in your linkman:ups.conf[5].
 231
 232 TESTING COMPATIBILITY
 233 ---------------------
 234
 235 If your UPS isn't listed above, you can try going through the list until
 236 you find one that works.  There is a lot of cable and interface reuse in
 237 the UPS world, and you may find a match.
 238
 239 To do this, first make sure nothing important is plugged into the
 240 outlets on the UPS, as you may inadvertently switch it off.  Definitely
 241 make sure that the computer you're using is not plugged into that UPS.
 242 Plug in something small like a lamp so you know when power is being
 243 supplied to the outlets.
 244
 245 Now, you can either attempt to make an educated guess based on the
 246 documentation your manufacturer has provided (if any), or just start
 247 going down the list.
 248
 249 Step 1
 250 ~~~~~~
 251
 252 Pick a driver to try from the list (genericups -h) and go to step 2.
 253
 254 Step 2
 255 ~~~~~~
 256
 257 Start the driver with the type you want to try -
 258
 259         genericups -x upstype=n /dev/port
 260
 261 Let upsd sync up (watch the syslog), and then run upsc to see what it
 262 found.  If the STATUS is right (should be OL for on line), continue to
 263 <<_step_3,Step 3>>, otherwise go back to step 1.
 264
 265 Alternatively, you can run genericups in debug mode -
 266
 267         genericups -DDDDD -x upstype=n /dev/port
 268
 269 In this mode it will be running in the foreground and continuously
 270 display the line and battery status of the UPS.
 271
 272 Step 3
 273 ~~~~~~
 274
 275 Disconnect the UPS from the wall/mains power.  This is easiest if you
 276 have a switched outlet in between it and the wall, but you can also just
 277 pull the plug to test.  The lamp should stay lit, and the status should
 278 switch to "OB".  If the lamp went out or the status didn't go to "OB"
 279 within about 15 seconds, go to <<_step_1,Step 1>>.  Otherwise, continue
 280 to <<_step_4,Step 4>>.
 281
 282 Step 4
 283 ~~~~~~
 284
 285 At this point, we know that OL and OB work.  If nothing else beyond
 286 this point works, you at least know what your OL/OB value should be.
 287
 288 Wait for the UPS to start complaining about a low battery.  Depending on
 289 the size of your UPS battery and the lamp's bulb, this could take
 290 awhile.  It should start complaining audibly at some point.  When this
 291 happens, STATUS should show "OB LB" within 15 seconds.  If not, go to
 292 <<_step_1,Step 1>>, otherwise continue to <<_step_5,Step 5>>.
 293
 294 Step 5
 295 ~~~~~~
 296
 297 So far: OL works, OB works, and LB works.
 298
 299 With the UPS running on battery, run the genericups driver with the -k
 300 switch to shut it down.
 301
 302         genericups -x upstype=n -k /dev/port
 303
 304 If the UPS turns off the lamp, you're done.  At this point, you have
 305 verified that the shutdown sequence actually does what you want.  You
 306 can start using the genericups driver with this type number for normal
 307 operations.
 308
 309 You should use your findings to add a section to your ups.conf.
 310 Here is a quick example:
 311
 312         [myups]
 313                 driver = genericups
 314                 port = /dev/ttyS0
 315                 upstype = 1
 316
 317 Change the port and upstype values to match your system.
 318
 319 NEW SUPPORT
 320 -----------
 321
 322 If the above testing sequence fails, you will probably need to create a
 323 new entry to support your hardware.  All UPS types are determined from the
 324 table in the genericups.h file in the source tree.
 325
 326 On a standard 9 pin serial port, there are 6 lines that are used as the
 327 standard "high/low" signal levels.  4 of them are incoming (to the PC,
 328 from the UPS), and the other 2 are outgoing (to the UPS, from the PC).
 329 The other 3 are the receive/transmit lines and the ground.
 330
 331 Be aware that many manufacturers remap pins within the cable.  If you have
 332 any doubts, a quick check with a multimeter should confirm whether the
 333 cable is straight-through or not.  Another thing to keep in mind is that
 334 some cables have electronics in them to do special things.  Some have
 335 resistors and transistors on board to change behavior depending on what's
 336 being supplied by the PC.
 337
 338 SPECIFIC MODEL NOTES
 339 --------------------
 340
 341 These have been contributed by users of this driver.
 342
 343 The Centralion CL series may power down the load if the driver starts up
 344 with the UPS running on battery as the default line settings contain the
 345 shutdown sequence.  - Neil Muller
 346
 347 The Tripp-Lite Internet Office 700 must be used with the black 73-0844
 348 cable instead of the gray 73-0743 cable.  This entry should work with any
 349 of their models with the Lan 2.2 interface - see the sticker by the DB9
 350 connector on the UPS.  - Stephen Brown
 351
 352 Type 5 should work with the Tripp-Lite Lan 2.1 interface and the 73-0724
 353 cable.  This was tested with the OmniSmart 675 PNP on Red Hat 7.2.  - Q
 354 Giese
 355
 356 Types 7 and 10 should both work with the PhoenixTec A1000.
 357
 358 BUGS
 359 ----
 360
 361 There is no way to reliably detect a contact-closure UPS.  This means the
 362 driver will start up happily even if no UPS is detected.  It also means
 363 that if the connection between the UPS and computer is interrupted, you
 364 may not be able to sense this in software.
 365
 366 Most contact-closure UPSes will not power down the load if the line power
 367 is present.  This can create a race when using slave linkman:upsmon[8]
 368 systems.  See the linkman:upsmon[8] man page for more information.
 369
 370 The solution to both of these problems is to upgrade to a smart protocol
 371 UPS of some kind that allows detection and proper load cycling on command.
 372
 373 SEE ALSO
 374 --------
 375
 376 The core driver
 377 ~~~~~~~~~~~~~~~
 378 linkman:nutupsdrv[8]
 379
 380 Internet resources
 381 ~~~~~~~~~~~~~~~~~~
 382 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/