Note

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

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

•most Linux systems,

•FreeBSD (beta stage) and maybe other *BSD,

•Darwin / Mac OS X,

•Solaris 10 and illumos-based distributions.

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

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:

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.

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.

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.

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.

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

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.

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

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.

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.

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.

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

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.

If this flag is set, the driver will not use Interrupt In transfers during the shorter "pollinterval" cycles (not recommended, but needed if these reports are broken on your UPS).

Set the tolerance for how many times in a row could we have "Got 0 HID objects" when using USB interrupt mode? This may normally be due to a device having nothing urgent to report, so the default value is -1 and this situation is not handled in any way specially. However with some devices this was seen in conjunction with a frozen controller, where only a driver reconnection restored the data exchange (e.g. APC BXnnnnMI) — in such cases you may want to use a reasonable non-negative value here.

If this flag is set, the driver will treat OL+DISCHRG status as offline/on-battery.

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

DEPRECATED, old name for onlinedischarge_battery described above.

If this flag is set, the driver will treat OL+DISCHRG status as calibration. Some UPS models (e.g. APC were seen to do so) report OL+DISCHRG when they are in calibration mode. This usually happens after a few seconds reporting an OFF state as well, while the hardware is switching to on-battery mode.

Set the minimum frequency (in seconds) at which warnings would be emitted for an otherwise not handled OL+DISCHRG device status combination. Negative values disable sequentially repeated messages (when this state appears and persists).

If the device does not report battery.charge, the default value is 30 seconds (fairly frequent, in case the UPS-reported state combination does reflect a bad power condition and so the situation is urgent).

If it does report battery.charge, by default the repeated notifications would only be logged if this charge is different from when the message was emitted previously (e.g. when the battery is really discharging).

If both this option is set, and battery.charge is correctly reported, either of these rules allow the notification to be logged.

See details in onlinedischarge_log_throttle_sec and battery.charge based log message throttling description above. This option adds a concept of UPS "hovering" a battery charge at some level deemed safe for its chemistry, and not forcing it to be fully charged all the time. As long as the current value of battery.charge remains at or above this threshold percentage (default 100), the OL+DISCHRG message logging is not triggered by variations of the charge.

Set to delay status-setting (and log messages) about device entering LB or LB+RB state.

Some APC BXnnnnMI device models or firmware versions (reportedly 2023-2024), or APC BVKnnnnM2 device models, 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). This setting lets the driver ignore short-lived states and only pay attention if they persist longer than this setting (and the device power state is OL).

Set to apply lbrb_log_delay_sec even if device is not calibrating.

Set to disable fix-ups for broken USB encoding, etc. which we apply by default on certain models (vendors/products) which were reported as not following the protocol strictly. This flag allows to disable the feature in particular device configurations.

It is always possible that the vendors eventually release fixed firmware, or re-use identifiers by which we match suspected broken devices for unrelated products, so processing these fix-ups would be a waste of time there.

It is also always possible that NUT fix-ups cause issues on some devices, whether due to NUT bugs or because the vendor protocol implementation is broken in more than one place.

Original PowerCOM HID subdriver code (until version 0.7) sent UPS shutdown and stayoff commands in a wrong byte order, than what is needed by actual devices seen in the field in 2024. The byte order is fixed to satisfy new devices by default since version 0.71. Just in case there are different firmwares out there with opposite behaviors, we provide this toggle to use old behavior in a particular deployment. Maybe it was just a bug and nobody needs this fall-back...

With this option, the driver will connect to any device, including ones that are not yet supported. This must always be combined with the "vendorid" option. In this mode, the driver will not do anything useful except for printing debugging information (typically used with -DD).

With this option, the driver activates a tweak to workaround buggy firmware returning invalid HID report length. Some APC Back-UPS units are known to have this bug.

If this flag is set, the driver will not poll UPS. This also implies using of INPUT flagged objects. Some Powercom units need this option.

Limit the number of bytes to read from interrupt pipe. For some Powercom units this option should be equal to 8.

The driver automatically tries to reconnect to the UPS on unexpected error. This parameter (in seconds) allows it to wait before attempting the reconnection. The default value is 0.

•Arnaud Quette

•Peter Selinger

•Arjen de Korte