Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
USBHID-UPS(8)			  NUT Manual			 USBHID-UPS(8)

       usbhid-ups - Driver for USB/HID UPS equipment

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

       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.

       At the present time, usbhid-ups supports:

       o   the newer Eaton USB models,

       o   all MGE USB models,

       o   all Dell USB	models,

       o   all AMETEK Powervar UPM models,

       o   some	APC models,

       o   some	Belkin models,

       o   some	Cyber Power Systems models,

       o   some	Powercom models,

       o   some	TrippLite models.

       For a more complete list, refer to the NUT hardware compatibility list,
       available in the	source distribution as data/drivers.list, or on	the
       NUT website. You	may use	the "explore" driver option to gather
       information from	HID UPSes which	are not	yet supported; see below for

       This driver is known to work on:

       o   most	Linux systems,

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

       o   Darwin / Mac	OS X,

       o   Solaris 10.

       This driver also	supports the following optional	settings:

	   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). Usually this must be lower
	   than	ondelay, but the driver	will not warn you upon startup if it

	   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.

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

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

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

       vendor=regex, product=regex, serial=regex, vendorid=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)) that must match the UPS's entire vendor/product/serial
	   string (minus any surrounding whitespace), or the whole 4-digit
	   hexadecimal code for	vendorid and productid.	Try -DD	for finding
	   out the strings to match.


	   o   -x vendor="Foo.Corporation.*"

	   o   -x vendorid=051d* (APC)

	   o   -x product=".*(Smart|Back)-?UPS.*"

	   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", bus="00[2-3]").

       device =	regex
	   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", device="00[1-2]").
	   Note	that device numbers are	not guaranteed by the OS to be stable
	   across re-boots or device re-plugging.

	   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.

       This driver is not built	by default. You	can build it by	using
       "configure --with-usb=yes". Note	that it	will also install other	USB

       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 README
       file in nut/scripts/hotplug or nut/scripts/udev.

   Selecting a specific	UPS
       The driver ignores the "port" value in ups.conf.	Unlike previous
       versions	of this	driver,	it is now possible to control multiple UPS
       units simultaneously with this driver, provided they can	be
       distinguished by	setting	some combination of the	"vendor", "product",
       "serial", "vendorid", and "productid" options. For instance:

		   driver = usbhid-ups
		   port	= auto
		   vendorid = 0463
		   driver = usbhid-ups
		   port	= auto
		   vendorid = 09ae

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

       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.

   Repetitive timeout and staleness
       Some models tends to be unresponsive with the default polling
       frequency. The result is	that your system log will have lots of
       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). This should solve the	issue.

       Note that if you	increase "pollinterval"	beyond 10 or 15	seconds, you
       might also want to increase "pollfreq" by the same factor.

   Got EPERM: Operation	not permitted upon driver startup
       You have	forgotten to install the hotplug files,	as explained in	the
       INSTALLATION section above. Don't forget	to restart hotplug so that it
       applies these changes.

   Unattended shutdowns
       The hardware which 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
       don't 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

       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.

       This driver, formerly called newhidups, replaces	the legacy hidups
       driver, which only supported Linux systems.

       Originally sponsored by MGE UPS SYSTEMS.	Now sponsored by Eaton Arnaud Quette, Peter	Selinger, Arjen	de

   The core driver

   Internet resources
       The NUT (Network	UPS Tools) home	page:

Network	UPS Tools 2.7.4.	  08/28/2021			 USBHID-UPS(8)


Want to link to this manual page? Use this URL:

home | help