newhidups(8)

1NEWHIDUPS(8)                Network UPS Tools (NUT)               NEWHIDUPS(8)
2
3
4

NAME

6       newhidups - New driver for USB/HID UPS equipment
7

NOTE

9       This  man  page  only  documents  the hardware‐specific features of the
10       newhidups driver.  For information about the core driver,  see  nutups‐
11       drv(8).
12
13

SUPPORTED HARDWARE

15       newhidups brings USB/HID UPS monitoring to NUT on all platform support‐
16       ing USB through libusb.It should detect any UPS that uses the HID power
17       device  class,  but the amount of data will vary depending on the manu‐
18       facturer and model.
19
20       At the present time, newhidups supports:
21
22           all MGE UPS SYSTEMS USB models,
23           some APC models,
24           some Belkin models,
25           some Cyber Power Systems models.
26
27       For a more complete list, refer to the NUT hardware compatibility list,
28       available  in  the  source distribution as data/drivers.list, or on the
29       NUT website. You may use the "explore" driver option to gather informa‐
30       tion from HID UPSes which are not yet supported; see below for details.
31
32       This driver is known to work on:
33
34           most Linux systems,
35           FreeBSD (beta stage) and maybe other *BSD,
36           Solaris 10 (not yet validated).
37
38

EXTRA ARGUMENTS

40       This driver also supports the following optional settings:
41
42
43       offdelay=num
44              Set  the timer before the UPS is turned off after the kill power
45              command is sent (via the -k switch).  The default  value  is  20
46              (in seconds), and MUST BE LOWER than ondelay.
47
48
49       ondelay=num
50              Set the timer for the UPS to switch on in case the power returns
51              after the kill power command had been sent but before the actual
52              switch  off. This ensures the machines connected to the UPS are,
53              in all cases, rebooted after a power failure.  The default value
54              is 30 (in seconds), and MUST BE GREATER than offdelay.
55
56
57       vendor=regex
58
59       product=regex
60
61       serial=regex
62
63       vendorid=regex
64
65       productid=regex
66
67              Select  a specific UPS, in case there is more than one connected
68              via USB. Each option specifies an  extended  regular  expression
69              (see  regex(7))  that  must  match the UPS's entire vendor/prod‐
70              uct/serial string (minus any  surrounding  whitespace),  or  the
71              whole  4-digit  hexadecimal code for vendorid and productid. Try
72              -D -D for finding out the strings to match.
73
74              Examples:
75
76                  -x vendor="Foo.Corporation.*"
77
78                  -x vendorid=051d (APC)
79
80                  -x product=".*(Smart|Back)-?UPS.*"
81
82
83       bus=regex
84
85              Select a UPS on a specific USB bus or group of busses. The argu‐
86              ment  is a regular expression that must match the bus name where
87              the UPS is connected (e.g. bus="002", bus="00[2-3]").
88
89
90       explore
91              With this option, the driver will connect to any device, includ‐
92              ing  ones  that  are not yet supported. This must always be com‐
93              bined with the "vendorid" option. In this mode, the driver  will
94              not do anything useful except for printing debugging information
95              (typically used with -DD).
96
97

INSTALLATION

99       This driver is not built by default.  You can build it by  using  "make
100       usb",  and  install it using "make install‐usb". Note that it will also
101       install other USB drivers.  You also need to install manually the  hot‐
102       plug  files  (libhidups  and  libhid.usermap),  generally  in  etc/hot‐
103       plug/usb/, to address the permission settings problem. Lastly note that
104       the  libhidups  file  must  have  execution flag set (ie using chmod +x
105       ...).
106
107       On Linux with MGE equipment, you will need at least a 2.4.25  or  2.6.2
108       kernel  as  well as libusb-0.1.8 or later to disable hiddev support and
109       avoid conflict.  Otherwise, you will only be  able  to  use  the  older
110       hidups driver, which is no longer maintained.
111
112

IMPLEMENTATION

114       The  driver  ignores the "port" value in ups.conf. Unlike previous ver‐
115       sions of this driver, it is now possible to control multiple UPS  units
116       simultaneously  with  this driver. They can be distinguished by setting
117       some combination of the "vendor", "product", "serial", "vendorid",  and
118       "productid" options. For instance:
119
120            [mge]
121                 driver = newhidups
122                 port = auto
123                 vendorid = 0463
124            [tripplite]
125                 driver = newhidups
126                 port = auto
127                 vendorid = 09ae
128
129

KNOWN ISSUES AND BUGS

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

AUTHORS

138   Sponsored by MGE UPS SYSTEMS <http://opensource.mgeups.com/>
139       Arnaud Quette, Peter Selinger
140
141