Ubuntu Manpage: tripplite_usb - Driver for older Tripp Lite USB UPSes (not PDC HID)

Provided by: nut-server_2.8.1-4ubuntu1_amd64

NAME

       tripplite_usb - Driver for older Tripp Lite USB UPSes (not PDC HID)

SYNOPSIS

       tripplite_usb -h

       tripplite_usb -a UPS_NAME [OPTIONS]

SUPPORTED HARDWARE

       This driver should work with older Tripp Lite UPSes which are detected as USB HID-class devices, but are
       not true HID Power-Device Class devices. So far, the devices supported by tripplite_usb have product ID
       0001, and the newer units (such as those with "LCD" in the model name) with product ID 2001 require the
       usbhid-ups(8) driver instead.

       Please report success or failure to the nut-upsuser mailing list. A key piece of information is the
       protocol number, returned in ups.firmware.aux. Also, be sure to turn on debugging (-DDD) for more
       informative log messages.

       If your Tripp Lite UPS uses a serial port, you may wish to investigate the tripplite(8) or tripplitesu(8)
       drivers.

       This driver has been tested with the following models:

       •   INTERNETOFFICE700

       •   OMNIVS1000

       •   OMNIVS1500XL (some warnings)

       •   SMART700USB

       •   SMART1500RM2U

       •   SMART2200RMXL2U

       •   SMART3000RM2U

       If you have used Tripp Lite’s PowerAlert software to connect to your UPS, there is a good chance that
       tripplite_usb will work if it uses one of the following protocols:

       •   Protocol 0004

       •   Protocol 1001

       •   Protocol 2001

       •   Protocol 3003

       •   Protocol 3005

       On the other hand, if the web page for your UPS on the Tripp-Lite website says "HID-compliant USB port
       also enables direct integration with built-in power management and auto-shutdown features of Windows and
       MAC OS X", then you should use the usbhid-ups(8) driver instead.

EXTRA ARGUMENTS

This driver supports the following optional settings in the ups.conf(5) file (or with -x on the command
line):

port = string
Some value must be set, typically auto.

Note
This could be a device filesystem path like /dev/usb/hiddev0 but current use of libusb API
precludes knowing and matching by such identifiers. They may also be inherently unreliable
(dependent on re-plugging and enumeration order). At this time the actual value is ignored, but
syntactically some port configuration must still be there.

It is possible to control multiple UPS units simultaneously by running several instances of this driver,
provided they can be uniquely distinguished by setting some combination of the vendor, product, vendorid,
productid, serial, bus and/or device options detailed below. For devices or operating systems that do not
provide sufficient information, the allow_duplicates option can be of use (limited and risky!)

vendorid = regex, productid = regex, vendor = regex, product = regex, serial = regex
Select a specific UPS, in case there is more than one connected via USB. Each option specifies an
extended regular expression (see regex(7) for more information on regular expressions), which must
match the UPS’s entire respective vendor/product/serial string (minus any surrounding whitespace), or
the whole 4-digit hexadecimal code for vendorid and productid.

Try lsusb(8) or running this NUT driver with -DD command-line argument for finding out the strings to
match.

Examples:

• -x vendor="Foo.Corporation.*"

• -x vendorid="051d*" (APC)

• -x product=".*(Smart|Back)-?UPS.*"

bus = regex
Select a UPS on a specific USB bus or group of buses. The argument is a regular expression that must
match the bus name where the UPS is connected (e.g. bus="002" or bus="00[2-3]") as seen on Linux in
/sys/bus/usb/devices or lsusb(8); including leading zeroes.

device = regex
Select a UPS on a specific USB device or group of devices. The argument is a regular expression that
must match the device name where the UPS is connected (e.g. device="001" or device="00[1-2]") as
seen on Linux in /sys/bus/usb/devices or lsusb(8); including leading zeroes.

Note
device numbers are not guaranteed by the OS to be stable across re-boots or device re-plugging.

busport = regex
If supported by the hardware, OS and libusb on the particular deployment, this option should allow to
specify physical port numbers on an USB hub, rather than logical device enumeration values, and in
turn — this should be less volatile across reboots or re-plugging. The value may be seen in the USB
topology output of lsusb -tv on systems with that tool, for example.

Note
this option is not practically supported by some NUT builds (it should be ignored with a warning
then), and not by all systems that NUT can run on.

