GENERICUPS(8)
=============

NAME
----

genericups - Driver for contact-closure UPS equipment

SYNOPSIS
--------

*genericups* -h

*genericups* -a 'UPS_NAME' ['OPTIONS']

NOTE: This man page only documents the specific features of the genericups
driver.  For information about the core driver, see linkman:nutupsdrv[8].

SUPPORTED HARDWARE
------------------

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
-------

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.

EXTRA ARGUMENTS
---------------

This driver supports the following settings in the linkman:ups.conf[5]:

upstype='type'::

Required.  Configures the driver for a specific kind of UPS.  See the
<<_ups_types,UPS Types>> section below for more information on which entries
are available.

mfr='string'::

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.

model='string'::

Optional.  This is like `mfr` above, but it overrides the model string
instead.

serial='string'::

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.

sdtime='value'::

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.
+
The default behavior of the driver is to exit immediately.  If this
doesn't reliably trigger a shutdown in your UPS hardware, use this
setting to give it more time to react.

NOTE: Very large values for +sdtime+ may create warnings from upsdrvctl if
it gets tired of waiting for the driver to return.

CUSTOM CONFIGURATIONS
---------------------

You may override the values for `CP`, `OL`, `LB`, and `SD` by defining them in
the linkman:ups.conf[5] after the `upstype` setting.

For example, to set the cable power to `DTR` and the low battery value to
`DCD`, it would look like this:

----
	CP = DTR

	LB = DCD
----

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.

These values may be negated for active low signals.  That is, `LB=-DCD`
recognizes a low battery condition when `DCD` is not held high.

TYPE INFORMATION
----------------

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:

OL:: On line (no power failure) (opposite of 'OB' -- on battery)

LB:: Low battery

RB:: Replace battery

BYPASS:: Battery bypass active or no battery installed

SD:: Shutdown load

CP:: Cable power (must be present for cable to have valid reading)

CTS:: Clear to Send.  Received from the UPS.

RTS:: Ready to Send.  Sent by the PC.

DCD:: Data Carrier Detect.  Received from the UPS.

RNG:: Ring indicate.  Received from the UPS.

DTR:: Data Terminal Ready.  Sent by the PC.

DSR:: Data Set Ready.  Received from the UPS.

ST:: Send a BREAK on the transmit data line

NULL:: Disable this signal.  Disabled signal will always be low except for 'OL'
       which will always be high.

none:: Alias to `NULL` which matches some other documentation.

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.

UPS TYPES
---------

0 = UPSonic LAN Saver 600

    [CP=DTR+RTS] [OL=-CTS] [LB=DCD] [SD=DTR]

1 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0095A/C cable

    [CP=DTR] [OL=-RNG] [LB=DCD] [SD=RTS]

2 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0020B cable
(Note: Type 2 has also been reported to work with the 940-0020C cable).

    [CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR+RTS]

3 = PowerTech Comp1000 with DTR cable power

    [CP=DTR] [OL=CTS] [LB=DCD] [SD=DTR+RTS]

4 = Generic RUPS Model

    [CP=RTS] [OL=CTS] [LB=-DCD] [SD=-RTS]

5 = Tripp Lite UPS with Lan2.2 interface (black 73-0844 cable)

    [CP=DTR] [OL=CTS] [LB=-DCD] [SD=DTR+RTS]

6 = Best Patriot with INT51 cable

    [CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]

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)

    [CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]

8 = Nitram Elite 500

    [CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]

9 = APC Back-UPS/Back-UPS Pro/Smart-UPS with 940-0023A cable

    [CP=none] [OL=-DCD] [LB=CTS] [SD=RTS]

10 = Victron Lite with crack cable

     [CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]

11 = Powerware 3115

     [CP=DTR] [OL=-CTS] [LB=-DCD] [SD=ST]

12 = APC Back-UPS Office with 940-0119A cable

     [CP=RTS] [OL=-CTS] [LB=DCD] [SD=DTR]

