USBHID-UPS(8)

📦

version 2.8.5 · 18 versions

💖 NAME 💖

okay bestie, meet usbhid-ups(8) — from the NUT manual, the driver for USB/HID UPS equipment. That's the whole name section, but the tea is just getting started. 💅

✨ SYNOPSIS ✨

usbhid-ups -h

usbhid-ups -a UPS_NAME [OPTIONS]

Note 📝 This man page only documents the hardware-specific features of the usbhid-ups driver. For info about the core driver, see nutupsdrv(8).

🦋 SUPPORTED HARDWARE 🦋

usbhid-ups 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. iykyk

At the present time, usbhid-ups supports:

the newer Eaton USB models,
all MGE USB models,
all Dell USB models,
all AMETEK Powervar UPM models,
some APC models,
some Belkin models,
some Cyber Power Systems models,
some Powercom models,
some PowerWalker models,
some TrippLite models.

For a more complete list, refer to the NUT hardware compatibility list, available in the NUT 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, to help add such support; see below for details. 👀

This driver is known to work on:

most Linux systems,
FreeBSD (beta stage) and maybe other *BSD,
Darwin / Mac OS X,
Solaris 10 and illumos-based distributions.

💅 EXTRA ARGUMENTS 💅

This driver also supports the following optional settings:

port = string — Required option for all NUT drivers. Some value must be set, typically auto for drivers that handle USB connections.

Note 🫶 This could be a device filesystem path like /dev/usb/hiddev0 but current use of libusb API precludes knowing and matching by such identifiers. They may also be inherently unreliable (dependent on re-plugging and enumeration order). At this time the actual value is ignored, but syntactically some port configuration must still be there.

It is possible to control multiple UPS units simultaneously by running several instances of this driver, provided they can be uniquely distinguished by setting some combination of the vendor, product, vendorid, productid, serial, bus and/or device options detailed below. For devices or operating systems that do not provide sufficient information, the allow_duplicates option can be of use (limited and risky!) 😬

vendorid = regex, productid = regex, vendor = regex, product = regex, serial = regex — Select a specific UPS, in case there is more than one connected via USB. Each option specifies an extended regular expression (see regex(7) for more information on regular expressions), which must match the UPS's entire respective vendor/product/serial string values (minus any surrounding whitespace), or the whole 4-digit hexadecimal code for vendorid and productid.

Try lsusb(8) or running this NUT driver with -DD command-line argument for finding out the strings to match. 🔍

Examples:

-x vendor="Foo.Corporation.*"
-x vendorid="051d*" (APC)
-x product=".*(Smart|Back)-?UPS.*"

bus = regex — OPTIONAL, NOT RECOMMENDED. 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" or bus="00[2-3]") as seen on Linux in /sys/bus/usb/devices or lsusb(8); including leading zeroes.

Note 😭 Bus numbers are not guaranteed by the OS to be stable across re-boots, kernel driver reloads or device re-plugging (e.g. changing visible population of USB hubs).

device = regex — OPTIONAL, NOT RECOMMENDED. 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" or device="00[1-2]") as seen on Linux in /sys/bus/usb/devices or lsusb(8); including leading zeroes.

Note 😭 Device numbers are not guaranteed by the OS to be stable across re-boots or device re-plugging.

busport = regex — OPTIONAL, NOT RECOMMENDED. If supported by the hardware, OS and libusb on the particular deployment, this option should allow to specify physical port numbers on an USB hub, rather than logical device enumeration values, and in turn — this should be less volatile across reboots or re-plugging. The value may be seen in the USB topology output of lsusb -tv on systems with that tool, for example.

Note 😭 This option is not practically supported by some NUT builds (it should be ignored with a warning then), and not by all systems that NUT can run on.

allow_duplicates — OPTIONAL, NOT RECOMMENDED. If you have several UPS devices which may not be uniquely identified by the options above (e.g. only VID:PID can be discovered there), this flag allows each driver instance where it is set to take the first match if available, or proceed to try another.

Normally the driver initialization would abort at this point claiming "Resource busy" or similar error, assuming that the otherwise properly matched device is unique — and some other process already handles it.

