189 lines
6.8 KiB
Groff
189 lines
6.8 KiB
Groff
.TH USBHID-UPS 8 "Tue Nov 10 2009" "" "Network UPS Tools (NUT)"
|
|
.SH NAME
|
|
usbhid-ups \- Driver for USB/HID UPS equipment
|
|
.SH NOTE
|
|
This man page only documents the hardware\(hyspecific features of the
|
|
usbhid-ups driver. For information about the core driver, see
|
|
\fBnutupsdrv\fR(8).
|
|
|
|
This driver replaces the legacy hidups driver, which only supported
|
|
Linux systems, and was formerly called newhidups.
|
|
|
|
.SH SUPPORTED HARDWARE
|
|
.B 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.
|
|
|
|
.SH EXTRA ARGUMENTS
|
|
This driver also supports the following optional settings:
|
|
|
|
.IP "offdelay=\fInum\fR"
|
|
Set the timer before the UPS is turned off after the kill power command is
|
|
sent (via the \fB\-k\fR switch).
|
|
|
|
The default value is 20 (in seconds). Usually this \fBmust be lower\fR than
|
|
ondelay, but the driver will \fBnot\fR warn you upon startup if it isn't.
|
|
|
|
.IP "ondelay=\fInum\fR"
|
|
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 \fBmust be greater\fR
|
|
than offdelay, but the driver will \fBnot\fR 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 \fBups.conf\fR helps.
|
|
|
|
.IP "pollfreq=\fInum\fR"
|
|
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).
|
|
|
|
.IP "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).
|
|
|
|
.IP "vendor=\fIregex\fR"
|
|
.IP "product=\fIregex\fR"
|
|
.IP "serial=\fIregex\fR"
|
|
.IP "vendorid=\fIregex\fR"
|
|
.IP "productid=\fIregex\fR"
|
|
|
|
Select a specific UPS, in case there is more than one connected via
|
|
USB. Each option specifies an extended regular expression (see
|
|
\fBregex(7)\fR) 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 \fB-DD\fR for
|
|
finding out the strings to match.
|
|
|
|
Examples:
|
|
|
|
\fB-x vendor="Foo.Corporation.*"\fR
|
|
|
|
\fB-x vendorid=051d\fR (APC)
|
|
|
|
\fB-x product=".*(Smart|Back)-?UPS.*"\fR
|
|
|
|
.IP "bus=\fIregex\fR"
|
|
|
|
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]").
|
|
|
|
.IP "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
|
|
\fB-DD\fR).
|
|
|
|
.SH 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.
|
|
|
|
|
|
.SH IMPLEMENTATION
|
|
The driver ignores the "port" value in \fBups.conf\fR. 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:
|
|
|
|
.nf
|
|
[mge]
|
|
driver = usbhid-ups
|
|
port = auto
|
|
vendorid = 0463
|
|
[tripplite]
|
|
driver = usbhid-ups
|
|
port = auto
|
|
vendorid = 09ae
|
|
.fi
|
|
|
|
.SH KNOWN ISSUES AND BUGS
|
|
.SS "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:
|
|
.nf
|
|
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
|
|
.fi
|
|
|
|
In this case, simply modify the general parameter "pollinterval" to a higher
|
|
value (like 10 for 10 seconds). This should solve the issue.
|
|
|
|
.SS "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.
|
|
|
|
.SS "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 \fBmust\fR 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.
|
|
|
|
.SH AUTHORS
|
|
.SS Sponsored by MGE UPS SYSTEMS <http://opensource.mgeups.com/>
|
|
Arnaud Quette, Peter Selinger, Arjen de Korte
|
|
|
|
.SH SEE ALSO
|
|
|
|
.SS The core driver:
|
|
\fBnutupsdrv\fR(8)
|
|
|
|
.SS Internet resources:
|
|
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
|