next up previous contents index
Next: Building and Installing apcupsd Up: Apcupsd User's Guide Previous: Choosing a Configuration Type   Contents   Index

Subsections


USB Configuration

Apcupsd supports USB connections on all major operating systems: Linux, FreeBSD, OpenBSD, NetBSD, Windows, Solaris, and Mac OS X Darwin. If you plan to use a USB conenction, please read the appropriate subsection in its entirety. You can skip this section if your UPS has a serial (RS232-C) or Ethernet interface or if you are not running one of the platforms listed above.


Linux USB Configuration


Known Linux USB Issues

Problem
Linux 2.4 series kernels older than 2.4.22 (RH 9, RHEL 3) do not bind the USB device to the proper driver. This is evidenced by /proc/bus/usb/devices listing the UPS correctly but it will have ``driver=(none)'' instead of ``driver=(hid)''. This affects RHEL3, among others.
Workaround
Upgrade linux kernel to 2.4.22 or higher. Alternately, you apply the linux-2.4.20-killpower.patch and linux-2.4.20-USB-reject.patch patches to your kernel and rebuild it. These patches can be found in the examples/ directory in the apcupsd source distribution.

Problem
Mandrake 10.0 and 10.1 systems with high security mode enabled (running kernel-secure kernel) use static device nodes but still assign USB minor numbers dynamically. This is evidenced by hiddev0: USB HID v1.10 Device [...] instead of hiddev96: ... in dmesg log.
Workaround
Boot standard kernel instead of kernel-secure or disable CONFIG_USB_DYNAMIC_MINORS and rebuild kernel-secure.

Problem
USB driver linux-usb.c fails to compile, reporting errors about HID_MAX_USAGES undefined. This is due to a defect in the linux kernel hiddev.h header file on 2.6.5 and higher kernels.
Workaround
Upgrade to apcupsd-3.10.14 or higher. These versions contain a workaround for the defect.

Problem
On some systems such as Slackware 10.0, no USB devices will show up (see the next section).
Workaround
Add the following to rc.local

     mount -t usbdevfs none /proc/bus/usb

Problem
2.6 kernels use udev and some distributions to not configure it to automatically create /dev/usb/hiddev?? as they should, causing apcupsd to fail to locate the UPS.
Workaround
Edit the file /etc/udev/rules.d/50-udev.rules, and add the following:

     KERNEL="hiddev*", NAME="usb/hiddev%n"

More details are provided in the following section ...


Checking Out Your Linux USB Subsystem

You need to check three things:

  1. That your USB subsystem can see the UPS
  2. That the kernel has bound the correct driver
  3. That the correct device nodes are available in /dev


Verifying Device Detection and Driver

To make sure that your USB subsystem can see the UPS, just do this from a shell prompt:

     cat /proc/bus/usb/devices

This information is updated by the kernel whenever a device is plugged in or unplugged, irrespective of whether apcupsd is running or not. It contains details on all the USB devices in your system including hubs (internal and external), input devices, and UPSes.

You should get some output back that includes something like this, featuring a BackUPS RS 1000:

     T:  Bus=02 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  3 Spd=1.5 MxCh= 0
     D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
     P:  Vendor=051d ProdID=0002 Rev= 1.06
     S:  Manufacturer=American Power Conversion
     S:  Product=Back-UPS RS 1000 FW:7.g3 .D USB FW:g3
     S:  SerialNumber=JB0308036505
     C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 24mA
     I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=00 Prot=00 Driver=hid

The important things to check for are the S: lines describing your UPS and and the I: line showing what driver is handling it. If on the I: line, Driver is listed as Driver=none then you do not have the HID driver loaded or the driver did not attach to the UPS. One common cause is having a Linux kernel older than 2.4.22 (such as a stock RedHat 9 or RHEL 3 kernel). If this is the case for your system, please upgrade to at least kernel version 2.4.22 and try again. If you are already running a 2.4.22 or higher kernel, please read further for instructions for other possible courses of action.

For a detailed description of the contents of the /proc/bus/usb files, see Interpreting /proc/bus/usb (linux-2.4) or Interpreting /proc/bus/usb (linux-2.6) as appropriate for your kernel version.

