USBHID-UPS(8)
=============

NAME
----

usbhid-ups - Driver for USB/HID UPS equipment

SYNOPSIS
--------

*usbhid-ups* -h

*usbhid-ups* -a 'UPS_NAME' ['OPTIONS']

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 NUT 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, to help add such support; 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 and illumos-based distributions.

EXTRA ARGUMENTS
---------------

This driver also supports the following optional settings:

include::nut_usb_addvars.txt[]

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

*lowbatt*='num'::
Set the percentage at which the UPS will consider the battery charge as
critically low, possibly resulting in a forced shutdown (FSD) situation.
+
This value is typically dictated by the UPS device, although there is a
fallback default value of 30 (in percent). Overriding this value can be
helpful when the UPS sets this value to a lower percentage than intended.

*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), or 60 for CPS devices.
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. More details
below.

*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), or 120 for CPS devices.
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. According to support statement (for at
least some CPS models), "our UPS systems are unable to set up power on delay".

*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), or 12 sec for CPS devices.
+
NOTE: This setting is different from a `POLLFREQ` supported by linkman:upsmon[8]
(for details see its linkman:upsmon.conf[5]).

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

*winhid*::
If this flag is set on Windows builds, use the experimental native Windows HID
backend instead of libusb.
+
This backend currently follows a read-focused scope. It supports
device discovery and matching by identifiers such as `vendorid` and
`productid`, input/feature reads, and interrupt-report fallback handling.
Feature-report writes are not implemented in this phase, so writable
`setvar`/`instcmd` operations may be unavailable.
+
This option is ignored on non-WIN32 builds.

*interrupt_pipe_no_events_tolerance*='num'::
Set the tolerance for how many times in a row could we have "Got 0 HID objects"
when using USB interrupt mode?  This may normally be due to a device having
nothing urgent to report, so the default value is `-1` and this situation is
not handled in any way specially.  However with some devices this was seen
in conjunction with a frozen controller, where only a driver reconnection
restored the data exchange (e.g. APC BXnnnnMI) -- in such cases you may want
to use a reasonable non-negative value here.

*onlinedischarge_battery*::
If this flag is set, the driver will treat `OL+DISCHRG` status as
offline/on-battery.
+
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*::
DEPRECATED, old name for `onlinedischarge_battery` described above.

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

*onlinedischarge_log_throttle_sec*='num'::
Set the minimum frequency (in seconds) at which warnings would be emitted
for an otherwise not handled `OL+DISCHRG` device status combination.
Negative values disable sequentially repeated messages (when this state
appears and persists).
+
If the device does not report `battery.charge`, the default value is 30 seconds
(fairly frequent, in case the UPS-reported state combination does reflect a
bad power condition and so the situation is urgent).
+
If it does report `battery.charge`, by default the repeated notifications
would only be logged if this charge is different from when the message was
emitted previously (e.g. when the battery is really discharging).
+
If both this option is set, and `battery.charge` is correctly reported,
either of these rules allow the notification to be logged.

*onlinedischarge_log_throttle_hovercharge*='num'::
See details in `onlinedischarge_log_throttle_sec` and `battery.charge` based
log message throttling description above.  This option adds a concept of UPS
"hovering" a battery charge at some level deemed safe for its chemistry, and
not forcing it to be fully charged all the time.  As long as the current value
of `battery.charge` remains at or above this threshold percentage (default 100),
the `OL+DISCHRG` message logging is not triggered by variations of the charge.

*lbrb_log_delay_sec*='num'::
Set to delay status-setting (and log messages) about device entering `LB` or
`LB+RB` state.
+
Some APC BXnnnnMI device models or firmware versions (reportedly 2023-2024),
or APC BVKnnnnM2 device models, or APC BKnnnnM2-CH (a China-market-only model),
frequently report "low battery", "replace battery", and "all ok" states
changing rapidly within a couple of seconds, sometimes (but not always)
preceded by `OL+DISCHRG` (presumably calibration).
+
This setting lets the driver ignore short-lived states and only pay attention
if they persist longer than this setting (and the device power state is `OL`).

*lbrb_log_delay_without_calibrating*::
Set to apply `lbrb_log_delay_sec` even if device is not calibrating.

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

*powercom_sdcmd_byte_order_fallback*::
Original `PowerCOM HID` subdriver code (until version 0.7) sent UPS `shutdown`
and `stayoff` commands in a wrong byte order, than what is needed by actual
devices seen in the field in 2024.  The byte order is fixed to satisfy new
devices by default since version 0.71.  Just in case there are different
firmwares out there with opposite behaviors, we provide this toggle to use
old behavior in a particular deployment.  Maybe it was just a bug and nobody
needs this fall-back...

*powercom_sdcmd_discrete_delay*::
Some devices (Raptor and Smart KING Pro series) follow the protocol
where we can not set arbitrary value of shutdown delay in seconds
(like in other powercom UPSes), but must use values only from the
"Table of possible delays for Shutdown commands" specified in the
protocol document. This option causes the driver to convert delays
between seconds (in standard NUT variables) and nearest indexed
entry from that table.

*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 may be not built by default.  You can build it by installing
prerequisites and 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
`scripts/hotplug/README.adoc` or `scripts/udev/README.adoc` files in NUT
sources.

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 instances of this driver running
in parallel, provided they can be distinguished by setting some combination
of the device-matching options.

For example:

	[mge]
		driver = usbhid-ups
		port = auto
		vendorid = 0463
	[tripplite]
		driver = usbhid-ups
		port = auto
		vendorid = 09ae

To monitor devices using the same vendor and product identification (e.g.
two pieces of the same model), you would need to find a reliable unique
matching criteria:

* The 'serial' number is the best option, if populated.
* Link-level `bus`/`device`/`busport` may be unreliable (due to re-enumeration
  on a whim by the operating system).
* If nothing else helps, `allow_duplicates` may be an option in some cases.

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

UPS reports 65535 sec (or 18:12:15) of battery.runtime capability
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

From a number of reports, it seems that some devices either can not report
more than a 16-bit unsigned value in the standard field for remaining run
time (vendor extended fields may exist but be unknown to the mapping tables
in your current NUT driver build), or return `-1` for error and that gets
treated as an unsigned 16-bit 65535 value.

According to some issue discussions, passing a battery test (calibration)
can help the UPS re-estimate the time more correctly.

This problem may also be linked to a very lightly loaded large-capacity UPS.
In some cases vendor documentation explicitly states that runtime calculation
is not reliable with loads under e.g. 10%.

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.

With certain devices and operating systems, notably MGE/Eaton USB Vendor ID
(`0x0463`) on some versions of the Linux kernel, you might encounter poor
interaction with the "USB HID quirk" mechanism, which precludes Linux from
seeing the device as a `hid-generic` first, to hand it over to a NUT driver
later. For more details, see the NUT FAQ document. This particular quirk can
be tuned with a kernel boot parameter (via GRUB etc.):

        usbhid.quirks=0x0463:0xffff:0x08

Conversely, some hardware controllers may "fall asleep" when not contacted
for too long; CPS devices are commonly associated with such behaviour.
In this case, consider enabling `pollonly` flag and/or keeping `pollfreq`
and/or `pollinterval` small.

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.

For many Cyberpower UPSs, `offdelay` must be set to `0` for normal behavior
(the load is restored when AC power returns).  Setting `offdelay` above `0`
will restart the UPS load *regardless of whether or not power has returned*,
and setting `offdelay` below `0` will disable the auto-power-on function of
the UPS, keeping the load off even when power returns.

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: https://www.networkupstools.org/
