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