301 lines
10 KiB
Text
301 lines
10 KiB
Text
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].
|
|
|
|
SUPPORTED HARDWARE
|
|
------------------
|
|
|
|
*usbhid-ups* brings USB/HID UPS monitoring to NUT on all platforms 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,
|
|
- all AMETEK Powervar UPM models,
|
|
- some APC models,
|
|
- some Belkin models,
|
|
- some Cyber Power Systems models,
|
|
- some Powercom models,
|
|
- some PowerWalker models,
|
|
- some TrippLite models.
|
|
|
|
For a more complete list, refer to the NUT hardware compatibility list,
|
|
available in the source distribution as data/driver.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.
|
|
+
|
|
Note that many Cyber Power Systems (CPS) models tend to divide this delay by
|
|
60 and round down, so the minimum advisable value is 60 to avoid powering off
|
|
immediately after NUT sends the shutdown command to the UPS.
|
|
|
|
*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 UPSes will restart no matter what, even if the power is
|
|
(still) out at the moment this timer elapses. In that case, you could see
|
|
whether setting `ondelay = -1` in *ups.conf* helps.
|
|
+
|
|
Note that many CPS models tend to divide this delay by 60 and round down, so
|
|
the minimum advisable value is 120 to allow a short delay between when the UPS
|
|
shuts down, and when the power returns.
|
|
|
|
*pollfreq*='num'::
|
|
Set polling frequency for full updates, in seconds. Compared to the quick
|
|
updates performed every "pollinterval" (the latter option is described in
|
|
linkman:ups.conf[5]), the "pollfreq" interval is for polling the less-critical
|
|
variables. The default value is 30 (in seconds).
|
|
|
|
*pollonly*::
|
|
If this flag is set, the driver will not use Interrupt In transfers during the
|
|
shorter "pollinterval" cycles (not recommended, but needed if these reports
|
|
are broken on your UPS).
|
|
|
|
*onlinedischarge*::
|
|
If this flag is set, the driver will treat `OL+DISCHRG` status as offline.
|
|
For most devices this combination means calibration or similar maintenance;
|
|
however some UPS models (e.g. CyberPower UT series) emit `OL+DISCHRG` when
|
|
wall power is lost -- and need this option to handle shutdowns.
|
|
|
|
*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 buses. 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]").
|
|
|
|
*device =* 'regex'::
|
|
|
|
Select a UPS on a specific USB device or group of devices. The argument is
|
|
a regular expression that must match the device name where the UPS is
|
|
connected (e.g. device="001", device="00[1-2]").
|
|
Note that device numbers are not guaranteed by the OS to be stable across
|
|
re-boots or device re-plugging.
|
|
|
|
*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).
|
|
|
|
*maxreport*::
|
|
With this option, the driver activates a tweak to workaround buggy firmware
|
|
returning invalid HID report length. Some APC Back-UPS units are known to have
|
|
this bug.
|
|
|
|
*interruptonly*::
|
|
If this flag is set, the driver will not poll UPS. This also implies using of
|
|
INPUT flagged objects. Some Powercom units need this option.
|
|
|
|
*interruptsize*='num'::
|
|
Limit the number of bytes to read from interrupt pipe. For some Powercom units
|
|
this option should be equal to 8.
|
|
|
|
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.
|
|
|
|
IMPLEMENTATION
|
|
--------------
|
|
|
|
Selecting a specific UPS
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
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
|
|
|
|
USB Polling and Interrupt Transfers
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
The *usbhid-ups* driver has two polling intervals. The "pollinterval"
|
|
configuration option controls what can be considered the "inner loop", where
|
|
the driver polls and waits briefly for "interrupt" reports. The "pollfreq"
|
|
option is for less frequent updates of a larger set of values, and as such, we
|
|
recommend setting that interval to several times the value of "pollinterval".
|
|
|
|
Many UPSes will respond to a USB Interrupt In transfer with HID reports
|
|
corresponding to values which have changed. This saves the driver from having
|
|
to poll each value individually with USB Control transfers. Since the `OB` and
|
|
`LB` status flags are important for a clean shutdown, the driver also
|
|
explicitly polls the HID paths corresponding to those status bits during the
|
|
inner "pollinterval" time period. The "pollonly" option can be used to skip
|
|
the Interrupt In transfers if they are known not to work.
|
|
|
|
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 (such as 10 seconds). This should solve the issue.
|
|
|
|
Note that if you increase "pollinterval" beyond 10 or 15 seconds, you might
|
|
also want to increase "pollfreq" by the same factor.
|
|
|
|
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.
|
|
|
|
UPS cuts power too soon
|
|
~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Note that many Cyber Power Systems (CPS) models tend to divide `offdelay`
|
|
by 60 and round down, so the minimum advisable value is 60 (seconds) to avoid
|
|
powering off immediately after NUT sends the shutdown command to the UPS.
|
|
|
|
UPS does not set battery.charge.low but says OK
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
Note that many Cyber Power Systems (CPS) models tend to allow only certain
|
|
values for `battery.charge.low` and anything outside of the set of allowed
|
|
values are rounded or ignored.
|
|
|
|
A shell loop like this can help you map out the allowed values:
|
|
|
|
====
|
|
for i in `seq 90 -1 0`; do echo "set to $i"; \
|
|
upsrw -s battery.charge.low=$i -u * -p * cps-big; \
|
|
sleep 1; upsc cps-big battery.charge.low; echo ""; \
|
|
done
|
|
====
|
|
|
|
For example, for CPS PR1000LCDRTXL2U model, the only allowed values are
|
|
`[60,55,50,45,40,35,30,25,20]` and in some cases, your UPS may effectively
|
|
not support a value of 10 for the `battery.charge.low` setting.
|
|
|
|
HISTORY
|
|
-------
|
|
|
|
This driver, formerly called 'newhidups', replaces the legacy 'hidups' driver,
|
|
which only supported Linux systems.
|
|
|
|
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/
|