13 = RPT Repoteck RPT-800A/RPT-162A

     [CP=DTR+RTS] [OL=DCD] [LB=-CTS] [SD=ST]

14 = Online P-series

     [CP=DTR] [OL=DCD] [LB=-CTS] [SD=RTS]

15 = Powerware 5119, 5125

     [CP=DTR] [OL=CTS] [LB=-DCD] [SD=ST]

16 = Nitram Elite 2002

     [CP=DTR+RTS] [OL=CTS] [LB=-DCD] [SD=???]

17 = PowerKinetics 9001

     [CP=DTR] [OL=CTS] [LB=-DCD] [SD=???]

18 = TrippLite Omni 450LAN with Martin's cabling

     [CP=DTR] [OL=CTS] [LB=DCD] [SD=none]

19 = Fideltronic Ares Series

     [CP=DTR] [OL=CTS] [LB=-DCD] [SD=RTS]

20 = Powerware 5119 RM (check `docs/cables/powerware.txt` in NUT sources)

     [CP=DTR] [OL=-CTS] [LB=DCD] [SD=ST]

21 = Generic RUPS 2000 (Megatec M2501 cable)

     [CP=RTS] [OL=CTS] [LB=-DCD] [SD=RTS+DTR]

22 = Gamatronic All models with alarm interface
     (also CyberPower SL series)

     [CP=RTS] [OL=CTS] [LB=-DCD] [SD=DTR]

23 = Generic FTTx (Fiber to the x) battery backup
     with 4-wire telemetry interface

     [CP=RTS] [OL=CTS] [LB=-DCD] [RB=-RNG] [BYPASS=-DSR] [SD=none]

SIMILAR MODELS
--------------

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't match,
don't despair.  You can fix that easily by using the `mfr` and `model`
variables documented above in your linkman:ups.conf[5].

TESTING COMPATIBILITY
---------------------

If your UPS isn't 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.

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're 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.

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.

Step 1
~~~~~~

Pick a driver to try from the list (run `genericups -h`) and go to step 2.

Step 2
~~~~~~

Start the driver with the type you want to try, e.g.:

        genericups -x upstype=n /dev/port

Let linkman:upsd[8] sync up (watch the syslog), and then run linkman:upsc[8]
to see what it found.  If the `STATUS` is correct (should be "OL" for online),
continue to <<_step_3,Step 3>>, otherwise go back to step 1.

Alternatively, you can run `genericups` in debug mode, e.g.:

        genericups -DDDDD -x upstype=n /dev/port

In this mode it will be running in the foreground and continuously
display the line and battery status of the UPS.

Step 3
~~~~~~

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't go to "OB"
within about 15 seconds, go to <<_step_1,Step 1>>.  Otherwise, continue
to <<_step_4,Step 4>>.

Step 4
~~~~~~

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.

Wait for the UPS to start complaining about a low battery.  Depending on
the size of your UPS battery and the lamp's 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,Step 1>>, otherwise continue to <<_step_5,Step 5>>.

Step 5
~~~~~~

So far: OL works, OB works, and LB works.

With the UPS running on battery, run the genericups driver with the -k
switch to shut it down.

        genericups -x upstype=n -k /dev/port

If the UPS turns off the lamp, you're 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.

You should use your findings to add a section to your ups.conf.
Here is a quick example:

        [myups]
                driver = genericups
                port = /dev/ttyS0
                upstype = 1

Change the port and upstype values to match your system.

NEW SUPPORT
-----------

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.

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.

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's
being supplied by the PC.

SPECIFIC MODEL NOTES
--------------------

These have been contributed by users of this driver.

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

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

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

Types 7 and 10 should both work with the PhoenixTec A1000.

BUGS
----

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 linkman:upsmon[8]
systems.  See the linkman:upsmon[8] man page for more information.

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.

SEE ALSO
--------

The core driver
~~~~~~~~~~~~~~~

linkman:nutupsdrv[8]

Internet resources:
~~~~~~~~~~~~~~~~~~~

The NUT (Network UPS Tools) home page: https://www.networkupstools.org/
