OLD/apcupsd-usb.txt

   1 TITLE:          Installing an APC USB UPS using apcupsd
   2 LFS VERSION:    3.3
   3 AUTHOR:         Bryan Mason bmason@bmason.com
   4
   5 SYNOPSIS:
   6         Describes how to install some of the new Uninterruptable Power
   7         Supplies (UPS's) from American Power Conversion (APC) that use a
   8         Universal Serial Bus (USB) interface to connect to the host.
   9
  10 HINT:
  11
  12 Version 1.0.0
  13 23 January 2003
  14
  15 Contents
  16 ========
  17
  18         1. Introduction
  19         2. Configuring the LFS Kernel for USB and HID Support
  20         3. Installing apcupsd with USB Support
  21         4. Configuring Apcupsd
  22         5. Testing the Installation
  23         6. Creating Scripts
  24         7. Advanced Testing
  25         8. Tested Configurations
  26         9. Troubleshooting
  27
  28
  29 1. Introduction
  30 ===============
  31
  32         John McSwain's hint entitled "Apcupsd", which can be found at
  33         <http://hints.linuxfromscratch.org/hints/apcupsd.txt> describes
  34         how to install an Uninterruptable Power Supply (UPS) made by
  35         American Power Conversion (APC) using apcupsd as the software
  36         interface between the UPS and the LFS system.  Apcupsd monitors
  37         the UPS and informs the system when a power loss has occurred
  38         and can subsequently shutdown the system if power is not
  39         restored within a predetermined time.
  40
  41         This hint works fine for those UPS's that use a serial cable to
  42         interface to the host computer, but many of APC's new UPS's use
  43         a Universal Serial Bus (USB) hardware interface to connect to
  44         the system that is being provided power by the UPS.  Although
  45         the latest stable version of apcupsd, version 3.8.5, does not
  46         support these USB interfaces, versions 3.9.4 and later provide
  47         direct support for USB UPS's.  This hint is based on version
  48         3.10.3 of apcupsd, the latest development version of apcupsd
  49         available at the time of writing.
  50
  51         Installation of a USB UPS consists of the following basic steps,
  52         which are described in more detail below:
  53         1) Configuring the LFS Kernel for USB and HID support
  54         2) Installing apcupsd with USB support
  55         3) Configuring apcupsd
  56         3) Testing the installation
  57         4) Creating scripts
  58
  59         If you have any comments or corrections to be made to this
  60         document, please send an e-mail message to the author at
  61         <bmason@bmason.com>.
  62
  63
  64 2. Configuring the LFS Kernel for USB and HID Support
  65 =====================================================
  66
  67         To enable the use of a USB UPS in Linux, not only USB support is
  68         required, but also support for Human Interface Devices (HIDs).
  69         The documentation on the apcupsd Web site states that Alan Cox's
  70         patch are required to enable HID support.  This may have been
  71         true on older kernels, but HID support now seems to be an
  72         integral part of kernel version 2.4.18 which is the version used
  73         in LFS 3.3.
  74
  75         To enable USB and HID, make sure that the following items are
  76         enabled either as a module or as part of the kernel.  Generally
  77         it's easier to install these as part of the kernel; otherwise
  78         the modules will have to be loaded in the boot script and a delay
  79         will need to be made so that the USB drivers can recognize the
  80         UPS.
  81
  82         - "Input Core Support" (CONFIG_INPUT)
  83         - "Support for USB" (CONFIG_USB)
  84         - "Preliminary USB File System" (CONFIG_USB_DEVICEFS)
  85         - "USB Human Interface Device (full HID) support" (CONFIG_USB_HID)
  86         - "/dev/hiddev raw HID device support" (CONFIG_USB_HIDDEV)
  87         - One of:
  88                 "UHCI (Intel PIIX4, VIA, ...) support" (CONFIG_USB_UHCI)
  89                 or "UHCI Alternate Driver (JE) support" (CONFIG_USB_UHCI_ALT)
  90                 or "OHCI (Compaq, iMacs, OPTi, SiS, ALi, ...) support"
  91                    (CONFIG_USB_OHCI)
  92           Which one of these options is enabled will depend on the
  93           chip set used in the system on which LFS is running.  See your
  94           motherboard documentation and the help system within
  95           menuconfig for additional information.
  96
  97         After the kernel is configured, proceed with the normal process
  98         of building and installing a new Linux kernel (make bzImage,
  99         make modules, make modules_install, copy the bzImage file, etc.)
 100
 101         Strictly speaking, the "Preliminary USB File System" support
 102         isn't required, but it should make debugging easier if there are
 103         problems.
 104
 105
 106 3. Installing apcupsd with USB Support
 107 ======================================
 108
 109         3.1 Review Existing Documentation
 110
 111         Before you install apcupsd, it might be a good idea to review
 112         the documentation for the latest version of apcupsd at
 113         <http://www.apcupsd.com/beta_users_manual/index.html>.
 114         Specifically, the following sections might be useful:
 115         - Quick Start for Beginners
 116         - Compiling and Installing
 117         - Using Apcupsd with a USB UPS
 118
 119         Also, reviewing John McSwain's apcupsd hint at
 120         <http://hints.linuxfromscratch.org/hints/apcupsd.txt> is also
 121         probably a good idea.
 122
 123         Much of what follows is based on the documentation listed above
 124         -- I've just put it in a convenient, easy to swallow format (I
 125         hope).
 126
 127
 128         3.2 Download and Unpack Apcupsd
 129
 130         The source tarballs for apcupsd version 3.10.3 are located at
 131         the following sites:
 132
 133         SourceForge: http://sourceforge.net/projects/apcupsd/
 134         Apcupsd Home:
 135           ftp://ftp.apcupsd.com/pub/apcupsd/development/apcupsd-3.10.3.tar.gz
 136
 137
 138         3.3 Create the HID Devices
 139
 140         After the source has been unpacked, use the "make-hiddev" script
 141         in the "examples" directory of the apcupsd source tree to make
 142         the HID devices.  Make-hiddev performs the following commands:
 143
 144         ---------------------------------------------------------------
 145         #!/bin/sh
 146         mkdir -p /dev/usb/hid
 147         mknod /dev/usb/hid/hiddev0 c 180 96
 148         mknod /dev/usb/hid/hiddev1 c 180 97
 149         mknod /dev/usb/hid/hiddev2 c 180 98
 150         mknod /dev/usb/hid/hiddev3 c 180 99
 151         mknod /dev/usb/hid/hiddev4 c 180 100
 152         mknod /dev/usb/hid/hiddev5 c 180 101
 153         mknod /dev/usb/hid/hiddev6 c 180 102
 154         mknod /dev/usb/hid/hiddev7 c 180 103
 155         mknod /dev/usb/hid/hiddev8 c 180 104
 156         mknod /dev/usb/hid/hiddev9 c 180 105
 157         mknod /dev/usb/hid/hiddev10 c 180 106
 158         mknod /dev/usb/hid/hiddev11 c 180 107
 159         mknod /dev/usb/hid/hiddev12 c 180 108
 160         mknod /dev/usb/hid/hiddev13 c 180 109
 161         mknod /dev/usb/hid/hiddev14 c 180 110
 162         mknod /dev/usb/hid/hiddev15 c 180 111
 163         ----------------------------------------------------------------
 164
 165         After running make-hiddev, connect your UPS to your LFS system,
 166         and then build and run the "hid-ups" test program to test the
 167         connection between your system and the UPS.
 168
 169         If you compiled USB and/or HID support into modules, make sure
 170         that you have loaded the modules before running hid- ups.  The
 171         following modules should be loaded:
 172         - "hid"
 173         - "input"
 174         - "usbcore"
 175         - "usb-uhci" (or "usb-ohci" or whatever module you created)
 176
 177         To compile and execute hid-ups, execute the following commands
 178         (substituting "<apcupsd-src>" with the directory to which you
 179         unpacked the apcupsd source tarballs.
 180
 181         ----------------------------------------------------------------
 182         cd <apcupsd-src>/examples
 183         make hid-ups
 184         ./hid-ups
 185         ----------------------------------------------------------------
 186
 187         If hid-ups is successful, the tail of the output from hid-ups
 188         should look similar to the following:
 189
 190         ----------------------------------------------------------------
 191         FeatureReport 53
 192           Field 0, app UPS, phys PowerSummary
 193             Usage 0, APCPanelTest = 0
 194
 195         FeatureReport 28
 196           Field 0, app UPS, phys PowerSummary
 197             Usage 0, APCBattReplacementDate = 267777  2001-04-16
 198
 199
 200         FeatureReport 64
 201           Field 0, app UPS, phys APCGeneralCollection
 202             Usage 0, APCForceShutdown = 0
 203
 204         Waiting for events ... (interrupt to exit)
 205         ----------------------------------------------------------------
 206
 207         Press Ctrl-C to exit hid-ups.
 208
 209
 210         3.4 Install Apcupsd
 211
 212         Now configure, compile, and install apcupsd by running the
 213         following commands:
 214
 215         ----------------------------------------------------------------
 216         ./configure --prefix=/usr --sbindir=/sbin \
 217                 --with-serial-dev=/dev/usb/hid/hiddev[0-9] \
 218                 --with-upstype=usb --with-upscable=usb --enable-usb \
 219                 --enable-pthreads --enable-powerflute &&
 220         make &&
 221         make install
 222         ----------------------------------------------------------------
 223
 224         Below are descriptions of the options passed to the configure
 225         script:
 226
 227         --with-serial-dev=/dev/usb/hid/hiddev[0-9]: This is not a typo,
 228         and should be entered exactly as shown.  This syntax allows
 229         apcupsd to search all the USB devices to find the UPS.
 230
 231         --with-upstype=usb: This tells apcupsd to default to a USB UPS.
 232         This option can be changed at runtime by modifying apcupsd's
 233         configuration file.
 234
 235         --with-upscable=usb: This tells apcupsd to default to a USB
 236         cable.  This option can be changed at runtime by modifying
 237         apucpsd's configuration file.
 238
 239         --enable-usb: This enables the USB support in apcupsd.
 240
 241         --enable-pthreads: This option enables pthreads support causing
 242         apcupsd to be built as a threaded program rather than forking to
 243         create separate processes. This should cause apcupsd to be more
 244         efficient with memory and resources.  This is not strictly
 245         needed for USB support, but is a good idea.
 246
 247         --enable-powerflute: This enables the building of powerflute,
 248         which is an ncurses-based program that can be used to monitor
 249         the UPS.  This is not strictly need for USB support or even to
 250         build apcupsd, but it could be a useful program.
 251
 252
 253 4. Configuring Apcupsd
 254 ======================
 255
 256         The apcupsd configuration file is located by default at
 257         /etc/apcupsd/apcupsd.conf.  There shouldn't be much of a need to
 258         change anything in this file, since most of the important
 259         settings have already been specified during the compilation of
 260         apcupsd in Section 3.4 above.
 261
 262         The only thing that might be a good idea is to modify the
 263         behavior of apcupsd and syslogd so that apcupsd events are sent
 264         to their own file, /var/log/apcupsd.log. To do this, modify the
 265         following line in apcupsd.conf:
 266
 267         From:   #FACILITY local0
 268         To:     FACILITY local1
 269
 270         Then add the following lines to /etc/syslog.conf:
 271
 272         ----------------------------------------------------------------
 273         # Logging for apcupsd
 274         local1.*                        -/var/log/apcupsd.log
 275         ----------------------------------------------------------------
 276
 277         If the "local1" facility is already being used by another
 278         program, then change "local1" in the examples above to "local2"
 279         or another free local facility.
 280
 281         After this is done, syslogd needs to be restarted by executing
 282         the following command:
 283
 284         ----------------------------------------------------------------
 285         /etc/rc.d/init.d/sysklogd restart
 286         ----------------------------------------------------------------
 287
 288 5. Testing the Installation
 289 ===========================
 290
 291         5.1 Running apcupsd
 292
 293         The first step in testing is to run the apcupsd program itself.
 294         Simply execute:
 295
 296         ----------------------------------------------------------------
 297         apcupsd
 298         ----------------------------------------------------------------
 299
 300         Wait for apcupsd to configure itself and establish contact with
 301         the UPS, and then execute:
 302
 303         ----------------------------------------------------------------
 304         tail /var/log/apcupsd.log
 305         ----------------------------------------------------------------
 306
 307         The result should be something similar to the following:
 308
 309         ----------------------------------------------------------------
 310         Jan  3 15:51:21 linux apcupsd[22825]: apcupsd 3.10.3 (12 \
 311         December 2002) unknown startup succeeded
 312         Jan  3 15:51:21 linux apcupsd[22827]: NIS server startup \
 313         succeeded
 314         ----------------------------------------------------------------
 315
 316         If apcupsd generates an error code and then exits, see the
 317         "Testing" section of the apcupsd documentation, at
 318         <http://www.apcupsd.com/beta_users_manual/testing.html>, for
 319         information on possible sources of problems.
 320
 321
 322         5.2 Getting UPS status
 323
 324         Once apcupsd is successfully loaded, the next step is to get
 325         status from the UPS.  To do this, execute the following command:
 326
 327         ----------------------------------------------------------------
 328         apcaccess status
 329         ----------------------------------------------------------------
 330
 331         The result should be similar to the following:
 332
 333         ----------------------------------------------------------------
 334         APC      : 001,034,0833
 335         DATE     : Fri Jan 03 15:53:21 PST 2003
 336         HOSTNAME : linux
 337         RELEASE  : 3.10.3
 338         VERSION  : 3.10.3 (12 December 2002) unknown
 339         UPSNAME  : linux
 340         CABLE    : USB Cable
 341         MODEL    : Back-UPS RS 1000
 342         UPSMODE  : Stand Alone
 343         STARTTIME: Fri Jan 03 15:51:20 PST 2003
 344         STATUS   : ONLINE
 345         LINEV    : 122.0 Volts
 346         LOADPCT  :   2.0 Percent Load Capacity
 347         BCHARGE  : 100.0 Percent
 348         TIMELEFT : 341.0 Minutes
 349         MBATTCHG : 10 Percent
 350         MINTIMEL : 10 Minutes
 351         MAXTIME  : 0 Seconds
 352         LOTRANS  : 097.0 Volts
 353         HITRANS  : 138.0 Volts
 354         ALARMDEL : Always
 355         BATTV    : 27.1 Volts
 356         NUMXFERS : 0
 357         TONBATT  : 0 seconds
 358         CUMONBATT: 0 seconds
 359         XOFFBATT : N/A
 360         SELFTEST : NO
 361         STATFLAG : 0x02000008 Status Flag
 362         MANDATE  : 2002-10-13
 363         SERIALNO : JB0241034799
 364         BATTDATE : 2001-09-25
 365         NOMBATTV :  24.0
 366         FIRMWARE : .g2 .D USB FW:g2
 367         APCMODEL : Back-UPS RS 1000
 368         END APC  : Fri Jan 03 15:54:04 PST 2003
 369         ----------------------------------------------------------------
 370
 371 6. Creating Scripts
 372 ===================
 373
 374         6.1 Creating the boot script
 375
 376         The following boot script will start, stop, restart, etc. apcupsd.
 377         It is based on the LFS boot script template (/etc/rc.d/init.d/template) and
 378         the file apcupsd in the platforms/unknown directory of the apcupsd
 379         source tree.
 380
 381         ----------------------------------------------------------------
 382         #!/bin/bash
 383         # Begin /etc/rc.d/init.d/apcupsd
 384
 385         # Based on sysklogd script from LFS-3.1 and earlier.
 386         # Rewritten by Gerard Beekmans  - gerard@linuxfromscratch.org
 387         # Apcupsd version written by Bryan Mason - bmason@bmason.com
 388
 389         source /etc/sysconfig/rc
 390         source $rc_functions
 391
 392         case "$1" in
 393                 start)
 394         #               Uncomment the following lines if the USB and HID
 395         #               drivers were built as kernel modules
 396         #
 397         #               echo "Installing modules for USB and HID..."
 398         #               modprobe usb-uhci &&
 399         #               modprobe hid
 400         #               evaluate_retval
 401         #
 402         #               echo "Waiting for the UPS to be recognized..."
 403         #               sleep 5
 404
 405                         echo "Starting APC UPS Daemon (apcupsd)..."
 406                         rm -f /etc/apcupsd/powerfail
 407                         rm -f /etc/nologin
 408                         loadproc /sbin/apcupsd
 409                         ;;
 410
 411                 stop)
 412                         echo "Stopping APC UPS Daemon (apcupsd)..."
 413                         killproc /sbin/apcupsd
 414
 415         #               Uncomment the following lines if the USB and HID
 416         #               drivers were built as kernel modules
 417         #
 418         #               echo "Removing modules for USB and HID..."
 419         #               rmmod usb-uhci hid input usbcore
 420         #               evaluate_retval
 421
 422                         # Sometimes killproc can't kill apcupsd, which
 423                         # interrupts the shutdown process.
 424                         # That isn't good.  So lets make sure to always
 425                         # exit with a status of 0.
 426                         exit 0
 427                         ;;
 428
 429                 reload)
 430                         echo "Reloading APC UPS Daemon (apcupsd)..."
 431                         reloadproc /sbin/apcupsd
 432                         ;;
 433
 434                 restart)
 435                         $0 stop
 436                         sleep 1
 437                         $0 start
 438                         ;;
 439
 440                 status)
 441                         statusproc /sbin/apcupsd
 442                         ;;
 443
 444                 *)
 445                         echo "Usage: $0 {start|stop|reload|restart|status}"
 446                         exit 1
 447                         ;;
 448
 449          esac
 450
 451         # End /etc/rc.d/init.d/apcupsd
 452         ----------------------------------------------------------------
 453
 454         This file can be made by copying /etc/rc.d/init.d/template to
 455         /etc/rc.d/init.d/apcupsd or made from scratch.  If it is made
 456         from scratch, be sure to set the correct permissions on the
 457         file by running "chmod 750 /etc/rc.d/init.d/apcupsd".
 458
 459
 460         6.2 Creating the links for the boot script
 461
 462         Apcupsd should be started as soon as possible during the boot
 463         process, right after sysklogd is started.  Since sysklogd
 464         uses S10, apcupsd can be started at S15 or S20.  Apcupsd
 465         should also be one of the last things to be stopped, right
 466         before sysklogd is stopped.  Create the symbolic links by
 467         executing the following commands:
 468
 469         ----------------------------------------------------------------
 470         cd /etc/rc.d &&
 471         cd rc0.d &&
 472         ln -s ../init.d/apcupsd K35apcupsd &&
 473         cd ../rc1.d &&
 474         ln -s ../init.d/apcupsd K75apcupsd &&
 475         cd ../rc2.d &&
 476         ln -s ../init.d/apcupsd S15apcupsd &&
 477         cd ../rc3.d &&
 478         ln -s ../init.d/apcupsd S15apcupsd &&
 479         cd ../rc4.d &&
 480         ln -s ../init.d/apcupsd S15apcupsd &&
 481         cd ../rc5.d &&
 482         ln -s ../init.d/apcupsd S15apcupsd &&
 483         cd ../rc6.d &&
 484         ln -s ../init.d/apcupsd K35apcupsd
 485         ----------------------------------------------------------------
 486
 487         Of course, if you've renumbered your boot scripts, then you'll
 488         need to link the apcupsd boot script accordingly.
 489
 490
 491         6.3 Creating the UPS Powerdown Script
 492
 493         Normally, the last thing that needs to happen before the system
 494         shuts down is to power off the UPS.  Unfortunately, one of the
 495         known limitations of apcupsd interfacing to a USB UPS is that
 496         the "--killpower" option to apcupsd doesn't work, which means
 497         that it is not possible to power off a USB UPS.  Although the
 498         apcupsd documentation states that the UPS should shut itself
 499         down one to two minutes after the system, I did not observer
 500         this in my testing.  In my case, the UPS continued to supply
 501         power to the computer until the batteries drained to a critically
 502         low level.  Of course, this wasn't a problem because the system
 503         had already been shut down.
 504
 505
 506 7. Advanced Testing
 507 ===================
 508
 509         Many tests that should be run on the system before the
 510         installation is considered complete and stable.  The "Testing"
 511         section of the apcupsd documentation, located at
 512         <http://www.apcupsd.com/beta_users_manual/testing.html>, contains
 513         a list of such tests.  Briefly, the test sequence runs as
 514         follows:
 515         - Remove the USB cable from the UPS to make sure communications
 516           is working
 517         - Modify some of the scripts used by apcupsd so that they are
 518           "safe" (i.e. they won't actually shut down the system) and
 519           disconnect the UPS from utility power.
 520         - Perform a full shutdown test, but do not allow the UPS to
 521           power down.
 522         - Perform a full shutdown test, allowing the UPS to cut power to
 523           the system.
 524
 525
 526 8. Tested Configurations
 527 ========================
 528
 529         The following configuration has been tested and is fully
 530         functional after following the instructions in this hint:
 531
 532         * APC Back-Ups XS 1000
 533           Note: Apcupsd reports this as a Back-UPS RS 1000
 534
 535         If you have successfully installed another APC USB UPS on your
 536         LFS system, please send an e-mail message to <bmason@bmason.com>
 537         so I can add your model number to the above list.
 538
 539 9. Troubleshooting
 540 ==================
 541
 542         The installation of my USB UPS went very smoothly.  I didn't
 543         have to do much troubleshooting, so I don't have any
 544         troubleshooting steps to report.  If you experience problems
 545         with your installation and have a way to overcome them, please
 546         send an e-mail message to bmason@bmason.com with your
 547         experience, and I'll add it to this section.