Imported Upstream version 2.6.0
This commit is contained in:
arnaud.quette@free.fr
parent
26fb71b504
commit
459aaf9392
510 changed files with 40508 additions and 18859 deletions
207
docs/man/usbhid-ups.txt
Normal file
207
docs/man/usbhid-ups.txt
Normal file
|
|
@ -0,0 +1,207 @@
|
|||
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/
|
||||
Loading…
Add table
Add a link
Reference in a new issue