usbhid-ups(8)

1USBHID-UPS(8)                     NUT Manual                     USBHID-UPS(8)
2
3
4

NAME

6       usbhid-ups - Driver for USB/HID UPS equipment
7

NOTE

9       This man page only documents the hardware-specific features of the
10       usbhid-ups driver. For information about the core driver, see
11       nutupsdrv(8).
12
13       This driver, formerly called newhidups, replaces the legacy hidups
14       driver, which only supported Linux systems.
15

SUPPORTED HARDWARE

17       usbhid-ups brings USB/HID UPS monitoring to NUT on all platform
18       supporting USB through libusb. It should detect any UPS that uses the
19       HID power device class, but the amount of data will vary depending on
20       the manufacturer and model.
21
22       At the present time, usbhid-ups supports:
23
24       ·   the newer Eaton USB models,
25
26       ·   all MGE USB models,
27
28       ·   all Dell USB models,
29
30       ·   some APC models,
31
32       ·   some Belkin models,
33
34       ·   some Cyber Power Systems models,
35
36       ·   some Powercom models,
37
38       ·   some TrippLite models.
39
40       For a more complete list, refer to the NUT hardware compatibility list,
41       available in the source distribution as data/drivers.list, or on the
42       NUT website. You may use the "explore" driver option to gather
43       information from HID UPSes which are not yet supported; see below for
44       details.
45
46       This driver is known to work on:
47
48       ·   most Linux systems,
49
50       ·   FreeBSD (beta stage) and maybe other *BSD,
51
52       ·   Darwin / Mac OS X,
53
54       ·   Solaris 10.
55

EXTRA ARGUMENTS

57       This driver also supports the following optional settings:
58
59       offdelay=num
60           Set the timer before the UPS is turned off after the kill power
61           command is sent (via the -k switch).
62
63           The default value is 20 (in seconds). Usually this must be lower
64           than ondelay, but the driver will not warn you upon startup if it
65           isn’t.
66
67       ondelay=num
68           Set the timer for the UPS to switch on in case the power returns
69           after the kill power command had been sent but before the actual
70           switch off. This ensures the machines connected to the UPS are, in
71           all cases, rebooted after a power failure.
72
73           The default value is 30 (in seconds). Usually this must be greater
74           than offdelay, but the driver will not warn you upon startup if it
75           isn’t. Some UPS’es will restart no matter what, even if the power
76           is (still) out at the moment this timer elapses. In that case, you
77           could try if setting ondelay = -1 in ups.conf helps.
78
79       pollfreq=num
80           Set polling frequency, in seconds, to reduce the USB data flow.
81           Between two polling requests, the driver will wait for interrupts
82           (aka UPS notifications), which are data changes returned by the UPS
83           by itself. This mechanism allow to avoid or reduce staleness
84           message, due to the UPS being temporarily overloaded with too much
85           polling requests. The default value is 30 (in seconds).
86
87       pollonly
88           If this flag is set, the driver will ignore interrupts it receives
89           from the UPS (not recommended, but needed if these reports are
90           broken on your UPS).
91
92       vendor=regex, product=regex, serial=regex, vendorid=regex,
93       productid=regex
94           Select a specific UPS, in case there is more than one connected via
95           USB Each option specifies an extended regular expression (see
96           regex(7)) that must match the UPS’s entire vendor/product/serial
97           string (minus any surrounding whitespace), or the whole 4-digit
98           hexadecimal code for vendorid and productid. Try -DD for finding
99           out the strings to match.
100
101           Examples:
102
103           ·   -x vendor="Foo.Corporation.*"
104
105           ·   -x vendorid=051d* (APC)
106
107           ·   -x product=".*(Smart|Back)-?UPS.*"
108
109       bus=regex
110           Select a UPS on a specific USB bus or group of busses. The argument
111           is a regular expression that must match the bus name where the UPS
112           is connected (e.g. bus="002", bus="00[2-3]").
113
114       explore
115           With this option, the driver will connect to any device, including
116           ones that are not yet supported. This must always be combined with
117           the "vendorid" option. In this mode, the driver will not do
118           anything useful except for printing debugging information
119           (typically used with -DD).
120
121       maxreport
122           With this option, the driver activates a tweak to workaround buggy
123           firmware returning invalid HID report length. Some APC Back-UPS
124           units are known to have this bug.
125
126       interruptonly
127           If this flag is set, the driver will not poll UPS. This also
128           implies using of INPUT flagged objects. Some Powercom units need
129           this option.
130
131       interruptsize=num
132           Limit the number of bytes to read from interrupt pipe. For some
133           Powercom units this option should be equal to 8.
134

INSTALLATION

136       This driver is not built by default. You can build it by using
137       "configure --with-usb=yes". Note that it will also install other USB
138       drivers.
139
140       You also need to install manually the legacy hotplug files (libhidups
141       and libhid.usermap, generally in /etc/hotplug/usb/), or the udev file
142       (nut-usbups.rules, generally in /etc/udev/rules.d/) to address the
143       permission settings problem. For more information, refer to the README
144       file in nut/scripts/hotplug or nut/scripts/udev.
145
146       On Linux with MGE equipment, you will need at least a 2.4.25 or 2.6.2
147       kernel as well as libusb-0.1.8 or later to disable hiddev support and
148       avoid conflict.
149

IMPLEMENTATION

151       The driver ignores the "port" value in ups.conf. Unlike previous
152       versions of this driver, it is now possible to control multiple UPS
153       units simultaneously with this driver, provided they can be
154       distinguished by setting some combination of the "vendor", "product",
155       "serial", "vendorid", and "productid" options. For instance:
156
157           [mge]
158                   driver = usbhid-ups
159                   port = auto
160                   vendorid = 0463
161           [tripplite]
162                   driver = usbhid-ups
163                   port = auto
164                   vendorid = 09ae
165

KNOWN ISSUES AND BUGS

167   Repetitive timeout and staleness
168       Some models tends to be unresponsive with the default polling
169       frequency. The result is that your system log will have lots of
170       messages like:
171
172           usb 2-1: control timeout on ep0in
173           usb 2-1: usbfs: USBDEVFS_CONTROL failed cmd usbhid-ups rqt 128 rq 6 len 256
174           ret -110
175
176       In this case, simply modify the general parameter "pollinterval" to a
177       higher value (like 10 for 10 seconds). This should solve the issue.
178
179   Got EPERM: Operation not permitted upon driver startup
180       You have forgotten to install the hotplug files, as explained in the
181       INSTALLATION section above. Don’t forget to restart hotplug so that it
182       applies these changes.
183
184   Unattended shutdowns
185       The hardware which was used for development of this driver is almost
186       certainly different from what you have, and not all manufacturers
187       follow the USB HID Power Device Class specifications to the letter. You
188       don’t want to find out that yours has issues here when a power failure
189       hits your server room and you’re not around to manually restart your
190       servers.
191
192       If you rely on the UPS to shutdown your systems in case of mains
193       failure and to restart them when the power returns, you must test this.
194       You can do so by running upsmon -c fsd. With the mains present, this
195       should bring your systems down and then cycle the power to restart them
196       again. If you do the same without mains present, it should do the same,
197       but in this case, the outputs shall remain off until mains power is
198       applied again.
199

AUTHORS

201       Originally sponsored by MGE UPS SYSTEMS. Now sponsored by Eaton
202       http://opensource.eaton.com Arnaud Quette, Peter Selinger, Arjen de
203       Korte
204