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(8).
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:
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:
This driver also supports the following optional settings:
port = string
This could be a device filesystem path like /dev/usb/hiddev0 but current use of libusb API precludes knowing and matching by such identifiers. They may also be inherently unreliable (dependent on re-plugging and enumeration order). At this time the actual value is ignored, but syntactically some port configuration must still be there.
It is possible to control multiple UPS units simultaneously by running several instances of this driver, provided they can be uniquely distinguished by setting some combination of the vendor, product, vendorid, productid, serial, bus and/or device options detailed below. For devices or operating systems that do not provide sufficient information, the allow_duplicates option can be of use (limited and risky!)
vendorid = regex, productid = regex, vendor = regex, product = regex, serial = regex
Try lsusb(8) or running this NUT driver with -DD command-line argument for finding out the strings to match.
bus = regex
device = regex
device numbers are not guaranteed by the OS to be stable across re-boots or device re-plugging.
busport = regex
this option is not practically supported by some NUT builds (it should be ignored with a warning then), and not by all systems that NUT can run on.
Normally the driver initialization would abort at this point claiming "Resource busy" or similar error, assuming that the otherwise properly matched device is unique — and some other process already handles it.
This feature is inherently non-deterministic! The association of driver instance name to actual device may vary between runs!
If you only care to know that at least one of your no-name UPSes is online, this option can help.
If you must really know which one, it will not!
usb_set_altinterface = bAlternateSetting
Run the driver program with the --help option to see the exact list of subdriver values it would currently recognize.
this option first checks for exact matches to subdriver identification strings, such as "TrippLite HID 0.85" (which are prone to bit-rot), and if there was no exact match — retries with a case-insensitive extended regular expression.
When using this option, it is mandatory to also specify the vendorid and productid matching parameters.
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.
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.
If it takes so long on your device that a shutdown gets issued, you may want to look at upsmon option OFFDURATION used to filter out temporary values of "administrative OFF" as not a loss of a feed for the powered load.
It is always possible that the vendors eventually release fixed firmware, or re-use identifiers by which we match suspected broken devices for unrelated products, so processing these fix-ups would be a waste of time there.
It is also always possible that NUT fix-ups cause issues on some devices, whether due to NUT bugs or because the vendor protocol implementation is broken in more than one place.
for instance, it was found that Eaton MGE Ellipse Max 1500 FR UPS firmware stops responding every few hours, which causes usbhid-ups driver to detect an libusb insufficient memory error; in this case, when the usbhid-ups driver tries to reconnect too early, the activity sometimes led the UPS firmware to crash and turn off the load immediately! Setting this parameter to 30 seconds solved this problem (while 20 seconds were not enough).
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.
As mentioned above, 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 device-matching options. For instance:
driver = usbhid-ups
port = auto
vendorid = 0463 [tripplite]
driver = usbhid-ups
port = auto
vendorid = 09ae
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.
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.
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.
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.
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.
This driver, formerly called newhidups, replaces the legacy hidups driver, which only supported Linux systems.
Originally sponsored by MGE UPS SYSTEMS.
Now sponsored by Eaton http://opensource.eaton.com
The NUT (Network UPS Tools) home page: https://www.networkupstools.org/
|Network UPS Tools 2.8.1