Warning This feature is inherently non-deterministic! The association of driver instance name to actual device may vary between runs! If you only care to know that at least one of your no-name UPSes is online, this option can help. If you must really know which one, it will not!

usb_set_altinterface = bAlternateSetting — Force redundant call to usb_set_altinterface(), especially if needed for devices serving multiple USB roles where the UPS is not represented by the interface number 0 (default).
usb_config_index, usb_hid_rep_index, usb_hid_desc_index, usb_hid_ep_in, usb_hid_ep_out — Force use of specific interface, endpoint, descriptor index etc. numbers, rather than defaulting to 0 (rarely other values in certain drivers for some devices known to use non-zero numbers). Specified as a hexadecimal number.

As a rule of thumb for usb_hid_desc_index discovery, you can see larger wDescriptorLength values (roughly 600+ bytes) in reports of lsusb or similar tools.

LIBUSB_DEBUG = INTEGER — Run-time troubleshooting of USB-capable NUT drivers can involve not only raising the common NUT debug verbosity (e.g. using the DEBUG_MIN setting in ups.conf(5) or protocol commands to change the driver.debug value), but may also benefit from LibUSB specific debugging.

For the latter, you can set the LIBUSB_DEBUG driver option; alternatively you can classically export the environment variable LIBUSB_DEBUG before starting a NUT driver program (may be set and "exported" in driver init script or service method, perhaps via nut.conf(5)), to a numeric value such as 4 ("All messages are emitted"). 🔥

For more details, including the currently supported values for your version of the library, see e.g.:

subdriver=regex — Select the USB HID subdriver for the device manually, where automatic match by device attributes alone does not suffice (e.g. new devices for which no vendorid/productid pair was built into any driver — but common USB HID support is anticipated, or for different-capability devices with same interface chips, notably "phoenixtec/liebert" and "mge").

Run the driver program with the --help option to see the exact list of subdriver values it would currently recognize. 📋

Note 🧚 This option first checks for exact matches to subdriver identification strings, such as "TrippLite HID 0.85" (which are prone to bit-rot), and if there was no exact match — retries with a case-insensitive extended regular expression.

Note 🧚 When using this option, it is mandatory to also specify the vendorid and productid matching parameters.

lowbatt=num — Set the percentage at which the UPS will consider the battery charge as critically low, possibly resulting in a forced shutdown (FSD) situation. ⚡

This value is typically dictated by the UPS device, although there is a fallback default value of 30 (in percent). Overriding this value can be helpful when the UPS sets this value to a lower percentage than intended.

offdelay=num — Set the timer before the UPS is turned off after the kill power command is sent (via the -k switch).

The default value is 20 (in seconds), or 60 for CPS devices. Usually this must be lower than ondelay, but the driver will not warn you upon startup if it isn't.

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. More details below.

ondelay=num — 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.

The default value is 30 (in seconds), or 120 for CPS devices. Usually this must be greater than offdelay, but the driver will not warn you upon startup if it isn't. 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 ups.conf helps.

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. According to support statement (for at least some CPS models), "our UPS systems are unable to set up power on delay".

pollfreq=num — Set polling frequency for full updates, in seconds. Compared to the quick updates performed every "pollinterval" (the latter option is described in ups.conf(5)), the "pollfreq" interval is for polling the less-critical variables. The default value is 30 (in seconds), or 12 sec for CPS devices.

Note: this setting is not the same thing as the POLLFREQ that upsmon(8) supports, okay? Different beast entirely (go read its upsmon.conf(5) if you want the tea 💅).

pollonly — turn this flag on and the driver will ✋ not use Interrupt In transfers during the shorter pollinterval cycles. Lowkey not the move (not recommended, fr), but you need it if those reports are broken on your UPS. 🙈
winhid — on Windows builds, set this flag and the driver uses the experimental native Windows HID backend instead of libusb. Windows bestie, this one's for you 🪟✨

This backend currently follows a read-focused scope, no cap. It supports device discovery and matching by identifiers like vendorid and productid, input/feature reads, and interrupt-report fallback handling. Feature-report writes are not implemented in this phase, so writable setvar/instcmd operations may be unavailable. 😭

This option is ignored on non-WIN32 builds. (Sorry not sorry.)

