usbhid-ups
From: https://manpages.ubuntu.com/manpages/noble/en/man8/usbhid-ups.8.html 





noble (8) usbhid-ups.8.gz
Provided by: nut-server_2.8.1-3.1ubuntu2_amd64 bug


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 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:

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:





EXTRA ARGUMENTS

This driver also supports the following optional settings:


port = string Some value must be set, typically auto.

		Note
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
	   Select a specific UPS, in case there is more than one connected via USB. Each option
	   specifies an extended regular expression (see regex(7) for more information on regular
	   expressions), which must match the UPS’s entire respective vendor/product/serial
	   string (minus any surrounding whitespace), or the whole 4-digit hexadecimal code for
	   vendorid and productid.

	   Try lsusb(8) or running this NUT driver with -DD command-line argument for finding out
	   the strings to match.

		Examples:


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" or
	   bus="00[2-3]") as seen on Linux in /sys/bus/usb/devices or lsusb(8); including leading
	   zeroes.


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" or device="00[1-2]") as seen on Linux in /sys/bus/usb/devices or
	   lsusb(8); including leading zeroes.

		Note
device numbers are not guaranteed by the OS to be stable across re-boots or 
device re-plugging.


busport = regex
	   If supported by the hardware, OS and libusb on the particular deployment, this option
	   should allow to specify physical port numbers on an USB hub, rather than logical
	   device enumeration values, and in turn — this should be less volatile across reboots
	   or re-plugging. The value may be seen in the USB topology output of lsusb -tv on
	   systems with that tool, for example.

		   Note
		   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.


allow_duplicates
	   If you have several UPS devices which may not be uniquely identified by the options
	   above (e.g. only VID:PID can be discovered there), this flag allows each driver
	   instance where it is set to take the first match if available, or proceed to try
	   another.

	   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.

Warning
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
	   Force redundant call to usb_set_altinterface(), especially if needed for devices
	   serving multiple USB roles where the UPS is not represented by the interface number 0
	   (default).


subdriver=regex
	   Select the USB HID subdriver for the device manually, where automatic match by device
	   attributes alone does not suffice (e.g. new devices for which no vendorid/productid
	   pair was built into any driver — but common USB HID support is anticipated, or for
	   different-capability devices with same interface chips, notably "phoenixtec/liebert"
	   and "mge").

	   Run the driver program with the --help option to see the exact list of subdriver
	   values it would currently recognize.

		Note
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.

		Note
When using this option, it is mandatory to also specify the vendorid and 
productid matching parameters.


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 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.


onlinedischarge_calibration
	   If this flag is set, the driver will treat OL+DISCHRG status as calibration. Some UPS
	   models (e.g. APC were seen to do so) report OL+DISCHRG when they are in calibration
	   mode. This usually happens after a few seconds reporting an OFF state as well, while
	   the hardware is switching to on-battery mode.

		Note
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.


disable_fix_report_desc
	   Set to disable fix-ups for broken USB encoding, etc. which we apply by default on
	   certain models (vendors/products) which were reported as not following the protocol
	   strictly. This flag allows to disable the feature in particular device configurations.

	   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.


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.


waitbeforereconnect=num
	   The driver automatically tries to reconnect to the UPS on unexpected error. This
	   parameter (in seconds) allows it to wait before attempting the reconnection. The
	   default value is 0.

		Note
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).




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
       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:


           [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
       nutupsdrv(8)

   Internet resources
       The NUT (Network UPS Tools) home page: https://www.networkupstools.org/