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.
mount -t usbdevfs none /proc/bus/usb
KERNEL="hiddev*", NAME="usb/hiddev%n"
More details are provided in the following section ...
You need to check three things:
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
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:
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.
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.)
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:
This is the default configuration for a GENERIC kernel on many platforms so you most likely will not need to recompile.
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.
For detailed information on rebuilding your kernel, consult these references:
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
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.
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 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.
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.
Apcupsd supports USB UPSes on Solaris 10 and higher. Both x86 and SPARC platforms are supported.
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'.
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.
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.)
Apcupsd supports USB UPSes on Mac OS X (Darwin) 10.3.x and higher. Both Intel and PowerPC platforms are supported.
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.
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.