Man Linux: Main Page and Category List

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  replaces  the  legacy hidups driver, which only supported
       Linux systems, and was formerly called newhidups.

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 the Dell USB models,
           some APC models,
           some Belkin models,
           some Cyber Power Systems 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).

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

   Sponsored by MGE UPS SYSTEMS <http://opensource.mgeups.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/

                                Tue Nov 10 2009