1GENERICUPS(8)                     NUT Manual                     GENERICUPS(8)
2
3
4

NAME

6       genericups - Driver for contact-closure UPS equipment
7

NOTE

9       This man page only documents the specific features of the genericups
10       driver. For information about the core driver, see nutupsdrv(8).
11

SUPPORTED HARDWARE

13       This driver supports hardware from many different manufacturers as it
14       only uses the very simplest of signaling schemes. Contact closure
15       refers to a kind of interface where basic high/low signals are provided
16       to indicate status. This kind of UPS can only report line power and
17       battery status.
18
19       This means that you will only get the essentials in ups.status: OL, OB,
20       and LB (some UPSes may also support RB and BYPASS). Anything else
21       requires a smarter UPS.
22

CABLING

24       Cabling is different for every kind of UPS. See the table below for
25       information on what is known to work with a given UPS type.
26

EXTRA ARGUMENTS

28       This driver supports the following settings in the ups.conf(5):
29
30       upstype=type
31           Required. Configures the driver for a specific kind of UPS. See the
32           UPS Types section below for more information on which entries are
33           available.
34
35       mfr=string
36           Optional. The very nature of a generic UPS driver sometimes means
37           that the stock manufacturer data has no relation to the actual
38           hardware that is attached. With the mfr setting, you can change the
39           value that is seen by clients that monitor this UPS.
40
41       model=string
42           Optional. This is like mfr above, but it overrides the model string
43           instead.
44
45       serial=string
46           Optional. This is like mfr above and intended to record the
47           identification string of the UPS. It is titled "serial" because
48           usually this string is referred to as the serial number.
49
50       sdtime=value
51           Optional. The driver will sleep for this many seconds after setting
52           the shutdown signal. This is necessary for some hardware which
53           requires a sustained level to activate the shutdown sequence.
54
55           The default behavior of the driver is to exit immediately. If this
56           doesn’t reliably trigger a shutdown in your UPS hardware, use this
57           setting to give it more time to react.
58
59           Note
60           very large values for sdtime may create warnings from upsdrvctl if
61           it gets tired of waiting for the driver to return.
62

CUSTOM CONFIGURATIONS

64       You may override the values for CP, OL, LB, and SD by defining them in
65       the ups.conf(5) after the upstype setting.
66
67       For example, to set the cable power to DTR and the low battery value to
68       DCD, it would look like this:
69
70           CP = DTR
71
72           LB = DCD
73
74       Recognized values for input lines are CTS, DCD, and RNG. Recognized
75       values for output lines are DTR, RTS, and ST. See below for more about
76       what these signals mean.
77
78       These values may be negated for active low signals. That is, "LB=-DCD"
79       recognizes a low battery condition when DCD is not held high.
80

TYPE INFORMATION

82       The essence of a UPS definition in this driver is how it uses the
83       serial lines that are available. These are the abbreviations you will
84       see below:
85
86       OL
87           On line (no power failure) (opposite of OB - on battery)
88
89       LB
90           Low battery
91
92       RB
93           Replace battery
94
95       BYPASS
96           Battery bypass active or no battery installed
97
98       SD
99           Shutdown load
100
101       CP
102           Cable power (must be present for cable to have valid reading)
103
104       CTS
105           Clear to Send. Received from the UPS.
106
107       RTS
108           Ready to Send. Sent by the PC.
109
110       DCD
111           Data Carrier Detect. Received from the UPS.
112
113       RNG
114           Ring indicate. Received from the UPS.
115
116       DTR
117           Data Terminal Ready. Sent by the PC.
118
119       DSR
120           Data Set Ready. Received from the UPS.
121
122       ST
123           Send a BREAK on the transmit data line
124
125       NULL
126           Disable this signal. Disabled signal will always be low except for
127           OL which will always be high.
128
129       none
130           Alias to NULL which matches some other documentation.
131
132       A "-" in front of a signal name (like -RNG) means that the indicated
133       condition is signaled with an active low signal. For example, [LB=-RNG]
134       means the battery is low when the ring indicate line goes low, and that
135       the battery is OK when that line is held high.
136

UPS TYPES