Here is another example, this time featuring a Back-UPS 350:

     T:  Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#=  2 Spd=1.5 MxCh= 0
     D:  Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs=  1
     P:  Vendor=051d ProdID=0002 Rev= 1.00
     S:  Manufacturer=American Power Conversion
     S:  Product=Back-UPS 350 FW: 5.2.I USB FW: c1
     S:  SerialNumber=BB0115017954
     C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 30mA
     I:  If#= 0 Alt= 0 #EPs= 1 Cls=03(HID  ) Sub=00 Prot=00 Driver=hid
     E:  Ad=81(I) Atr=03(Int.) MxPS=   8 Ivl= 10ms

In general, if you see your UPS model in the S: field, which means Manufacturer=, Product=, and SerialNumber=, and you see Driver=hid in the I: field, you know the UPS has been recognized and is bound to the correct driver.

If your UPS doesn't appear in the list at all, check the obvious things: The UPS must be powered on, and a cable must be properly seated in both the data port of the UPS and one of your machine's USB ports. Many UPSes have phone ports to provide surge protection for phones or modems - make sure you haven't plugged your USB cable into one of those rather than the data port (which will usually be near the top edge of the case.)

Also, ensure that the correct drivers are loaded. Under Linux-2.4.x, you can check this out easily by examining the /proc/bus/usb/drivers file. Here's how you can do that:

     cat /proc/bus/usb/drivers

...and you should get:

             usbdevfs
             hub
     96-111: hiddev
             hid

On Linux-2.6.x, make sure the sysfs filesystem is mounted on /sys and do:

     ls -l /sys/bus/usb/drivers/

...where you should get:

     total 0
     drwxr-xr-x    2 root     root            0 May  1 18:55 hid
     drwxr-xr-x    2 root     root            0 May  1 18:55 hiddev
     drwxr-xr-x    2 root     root            0 May  1 18:55 hub
     drwxr-xr-x    2 root     root            0 May  1 18:55 usb
     drwxr-xr-x    2 root     root            0 May  1 18:55 usbfs

...or perhaps something like:

     total 0
     drwxr-xr-x  2 root root 0 Jan  6 15:27 hiddev
     drwxr-xr-x  2 root root 0 Jan  6 15:28 hub
     drwxr-xr-x  2 root root 0 Jan  6 15:28 usb
     drwxr-xr-x  2 root root 0 Jan  6 15:27 usbfs
     drwxr-xr-x  2 root root 0 Jan  6 15:28 usbhid

If your 2.6.x system does not have the /sys/bus/usb directory, either you do not have sysfs mounted on /sys or the USB module(s) have not been loaded. (Check /proc/mounts to make sure sysfs is mounted.)

A USB UPS needs all of these drivers - the USB device filesystem, the USB hub, the Human Interface Device subsystem driver, and the Human Interface Device driver. If you are compiling your own kernel, you want to enable

     CONFIG_USB
     CONFIG_USB_HID
     CONFIG_USB_HIDDEV
     CONFIG_USB_DEVICEFS

...as well as at least one USB Host Controller Driver...

     CONFIG_USB_UHCI_HCD (linux-2.6.x)
     CONFIG_USB_OHCI_HCD (linux-2.6.x)
     CONFIG_USB_UHCI     (linux-2.4.x)
     CONFIG_USB_OHCI     (linux-2.4.x)

For a typical USB section of a kernel .config file, please see Typical Linux Kernel Config


Device Nodes

Apcupsd accesses USB UPSes via the hiddev device nodes. Typically these are located in /dev/hiddevN, /dev/usb/hiddevN or /dev/usb/hiddev/hiddevN (where N is a digit 0 thru 9). Some distributions (some Debian releases, possibly others) do not provides these device nodes for you, so you will have to make them yourself. Check /dev, /dev/usb, and /dev/usb/hiddev and if you cannot find the hiddevN nodes, run (as root) the examples/make-hiddev script from the apcupsd source distribution.

Modern Linux distributions using the 2.6 kernel create device nodes dynamically on the fly as they are needed. It is basically a hotplug system, giving a lot more power to the user to determine what happens when a device is probed or opened. It is also a lot more complicated.

Some early 2.6 distributions (Fedora Core 3, for one) do not include hiddev rules in their default udev rule set. The bottom line for apcupsd on such a system is that if the hiddevN is not created when you plug in your UPS, apcupsd will terminate with an error. The solution to the problem is to add a rule to the udev rules file. On Fedora FC3, this file is found in /etc/udev/rules.d/50-udev.rules. Start by adding the following line:

     BUS="usb", SYSFS{idVendor}="051d", NAME="usb/hiddev%n"

