1USBHID-UPS(8) NUT Manual USBHID-UPS(8)
2
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
14 usbhid-ups brings USB/HID UPS monitoring to NUT on all platforms
15 supporting USB through libusb. It should detect any UPS that uses the
16 HID Power Device Class, but the amount of data will vary depending on
17 the manufacturer and model.
18 At the present time, usbhid-ups supports:
20 • the newer Eaton USB models,
22 • all MGE USB models,
24 • all Dell USB models,
26 • all AMETEK Powervar UPM models,
28 • some APC models,
30 • some Belkin models,
32 • some Cyber Power Systems models,
34 • some Powercom models,
36 • some PowerWalker models,
38 • some TrippLite models.
40 For a more complete list, refer to the NUT hardware compatibility list,
42 available in the source distribution as data/driver.list, or on the NUT
43 website. You may use the "explore" driver option to gather information
44 from HID UPSes which are not yet supported; see below for details.
45 This driver is known to work on:
47 • most Linux systems,
49 • FreeBSD (beta stage) and maybe other *BSD,
51 • Darwin / Mac OS X,
53 • Solaris 10.
55
57 This driver also supports the following optional settings:
58 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 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 Note that many Cyber Power Systems (CPS) models tend to divide this
68 delay by 60 and round down, so the minimum advisable value is 60 to
69 avoid powering off immediately after NUT sends the shutdown command
70 to the UPS.
71 ondelay=num
73 Set the timer for the UPS to switch on in case the power returns
74 after the kill power command had been sent, but before the actual
75 switch off. This ensures the machines connected to the UPS are, in
76 all cases, rebooted after a power failure.
77 The default value is 30 (in seconds). Usually this must be greater
79 than offdelay, but the driver will not warn you upon startup if it
80 isn’t. Some UPSes will restart no matter what, even if the power is
81 (still) out at the moment this timer elapses. In that case, you
82 could see whether setting ondelay = -1 in ups.conf helps.
83 Note that many CPS models tend to divide this delay by 60 and round
85 down, so the minimum advisable value is 120 to allow a short delay
86 between when the UPS shuts down, and when the power returns.
87 pollfreq=num
89 Set polling frequency for full updates, in seconds. Compared to the
90 quick updates performed every "pollinterval" (the latter option is
91 described in ups.conf(5)), the "pollfreq" interval is for polling
92 the less-critical variables. The default value is 30 (in seconds).
93 pollonly
95 If this flag is set, the driver will not use Interrupt In transfers
96 during the shorter "pollinterval" cycles (not recommended, but
97 needed if these reports are broken on your UPS).
98 onlinedischarge
100 If this flag is set, the driver will treat OL+DISCHRG status as
101 offline. For most devices this combination means calibration or
102 similar maintenance; however some UPS models (e.g. CyberPower UT
103 series) emit OL+DISCHRG when wall power is lost — and need this
104 option to handle shutdowns.
105 vendor=regex, product=regex, serial=regex, vendorid=regex,
107 productid=regex
108 Select a specific UPS, in case there is more than one connected via
109 USB. Each option specifies an extended regular expression (see
110 regex(7)) that must match the UPS’s entire vendor/product/serial
111 string (minus any surrounding whitespace), or the whole 4-digit
112 hexadecimal code for vendorid and productid. Try -DD for finding
113 out the strings to match.
114 Examples:
116 • -x vendor="Foo.Corporation.*"
118 • -x vendorid=051d* (APC)
120 • -x product=".*(Smart|Back)-?UPS.*"
122 bus=regex
124 Select a UPS on a specific USB bus or group of buses. The argument
125 is a regular expression that must match the bus name where the UPS
126 is connected (e.g. bus="002", bus="00[2-3]").
127 device = regex
129 Select a UPS on a specific USB device or group of devices. The
130 argument is a regular expression that must match the device name
131 where the UPS is connected (e.g. device="001", device="00[1-2]").
132 Note that device numbers are not guaranteed by the OS to be stable
133 across re-boots or device re-plugging.
134 explore
136 With this option, the driver will connect to any device, including
137 ones that are not yet supported. This must always be combined with
138 the "vendorid" option. In this mode, the driver will not do
139 anything useful except for printing debugging information
140 (typically used with -DD).
141 maxreport
143 With this option, the driver activates a tweak to workaround buggy
144 firmware returning invalid HID report length. Some APC Back-UPS
145 units are known to have this bug.
146 interruptonly
148 If this flag is set, the driver will not poll UPS. This also
149 implies using of INPUT flagged objects. Some Powercom units need
150 this option.
151 interruptsize=num
153 Limit the number of bytes to read from interrupt pipe. For some
154 Powercom units this option should be equal to 8.
155
157 This driver is not built by default. You can build it by using
158 "configure --with-usb=yes". Note that it will also install other USB
159 drivers.
160 You also need to install manually the legacy hotplug files (libhidups
162 and libhid.usermap, generally in /etc/hotplug/usb/), or the udev file
163 (nut-usbups.rules, generally in /etc/udev/rules.d/) to address the
164 permission settings problem. For more information, refer to the README
165 file in nut/scripts/hotplug or nut/scripts/udev.
166
168 Selecting a specific UPS
169 The driver ignores the "port" value in ups.conf. Unlike previous
170 versions of this driver, it is now possible to control multiple UPS
171 units simultaneously with this driver, provided they can be
172 distinguished by setting some combination of the "vendor", "product",
173 "serial", "vendorid", and "productid" options. For instance:
174 [mge]
176 driver = usbhid-ups
177 port = auto
178 vendorid = 0463
179 [tripplite]
180 driver = usbhid-ups
181 port = auto
182 vendorid = 09ae
183 USB Polling and Interrupt Transfers
185 The usbhid-ups driver has two polling intervals. The "pollinterval"
186 configuration option controls what can be considered the "inner loop",
187 where the driver polls and waits briefly for "interrupt" reports. The
188 "pollfreq" option is for less frequent updates of a larger set of
189 values, and as such, we recommend setting that interval to several
190 times the value of "pollinterval".
191 Many UPSes will respond to a USB Interrupt In transfer with HID reports
193 corresponding to values which have changed. This saves the driver from
194 having to poll each value individually with USB Control transfers.
195 Since the OB and LB status flags are important for a clean shutdown,
196 the driver also explicitly polls the HID paths corresponding to those
197 status bits during the inner "pollinterval" time period. The "pollonly"
198 option can be used to skip the Interrupt In transfers if they are known
199 not to work.
200
202 Repetitive timeout and staleness
203 Some models tends to be unresponsive with the default polling
204 frequency. The result is that your system log will have lots of
205 messages like:
206 usb 2-1: control timeout on ep0in
208 usb 2-1: usbfs: USBDEVFS_CONTROL failed cmd usbhid-ups rqt 128 rq 6 len 256
209 ret -110
210 In this case, simply modify the general parameter "pollinterval" to a
212 higher value (such as 10 seconds). This should solve the issue.
213 Note that if you increase "pollinterval" beyond 10 or 15 seconds, you
215 might also want to increase "pollfreq" by the same factor.
216 Got EPERM: Operation not permitted upon driver startup
218 You have forgotten to install the hotplug files, as explained in the
219 INSTALLATION section above. Don’t forget to restart hotplug so that it
220 applies these changes.
221 Unattended shutdowns
223 The hardware which was used for development of this driver is almost
224 certainly different from what you have, and not all manufacturers
225 follow the USB HID Power Device Class specifications to the letter. You
226 don’t want to find out that yours has issues here when a power failure
227 hits your server room and you’re not around to manually restart your
228 servers.
229 If you rely on the UPS to shutdown your systems in case of mains
231 failure and to restart them when the power returns, you must test this.
232 You can do so by running upsmon -c fsd. With the mains present, this
233 should bring your systems down and then cycle the power to restart them
234 again. If you do the same without mains present, it should do the same,
235 but in this case, the outputs shall remain off until mains power is
236 applied again.
237 UPS cuts power too soon
239 Note that many Cyber Power Systems (CPS) models tend to divide offdelay
240 by 60 and round down, so the minimum advisable value is 60 (seconds) to
241 avoid powering off immediately after NUT sends the shutdown command to
242 the UPS.
243 UPS does not set battery.charge.low but says OK
245 Note that many Cyber Power Systems (CPS) models tend to allow only
246 certain values for battery.charge.low and anything outside of the set
247 of allowed values are rounded or ignored.
248 A shell loop like this can help you map out the allowed values:
250 for i in `seq 90 -1 0`; do echo "set to $i"; \
252 upsrw -s battery.charge.low=$i -u * -p * cps-big; \
253 sleep 1; upsc cps-big battery.charge.low; echo ""; \
254 done
255 For example, for CPS PR1000LCDRTXL2U model, the only allowed values are
257 [60,55,50,45,40,35,30,25,20] and in some cases, your UPS may
258 effectively not support a value of 10 for the battery.charge.low
259 setting.
260
262 This driver, formerly called newhidups, replaces the legacy hidups
263 driver, which only supported Linux systems.
264
266 Originally sponsored by MGE UPS SYSTEMS.
267 Now sponsored by Eaton http://opensource.eaton.com
269 • Arnaud Quette
271 • Peter Selinger
273 • Arjen de Korte
275
277 The core driver
278 nutupsdrv(8)
279 Internet resources
281 The NUT (Network UPS Tools) home page: http://www.networkupstools.org/
282Network UPS Tools 2.8.0 04/26/2022 USBHID-UPS(8)