208 lines
6.8 KiB
Plaintext
208 lines
6.8 KiB
Plaintext
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
|
|
linkman: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 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
|
|
-------
|
|
|
|
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
|
|
~~~~~~~~~~~~~~~~
|
|
linkman:nutupsdrv[8]
|
|
|
|
Internet resources
|
|
~~~~~~~~~~~~~~~~~~
|
|
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
|