(Note that this rule uses obsolete udev syntax and is specific to FC3 and other distributions of similar vintage.)

Then either reboot your system, or unplug and replug your UPS and then restart apcupsd. At that point a /dev/usb/hiddevN node should appear and apcupsd should work fine.

If you have several UPSes or you just want to give your UPS a fixed name, you can use rules like the following:

     KERNEL=="hiddev*", SYSFS{serial}=="JB0319033692", SYMLINK="ups0"
     KERNEL=="hiddev*", SYSFS{serial}=="JB0320004845", SYMLINK="ups1"

(Note that this rule uses modern udev syntax and is appropriate only for more recent distros such as RHEL4 and FC4.)

Replace the serial number in quotes with the one that corresponds to your UPS. Then whenever you plug in your UPS a symlink called ups0, ups1, etc. will be created pointing to the correct hiddev node. This technique is highly recommended if you have more than one UPS connected to the same server since rearranging your USB cables or even upgrading the kernel can affect the order in which devices are detected and thus change which hiddev node corresponds to which UPS. If you use the symlink-by-serial-number approach the link will always point to the correct device node.

You can use...

     udevinfo -a -p /sys/class/usb/hiddev0/

...to get more information on the fields that can be matched besides serial number.

An additional device-node-related problem is the use of dynamic minors. Some distributions, such as Mandrake 10, ship with a kernel having CONFIG_USB_DYNAMIC_MINORS turned on. This is not ideal for running with apcupsd, and the easiest solution is to turn CONFIG_USB_DYNAMIC_MINORS off and rebuild your kernel, or find a pre-built kernel with it off. For a kernel with CONFIG_USB_DYNAMIC_MINORS turned on to work with apcupsd, you must enable devfs. The following will tell you if devfs is enabled:

     $ ps ax | grep devs

...which should give something like the following:

     533 ?        S      0:00 devfsd /dev

What complicates the situation much more on Mandrake kernels is their security level since CONFIG_DYNAMIC_USB_MINORS is turned on, but on higher security levels devfs is turned off. The net result, is that in those situations hiddev is completely unusable so apcupsd will not work. So, in these cases, the choices are:

  1. Reduce the security level setting of the system (not sure if this is possible after the initial install).
  2. Custom build a high security kernel with devfs enabled and make sure devfs is mounted and devfsd is running.
  3. Custom build a high security kernel with dynamic minors disabled
  4. Use udev


Miscellaneous

If all these things check out and you still can't see the UPS, something is more seriously wrong than this manual can cover - find expert help. If you are unable to list USB devices or drivers, you kernel may not be USB-capable and that needs to be fixed.


BSD USB Configuration


Known BSD USB Issues

Problem
FreeBSD lockups: Some users have experienced lockups (apcupsd stops responding) on FreeBSD systems.
Solution
Recent versions of Apcupsd have addressed this issue. Please upgrade to apcupsd-3.10.18 or higher.

Problem
FreeBSD kernel panics if USB cable is unplugged while apcupsd is running.
Solution
This is a kernel bug and is most easily worked around by not hot- unplugging the UPS while apcupsd is running. This issue may be fixed in recent FreeBSD kernels.


Platforms and Versions

The BSD USB driver supports FreeBSD, OpenBSD and NetBSD. (Thanks go to the BSD developers who kept a nearly identical interface across all three platforms.)


Kernel Configuration

Users of OpenBSD, NetBSD, and some versions of FreeBSD will need to rebuild the kernel in order to enable the ugen driver and disable the uhid driver. uhid is not sufficient for apcupsd at this time and we need to prevent it from grabbing the UPS device. You should make the following changes to your kernel config file:

FreeBSD (v5.4 and below, v6.0)
(you will not lose use of USB keyboard and mouse):
Disable: uhid
Enable: ugen

FreeBSD (v5.5, v6.1 and above)
(you will not lose use of USB keyboard and mouse):
Disable: (nothing)
Enable: ugen

This is the default configuration for a GENERIC kernel on many platforms so you most likely will not need to recompile.

