USBHID-UPS(8)                     NUT Manual                     USBHID-UPS(8)



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:

       o   the newer Eaton USB models,

       o   all MGE USB models,

       o   all Dell USB models,

       o   some APC models,

       o   some Belkin models,

       o   some Cyber Power Systems models,

       o   some Powercom models,

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

       o   most Linux systems,

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

       o   Darwin / Mac OS X,

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

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

           o   -x vendorid=051d* (APC)

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

SEE ALSO
   The core driver
       nutupsdrv(8)

   Internet resources
       The NUT (Network UPS Tools) home page: http://www.networkupstools.org/



Network UPS Tools 2.7.3.          12/29/2015                     USBHID-UPS(8)
