Ubuntu Manpage: usbhid-ups - Driver for USB/HID UPS equipment

Provided by: nut-server_2.7.4-11ubuntu4_amd64

NAME

       usbhid-ups - Driver for USB/HID UPS equipment

NOTE

       This man page only documents the hardware-specific features of the usbhid-ups driver. For
       information about the core driver, see nutupsdrv(8).

       This driver, formerly called newhidups, replaces the legacy hidups driver, which only
       supported Linux systems.

SUPPORTED HARDWARE

       usbhid-ups brings USB/HID UPS monitoring to NUT on all platform supporting USB through
       libusb. It should detect any UPS that uses the HID power device class, but the amount of
       data will vary depending on the manufacturer and model.

       At the present time, usbhid-ups supports:

       •   the newer Eaton USB models,

       •   all MGE USB models,

       •   all Dell USB models,

       •   some APC models,

       •   some Belkin models,

       •   some Cyber Power Systems models,

       •   some Powercom models,

       •   some TrippLite models.

       For a more complete list, refer to the NUT hardware compatibility list, available in the
       source distribution as data/drivers.list, or on the NUT website. You may use the "explore"
       driver option to gather information from HID UPSes which are not yet supported; see below
       for details.

       This driver is known to work on:

       •   most Linux systems,

       •   FreeBSD (beta stage) and maybe other *BSD,

       •   Darwin / Mac OS X,

       •   Solaris 10.

EXTRA ARGUMENTS

This driver also supports the following optional settings:

offdelay=num
Set the timer before the UPS is turned off after the kill power command is sent (via
the -k switch).

The default value is 20 (in seconds). Usually this must be lower than ondelay, but the
driver will not warn you upon startup if it isn’t.

ondelay=num
Set the timer for the UPS to switch on in case the power returns after the kill power
command had been sent but before the actual switch off. This ensures the machines
connected to the UPS are, in all cases, rebooted after a power failure.

The default value is 30 (in seconds). Usually this must be greater than offdelay, but
the driver will not warn you upon startup if it isn’t. Some UPS’es will restart no
matter what, even if the power is (still) out at the moment this timer elapses. In
that case, you could try if setting ondelay = -1 in ups.conf helps.

pollfreq=num
Set polling frequency, in seconds, to reduce the USB data flow. Between two polling
requests, the driver will wait for interrupts (aka UPS notifications), which are data
changes returned by the UPS by itself. This mechanism allow to avoid or reduce
staleness message, due to the UPS being temporarily overloaded with too much polling
requests. The default value is 30 (in seconds).

pollonly
If this flag is set, the driver will ignore interrupts it receives from the UPS (not
recommended, but needed if these reports are broken on your UPS).

vendor=regex, product=regex, serial=regex, vendorid=regex, productid=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)) that must match the UPS’s
entire vendor/product/serial string (minus any surrounding whitespace), or the whole
4-digit hexadecimal code for vendorid and productid. Try -DD 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 busses. The argument is a regular
expression that must match the bus name where the UPS is connected (e.g. bus="002",
bus="00[2-3]").

explore
With this option, the driver will connect to any device, including ones that are not
yet supported. This must always be combined with the "vendorid" option. In this mode,
the driver will not do anything useful except for printing debugging information
(typically used with -DD).

maxreport
With this option, the driver activates a tweak to workaround buggy firmware returning
invalid HID report length. Some APC Back-UPS units are known to have this bug.

interruptonly
If this flag is set, the driver will not poll UPS. This also implies using of INPUT
flagged objects. Some Powercom units need this option.

interruptsize=num
Limit the number of bytes to read from interrupt pipe. For some Powercom units this
option should be equal to 8.

INSTALLATION

       This driver is not built by default. You can build it by using "configure --with-usb=yes".
       Note that it will also install other USB drivers.

       You also need to install manually the legacy hotplug files (libhidups and libhid.usermap,
       generally in /etc/hotplug/usb/), or the udev file (nut-usbups.rules, generally in
       /etc/udev/rules.d/) to address the permission settings problem. For more information,
       refer to the README file in nut/scripts/hotplug or nut/scripts/udev.

       On Linux with MGE equipment, you will need at least a 2.4.25 or 2.6.2 kernel as well as
       libusb-0.1.8 or later to disable hiddev support and avoid conflict.

IMPLEMENTATION

       The driver ignores the "port" value in ups.conf. Unlike previous versions of this driver,
       it is now possible to control multiple UPS units simultaneously with this driver, provided
       they can be distinguished by setting some combination of the "vendor", "product",
       "serial", "vendorid", and "productid" options. For instance:

           [mge]
                   driver = usbhid-ups
                   port = auto
                   vendorid = 0463
           [tripplite]
                   driver = usbhid-ups
                   port = auto
                   vendorid = 09ae

KNOWN ISSUES AND BUGS

Repetitive timeout and staleness
Some models tends to be unresponsive with the default polling frequency. The result is
that your system log will have lots of messages like:

usb 2-1: control timeout on ep0in
usb 2-1: usbfs: USBDEVFS_CONTROL failed cmd usbhid-ups rqt 128 rq 6 len 256
ret -110

In this case, simply modify the general parameter "pollinterval" to a higher value (like
10 for 10 seconds). This should solve the issue.

Got EPERM: Operation not permitted upon driver startup
You have forgotten to install the hotplug files, as explained in the INSTALLATION section
above. Don’t forget to restart hotplug so that it applies these changes.

Unattended shutdowns
The hardware which was used for development of this driver is almost certainly different
from what you have, and not all manufacturers follow the USB HID Power Device Class
specifications to the letter. You don’t want to find out that yours has issues here when a
power failure hits your server room and you’re not around to manually restart your
servers.

If you rely on the UPS to shutdown your systems in case of mains failure and to restart
them when the power returns, you must test this. You can do so by running upsmon -c fsd.
With the mains present, this should bring your systems down and then cycle the power to
restart them again. If you do the same without mains present, it should do the same, but
in this case, the outputs shall remain off until mains power is applied again.

AUTHORS

       Originally sponsored by MGE UPS SYSTEMS. Now sponsored by Eaton
       http://opensource.eaton.com Arnaud Quette, Peter Selinger, Arjen de Korte