NetBSD (v3.x and below)
(you will lose use of USB keyboard and mouse):
Disable: uhidev, ums, wsmouse, ukbd, wskbd, uhid
Enable: ugen

NetBSD (v4.0 and above)
You can use apcupsd on single USB port without disabling the USB keyboard and mouse on other ports, though all other devices will be disabled on the port you pick for your UPS.

First, decide which hub and port you wish to use. You can find out the hub and port numbers for any particular physical connector by plugging a USB device into it and looking at the messages printed by the kernel; you should messages something like this:

     uxx0 at uhub0 port 1
     uxx0: <some device name>

To use your APC UPS on this port, configure the kernel to prefer attachment of the ugen driver over other drivers on this hub and port only, by adding a line like this to your kernel config file:

     ugen*   at uhub0 port 1 flags 1

(The "flags 1" forces the ugen to attach instead of anything else detected there.)

Configure and build that kernel as per the references below, and your UPS will now attach as a ugen device when plugged into that port.

Don't forget to cd to /dev and "./MAKEDEV ugen1" (and 2 and so on) if you have more than one generic usb device on your system.

OpenBSD
(you will lose use of USB keyboard and mouse):
Disable: uhidev, ums, wsmouse, ukbd, wskbd, uhid
Enable: ugen

For detailed information on rebuilding your kernel, consult these references:

FreeBSD
http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html
NetBSD
http://www.netbsd.org/guide/en/chap-kernel.html
OpenBSD
http://www.openbsd.org/faq/faq5.html#Building


Verifying Device Detection and Driver

After building a properly configured kernel, reboot into that kernel and plug in your UPS USB cable. You should see a dmesg log message like the following:

     ugen0: American Power Conversion Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, rev 1.10/1.06, addr 2

Note that the ugen driver is called out. If you see uhid instead, it probably means you did not properly disable the uhid driver when you compiled your kernel or perhaps you're not running the new kernel.

You can also check with 'usbdevs -d' to get a list of USB devices recognized by the system as well as the drivers they are associated with. For example:

     # usbdevs -d
     addr 1: UHCI root hub, VIA
       uhub0
      addr 2: Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, American Power Conversion
        ugen0


Device Nodes

Apcupsd communicates with the UPS through the USB generic device, ugen. You may or may not need to manually make ugen device nodes in /dev, depending on what OS you are using.

FreeBSD
No manual intervention needed. FreeBSD automatically creates the ugen nodes on demand.

NetBSD
By default, NetBSD only creates nodes for the first ugen device, ugen0. Check "usbdevs -d" to see which device your UPS was bound to and then create the appropriate node by running "cd /dev ; ./MAKEDEV ugenN", where ugenN is the ugen device name shown by usbdevs. It is probably a good idea to create several sets of ugen nodes in case you add more USB devices.

OpenBSD
Similar to NetBSD, OpenBSD creates nodes for ugen0 and ugen1. Check "usbdevs -d" to see which device your UPS was bound to and then create the appropriate node by running "cd /dev ; ./MAKEDEV ugenN", where ugenN is the ugen device name shown by usbdevs. It is probably a good idea to create several sets of ugen nodes in case you add more USB devices.


Windows USB Configuration


Platforms and Versions

Apcupsd supports USB UPSes on Windows 98, Windows ME (untested, but expected to work), Windows NT 4.0, Windows 2000, Windows XP, and Windows Server 2003. Windows Vista is untested at this time. 64-bit platforms (x64) are also supported.


USB Driver Installation

USB connected UPSes on Windows require a special driver. In most cases, this driver is automatically installed when you install Apcupsd. However, if you unchecked the "USB Driver" package during installation or if you're running Windows 98 or ME, you will need to install the driver manually.

For detailed instructions, please see the install.txt file located in the driver
folder of your Apcupsd install.


Verifying Device Detection and Driver

After installing Apcupsd (and the Apcupsd USB driver, if necessary), plug in your UPS USB cable and open the Windows Device Manager. You should see a "LibUSB-Win32 Devices" section, under which is listed "American Power Conversion USB UPS (Apcupsd)". You should NOT see "HID UPS Battery" under the "Batteries" section.

If the "LibUSB-Win32 Devices" section does not appear, check that your UPS is powered on and that the USB cable is connected at both ends. Reinstall the driver as directed above if needed.


Solaris USB Configuration


Platforms and Versions

