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 TrippLite models
37
38       For a more complete list, refer to the NUT hardware compatibility list,
39       available in the source distribution as data/drivers.list, or on the
40       NUT website. You may use the "explore" driver option to gather
41       information from HID UPSes which are not yet supported; see below for
42       details.
43
44       This driver is known to work on:
45
46       ·   most Linux systems,
47
48       ·   FreeBSD (beta stage) and maybe other *BSD,
49
50       ·   Darwin / Mac OS X,
51
52       ·   Solaris 10.
53

EXTRA ARGUMENTS

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

INSTALLATION

120       This driver is not built by default. You can build it by using
121       "configure --with-usb=yes". Note that it will also install other USB
122       drivers.
123
124       You also need to install manually the legacy hotplug files (libhidups
125       and libhid.usermap, generally in /etc/hotplug/usb/), or the udev file
126       (nut-usbups.rules, generally in /etc/udev/rules.d/) to address the
127       permission settings problem. For more information, refer to the README
128       file in nut/scripts/hotplug or nut/scripts/udev.
129
130       On Linux with MGE equipment, you will need at least a 2.4.25 or 2.6.2
131       kernel as well as libusb-0.1.8 or later to disable hiddev support and
132       avoid conflict.
133

IMPLEMENTATION

135       The driver ignores the "port" value in ups.conf. Unlike previous
136       versions of this driver, it is now possible to control multiple UPS
137       units simultaneously with this driver, provided they can be
138       distinguished by setting some combination of the "vendor", "product",
139       "serial", "vendorid", and "productid" options. For instance:
140
141           [mge]
142                   driver = usbhid-ups
143                   port = auto
144                   vendorid = 0463
145           [tripplite]
146                   driver = usbhid-ups
147                   port = auto
148                   vendorid = 09ae
149

KNOWN ISSUES AND BUGS

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

AUTHORS

185       Originally sponsored by MGE UPS SYSTEMS. Now sponsored by Eaton
186       http://opensource.eaton.com Arnaud Quette, Peter Selinger, Arjen de
187       Korte
188