'\" t
.\"     Title: usbhid-ups
.\"    Author: [see the "AUTHORS" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 01/25/2023
.\"    Manual: NUT Manual
.\"    Source: Network UPS Tools 2.8.0
.\"  Language: English
.\"
.TH "USBHID\-UPS" "8" "01/25/2023" "Network UPS Tools 2\&.8\&.0" "NUT Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
usbhid-ups \- Driver for USB/HID UPS equipment
.SH "NOTE"
.sp
This man page only documents the hardware\-specific features of the usbhid\-ups driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.
.SH "SUPPORTED HARDWARE"
.sp
\fBusbhid\-ups\fR 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\&.
.sp
At the present time, usbhid\-ups supports:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the newer Eaton USB models,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
all MGE USB models,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
all Dell USB models,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
all AMETEK Powervar UPM models,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
some APC models,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
some Belkin models,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
some Cyber Power Systems models,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
some Powercom models,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
some PowerWalker models,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
some TrippLite models\&.
.RE
.sp
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\&.
.sp
This driver is known to work on:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
most Linux systems,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
FreeBSD (beta stage) and maybe other *BSD,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Darwin / Mac OS X,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Solaris 10\&.
.RE
.SH "EXTRA ARGUMENTS"
.sp
This driver also supports the following optional settings:
.PP
\fBoffdelay\fR=\fInum\fR
.RS 4
Set the timer before the UPS is turned off after the kill power command is sent (via the
\fB\-k\fR
switch)\&.
.sp
The default value is 20 (in seconds)\&. Usually this
\fBmust be lower\fR
than
\fIondelay\fR, but the driver will
\fBnot\fR
warn you upon startup if it isn\(cqt\&.
.sp
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\&.
.RE
.PP
\fBondelay\fR=\fInum\fR
.RS 4
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\&.
.sp
The default value is 30 (in seconds)\&. Usually this
\fBmust be greater\fR
than offdelay, but the driver will
\fBnot\fR
warn you upon startup if it isn\(cqt\&. 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
\fBups\&.conf\fR
helps\&.
.sp
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\&.
.RE
.PP
\fBpollfreq\fR=\fInum\fR
.RS 4
Set polling frequency for full updates, in seconds\&. Compared to the quick updates performed every "pollinterval" (the latter option is described in
\fBups.conf\fR(5)), the "pollfreq" interval is for polling the less\-critical variables\&. The default value is 30 (in seconds)\&.
.RE
.PP
\fBpollonly\fR
.RS 4
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)\&.
.RE
.PP
\fBonlinedischarge\fR
.RS 4
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 \(em and need this option to handle shutdowns\&.
.RE
.PP
\fBvendor\fR=\fIregex\fR, \fBproduct\fR=\fIregex\fR, \fBserial\fR=\fIregex\fR, \fBvendorid\fR=\fIregex\fR, \fBproductid\fR=\fIregex\fR
.RS 4
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\(cqs entire vendor/product/serial string (minus any surrounding whitespace), or the whole 4\-digit hexadecimal code for vendorid and productid\&. Try
\fB\-DD\fR
for finding out the strings to match\&.
.sp
Examples:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-x vendor="Foo\&.Corporation\&.*"
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-x vendorid=051d*
(APC)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\-x product="\&.*(Smart|Back)\-?UPS\&.*"
.RE
.RE
.PP
\fBbus\fR=\fIregex\fR
.RS 4
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]")\&.
.RE
.PP
\fBdevice =\fR \fIregex\fR
.RS 4
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\&.
.RE
.PP
\fBexplore\fR
.RS 4
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)\&.
.RE
.PP
\fBmaxreport\fR
.RS 4
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\&.
.RE
.PP
\fBinterruptonly\fR
.RS 4
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\&.
.RE
.PP
\fBinterruptsize\fR=\fInum\fR
.RS 4
Limit the number of bytes to read from interrupt pipe\&. For some Powercom units this option should be equal to 8\&.
.RE
.SH "INSTALLATION"
.sp
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\&.
.sp
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\&.
.SH "IMPLEMENTATION"
.SS "Selecting a specific UPS"
.sp
The driver ignores the "port" value in \fBups\&.conf\fR\&. 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:
.sp
.if n \{\
.RS 4
.\}
.nf
[mge]
        driver = usbhid\-ups
        port = auto
        vendorid = 0463
[tripplite]
        driver = usbhid\-ups
        port = auto
        vendorid = 09ae
.fi
.if n \{\
.RE
.\}
.SS "USB Polling and Interrupt Transfers"
.sp
The \fBusbhid\-ups\fR 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"\&.
.sp
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\&.
.SH "KNOWN ISSUES AND BUGS"
.SS "Repetitive timeout and staleness"
.sp
Some models tends to be unresponsive with the default polling frequency\&. The result is that your system log will have lots of messages like:
.sp
.if n \{\
.RS 4
.\}
.nf
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
.fi
.if n \{\
.RE
.\}
.sp
In this case, simply modify the general parameter "pollinterval" to a higher value (such as 10 seconds)\&. This should solve the issue\&.
.sp
Note that if you increase "pollinterval" beyond 10 or 15 seconds, you might also want to increase "pollfreq" by the same factor\&.
.SS "Got EPERM: Operation not permitted upon driver startup"
.sp
You have forgotten to install the hotplug files, as explained in the INSTALLATION section above\&. Don\(cqt forget to restart hotplug so that it applies these changes\&.
.SS "Unattended shutdowns"
.sp
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\(cqt want to find out that yours has issues here when a power failure hits your server room and you\(cqre not around to manually restart your servers\&.
.sp
If you rely on the UPS to shutdown your systems in case of mains failure and to restart them when the power returns, you \fBmust\fR test this\&. You can do so by running \fIupsmon \-c fsd\fR\&. 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\&.
.SS "UPS cuts power too soon"
.sp
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\&.
.SS "UPS does not set battery\&.charge\&.low but says OK"
.sp
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\&.
.sp
A shell loop like this can help you map out the allowed values:
.sp
.if n \{\
.RS 4
.\}
.nf
for i in `seq 90 \-1 0`; do echo "set to $i"; \e
    upsrw \-s battery\&.charge\&.low=$i \-u * \-p * cps\-big; \e
    sleep 1; upsc cps\-big battery\&.charge\&.low; echo ""; \e
done
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.SH "HISTORY"
.sp
This driver, formerly called \fInewhidups\fR, replaces the legacy \fIhidups\fR driver, which only supported Linux systems\&.
.SH "AUTHORS"
.sp
Originally sponsored by MGE UPS SYSTEMS\&.
.sp
Now sponsored by Eaton http://opensource\&.eaton\&.com
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Arnaud Quette
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Peter Selinger
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Arjen de Korte
.RE
.SH "SEE ALSO"
.SS "The core driver"
.sp
\fBnutupsdrv\fR(8)
.SS "Internet resources"
.sp
The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/