<!doctype html public "-//W3C//DTD HTML 4.0//EN">
<html>
<head>
<title>Apcupsd's Support for USB UPSes</title>
<meta name="Author" content="Kern Sibbald">
<link rel=stylesheet href="apcupsd-styles.css" type="text/css">
</head>
<body>
<h1>Apcupsd's Support for USB UPSes</h1>
<h2>General</h2>
Apcupsd version 3.9.8 or later (development version to be released as
3.10.0) provides direct support for USB UPSes on <b>Linux systems only</b>.
To run <b>apcupsd</b> with a USB UPS, you need the following
things:
<ul>
<li>A USB UPS (for example APC's BackUPS 350 CS) or an
IOGear Serial to USB converter.</li>
<li>Apcupsd version 3.9.8 or higher</li>
<li>Version 2.4.5 or later of the Linux kernel</li>
<li>Either Alan Cox's patch to your kernel. If you have
kernel 2.4.5, you must have patch <b>ac12</b> or
later. For later versions of the kernel, any
<b>ac</b> patch should do. Please note that USB
enabled kernels are becoming more and more common
so you may not need to build your own.</li>
<li>Or a pre-built kernel containing the USB patches such
as is available as an update for RedHat 7.1, or standard
in RedHat 7.2 and later. Other Linux vendors provide USB ready kernels
as well.</li>
</ul>
At the current time (August 2002), <b>apcupsd</b> supports USB on Linux
systems only. This is because there is no standard
USB programming interface and USB on the majority of
machines other than Windows and Linux is currently
under development and not stable.
<h2>Connecting a Serial port UPS to a USB port</h2>
If you would like to free up your serial port and
connect your existing serial port UPS to a USB port,
it is possible if you have one of the later kernels.
You simply get a serial to USB adapter that is supported
by the kernel, plug it in and make one minor change to
your <b>apcupsd.conf</b> file and away you go.
Thanks to Joe Acosta for this out to me.
<p>
The device that Joe and I are using is IOgear
guc232a USB 2 serial adapter. There may be other adapters
that work equally well. If you know of one, please let
us know.
<p>
At my site, running RedHat 7.1 with kernel 2.4.9-12,
I simply changed my <b>/etc/apcupsd/apcupsd.conf</b>
configuration line to be:
<p>
<b>DEVICE /dev/ttyUSB0</b>
<p>
Depending on whether or not you have <b>hotplug</b> working,
you may need to explicitly load the kernel modules
<b>usbserial</b> and <p>pl2303</b>. In my case, this
was not necessary.
<h2>Direct support for USB UPSes</h2>
The rest of this chapter concerns making <b>apcupsd</b> work
by connecting your USB enabled UPS directly to a USB port
on your Linux machine.
<p>Please note if you have cable number 940-0128A,
your UPS will be connected to your serial port
as a standard serial UPS and the rest of this chapter will
not apply to your case.
<h2>Getting and Building a Kernel</h2>
Please note that a number of Linux packagers are including
Alan Cox's patches in their standard releases. This is
true for RedHat 7.1, 7.2, and 7.3 if you have the latest
kernel updates. As a consequence before getting and
building your own kernel, if you are already running
a 2.4.5 kernel or later, please check whether or not
it already has the necessary USB updates. This can
be done by creating the device files and running the
USB test program as described below.
<p><p>
For some very brief instructions on how to get and build your
kernel, see the <a href="kernel_config.html">Kernel Configuration </a>
section of this manual. More information on configuring a kernel
can be found in the kernel-HOWTO do.
<h2>Making the Device Files</h2>
Once you have your kernel installed and working, you need to
define the hiddev device files. This can be done by invoking
the script in <b><apcupsd-src>/examples/make-hiddev</b>, which does the
following:
<pre>
#!/bin/sh
mkdir -p /dev/usb/hid
mknod /dev/usb/hid/hiddev0 c 180 96
mknod /dev/usb/hid/hiddev1 c 180 97
mknod /dev/usb/hid/hiddev2 c 180 98
mknod /dev/usb/hid/hiddev3 c 180 99
mknod /dev/usb/hid/hiddev4 c 180 100
mknod /dev/usb/hid/hiddev5 c 180 101
mknod /dev/usb/hid/hiddev6 c 180 102
mknod /dev/usb/hid/hiddev7 c 180 103
mknod /dev/usb/hid/hiddev8 c 180 104
mknod /dev/usb/hid/hiddev9 c 180 105
mknod /dev/usb/hid/hiddev10 c 180 106
mknod /dev/usb/hid/hiddev11 c 180 107
mknod /dev/usb/hid/hiddev12 c 180 108
mknod /dev/usb/hid/hiddev13 c 180 109
mknod /dev/usb/hid/hiddev14 c 180 110
mknod /dev/usb/hid/hiddev15 c 180 111
</pre>
<h2>Installing the HIDDEV Header File</h2>
If you have built the kernel, you must put
a copy of hiddev.h into /usr/include.
Use the following:
<pre>
cd /usr/src<kernel-source-directory>/
cp include/linux/hiddev.h /usr/include/linux/
</pre>
This step should not be necessary if you have
a preconfigured kernel as long as you have
loaded the <b>kernel-headers</b> rpm.
<h2>Building the Test Program</h2>
Next, we recommend that you build and run the
hid-ups test program. To build it enter:
<pre>
cd <apcupsd-src>/examples
make hid-ups
</pre>
There should be no errors.
<p></p>Now assuming that everything has gone
well to this point and that you have connected your
USB UPS, enter:
<pre>
./hid-ups
</pre>
It should print a sample report of the information that
it has obtained from your UPS. CAUTION! Do not run two
copies of this program at the same time, or your kernel
will freeze.
<p></p>
The report that is printed should look very similar to the
report in <b><src>/hid-ups.rpt</b>.
<p></p>If the program reports that the device was not found
ensure that all the appropriate modules are loaded as described
in the <a href="kernel_config.html">Kernel Configuration </a>
section of this manual, then unplug your UPS and plug it
back in. This should permit the kernel to recognize the
UPS.
<h2>Building and Installing apcupsd</h2>
If you have gotten this far successfully, the last step should
go fairly easily. You need a beta version 3.9.4 or later of
apcupsd. We recommend version 3.9.8.
Follow the instructions in the <a href="install.html">Installation Chapter</a>
of this manual, being sure to include the following options (in addition
to any others you need) on the <b>./configure</b> line:
<pre>
./configure \
--with-serial-dev=/dev/usb/hid/hiddev[0-9] \
--with-upstype=usb \
--with-upscable=usb \
--enable-pthreads \
--enable-usb
</pre>
Please note, it is IMPORTANT to include the
<b>--with-serial-dev=/dev/usb/hid/hiddev[0-9] \</b>
line. This will cause the <b>apcupsd.conf</b> file to contain:
<pre>
DEVICE /dev/usb/hid/hiddev[0-9]
</pre>
The <b>[0-9]</b> is not a typo, but should be entered exactly
as shown. This is because the UPS can change device numbers
while it is running. Every time there is a blip or slowdown
on the USB line, the kernel will invalidate the UPS connection,
then a few moments later, it will reconnect but with a different
device number. Not very Unix like, but that is what happens.
This bizarre syntax allows <b>apcupsd</b> to try a range of
devices until it finds or re-finds the UPS device.
<h2>USB Specific Information</h2>
<p></p>The UPS has an internal set of timers and remaining capacity
counters, which it uses to determine when to shutdown. These are in
addition to the <b>apcupsd</b> counters BATTERYLEVEL and
MINUTES. As a consequence, <b>apcupsd</b> will shutdown on the first
limit that triggers (either an <b>apcupsd</b> limit, or a UPS limit).
<p></p>The UPS internal
counter equivalent to BATTERYLEVEL can be found in the <b>hid-ups</b> report
as RemainingCapacityLimit, which is typically factory set to 10 percent.
In addition, the Low Battery signal is normally given by the UPS when
less than 2 minutes of run time remain.
<p>If you are technically inclined, you may want to look at the /proc file
system to see what devices are attached to your USB ports.
The most interesting information will be found by listing the
contents of <b>/proc/bus/usb/devices</b>. This information is
updated by the kernel whenever a device is plugged in or unplugged,
irrespective of whether <b>apcupsd</b> is running or not.
To interpret the
codes in this file, please see
<a href="http://www.linuxhq.com/kernel/v2.4/doc/usb/proc_usb_info.txt.html">
http://www.linuxhq.com/kernel/v2.4/doc/usb/proc_usb_info.txt.html</a>
<p>As a reference, on my system, I have the following entry
for my Back-UPS 350 direct connected USB device:
<pre>
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
</pre>
<p>And for my IOgear that runs my serial SmartUPS 1000 (plugged into
a USB port):
<pre>
T: Bus=01 Lev=01 Prnt=01 Port=01 Cnt=02 Dev#= 4 Spd=12 MxCh= 0
D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=0557 ProdID=2008 Rev= 0.01
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr=100mA
I: If#= 0 Alt= 0 #EPs= 3 Cls=ff(vend.) Sub=00 Prot=00 Driver=serial
E: Ad=81(I) Atr=03(Int.) MxPS= 10 Ivl= 1ms
E: Ad=02(O) Atr=02(Bulk) MxPS= 64 Ivl= 0ms
E: Ad=83(I) Atr=02(Bulk) MxPS= 64 Ivl= 0ms
</pre>
<p>
Note that the IOgear device is using the <b>serial</b> driver (the I: line)
while the Back-UPS 350 is using the <b>hid</b> driver.
<p>
Here is an example of a <b>cat /proc/modules</b> on my machine
(RedHat 7.1 - kernel 2.4.9-12). Note, I am running both an IOGear
serial USB device and a standard USB device.
<pre>
nfs 77312 9 (autoclean)
es1371 26816 0 (autoclean)
ac97_codec 9376 0 (autoclean) [es1371]
gameport 1856 0 (autoclean) [es1371]
soundcore 4144 4 (autoclean) [es1371]
nfsd 69920 4 (autoclean)
lockd 51664 1 (autoclean) [nfs nfsd]
sunrpc 62832 1 (autoclean) [nfs nfsd lockd]
parport_pc 14736 1 (autoclean)
lp 6176 0 (autoclean)
parport 24832 1 (autoclean) [parport_pc lp]
autofs 10784 1 (autoclean)
nls_iso8859-1 2880 1 (autoclean)
smbfs 35344 1 (autoclean)
3c59x 26336 1 (autoclean)
ipchains 36704 0
pl2303 7648 1
hid 18576 1
usbserial 18288 1 [pl2303]
input 3648 0 [hid]
usb-uhci 21568 0 (unused)
usbcore 50784 1 [pl2303 hid usbserial usb-uhci]
</pre>
<p>
I am not a kernel expert, but for a standard USB connection, I
believe that you need the following modules loaded:
<pre>
usbcore
input
hid
</pre>
<p>
For the IOGear serial USB connection, you need:
<pre>
usbcore
usbserial
pl2303
</pre>
<h2>Known Problems</h2>
<h3>Lock File not Released if UPS Disconnected</h3>
If either you disconnect the UPS or it disconnects because of some
electrical problem, it will most certainly reconnect with a different
device number. Apcupsd will detect this and reconnect properly. However,
<b>apcupsd</b> does not release the old device (serial port) lock
file and create a new one. This is not too serious.
<h3>Reinitialization If You Connect a Different UPS</h3>
If you disconnect the UPS and plug in a different one or a
different model, it will continue to function properly, but
in apcupsd version 3.9.4 the static data
such as the UPS name, model, serial number, and firmware will not
be updated. Versions 3.9.6 and greater detect
the change and do a complete reinitialization of the UPS and so
do not have this problem.
<h3>Power Off (killpower) of UPS Does Not Work</h3>
<p></p>Currently (as of 3.9.8) the code to power off the UPS does not
function properly. We are working on a solution, and it will be
forthcoming in a subsequent release. In the mean time, the UPS will
normally power itself down one to two minutes after the machine is
shutdown.
<h3>Apcupsd Cannot Reconnect After a Reboot</h3>
If apcupsd does not connect to the USB port when
you reboot, it is probably
the appropriate kernel modules are not getting loaded correctly.
<p>
You can check this by bringing up your system, fiddling
around until you get apcupsd to work with the UPS, then
do:
<p>
cat /proc/modules
<p>
and save the output some place. Then reboot your computer
and before you do anything else, do the cat /proc/modules
again. Most likely you will find some of the usb modules
are missing in the second listing.
<p>
There are two solutions:
<ul>
<li>Ensure that you have the hotplug program loaded. It should
fix the problem. This is a bit of magic, so we are not
exactly sure how it works. The rpm I (Kern) have loaded is:
<p>
<b>hotplug-2001_02_14-15</b>
<p>You might want to read the man page on <b>hotplug</b>,
and it might be necessary to:
<p>
cp /etc/hotplug/usb.rc /etc/init.d/hotplug
<p>to get it fully working.
<li>You can explicitly force the appropriate usb modules to be
loaded by adding:
<p>
<b>/sbin/modprobe <missing-module-name></b>
<p>
in the <b>/etc/rc.d/init.d/apcupsd</b> script just after the
<b>start)</b> case (at about line 17).
This will force the modules to be loaded before
apcupsd is invoked.</li>
</ul>
Normally, the modules you will need loaded are the following:
<br><b>usbcore<br>hid<br>input<br></b>
<h2>Discliamer</h2>
First, please rememeber this is beta software. It is not yet complete
and there are sure to be some problems. We would appreciate hearing
about your experiences.
<hr>
<a href="upsbible.html" target="_self"><img src="back.gif" border=0 alt="Back"></a>
<a href="snmp.html" target="_self"><img src="next.gif" border=0 alt="Next"></a>
<a href="index.html"><img src="home.gif" border=0 alt="Home"></a>
</body>
</html>