interrupt_pipe_no_events_tolerance=num — sets the tolerance for how many times in a row we could get "Got 0 HID objects" while using USB interrupt mode. Normally that just means the device has nothing urgent to report, so the default is -1 and this whole situation is handled... not specially at all, bestie. 💀 But with some devices this was seen alongside a frozen controller, where only a driver reconnection restored the data exchange (looking at you, APC BXnnnnMI) — so in those cases you may wanna use a reasonable non-negative value here. 🫶
onlinedischarge_battery — set this flag and the driver treats OL+DISCHRG status as offline/on-battery. 🔋

For most devices this combo just means calibration or some similar maintenance moment; however some UPS models (e.g. CyberPower UT series) emit OL+DISCHRG when wall power is lost — and they need this option to handle shutdowns. Slay responsibly.

onlinedischarge — DEPRECATED, it's just the old name for onlinedischarge_battery up above. Use the new one, bestie. 🚫
onlinedischarge_calibration — set this flag and the driver treats OL+DISCHRG status as calibration. Some UPS models (e.g. APC, we've seen it 👀) report OL+DISCHRG while they're in calibration mode. This usually happens a few seconds after also reporting an OFF state, while the hardware is switching over to on-battery mode. 🦋

Note: if this takes so long on your device that a shutdown gets issued, you might wanna peek at the upsmon option OFFDURATION, which filters out temporary values of "administrative OFF" so they don't read as a loss of feed for the powered load. iykyk 💅

onlinedischarge_log_throttle_sec=num — sets the minimum frequency (in seconds) at which warnings get emitted for an OL+DISCHRG device status combo that's otherwise not handled. Negative values disable sequentially repeated messages (for when this state shows up and just... persists 😭).

If the device does not report battery.charge, the default value is 30 seconds — fairly frequent, because if that UPS-reported state combo really does reflect a bad power condition, then bestie, the situation is urgent. 🚨

If it does report battery.charge, then by default the repeated notifications would only be logged when this charge differs from when the message was emitted previously (e.g. when the battery is genuinely discharging). 🔋✨

If both this option is set and battery.charge is correctly reported, either of these rules lets the notification get logged. Two paths, same slay.

onlinedischarge_log_throttle_hovercharge=num — the details live in onlinedischarge_log_throttle_sec and the battery.charge-based log message throttling description above ⬆️. This option adds the concept of a UPS "hovering" its battery charge at some level deemed safe for its chemistry, instead of forcing it to be fully charged 24/7. As long as the current value of battery.charge stays at or above this threshold percentage (default 100), the OL+DISCHRG message logging is not triggered by variations of the charge. Chill battery hours 🧘‍♀️
lbrb_log_delay_sec=num — set this to delay status-setting (and the log messages 🗣️) about a device entering LB or LB+RB state.

Some APC BXnnnnMI device models or firmware versions (reportedly 2023-2024 👀), or APC BVKnnnnM2 device models, or APC BKnnnnM2-CH (a China-market-only model), frequently report "low battery", "replace battery", and "all ok" states changing rapidly within a couple of seconds — sometimes (but not always) preceded by OL+DISCHRG (presumably calibration). Chaos behavior, honestly 💀

This setting lets the driver ignore those short-lived states and only pay attention if they persist longer than this setting (and the device power state is OL). Patience is a virtue, periodt.

lbrb_log_delay_without_calibrating — set this to apply lbrb_log_delay_sec even if the device is not calibrating. ✨
disable_fix_report_desc — set this to disable fix-ups for broken USB encoding, etc., which we apply by default on certain models (vendors/products) that were reported as not following the protocol strictly. This flag lets you disable the feature for particular device configurations. 🛠️

It's always possible that vendors eventually release fixed firmware, or re-use identifiers we match against suspected broken devices for totally unrelated products — so processing these fix-ups there would just be a waste of time, bestie. ⏰

It's also always possible that NUT fix-ups cause issues on some devices — whether from NUT bugs or because the vendor protocol implementation is broken in more than one place. 🙃

powercom_sdcmd_byte_order_fallback — the original PowerCOM HID subdriver code (all the way until version 0.7) sent UPS shutdown and stayoff commands in the wrong byte order than what the actual devices seen in the field in 2024 needed. The byte order got fixed to satisfy new devices by default since version 0.71. But just in case there are different firmwares out there with opposite behaviors, we provide this toggle to use the old behavior in a particular deployment. Maybe it was just a bug and nobody needs this fall-back... but here it is anyway 🫠
powercom_sdcmd_discrete_delay — some devices (Raptor and Smart KING Pro series) follow a protocol where we can not set an arbitrary value of shutdown delay in seconds (like on other powercom UPSes), but must use values only from the "Table of possible delays for Shutdown commands" specified in the protocol document 📜. This option makes the driver convert delays between seconds (in standard NUT variables) and the nearest indexed entry from that table. Math but make it protocol.
explore — with this option, the driver will connect to any device, including ones that aren't supported yet 👑. This must always be combined with the "vendorid" option. In this mode the driver won't do anything useful except print debugging information (typically used with -DD). It's giving detective era 🔍
maxreport — with this option, the driver activates a tweak to work around buggy firmware returning invalid HID report length. Some APC Back-UPS units are known to have this bug. 🙈
interruptonly — if this flag is set, the driver will not poll the UPS. This also implies using of INPUT flagged objects. Some Powercom units need this option. 📥
interruptsize=num — limits the number of bytes to read from the interrupt pipe. For some Powercom units this option should be equal to 8. 🔢
waitbeforereconnect=num — the driver automatically tries to reconnect to the UPS on unexpected error. This parameter (in seconds) lets it wait before attempting the reconnection. The default value is 0. ⏳

Note: for instance, it was found that Eaton MGE Ellipse Max 1500 FR UPS firmware stops responding every few hours, which causes the usbhid-ups driver to detect a libusb insufficient memory error 😭; in this case, when the usbhid-ups driver tries to reconnect too early, the activity sometimes led the UPS firmware to crash and turn off the load immediately! 🚨 Setting this parameter to 30 seconds solved this problem (while 20 seconds were not enough). So yeah, timing matters, bestie.

🛠️ INSTALLATION 🛠️

This driver may be not built by default, jsyk. You can build it by installing prerequisites and using configure --with-usb=yes. Note that it will also install other USB drivers. Two-for-one, lowkey a deal 💖

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 scripts/hotplug/README.adoc or scripts/udev/README.adoc files in NUT sources. Go read them, they're right there 🫶

🧚 IMPLEMENTATION 🧚

Selecting a specific UPS 🎯

As mentioned above, the driver ignores the "port" value in ups.conf. Bye port, didn't need you 💅

Unlike previous versions of this driver, it is now possible to control multiple UPS units simultaneously with instances of this driver running in parallel — provided they can be distinguished by setting some combination of the device-matching options. Main character energy, running them all at once 👑

For example:

[mge]
        driver = usbhid-ups
        port = auto
        vendorid = 0463
[tripplite]
        driver = usbhid-ups
        port = auto
        vendorid = 09ae

To monitor devices using the same vendor and product identification (e.g. two pieces of the same model), you would need to find a reliable unique matching criteria:

The serial number is the best option, if populated. ⭐
Link-level bus/device/busport may be unreliable (due to re-enumeration on a whim by the operating system 😤).
If nothing else helps, allow_duplicates may be an option in some cases.

USB Polling and Interrupt Transfers 🔄

The usbhid-ups 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". Two loops, one icon 💫

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. 🚫

💀 KNOWN ISSUES AND BUGS 💀

okay bestie, gather round, this is the part where we air out all the messy little quirks this driver has. none of these are your fault, they're just… the vibe of the hardware. 🙈

😭 UPS reports 65535 sec (or 18:12:15) of `battery.runtime` capability

so from like a bunch of reports, it looks like some devices straight up can't report more than a 16-bit unsigned value in the standard field for remaining run time (maybe vendor extended fields exist but they're unknown to the mapping tables in your current NUT driver build, iykyk), or they return -1 for an error and that just gets treated as an unsigned 16-bit 65535 value. iconic behavior honestly. 💅

