1USBHID-UPS(8) NUT Manual USBHID-UPS(8)
2
3
4
6 usbhid-ups - Driver for USB/HID UPS equipment
7
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
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
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
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
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
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
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
206 The core driver
207 nutupsdrv(8)
208
209 Internet resources
210 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
211
212
213
214Network UPS Tools 2.7.3. 12/29/2015 USBHID-UPS(8)