138       0 = UPSonic LAN Saver 600
139
140           [CP=DTR+RTS] [OL=-CTS] [LB=DCD] [SD=DTR]
141
142       1 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0095A/C cable
143
144           [CP=DTR] [OL=-RNG] [LB=DCD] [SD=RTS]
145
146       2 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0020B cable
147
148           [CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR+RTS]
149
150           Type 2 has also been reported to work with the 940-0020C cable.
151
152       3 = PowerTech Comp1000 with DTR cable power
153
154           [CP=DTR] [OL=CTS] [LB=DCD] [SD=DTR+RTS]
155
156       4 = Generic RUPS Model
157
158           [CP=RTS] [OL=CTS] [LB=-DCD] [SD=-RTS]
159
160       5 = Tripp Lite UPS with Lan2.2 interface (black 73-0844 cable)
161
162           [CP=DTR] [OL=CTS] [LB=-DCD] [SD=DTR+RTS]
163
164       6 = Best Patriot with INT51 cable
165
166           [CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]
167
168       7 = CyberPower Power99 Also Upsonic Power Guardian PG-500, Belkin
169       Belkin Home Office, F6H350-SER, F6H500-SER, F6H650-SER, Eaton
170       Management Card Contact - Config3 with cable 66033 (shutdown does not
171       work)
172
173           [CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
174
175       8 = Nitram Elite 500
176
177           [CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]
178
179       9 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0023A cable
180
181           [CP=none] [OL=-DCD] [LB=CTS] [SD=RTS]
182
183       10 = Victron Lite with crack cable
184
185           [CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
186
187       11 = Powerware 3115
188
189           [CP=DTR] [OL=-CTS] [LB=-DCD] [SD=ST]
190
191       12 = APC Back-UPS Office with 940-0119A cable
192
193           [CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR]
194
195       13 = RPT Repoteck RPT-800A/RPT-162A
196
197           [CP=DTR+RTS] [OL=DCD] [LB=-CTS] [SD=ST]
198
199       14 = Online P-series
200
201           [CP=DTR] [OL=DCD] [LB=-CTS] [SD=RTS]
202
203       15 = Powerware 5119, 5125
204
205           [CP=DTR] [OL=CTS] [LB=-DCD] [SD=ST]
206
207       16 = Nitram Elite 2002
208
209           [CP=DTR+RTS] [OL=CTS] [LB=-DCD] [SD=???]
210
211       17 = PowerKinetics 9001
212
213           [CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]
214
215       18 = TrippLite Omni 450LAN with Martin’s cabling
216
217           [CP=DTR] [OL=CTS] [LB=DCD] [SD=none]
218
219       19 = Fideltronic Ares Series
220
221           [CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]
222
223       20 = Powerware 5119 RM
224
225           [CP=DTR] [OL=-CTS] [LB=DCD] [SD=ST]
226
227           Check docs/cables/powerware.txt
228
229       21 = Generic RUPS 2000 (Megatec M2501 cable)
230
231           [CP=RTS] [OL=CTS] [LB=-DCD] [SD=RTS+DTR]
232
233       22 = Gamatronic All models with alarm interface (also CyberPower SL
234       series)
235
236           [CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]
237
238       23 = Generic FTTx (Fiber to the x) battery backup with 4-wire telemetry
239       interface
240
241           [CP=RTS] [OL=CTS] [LB=-DCD] [RB=-RNG] [BYPASS=-DSR] [SD=none]
242

SIMILAR MODELS

244       Many different UPS companies make models with similar interfaces. The
245       RUPS cable seems to be especially popular in the "power strip" variety
246       of UPS found in office supply stores. If your UPS works with an entry
247       in the table above, but the model or manufacturer information don’t
248       match, don’t despair. You can fix that easily by using the mfr and
249       model variables documented above in your ups.conf(5).
250

TESTING COMPATIBILITY

252       If your UPS isn’t listed above, you can try going through the list
253       until you find one that works. There is a lot of cable and interface
254       reuse in the UPS world, and you may find a match.
255
256       To do this, first make sure nothing important is plugged into the
257       outlets on the UPS, as you may inadvertently switch it off. Definitely
258       make sure that the computer you’re using is not plugged into that UPS.
259       Plug in something small like a lamp so you know when power is being
260       supplied to the outlets.
261
262       Now, you can either attempt to make an educated guess based on the
263       documentation your manufacturer has provided (if any), or just start
264       going down the list.
265
266   Step 1
267       Pick a driver to try from the list (genericups -h) and go to step 2.
268
269   Step 2
270       Start the driver with the type you want to try -
271
272           genericups -x upstype=n /dev/port
273
274       Let upsd sync up (watch the syslog), and then run upsc to see what it
275       found. If the STATUS is right (should be OL for on line), continue to
276       Step 3, otherwise go back to step 1.
277
278       Alternatively, you can run genericups in debug mode -
279
280           genericups -DDDDD -x upstype=n /dev/port
281
282       In this mode it will be running in the foreground and continuously
283       display the line and battery status of the UPS.
284
285   Step 3
286       Disconnect the UPS from the wall/mains power. This is easiest if you
287       have a switched outlet in between it and the wall, but you can also
288       just pull the plug to test. The lamp should stay lit, and the status
289       should switch to "OB". If the lamp went out or the status didn’t go to
290       "OB" within about 15 seconds, go to Step 1. Otherwise, continue to Step
291       4.
292
293   Step 4
294       At this point, we know that OL and OB work. If nothing else beyond this
295       point works, you at least know what your OL/OB value should be.
296
297       Wait for the UPS to start complaining about a low battery. Depending on
298       the size of your UPS battery and the lamp’s bulb, this could take
299       awhile. It should start complaining audibly at some point. When this
300       happens, STATUS should show "OB LB" within 15 seconds. If not, go to
301       Step 1, otherwise continue to Step 5.
302
303   Step 5
304       So far: OL works, OB works, and LB works.
305
306       With the UPS running on battery, run the genericups driver with the -k
307       switch to shut it down.
308
309           genericups -x upstype=n -k /dev/port
310
311       If the UPS turns off the lamp, you’re done. At this point, you have
312       verified that the shutdown sequence actually does what you want. You
313       can start using the genericups driver with this type number for normal
314       operations.
315
316       You should use your findings to add a section to your ups.conf. Here is
317       a quick example:
318
319           [myups]
320                   driver = genericups
321                   port = /dev/ttyS0
322                   upstype = 1
323
324       Change the port and upstype values to match your system.
325

NEW SUPPORT

327       If the above testing sequence fails, you will probably need to create a
328       new entry to support your hardware. All UPS types are determined from
329       the table in the genericups.h file in the source tree.
330
331       On a standard 9 pin serial port, there are 6 lines that are used as the
332       standard "high/low" signal levels. 4 of them are incoming (to the PC,
333       from the UPS), and the other 2 are outgoing (to the UPS, from the PC).
334       The other 3 are the receive/transmit lines and the ground.
335
336       Be aware that many manufacturers remap pins within the cable. If you
337       have any doubts, a quick check with a multimeter should confirm whether
338       the cable is straight-through or not. Another thing to keep in mind is
339       that some cables have electronics in them to do special things. Some
340       have resistors and transistors on board to change behavior depending on
341       what’s being supplied by the PC.
342

SPECIFIC MODEL NOTES

344       These have been contributed by users of this driver.
345
346       The Centralion CL series may power down the load if the driver starts
347       up with the UPS running on battery as the default line settings contain
348       the shutdown sequence. - Neil Muller
349
350       The Tripp-Lite Internet Office 700 must be used with the black 73-0844
351       cable instead of the gray 73-0743 cable. This entry should work with
352       any of their models with the Lan 2.2 interface - see the sticker by the
353       DB9 connector on the UPS. - Stephen Brown
354
355       Type 5 should work with the Tripp-Lite Lan 2.1 interface and the
356       73-0724 cable. This was tested with the OmniSmart 675 PNP on Red Hat
357       7.2. - Q Giese
358
359       Types 7 and 10 should both work with the PhoenixTec A1000.
360

BUGS

362       There is no way to reliably detect a contact-closure UPS. This means
363       the driver will start up happily even if no UPS is detected. It also
364       means that if the connection between the UPS and computer is
365       interrupted, you may not be able to sense this in software.
366
367       Most contact-closure UPSes will not power down the load if the line
368       power is present. This can create a race when using secondary upsmon(8)
369       systems. See the upsmon(8) man page for more information.
370
371       The solution to both of these problems is to upgrade to a smart
372       protocol UPS of some kind that allows detection and proper load cycling
373       on command.
374

SEE ALSO

376   The core driver
377       nutupsdrv(8)
378
379   Internet resources:
380       The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
381
382
383
384Network UPS Tools 2.8.0           04/26/2022                     GENERICUPS(8)
Impressum