per some issue discussions, passing a battery test (calibration) can help the UPS re-estimate the time more correctly. so like, run the calibration, let it cook. ✨

this problem may also be linked to a very lightly loaded large-capacity UPS. in some cases the vendor documentation explicitly states that runtime calculation is not reliable with loads under, e.g., 10%. so if your big girl UPS is doing basically nothing, she's guessing. 🌸

🔁 Repetitive timeout and staleness

some models tend to be unresponsive with the default polling frequency, and then your system log gets flooded with messages like:

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

in this case, simply modify the general parameter "pollinterval" to a higher value (such as 10 seconds). that should solve the issue. periodt. 🫶

heads up: if you increase "pollinterval" beyond 10 or 15 seconds, you might also want to increase "pollfreq" by the same factor. keep them in sync bestie, they're a package deal. 💖

with certain devices and operating systems — notably MGE/Eaton USB Vendor ID (0x0463) on some versions of the Linux kernel — you might encounter poor interaction with the "USB HID quirk" mechanism, which precludes Linux from seeing the device as a hid-generic first, to hand it over to a NUT driver later. for more details, see the NUT FAQ document. this particular quirk can be tuned with a kernel boot parameter (via GRUB etc.):

usbhid.quirks=0x0463:0xffff:0x08

conversely, some hardware controllers may "fall asleep" when not contacted for too long — CPS devices are commonly associated with such behaviour. in this case, consider enabling the pollonly flag and/or keeping pollfreq and/or pollinterval small. she needs attention, okay?? 💜

