usbhid-ups - Driver for USB/HID UPS equipment
This man page only documents the hardware-specific features of the usbhid-ups
driver. For information about the core driver, see nutupsdrv
This driver, formerly called newhidups
, replaces the legacy hidups
driver, which only supported Linux systems.
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 Powercom 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
•Darwin / Mac OS X,
This driver also supports the following optional settings:
Set the timer before the UPS is turned off
after the kill power command is sent (via the -k
The default value is 20 (in seconds). Usually this must be lower
, but the driver will not
warn you upon startup if it
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
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
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).
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).
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
finding out the strings to match.
•-x vendorid=051d* (APC)
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",
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).
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.
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.
Limit the number of bytes to read from
interrupt pipe. For some Powercom units this option should be equal to
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.
The driver ignores the "port" value in ups.conf
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.
driver = usbhid-ups
port = auto
vendorid = 0463
driver = usbhid-ups
port = auto
vendorid = 09ae
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
In this case, simply modify the general parameter "pollinterval" to a
higher value (like 10 for 10 seconds). This should solve the issue.
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.
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.
Originally sponsored by MGE UPS SYSTEMS. Now sponsored by Eaton
http://opensource.eaton.com Arnaud Quette, Peter Selinger, Arjen de Korte
The NUT (Network UPS Tools) home page: http://www.networkupstools.org/