allow_duplicates
If you have several UPS devices which may not be uniquely identified by the options above (e.g. only
VID:PID can be discovered there), this flag allows each driver instance where it is set to take the
first match if available, or proceed to try another.

Normally the driver initialization would abort at this point claiming "Resource busy" or similar
error, assuming that the otherwise properly matched device is unique — and some other process already
handles it.

Warning
This feature is inherently non-deterministic! The association of driver instance name to actual
device may vary between runs!

If you only care to know that at least one of your no-name UPSes is online, this option can help.

If you must really know which one, it will not!

usb_set_altinterface = bAlternateSetting
Force redundant call to usb_set_altinterface(), especially if needed for devices serving multiple USB
roles where the UPS is not represented by the interface number 0 (default).

• -x upsid="12345"

Select a specific UPS by its unique UPS ID. The argument is a regular expression that must match the UPS
ID string. This allows for precise identification of UPS devices when multiple devices of the same make
and model are connected. See below regarding how to read and write the ups id (unit id) using upsrw(8).

Notes for tripplite_usb driver handling of common USB matching settings:

• product is a regular expression to match the product string for the UPS. This would be useful if
you have two different Tripp Lite UPS models connected to the same monitoring system, and you
want to be sure that you shut them down in the correct order.

This regex is matched against the full USB product string as seen in lsusb(8). The ups.model in
the upsc(1) output only lists the name after TRIPP LITE, so to match a SMART2200RMXL2U, you could
use the regex .*SMART2200.*.

• The productid is a regular expression which matches the UPS PID as four hexadecimal digits. So
far, the only known devices that work with this driver have PID 0001.

• The serial option may be or not be helpful: it does not appear that these particular Tripp Lite
UPSes supported by this driver use the iSerial descriptor field to return a serial number.
However, in case your unit does, you may specify it here.

offdelay
This setting controls the delay between receiving the "kill" command (-k) and actually cutting power
to the computer.

battery_min, battery_max
These floating-point values correspond to the "empty" (10%) and "full" (100%) voltages of the
battery. They are used for an approximation of the battery state-of-charge. The calculated
battery.charge value will be clamped to the range of 10% through 100%, so the resting voltage of the
charged battery can be used for battery_max, and the higher float charge voltage should not cause
problems.

RUNTIME VARIABLES

       ups.delay.shutdown
           This variable is the same as the offdelay setting, but it can be changed at runtime by upsrw(8).

       ups.id
           Some SMARTPRO models feature an Unit ID (ups.id) that can be set and retrieved. If your UPS supports
           this feature, this variable will be listed in the output of upsrw(8).

       outlet.1.switch
           Some Tripp Lite units have a switchable outlet (usually outlet #1) which can be turned on and off by
           writing 1 or 0, respectively, to outlet.1.switch with upsrw(8).

           If your unit has multiple switchable outlets, substitute the outlet number for 1 in the variable
           name. Be sure to test this first — there is no other way to be certain that the number used by the
           driver matches the label on the unit.

KNOWN ISSUES AND BUGS

       The driver was not developed with any official documentation from Tripp Lite, so certain events may
       confuse the driver. If you observe any strange behavior, please re-run the driver with -DDD to increase
       the verbosity.

       So far, the Tripp Lite UPSes do not seem to have a serial number or other globally unique identifier
       accessible through USB. Thus, when monitoring several Tripp Lite USB UPSes, you should use either the
       bus, device or product configuration options to uniquely specify which UPS a given driver instance should
       control.

       For instance, you can easily monitor an OMNIVS1000 and a SMART1500RM2U at the same time, since they have
       different USB Product ID strings. If you have two SMART1500RM2U units, you would have to find which USB
       bus and device number each unit is on (via lsusb(8)).

       Some of the SMART*2U models have a configurable Unit ID number, and you can now use the upsid config
       argument to uniquely specify which UPS a given driver instance should control. This allows for precise
       identification of UPS devices when multiple devices are connected. To retrieve or set the upsid use the
       upsrw(8) utility.

AUTHORS

       Written by Charles Lepple, based on the tripplite(8) driver by Rickard E. (Rik) Faith and Nicholas Kain.

       Please do not email the authors directly - use the nut-upsdev mailing list.

       A Tripp Lite OMNIVS1000 was graciously donated to the NUT project by Bradley Feldman
       (http://www.bradleyloritheo.com)