🙅 Got `EPERM: Operation not permitted` upon driver startup

bestie. you forgot to install the hotplug files, as explained in the INSTALLATION section above. don't forget to restart hotplug so that it applies these changes. that's it, that's the whole bug. 😭

⚡ Unattended shutdowns

the hardware that 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 do not want to find out that yours has issues here when a power failure hits your server room and you're not around to manually restart your servers. that's giving horror movie energy. 💀

if you rely on the UPS to shutdown your systems in case of mains failure and to restart them when the power returns, you must test this. you can do so by running upsmon -c fsd. 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. 🔥

✂️ UPS cuts power too soon

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. 😳

for many Cyberpower UPSs, offdelay must be set to 0 for normal behavior (the load is restored when AC power returns). setting offdelay above 0 will restart the UPS load regardless of whether or not power has returned, and setting offdelay below 0 will disable the auto-power-on function of the UPS, keeping the load off even when power returns. so like, choose wisely, this is main character decision territory. 👑

🔋 UPS does not set `battery.charge.low` but says OK

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. so she'll say "OK" and then simply not do it. the audacity. 🙈

a shell loop like this can help you map out the allowed values:

for i in `seq 90 -1 0`; do echo "set to $i"; \
    upsrw -s battery.charge.low=$i -u * -p * cps-big; \
    sleep 1; upsc cps-big battery.charge.low; echo ""; \
done

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. so yeah, she has a very specific taste. 💅

📜 HISTORY

this driver, formerly called newhidups, replaces the legacy hidups driver, which only supported Linux systems. glow-up of the century honestly. ✨

👑 AUTHORS

originally sponsored by MGE UPS SYSTEMS.

now sponsored by Eaton http://opensource.eaton.com

Arnaud Quette
Peter Selinger
Arjen de Korte

legends, all three of them. 🫶

🔍 SEE ALSO

The core driver

nutupsdrv(8)

Internet resources

the NUT (Network UPS Tools) home page: https://www.networkupstools.org/historic/v2.8.5/

and that's the whole page bestie, you read every single bit of it, so proud of you. 🥹 this was Network UPS Tools 2.8.5, dated 10/07/2026, filed under USBHID-UPS(8). go plug in a UPS and be normal about it. mwah 💖🌸💅

📦 where this page comes from

fedora 43: nut 2.8.5-9.fc43 · GPL-2.0-or-later AND GPL-3.0-or-later
fedora 43: nut 2.8.5-9.fc43 · GPL-2.0-or-later AND GPL-3.0-or-later
fedora 44: nut 2.8.5-9.fc44 · GPL-2.0-or-later AND GPL-3.0-or-later
fedora 44: nut 2.8.5-9.fc44 · GPL-2.0-or-later AND GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-19: a language model's rewrite of the original, under its terms