Apcupsd supports USB UPSes on Solaris 10 and higher. Both x86 and SPARC platforms are supported.


Building Apcupsd with USB

Some specific packages are necessary when building Apcupsd with USB support on Solaris. You must install the SUNWlibusb and SUNWlibusbugen packages BEFORE attempting to build Apcupsd. These packages can be found on the Solaris installation CDROMs and should be installed with the pkgadd utility.

You also should build using the gcc compiler and ccs make, not Sun's compiler. The appropriate make utility can be found in /usr/ccs/bin. gcc can be installed from packages included on the Solaris installation CDROMs.

Configure and build Apcupsd normally, as described in Building and Installing Apcupsd. Be sure to include the --enable-usb flag to configure.

After building, install Apcupsd as root using 'make install', then perform a reconfigure boot ('reboot -- -r'). During installation, Apcupsd will automatically configure your USB subsystem to attach APC USB devices to the ugen driver. This is a critical step and must be completed by a reconfigure boot. Note that the USB config changes will be reversed if you remove Apcupsd using 'make uninstall'.


Verifying Device Detection and Driver

After installing Apcupsd as described above and performing a reconfigure boot, plug in your UPS USB cable. You should see a series of dmesg log messages similar to the following:

Dec  5 17:50:50 sunblade usba: [ID 912658 kern.info] USB 1.10 device (usb51d,2) operating at low speed (USB 1.x) on USB 1.10 root hub: input@4, ugen0 at bus address 3
Dec  5 17:50:50 sunblade usba: [ID 349649 kern.info]    American Power Conversion Smart-UPS 1000 FW:600.1.D USB FW:1.2 AS0127232356
Dec  5 17:50:50 sunblade genunix: [ID 936769 kern.info] ugen0 is /pci@1f,0/usb@c,3/input@4
Dec  5 17:50:50 sunblade genunix: [ID 408114 kern.info] /pci@1f,0/usb@c,3/input@4 (ugen0) online

Note that the ugen driver is called out. If you do not see any dmesg entries related to your UPS, ensure that it is turned on and that the USB cable is connected at both ends. Also verify that you installed Apcupsd as root using the 'make install' command and that you performed a reconfigure boot afterward.


Device Nodes

Apcupsd communicates with the UPS through the USB generic device, ugen. The reconfigure boot performed after Apcupsd installation will ensure the correct device nodes are created. Once your UPS has been recognized in dmesg as shown above, you can check /dev/usb to see if the device nodes have appeared:

[user@sunblade /]$ ls /dev/usb/51d.2/*
cntrl0      cntrl0stat  devstat     if0in1      if0in1stat

(51d.2 is the vendor/product id for APC UPSes.)


Mac OS X (Darwin) USB Configuration


Platforms and Versions

Apcupsd supports USB UPSes on Mac OS X (Darwin) 10.3.x and higher. Both Intel and PowerPC platforms are supported.


Building Apcupsd with USB

Some specific packages are necessary when building Apcupsd with USB support on Darwin. You must install libusb-0.1.12 or higher which can be obtained from MacPorts (formerly DarwinPorts) or Fink. Note that Apcupsd is sensitive to the install location of libusb, so beware if you change it from the default.

Apcupsd should be built using gcc, preferably from the XCode development tools. Currently the maintainer is using gcc-4.0.1 from XCode 2.4. Other version of gcc from other sources may also work.

Configure and build Apcupsd normally, as described in Building and Installing Apcupsd. Be sure to include the --enable-usb flag to configure.

After building, install Apcupsd as root using 'make install' and then reboot. During installation, Apcupsd will automatically install a simple dummy kext driver designed to prevent Apple's monitoring software from taking over the UPS. It is necessary to reboot in order to activate the kext. Note that this kext will be automatically removed if you uninstall Apcupsd using 'make uninstall', allowing Apple's monitoring tool to once again access the UPS.


Verifying Device Detection and Driver

After installing Apcupsd as described above and rebooting, plug in your UPS USB cable. You should notice that Darwin does NOT display the battery monitor tool in the menu bar. You can also check Apple Menu -> About This Mac -> More Info... -> USB to ensure that your UPS appears in the list of USB devices.


next up previous contents index
Next: Building and Installing apcupsd Up: Apcupsd User's Guide Previous: Choosing a Configuration Type   Contents   Index
2009-11-06